Pixbuf
A pixel buffer.
GdkPixbuf
contains information about an image's pixel data, its color space, bits per sample, width and height, and the rowstride (the number of bytes between the start of one row and the start of the next).
Creating new GdkPixbuf
The most basic way to create a pixbuf is to wrap an existing pixel buffer with a class@GdkPixbuf.Pixbuf instance. You can use the `ctor@GdkPixbuf.Pixbuf.new_from_data` function to do this.
Every time you create a new GdkPixbuf
instance for some data, you will need to specify the destroy notification function that will be called when the data buffer needs to be freed; this will happen when a GdkPixbuf
is finalized by the reference counting functions. If you have a chunk of static data compiled into your application, you can pass in NULL
as the destroy notification function so that the data will not be freed.
The `ctor@GdkPixbuf.Pixbuf.new` constructor function can be used as a convenience to create a pixbuf with an empty buffer; this is equivalent to allocating a data buffer using malloc()
and then wrapping it with gdk_pixbuf_new_from_data()
. The gdk_pixbuf_new()
function will compute an optimal rowstride so that rendering can be performed with an efficient algorithm.
As a special case, you can use the `ctor@GdkPixbuf.Pixbuf.new_from_xpm_data` function to create a pixbuf from inline XPM image data.
You can also copy an existing pixbuf with the method@Pixbuf.copy function. This is not the same as just acquiring a reference to the old pixbuf instance: the copy function will actually duplicate the pixel data in memory and create a new class@Pixbuf instance for it.
Reference counting
GdkPixbuf
structures are reference counted. This means that an application can share a single pixbuf among many parts of the code. When a piece of the program needs to use a pixbuf, it should acquire a reference to it by calling g_object_ref()
; when it no longer needs the pixbuf, it should release the reference it acquired by calling g_object_unref()
. The resources associated with a GdkPixbuf
will be freed when its reference count drops to zero. Newly-created GdkPixbuf
instances start with a reference count of one.
Image Data
Image data in a pixbuf is stored in memory in an 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 `method@GdkPixbuf.Pixbuf.get_rowstride`, indicates the number of bytes between rows.
NOTE: If you are copying raw pixbuf data with memcpy()
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 method@GdkPixbuf.Pixbuf.copy instead, or compute the width in bytes of the last row as:
last_row = width * ((n_channels * bits_per_sample + 7) / 8);
The same rule applies when iterating over each row of a GdkPixbuf
pixels array.
The following code illustrates a simple put_pixel()
function for RGB pixbufs with 8 bits per channel with an alpha channel.
static void
put_pixel (GdkPixbuf *pixbuf,
int x,
int y,
guchar red,
guchar green,
guchar blue,
guchar alpha)
{
int n_channels = gdk_pixbuf_get_n_channels (pixbuf);
// Ensure that the pixbuf is valid
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);
int width = gdk_pixbuf_get_width (pixbuf);
int height = gdk_pixbuf_get_height (pixbuf);
// Ensure that the coordinates are in a valid range
g_assert (x >= 0 && x < width);
g_assert (y >= 0 && y < height);
int rowstride = gdk_pixbuf_get_rowstride (pixbuf);
// The pixel buffer in the GdkPixbuf instance
guchar *pixels = gdk_pixbuf_get_pixels (pixbuf);
// The pixel we wish to modify
guchar *p = pixels + y * rowstride + x * n_channels;
p[0] = red;
p[1] = green;
p[2] = blue;
p[3] = alpha;
}
Loading images
The GdkPixBuf
class provides a simple mechanism for loading an image from a file in synchronous and asynchronous fashion.
For GUI applications, it is recommended to use the asynchronous stream API to avoid blocking the control flow of the application.
Additionally, GdkPixbuf
provides the class@GdkPixbuf.PixbufLoader` API for progressive image loading.
Saving images
The GdkPixbuf
class provides methods for saving image data in a number of file formats. The formatted data can be written to a file or to a memory buffer. GdkPixbuf
can also call a user-defined callback on the data, which allows to e.g. write the image to a socket or store it in a database.
Skipped during bindings generation
parameter
length
: length: Out parameter is not supportedmethod
read_pixels
: Return type guint8 is unsupportedmethod
save
: Varargs parameter is not supportedmethod
save_to_buffer
: Varargs parameter is not supportedparameter
buffer
: buffer: Out parameter is not supportedmethod
save_to_callback
: Varargs parameter is not supportedmethod
save_to_stream
: Varargs parameter is not supportedmethod
save_to_stream_async
: Varargs parameter is not supportedmethod
pixel-bytes
: Property has no getter nor settermethod
pixels
: Property has no getter nor setterparameter
data
: Array parameter of type guint8 is not supportedparameter
data
: Array parameter of type guint8 is not supportedparameter
width
: width: Out parameter is not supportedparameter
width
: width: Out parameter is not supported
Constructors
Creates a new GdkPixbuf
structure and allocates a buffer for it.
Creates a new #GdkPixbuf out of in-memory readonly image data.
Creates a new pixbuf by loading an image from a file.
Creates a new pixbuf by loading an image from a file.
Creates a new pixbuf by loading an image from a file.
Creates a new pixbuf by loading an image from an input stream.
Creates a new pixbuf by loading an image from an input stream.
Finishes an asynchronous pixbuf creation operation started with gdk_pixbuf_new_from_stream_async().
Creates a new pixbuf by parsing XPM data in memory.
Properties
Functions
Takes an existing pixbuf and checks for the presence of an associated "orientation" option.
Creates a transformation of the source image @src by scaling by
Creates a transformation of the source image @src by scaling by
Creates a new pixbuf by scaling src
to dest_width
x dest_height
and alpha blending the result with a checkboard of colors color1
and color2
.
Copies a rectangular area from src_pixbuf
to dest_pixbuf
.
Copies the key/value pair options attached to a GdkPixbuf
to another GdkPixbuf
.
Returns the length of the pixel data, in bytes.
Returns a GHashTable
with a list of all the options that may have been attached to the pixbuf
when it was loaded, or that may have been attached by another function using method@GdkPixbuf.Pixbuf.set_option.
Creates a new pixbuf which represents a sub-region of src_pixbuf
.
Provides a #GBytes buffer containing the raw pixel data; the data must not be modified.
Removes the key/value pair option attached to a GdkPixbuf
.
Rotates a pixbuf by a multiple of 90 degrees, and returns the result in a new pixbuf.
Modifies saturation and optionally pixelates src
, placing the result in dest
.
Vector version of gdk_pixbuf_save_to_callback()
.
Creates a transformation of the source image @src by scaling by
Create a new pixbuf containing a copy of src
scaled to dest_width
x dest_height
.