Image Data in Memory

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_new_from_inline          (gint data_length,
                                                         const guint8 *data,
                                                         gboolean copy_pixels,
                                                         GError **error);
GdkPixbuf *         gdk_pixbuf_new_subpixbuf            (GdkPixbuf *src_pixbuf,
                                                         int src_x,
                                                         int src_y,
                                                         int width,
                                                         int height);
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 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.

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

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, 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

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_new_from_inline ()

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

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.

GTK+ 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 flag 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.

data_length :

 Length in bytes of the data argument or -1 to disable length checks

data :

 Byte data containing a serialized GdkPixdata structure

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.

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

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().

Generated by GTK-Doc V1.14