Reference Counting and Memory Mangement: GDK-PixBuf Reference Manual

Reference Counting and Memory Mangement

Reference Counting and Memory Mangement — Functions for reference counting and memory management on pixbufs.

Functions

GdkPixbuf *	gdk_pixbuf_ref ()
void	gdk_pixbuf_unref ()
void	(*GdkPixbufDestroyNotify) ()

Includes

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

Description

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 keep a pointer to a pixbuf, it should add a reference to it by calling g_object_ref(). When it no longer needs the pixbuf, it should subtract a reference by calling g_object_unref(). The pixbuf will be destroyed when its reference count drops to zero. Newly-created GdkPixbuf structures start with a reference count of one.

As GdkPixbuf is derived from GObject now, gdk_pixbuf_ref() and gdk_pixbuf_unref() are deprecated in favour of g_object_ref() and g_object_unref() resp.

Finalizing a pixbuf means to free its pixel data and to free the GdkPixbuf structure itself. Most of the library functions that create GdkPixbuf structures create the pixel data by themselves and define the way it should be freed; you do not need to worry about those.

To provide preallocated pixel data, use gdk_pixbuf_new_from_bytes(). The gdk_pixbuf_new_from_data() API is an older variant that predates the existence of GBytes.

Functions

gdk_pixbuf_ref ()

GdkPixbuf *
gdk_pixbuf_ref (GdkPixbuf *pixbuf);

gdk_pixbuf_ref has been deprecated since version 2.0 and should not be used in newly-written code.

Use g_object_ref().

Adds a reference to a pixbuf.

[skip]

Parameters

pixbuf

A pixbuf.

Returns

The same as the pixbuf argument.

gdk_pixbuf_unref ()

void
gdk_pixbuf_unref (GdkPixbuf *pixbuf);

gdk_pixbuf_unref has been deprecated since version 2.0 and should not be used in newly-written code.

Use g_object_unref().

Removes a reference from a pixbuf.

[skip]

Parameters

pixbuf

A pixbuf.

GdkPixbufDestroyNotify ()

void
(*GdkPixbufDestroyNotify) (guchar *pixels,
                           gpointer data);

A function of this type is responsible for freeing the pixel array of a pixbuf. The gdk_pixbuf_new_from_data() function lets you pass in a pre-allocated pixel array so that a pixbuf can be created from it; in this case you will need to pass in a function of GdkPixbufDestroyNotify so that the pixel data can be freed when the pixbuf is finalized.

Parameters

pixels	The pixel array of the pixbuf that is being finalized.	[array][element-type guint8]
data	User closure data.	[closure]