[cairo] "data" in cairo_image_surface_get_data ()

[Baz]

On Nov 26, 2007 10:24 AM, Nguyen Vu Hung <vuhung16plus at gmail.com> wrote:
> Hi,
>
> Can anyone explain what is the "data" when the function
>
> cairo-image-surface-get-data();
> #http://cairographics.org/manual/cairo-Image-Surfaces.html#cairo-image-surface-get-data
>
> is returned?

It's exactly what it says in the docs - "pointer to the data of the
image surface, for direct inspection or modification". eg:

cairo_image_surface_t surf = cairo_image_surface_create_for_data
(data, format, width, height);
unsigned char *my_data = cairo_image_surface_get_data (surf);

At this point my_data == data.

cairo_image_surface_t surf = cairo_image_surface_create (format, width, height);
unsigned char *my_data = cairo_image_surface_get_data (surf);

At this point my_data is a chunk of memory in the format you just
asked for; see http://cairographics.org/manual/cairo-Image-Surfaces.html#cairo-format-t

If you wanted to figure out what format this data is in at a later
stage, you can call:
cairo_image_surface_get_format (surf);
cairo_image_surface_get_width (surf);
cairo_image_surface_get_height (surf);
cairo_image_surface_get_stride (surf);
... and you have all the info you need.

>
> Is it in the format of cairo-surface-t?
> #http://cairographics.org/manual/cairo-cairo-surface-t.html#cairo-surface-t

A cairo_surface_t is an abstract surface, it is not associated with a
bitmap. cairo_image_surface_get_data only operates on
cairo_image_surface_t, and returns data in the format you created the
cairo_image_surface_t with - not a copy of the data, but a pointer to
the data being used by the image surface.

>
> It would be nice if you can provide a simple example of how to use
> this function? ( read a PNG file from disk, call
> cairo-image-surface-get-data, etc, write PNG to disk ... )

The code in cairo-png.c accesses the image surface parameters
directly, eg cairo_image_surface_get_data (surf) is replaced by
surf->data, but otherwise its almost exactly what you're asking for. I
don't think an example using png would be that helpful though, it
would introduce too many complications from showing how libpng works.
Iterating over the samples retrieved from get_data is pretty easy
though:

  int i, j;
  unsigned char *data = cairo_image_surface_get_data (surf);
  int width = cairo_image_get_width(surf);
  int height = cairo_image_get_height(surf);
  int stride = cairo_image_get_stride(surf);
  for (i = 0; i < height; i++) {
      unsigned char *row = data + i * stride;
      for (int j = 0; j < width; j++) {
         // do something with the pixel at (i, j), which lies at row +
j * (pixel size),
         // based on the result of cairo_image_get_format and platform
endian-ness
      }
  }

Normally you wouldn't have to iterate over pixels like this because
your image i/o library will do some of the iteration for you.

Hope this helps,
Baz

>
> --
> Best Regards,
> Nguyen Hung Vu
> vuhung16plus{remove}@gmail.dot.com
> An inquisitive look at Harajuku
> http://www.flickr.com/photos/vuhung/sets/72157600109218238/
> _______________________________________________
> cairo mailing list
> cairo at cairographics.org
> http://lists.cairographics.org/mailman/listinfo/cairo
>