The gdk-pixbuf Library
<<< Previous Page | Home | Up | Next Page >>>

# Image Data in Memory

## Name

Image Data in Memory -- Creating a pixbuf from image data that is already in memory.

## Synopsis

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

    GdkPixbuf*  gdk_pixbuf_new                  (GdkColorspace colorspace,
                                                 gboolean has_alpha,
                                                 int bits_per_sample,
                                                 int width,
                                                 int height);
    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);
    GdkPixbuf*  gdk_pixbuf_new_from_xpm_data    (const char **data);
    GdkPixbuf*  gdk_pixbuf_copy                 (const GdkPixbuf *pixbuf);

## 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 gdk_pixbuf_ref() on the old pixbuf; the copy function will actually duplicate the pixel data in memory and create a new GdkPixbuf structure for it.

## Details

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

`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.
`height` : | Height of image in pixels.
Returns : | A newly-created GdkPixbuf with a reference count of 1, or NULL if not enough memory could be allocated for the image buffer.

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

`data` : | Image data in 8-bit/sample packed format.
`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.
`height` : | Height of the image in pixels.
`rowstride` : | Distance in bytes between rows.
`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.
`destroy_fn_data` : | Closure data to pass to the destroy notification function.
Returns : | A newly-created GdkPixbuf structure with a reference count of 1.

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

`data` : | Pointer to inline XPM data.
Returns : | A newly-created pixbuf with a reference count of 1.

### gdk_pixbuf_copy ()

    GdkPixbuf*  gdk_pixbuf_copy                 (const GdkPixbuf *pixbuf);

Creates a new GdkPixbuf with a copy of the information in the specified `pixbuf`.

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

## See Also

gdk_pixbuf_finalize().

<<< Previous Page | Home | Up | Next Page >>>
File Loading | Rendering