Pixbuf

Object Hierarchy:

Description:

[ CCode ( type_id = "gdk_pixbuf_get_type ()" ) ]
public sealed class Pixbuf : Object, Icon, LoadableIcon

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 [classPixbuf] 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.

Namespace: Gdk

Package: gdk-pixbuf-2.0

Content:

Properties:

public int bits_per_sample { get; construct; }
The number of bits per sample.
public Colorspace colorspace { get; construct; }
The color space of the pixbuf.
public bool has_alpha { get; construct; }
Whether the pixbuf has an alpha channel.
public int height { get; construct; }
The number of rows of the pixbuf.
public int n_channels { get; construct; }
The number of samples per pixel.
public Bytes pixel_bytes { owned get; construct; }
public void* pixels { get; construct; }
A pointer to the pixel data of the pixbuf.
public int rowstride { get; construct; }
The number of bytes between the start of a row and the start of the next row.
public int width { get; construct; }
The number of columns of the pixbuf.

Static methods:

public static int calculate_rowstride (Colorspace colorspace, bool has_alpha, int bits_per_sample, int width, int height)
Calculates the rowstride that an image created with those values would have.
public static Pixbuf from_pixdata (Pixdata pixdata, bool copy_pixels = true) throws Error
public static unowned PixbufFormat? get_file_info (string filename, out int width, out int height)
Parses an image file far enough to determine its format and size.
public static async unowned PixbufFormat? get_file_info_async (string filename, Cancellable? cancellable, out int width, out int height) throws Error
Asynchronously parses an image file far enough to determine its format and size.
public static SList<unowned PixbufFormat> get_formats ()
Obtains the available information about the image formats supported by GdkPixbuf.
public static bool init_modules (string path) throws Error
Initalizes the gdk-pixbuf loader modules referenced by the `loaders.

Creation methods:

public Pixbuf (Colorspace colorspace, bool has_alpha, int bits_per_sample, int width, int height)
Creates a new `GdkPixbuf` structure and allocates a buffer for it.
public Pixbuf.from_bytes (Bytes data, Colorspace colorspace, bool has_alpha, int bits_per_sample, int width, int height, int rowstride)
Creates a new Pixbuf out of in-memory readonly image data.
public Pixbuf.from_data (owned uint8[] data, Colorspace colorspace, bool has_alpha, int bits_per_sample, int width, int height, int rowstride, PixbufDestroyNotify? destroy_fn = free)
public Pixbuf.from_file (string filename) throws Error
Creates a new pixbuf by loading an image from a file.
public Pixbuf.from_file_at_scale (string filename, int width, int height, bool preserve_aspect_ratio) throws Error
Creates a new pixbuf by loading an image from a file.
public Pixbuf.from_file_at_size (string filename, int width, int height) throws Error
Creates a new pixbuf by loading an image from a file.
public Pixbuf.from_inline (uint8[] data, bool copy_pixels = true) throws Error
Creates a `GdkPixbuf` from a flat representation that is suitable for storing as inline data in a program.
public Pixbuf.from_resource (string resource_path) throws Error
Creates a new pixbuf by loading an image from an resource.
public Pixbuf.from_resource_at_scale (string resource_path, int width, int height, bool preserve_aspect_ratio) throws Error
Creates a new pixbuf by loading an image from an resource.
public Pixbuf.from_stream (InputStream stream, Cancellable? cancellable = null) throws Error
Creates a new pixbuf by loading an image from an input stream.
public async Pixbuf.from_stream_async (InputStream stream, Cancellable? cancellable = null) throws Error
Creates a new pixbuf by asynchronously loading an image from an input stream.
public Pixbuf.from_stream_at_scale (InputStream stream, int width, int height, bool preserve_aspect_ratio, Cancellable? cancellable = null) throws Error
Creates a new pixbuf by loading an image from an input stream.
public async Pixbuf.from_stream_at_scale_async (InputStream stream, int width, int height, bool preserve_aspect_ratio, Cancellable? cancellable = null) throws Error
Creates a new pixbuf by asynchronously loading an image from an input stream.
public Pixbuf.from_xpm_data (string[] data)
Creates a new pixbuf by parsing XPM data in memory.
public Pixbuf.subpixbuf (Pixbuf src_pixbuf, int src_x, int src_y, int width, int height)
Creates a new pixbuf which represents a sub-region of `src_pixbuf`.
public Pixbuf.with_unowned_data (uint8[] data, Colorspace colorspace, bool has_alpha, int bits_per_sample, int width, int height, int rowstride, PixbufDestroyNotify? destroy_fn = null)
Creates a new Pixbuf out of in-memory image data.

Methods:

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 [methodGdkPixbuf.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`.

Inherited Members:

All known members inherited from class GLib.Object

All known members inherited from interface GLib.Icon

All known members inherited from interface GLib.LoadableIcon

load

load_async