Image Data in Memory: GDK-PixBuf Reference Manual

## Image Data in Memory Image Data in Memory — Creating a pixbuf from image data that is already in memory. |

## Functions

GdkPixbuf * | gdk_pixbuf_new ()
GdkPixbuf * | gdk_pixbuf_new_from_bytes ()
GdkPixbuf * | gdk_pixbuf_new_from_data ()
GdkPixbuf * | gdk_pixbuf_new_from_xpm_data ()
GdkPixbuf * | gdk_pixbuf_new_from_inline ()
GdkPixbuf * | gdk_pixbuf_new_subpixbuf ()
GdkPixbuf * | gdk_pixbuf_copy ()

## Includes

    #include <gdk-pixbuf/gdk-pixbuf.h>

## Description

The most basic way to create a pixbuf is to wrap an existing pixel buffer with a GdkPixbuf structure. You can use the `gdk_pixbuf_new_from_data()` function to do this You 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 `gdk_pixbuf_new()` 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 `gdk_pixbuf_new_from_xpm_data()` function to create a pixbuf from inline XPM image data.

You can also copy an existing pixbuf with the `gdk_pixbuf_copy()` function. This is not the same as just doing a `g_object_ref()` on the old pixbuf; the copy function will actually duplicate the pixel data in memory and create a new GdkPixbuf structure for it.

## Functions

### gdk_pixbuf_new ()

    GdkPixbuf *
    gdk_pixbuf_new (GdkColorspace colorspace,
                    gboolean has_alpha,
                    int bits_per_sample,
                    int width,
                    int height);

Creates a new GdkPixbuf structure and allocates a buffer for it. The buffer has an optimal rowstride. Note that the buffer is not cleared; you will have to fill it completely yourself.

#### Parameters

colorspace | Color space for image |
has_alpha | Whether the image should have transparency information |
bits_per_sample | Number of bits per color sample |
width | Width of image in pixels, must be > 0 |
height | Height of image in pixels, must be > 0 |

#### Returns

A newly-created GdkPixbuf with a reference count of 1, or `NULL` if not enough memory could be allocated for the image buffer.

[nullable]

### gdk_pixbuf_new_from_bytes ()

    GdkPixbuf *
    gdk_pixbuf_new_from_bytes (GBytes *data,
                               GdkColorspace colorspace,
                               gboolean has_alpha,
                               int bits_per_sample,
                               int width,
                               int height,
                               int rowstride);

Creates a new GdkPixbuf out of in-memory readonly image data. Currently only RGB images with 8 bits per sample are supported. This is the GBytes variant of `gdk_pixbuf_new_from_data()`.

#### Parameters

data | Image data in 8-bit/sample packed format inside a GBytes |
colorspace | Colorspace for the image data |
has_alpha | Whether the data has an opacity channel |
bits_per_sample | Number of bits per sample |
width | Width of the image in pixels, must be > 0 |
height | Height of the image in pixels, must be > 0 |
rowstride | Distance in bytes between row starts |

#### Returns

A newly-created GdkPixbuf structure with a reference count of 1.

[transfer full]

Since: 2.32

### gdk_pixbuf_new_from_data ()

    GdkPixbuf *
    gdk_pixbuf_new_from_data (const guchar *data,
                              GdkColorspace colorspace,
                              gboolean has_alpha,
                              int bits_per_sample,
                              int width,
                              int height,
                              int rowstride,
                              GdkPixbufDestroyNotify destroy_fn,
                              gpointer destroy_fn_data);

Creates a new GdkPixbuf out of in-memory image data. Currently only RGB images with 8 bits per sample are supported.

Since you are providing a pre-allocated pixel buffer, you must also specify a way to free that data. This is done with a function of type GdkPixbufDestroyNotify. When a pixbuf created with is finalized, your destroy notification function will be called, and it is its responsibility to free the pixel array.

See also `gdk_pixbuf_new_from_bytes()`.

#### Parameters

data | Image data in 8-bit/sample packed format. | [array]
colorspace | Colorspace for the image data |
has_alpha | Whether the data has an opacity channel |
bits_per_sample | Number of bits per sample |
width | Width of the image in pixels, must be > 0 |
height | Height of the image in pixels, must be > 0 |
rowstride | Distance in bytes between row starts |
destroy_fn | Function used to free the data when the pixbuf's reference count drops to zero, or `NULL` if the data should not be freed. | [scope async][allow-none]
destroy_fn_data | Closure data to pass to the destroy notification function. | [closure]

#### Returns

A newly-created GdkPixbuf structure with a reference count of 1.

[transfer full]

### gdk_pixbuf_new_from_xpm_data ()

    GdkPixbuf *
    gdk_pixbuf_new_from_xpm_data (const char **data);

Creates a new pixbuf by parsing XPM data in memory. This data is commonly the result of including an XPM file into a program's C source.

#### Parameters

data | Pointer to inline XPM data. | [array zero-terminated=1]

#### Returns

A newly-created pixbuf with a reference count of 1.

### gdk_pixbuf_new_from_inline ()

    GdkPixbuf *
    gdk_pixbuf_new_from_inline (gint data_length,
                                const guint8 *data,
                                gboolean copy_pixels,
                                GError **error);

`gdk_pixbuf_new_from_inline` has been deprecated since version 2.32 and should not be used in newly-written code.

Use GResource instead.

Create a GdkPixbuf from a flat representation that is suitable for storing as inline data in a program. This is useful if you want to ship a program with images, but don't want to depend on any external files.

gdk-pixbuf ships with a program called gdk-pixbuf-csource, which allows for conversion of GdkPixbufs into such a inline representation. In almost all cases, you should pass the `--raw` option to `gdk-pixbuf-csource`. A sample invocation would be:

    1
    gdk-pixbuf-csource --raw --name=myimage_inline myimage.png

For the typical case where the inline pixbuf is read-only static data, you don't need to copy the pixel data unless you intend to write to it, so you can pass `FALSE` for `copy_pixels` . (If you pass `--rle` to `gdk-pixbuf-csource`, a copy will be made even if `copy_pixels` is `FALSE`, so using this option is generally a bad idea.)

If you create a pixbuf from const inline data compiled into your program, it's probably safe to ignore errors and disable length checks, since things will always succeed:

    1
    pixbuf = gdk_pixbuf_new_from_inline (-1, myimage_inline, FALSE, NULL);

For non-const inline data, you could get out of memory. For untrusted inline data located at runtime, you could have corrupt inline data in addition.

#### Parameters

data_length | Length in bytes of the `data` argument or -1 to disable length checks |
data | Byte data containing a serialized GdkPixdata structure. | [array length=data_length]
copy_pixels | Whether to copy the pixel data, or use direct pointers `data` for the resulting pixbuf |
error | GError return location, may be `NULL` to ignore errors |

#### Returns

A newly-created GdkPixbuf structure with a reference, count of 1, or `NULL` if an error occurred.

### gdk_pixbuf_new_subpixbuf ()

    GdkPixbuf *
    gdk_pixbuf_new_subpixbuf (GdkPixbuf *src_pixbuf,
                              int src_x,
                              int src_y,
                              int width,
                              int height);

Creates a new pixbuf which represents a sub-region of `src_pixbuf` . The new pixbuf shares its pixels with the original pixbuf, so writing to one affects both. The new pixbuf holds a reference to `src_pixbuf` , so `src_pixbuf` will not be finalized until the new pixbuf is finalized.

Note that if `src_pixbuf` is read-only, this function will force it to be mutable.

#### Parameters

src_pixbuf | a GdkPixbuf |
src_x | X coord in `src_pixbuf` |
src_y | Y coord in `src_pixbuf` |
width | width of region in `src_pixbuf` |
height | height of region in `src_pixbuf` |

#### Returns

a new pixbuf.

[transfer full]

### gdk_pixbuf_copy ()

    GdkPixbuf *
    gdk_pixbuf_copy (const GdkPixbuf *pixbuf);

Creates a new GdkPixbuf with a copy of the information in the specified `pixbuf` . Note that this does not copy the options set on the original GdkPixbuf, use `gdk_pixbuf_copy_options()` for this.

#### Parameters

pixbuf | A pixbuf. |

#### Returns

A newly-created pixbuf with a reference count of 1, or `NULL` if not enough memory could be allocated.

[nullable][transfer full]

## See Also

gdk_pixbuf_finalize().