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).
typeof (unichar2)typeof
(unichar2) Creating new `GdkPixbuf`
The most basic way to create a pixbuf is to wrap an existing pixel buffer with a [classGdkPixbuf.Pixbuf] instance. You can
use the [`ctorGdkPixbuf.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 [`ctorGdkPixbuf.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 [`ctorGdkPixbuf.Pixbuf.new_from_xpm_data`] function to create a pixbuf from inline XPM
image data.
You can also copy an existing pixbuf with the [methodPixbuf.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.
typeof (unichar2)typeof
(unichar2) 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.
typeof (unichar2)typeof
(unichar2) 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 [`methodGdkPixbuf.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 [methodGdkPixbuf.Pixbuf.copy] instead, or compute the width in bytes of the last row as:
```c 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.
```c 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;
} ```
typeof (unichar2)typeof
(unichar2) 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 [classGdkPixbuf.PixbufLoader`] API for progressive image loading.
typeof (unichar2)typeof
(unichar2) 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.
- public Pixbuf add_alpha (bool substitute_color, uint8 r, uint8 g, uint8 b)
Takes an existing pixbuf and adds an alpha channel to it.
- public Pixbuf? apply_embedded_orientation ()
Takes an existing pixbuf and checks for the presence of an associated
"orientation" option.
- public void composite (Pixbuf dest, int dest_x, int dest_y, int dest_width, int dest_height, double offset_x, double offset_y, double scale_x, double scale_y, InterpType interp_type, int overall_alpha)
Creates a transformation of the source image
this by scaling by scale_x and scale_y then translating by offset_x
and offset_y.
- public void composite_color (Pixbuf dest, int dest_x, int dest_y, int dest_width, int dest_height, double offset_x, double offset_y, double scale_x, double scale_y, InterpType interp_type, int overall_alpha, int check_x, int check_y, int check_size, uint32 color1, uint32 color2)
Creates a transformation of the source image
this by scaling by scale_x and scale_y then translating by offset_x
and offset_y, then alpha blends the rectangle (dest_x ,dest_y, dest_width,
dest_height) of the resulting image with a checkboard of the colors color1 and color2 and
renders it onto the destination image.
- public Pixbuf? composite_color_simple (int dest_width, int dest_height, InterpType interp_type, int overall_alpha, int check_size, uint32 color1, uint32 color2)
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`.
- public Pixbuf? copy ()
Creates a new `GdkPixbuf` with a copy of the information in the
specified `pixbuf`.
- public void copy_area (int src_x, int src_y, int width, int height, Pixbuf dest_pixbuf, int dest_x, int dest_y)
Copies a rectangular area from `src_pixbuf` to `dest_pixbuf`.
- public bool copy_options (Pixbuf dest_pixbuf)
Copies the key/value pair options attached to a `GdkPixbuf` to another
`GdkPixbuf`.
- public void fill (uint32 pixel)
Clears a pixbuf to the given RGBA value, converting the RGBA value
into the pixbuf's pixel format.
- public Pixbuf? flip (bool horizontal)
Flips a pixbuf horizontally or vertically and returns the result in a
new pixbuf.
- public int get_bits_per_sample ()
Queries the number of bits per color sample in a pixbuf.
- public size_t get_byte_length ()
Returns the length of the pixel data, in bytes.
- public Colorspace get_colorspace ()
Queries the color space of a pixbuf.
- public bool get_has_alpha ()
Queries whether a pixbuf has an alpha channel (opacity information).
- public int get_height ()
Queries the height of a pixbuf.
- public int get_n_channels ()
Queries the number of channels of a pixbuf.
- public unowned string? get_option (string key)
Looks up key in the list of options that may have been
attached to the this when it was loaded, or that may have been attached by another function using
set_option.
- public HashTable<unowned string,unowned string> get_options ()
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.
- public unowned uint8[] get_pixels ()
Queries a pointer to the pixel data of a pixbuf.
- public unowned uint8[] get_pixels_with_length ()
Queries a pointer to the pixel data of a pixbuf.
- public int 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.
- public int get_width ()
Queries the width of a pixbuf.
- public Bytes read_pixel_bytes ()
Provides a Bytes buffer containing the raw
pixel data; the data must not be modified.
- public uint8 read_pixels ()
Provides a read-only pointer to the raw pixel data.
- public bool remove_option (string key)
Removes the key/value pair option attached to a `GdkPixbuf`.
- public Pixbuf? rotate_simple (PixbufRotation angle)
Rotates a pixbuf by a multiple of 90 degrees, and returns the result
in a new pixbuf.
- public void saturate_and_pixelate (Pixbuf dest, float saturation, bool pixelate)
Modifies saturation and optionally pixelates `src`, placing the result
in `dest`.
- public bool save (string filename, string type, ...) throws Error
Saves pixbuf to a file in format type.
- public bool save_to_buffer (out uint8[] buffer, string type, ...) throws Error
Saves pixbuf to a new buffer in format `type`, which is currently
"jpeg", "png", "tiff", "ico" or "bmp".
- public bool save_to_bufferv (out uint8[] buffer, string type, string[]? option_keys, string[]? option_values) throws Error
Vector version of `gdk_pixbuf_save_to_buffer()`.
- public bool save_to_callback (PixbufSaveFunc save_func, string type, ...) throws Error
Saves pixbuf in format `type` by feeding the produced data to a
callback.
- public bool save_to_callbackv (PixbufSaveFunc save_func, string type, string[]? option_keys, string[]? option_values) throws Error
Vector version of `gdk_pixbuf_save_to_callback()`.
- public bool save_to_stream (OutputStream stream, string type, Cancellable? cancellable = null, ...) throws Error
Saves `pixbuf` to an output stream.
- public async void save_to_stream_async (OutputStream stream, string type, Cancellable? cancellable = null, ...) throws Error
Saves `pixbuf` to an output stream asynchronously.
- public bool save_to_streamv (OutputStream stream, string type, string[]? option_keys, string[]? option_values, Cancellable? cancellable = null) throws Error
Saves `pixbuf` to an output stream.
- public async void save_to_streamv_async (OutputStream stream, string type, string[]? option_keys, string[]? option_values, Cancellable? cancellable = null) throws Error
Saves `pixbuf` to an output stream asynchronously.
- public bool savev (string filename, string type, string[]? option_keys, string[]? option_values) throws Error
Vector version of `gdk_pixbuf_save()`.
- public void scale (Pixbuf dest, int dest_x, int dest_y, int dest_width, int dest_height, double offset_x, double offset_y, double scale_x, double scale_y, InterpType interp_type)
Creates a transformation of the source image
this by scaling by scale_x and scale_y then translating by offset_x
and offset_y, then renders the rectangle (dest_x, dest_y, dest_width,
dest_height) of the resulting image onto the destination image replacing the previous contents.
- public Pixbuf? scale_simple (int dest_width, int dest_height, InterpType interp_type)
Create a new pixbuf containing a copy of `src` scaled to `dest_width`
x `dest_height`.
- public bool set_option (string key, string value)
Attaches a key/value pair as an option to a `GdkPixbuf`.