
@c %start of fragment

@node The GdkPixbuf Structure
@chapter The GdkPixbuf Structure
Information that describes an image.

@section Overview
The structure contains information that describes an image in memory.

Image data in a pixbuf is stored in memory in uncompressed, packed format. Rows
in the image are stored top to bottom, and in each row pixels are stored from
left to right. There may be padding at the end of a row. The "rowstride" value
of a pixbuf, as returned by @code{gdk-pixbuf-get-rowstride}, indicates the
number of bytes between rows.

The following code illustrates a simple put_pixel() function for RGB pixbufs
with 8 bits per channel with an alpha channel. It is not included in the
gdk-pixbuf library for performance reasons; rather than making several function
calls for each pixel, your own code can take shortcuts.

@example 

static void
put_pixel (GdkPixbuf *pixbuf, int x, int y, guchar red, guchar green, guchar blue, guchar alpha)
@{
  int width, height, rowstride, n_channels;
  guchar *pixels, *p;

  n_channels = gdk_pixbuf_get_n_channels (pixbuf);

  g_assert (gdk_pixbuf_get_colorspace (pixbuf) == GDK_COLORSPACE_RGB);
  g_assert (gdk_pixbuf_get_bits_per_sample (pixbuf) == 8);
  g_assert (gdk_pixbuf_get_has_alpha (pixbuf));
  g_assert (n_channels == 4);

  width = gdk_pixbuf_get_width (pixbuf);
  height = gdk_pixbuf_get_height (pixbuf);

  g_assert (x >= 0 && x < width);
  g_assert (y >= 0 && y < height);

  rowstride = gdk_pixbuf_get_rowstride (pixbuf);
  pixels = gdk_pixbuf_get_pixels (pixbuf);

  p = pixels + y * rowstride + x * n_channels;
  p[0] = red;
  p[1] = green;
  p[2] = blue;
  p[3] = alpha;
@}
      
@end example

This function will not work for pixbufs with images that are other than 8 bits
per sample or channel, but it will work for most of the pixbufs that GTK+ uses.

If you are doing @code{memcpy} of raw pixbuf data, note that the last row in the
pixbuf may not be as wide as the full rowstride, but rather just as wide as the
pixel data needs to be. That is, it is unsafe to do @samp{memcpy (dest, pixels,
rowstride * height)} to copy a whole pixbuf. Use @code{gdk-pixbuf-copy} instead,
or compute the width in bytes of the last row as @samp{width * ((n_channels *
bits_per_sample + 7) / 8)}.

@section Usage
@include defuns-gdk-pixbuf.xml.texi

@c %end of fragment
