1
<refentry id="gdk-pixbuf-refcounting">
3
<refentrytitle role="top_of_page">Reference Counting and Memory Mangement</refentrytitle>
4
<manvolnum>3</manvolnum>
5
<refmiscinfo>GDK-PIXBUF Library</refmiscinfo>
9
<refname>Reference Counting and Memory Mangement</refname>
11
Functions for reference counting and memory management on pixbufs.</refpurpose>
12
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
15
<refsynopsisdiv role="synopsis">
16
<title role="synopsis.title">Synopsis</title>
20
#include <gdk-pixbuf/gdk-pixbuf.h>
23
<link linkend="GdkPixbuf">GdkPixbuf</link>* <link linkend="gdk-pixbuf-ref">gdk_pixbuf_ref</link> (<link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf);
24
<link linkend="void">void</link> <link linkend="gdk-pixbuf-unref">gdk_pixbuf_unref</link> (<link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf);
25
<link linkend="void">void</link> (<link linkend="GdkPixbufDestroyNotify">*GdkPixbufDestroyNotify</link>) (<link linkend="guchar">guchar</link> *pixels,
26
<link linkend="gpointer">gpointer</link> data);
38
<refsect1 role="desc">
39
<title role="desc.title">Description</title>
41
<link linkend="GdkPixbuf"><type>GdkPixbuf</type></link> structures are reference counted. This means that an
42
application can share a single pixbuf among many parts of the
43
code. When a piece of the program needs to keep a pointer to a
44
pixbuf, it should add a reference to it by calling <link linkend="g-object-ref"><function>g_object_ref()</function></link>.
45
When it no longer needs the pixbuf, it should subtract a reference
46
by calling <link linkend="g-object-unref"><function>g_object_unref()</function></link>. The pixbuf will be destroyed when
47
its reference count drops to zero. Newly-created <link linkend="GdkPixbuf"><type>GdkPixbuf</type></link>
48
structures start with a reference count of one.
53
As <link linkend="GdkPixbuf"><type>GdkPixbuf</type></link> is derived from <link linkend="GObject"><type>GObject</type></link> now, <link linkend="gdk-pixbuf-ref"><function>gdk_pixbuf_ref()</function></link> and
54
<link linkend="gdk-pixbuf-unref"><function>gdk_pixbuf_unref()</function></link> are deprecated in favour of <link linkend="g-object-ref"><function>g_object_ref()</function></link>
55
and <link linkend="g-object-unref"><function>g_object_unref()</function></link> resp.
60
<emphasis>Finalizing</emphasis> a pixbuf means to free its pixel
61
data and to free the <link linkend="GdkPixbuf"><type>GdkPixbuf</type></link> structure itself. Most of the
62
library functions that create <link linkend="GdkPixbuf"><type>GdkPixbuf</type></link> structures create the
63
pixel data by themselves and define the way it should be freed;
64
you do not need to worry about those. The only function that lets
65
you specify how to free the pixel data is
66
<link linkend="gdk-pixbuf-new-from-data"><function>gdk_pixbuf_new_from_data()</function></link>. Since you pass it a pre-allocated
67
pixel buffer, you must also specify a way to free that data. This
68
is done with a function of type <link linkend="GdkPixbufDestroyNotify"><type>GdkPixbufDestroyNotify</type></link>. When a
69
pixbuf created with <link linkend="gdk-pixbuf-new-from-data"><function>gdk_pixbuf_new_from_data()</function></link> is finalized, your
70
destroy notification function will be called, and it is its
71
responsibility to free the pixel array.
75
<refsect1 role="details">
76
<title role="details.title">Details</title>
78
<title><anchor id="gdk-pixbuf-ref" role="function" condition="deprecated:Use g_object_ref()."/>gdk_pixbuf_ref ()</title>
79
<indexterm role="deprecated"><primary>gdk_pixbuf_ref</primary></indexterm><programlisting><link linkend="GdkPixbuf">GdkPixbuf</link>* gdk_pixbuf_ref (<link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf);</programlisting>
80
<warning><para><literal>gdk_pixbuf_ref</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-object-ref"><function>g_object_ref()</function></link>.</para></warning>
82
Adds a reference to a pixbuf.</para>
85
</para><variablelist role="params">
86
<varlistentry><term><parameter>pixbuf</parameter> :</term>
87
<listitem><simpara> A pixbuf.
88
</simpara></listitem></varlistentry>
89
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The same as the <parameter>pixbuf</parameter> argument.
91
</simpara></listitem></varlistentry>
92
</variablelist></refsect2>
94
<title><anchor id="gdk-pixbuf-unref" role="function" condition="deprecated:Use g_object_unref()."/>gdk_pixbuf_unref ()</title>
95
<indexterm role="deprecated"><primary>gdk_pixbuf_unref</primary></indexterm><programlisting><link linkend="void">void</link> gdk_pixbuf_unref (<link linkend="GdkPixbuf">GdkPixbuf</link> *pixbuf);</programlisting>
96
<warning><para><literal>gdk_pixbuf_unref</literal> is deprecated and should not be used in newly-written code. Use <link linkend="g-object-unref"><function>g_object_unref()</function></link>.</para></warning>
98
Removes a reference from a pixbuf.</para>
101
</para><variablelist role="params">
102
<varlistentry><term><parameter>pixbuf</parameter> :</term>
103
<listitem><simpara> A pixbuf.
104
</simpara></listitem></varlistentry>
105
</variablelist></refsect2>
107
<title><anchor id="GdkPixbufDestroyNotify" role="function"/>GdkPixbufDestroyNotify ()</title>
108
<indexterm><primary>GdkPixbufDestroyNotify</primary></indexterm><programlisting><link linkend="void">void</link> (*GdkPixbufDestroyNotify) (<link linkend="guchar">guchar</link> *pixels,
109
<link linkend="gpointer">gpointer</link> data);</programlisting>
111
A function of this type is responsible for freeing the pixel array
112
of a pixbuf. The <link linkend="gdk-pixbuf-new-from-data"><function>gdk_pixbuf_new_from_data()</function></link> function lets you
113
pass in a pre-allocated pixel array so that a pixbuf can be
114
created from it; in this case you will need to pass in a function
115
of <link linkend="GdkPixbufDestroyNotify"><type>GdkPixbufDestroyNotify</type></link> so that the pixel data can be freed
116
when the pixbuf is finalized.
117
</para><variablelist role="params">
118
<varlistentry><term><parameter>pixels</parameter> :</term>
119
<listitem><simpara>The pixel array of the pixbuf that is being finalized.
120
</simpara></listitem></varlistentry>
121
<varlistentry><term><parameter>data</parameter> :</term>
122
<listitem><simpara>User closure data.
125
</simpara></listitem></varlistentry>
126
</variablelist></refsect2>
133
<title>See Also</title>
135
<link linkend="GdkPixbuf"><type>GdkPixbuf</type></link>, <link linkend="gdk-pixbuf-new-from-data"><function>gdk_pixbuf_new_from_data()</function></link>.