1 <!-- ##### SECTION Title ##### -->
2 Reference Counting and Memory Mangement
4 <!-- ##### SECTION Short_Description ##### -->
6 Functions for reference counting and memory management on pixbufs.
8 <!-- ##### SECTION Long_Description ##### -->
10 #GdkPixbuf structures are reference counted. This means that an
11 application can share a single pixbuf among many parts of the
12 code. When a piece of the program needs to keep a pointer to a
13 pixbuf, it should add a reference to it by calling g_object_ref().
14 When it no longer needs the pixbuf, it should subtract a reference
15 by calling g_object_unref(). The pixbuf will be destroyed when
16 its reference count drops to zero. Newly-created #GdkPixbuf
17 structures start with a reference count of one.
22 As #GdkPixbuf is derived from #GObject now, gdk_pixbuf_ref() and
23 gdk_pixbuf_unref() are deprecated in favour of g_object_ref()
24 and g_object_unref () resp.
29 <emphasis>Finalizing</emphasis> a pixbuf means to free its pixel
30 data and to free the #GdkPixbuf structure itself. Most of the
31 library functions that create #GdkPixbuf structures create the
32 pixel data by themselves and define the way it should be freed;
33 you do not need to worry about those. The only function that lets
34 you specify how to free the pixel data is
35 gdk_pixbuf_new_from_data(). Since you pass it a pre-allocated
36 pixel buffer, you must also specify a way to free that data. This
37 is done with a function of type #GdkPixbufDestroyNotify. When a
38 pixbuf created with gdk_pixbuf_new_from_data() is finalized, your
39 destroy notification function will be called, and it is its
40 responsibility to free the pixel array.
43 <!-- ##### SECTION See_Also ##### -->
45 #GdkPixbuf, gdk_pixbuf_new_from_data().
48 <!-- ##### SECTION Stability_Level ##### -->
51 <!-- ##### FUNCTION gdk_pixbuf_ref ##### -->
60 <!-- ##### FUNCTION gdk_pixbuf_unref ##### -->
68 <!-- ##### USER_FUNCTION GdkPixbufDestroyNotify ##### -->
70 A function of this type is responsible for freeing the pixel array
71 of a pixbuf. The gdk_pixbuf_new_from_data() function lets you
72 pass in a pre-allocated pixel array so that a pixbuf can be
73 created from it; in this case you will need to pass in a function
74 of #GdkPixbufDestroyNotify so that the pixel data can be freed
75 when the pixbuf is finalized.
78 @pixels: The pixel array of the pixbuf that is being finalized.
79 @data: User closure data.