Next: , Previous: X Window System Interaction, Up: Top

29 The GdkPixbuf Structure

Information that describes an image.

29.1 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 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.

     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;

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 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 ‘memcpy (dest, pixels, rowstride * height)’ to copy a whole pixbuf. Use gdk-pixbuf-copy instead, or compute the width in bytes of the last row as ‘width * ((n_channels * bits_per_sample + 7) / 8)’.

29.2 Usage

— Class: <gdk-pixbuf>

Derives from <gobject>.

This class defines the following slots:

The colorspace in which the samples are interpreted
The number of samples per pixel
Whether the pixbuf has an alpha channel
The number of bits per sample
The number of columns of the pixbuf
The number of rows of the pixbuf
The number of bytes between the start of a row and the start of the next row
A pointer to the pixel data of the pixbuf
— Function: gdk-pixbuf-get-colorspace (self <gdk-pixbuf>) ⇒  (ret <gdk-colorspace>)
— Method: get-colorspace

Queries the color space of a pixbuf.

A pixbuf.
Color space.
— Function: gdk-pixbuf-get-n-channels (self <gdk-pixbuf>) ⇒  (ret int)
— Method: get-n-channels

Queries the number of channels of a pixbuf.

A pixbuf.
Number of channels.
— Function: gdk-pixbuf-get-has-alpha (self <gdk-pixbuf>) ⇒  (ret bool)
— Method: get-has-alpha

Queries whether a pixbuf has an alpha channel (opacity information).

A pixbuf.
#t’ if it has an alpha channel, ‘#f’ otherwise.
— Function: gdk-pixbuf-get-bits-per-sample (self <gdk-pixbuf>) ⇒  (ret int)
— Method: get-bits-per-sample

Queries the number of bits per color sample in a pixbuf.

A pixbuf.
Number of bits per color sample.
— Function: gdk-pixbuf-get-width (self <gdk-pixbuf>) ⇒  (ret int)
— Method: get-width

Queries the width of a pixbuf.

A pixbuf.
Width in pixels.
— Function: gdk-pixbuf-get-height (self <gdk-pixbuf>) ⇒  (ret int)
— Method: get-height

Queries the height of a pixbuf.

A pixbuf.
Height in pixels.
— Function: gdk-pixbuf-get-rowstride (self <gdk-pixbuf>) ⇒  (ret int)
— Method: get-rowstride

Queries the rowstride of a pixbuf, which is the number of bytes between the start of a row and the start of the next row.

A pixbuf.
Distance between row starts.
— Function: gdk-pixbuf-get-option (self <gdk-pixbuf>) (key mchars) ⇒  (ret mchars)
— Method: get-option

Looks up key in the list of options that may have been attached to the pixbuf when it was loaded.

a <gdk-pixbuf>
a nul-terminated string.
the value associated with key. This is a nul-terminated string that should not be freed or ‘#f’ if key was not found.