[Xcb] about xcb_image

[Barton C Massey]

In message <Pine.LNX.4.64.0802210909030.1308 at grozny.maths.univ-evry.fr> you wrote:
> I'm trying to use the new xcb_image api in the efl (especially in evas), 
> and I have some difficulties to understand what values to pass to 
> xcb_create_native.
> 
> The old call was:
> 
> xcb_image_create(c, depth, XCB_IMAGE_FORMAT_Z_PIXMAP, 0, data, w, h, 32, 0);
> 
> I tried something that I thought correct:
> 
> xcb_image_create_native(c, w, h, XCB_IMAGE_FORMAT_Z_PIXMAP, depth, NULL, 0, data)
> 
> Am I wrong ?

The memory allocation (last three arguments) for
xcb_image_create() is magic, to say the least.  What exactly
is in "data", and what are you trying to do with it?

Other than that potential problem, I see nothing obvious
wrong.

> same question for
> 
> xcb_image_shm_create(c, depth, XCB_IMAGE_FORMAT_Z_PIXMAP, NULL, w, h);
> 
> and
> 
> xcb_image_create_native(c, w, h, XCB_IMAGE_FORMAT_Z_PIXMAP, depth, NULL, ~0, NULL);

You might want 0 in the next-to-last argument here, if you
want create_native() to allocate and set up the storage.
Otherwise you'll need to do it yourself...


My documentation for the memory stuff is *horrible*.  This
comment in the source is slightly better:

   * Ways this function can be called:
   *   * with data: we fail if bytes isn't
   *     large enough, else leave well enough alone.
   *   * with base and !data: if bytes is zero, we
   *     default; otherwise we fail if bytes isn't
   *     large enough, else fill in data
   *   * with !base and !data: we malloc storage
   *     for the data, save that address as the base,
   *     and fail if malloc does.
   *
   * When successful, we establish the invariant that data
   * points at sufficient storage that may have been
   * supplied, and base is set iff it should be
   * auto-freed when the image is destroyed.
   *
   * Except as a special case when base = 0 && data == 0 &&
   * bytes == ~0 we just return the image structure and let
   * the caller deal with getting the allocation right.

but I'm not sure it's exactly right :-9.  The C code is
clearer, sadly:

  if (!base && !data && bytes == ~0)
      return image;
  if (!base && data && bytes == 0)
      bytes = image->size;
  image->base = base;
  image->data = data;
  if (!image->data) {
      if (image->base) {
          image->data = image->base;
      } else {
          bytes = image->size;
          image->base = malloc(bytes);
          image->data = image->base;
      }
  }
  if (!image->data || bytes < image->size) {
      free(image);
      return 0;
  }
  return image;

Somebody should work on the doxygen.

> not really related, but i think that the doc of the return value of 
> xcb_image_shm_put is wrong (it is mentioned several times that, on sucess, 
> the returned value is 1, while a pointer is returned. Is it normal ?

Doc bug, fixed, thanks!

     Bart