PATH:
usr
/
share
/
gtk-doc
/
html
/
gdk-pixbuf
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <title>Reference Counting and Memory Mangement: GDK-PixBuf Reference Manual</title> <meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"> <link rel="home" href="index.html" title="GDK-PixBuf Reference Manual"> <link rel="up" href="rn01.html" title="API Reference"> <link rel="prev" href="gdk-pixbuf-The-GdkPixbuf-Structure.html" title="The GdkPixbuf Structure"> <link rel="next" href="gdk-pixbuf-File-Loading.html" title="File Loading"> <meta name="generator" content="GTK-Doc V1.27 (XML mode)"> <link rel="stylesheet" href="style.css" type="text/css"> </head> <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle"> <td width="100%" align="left" class="shortcuts"> <a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> <a href="#gdk-pixbuf-Reference-Counting-and-Memory-Mangement.description" class="shortcut">Description</a></span> </td> <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> <td><a accesskey="u" href="rn01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> <td><a accesskey="p" href="gdk-pixbuf-The-GdkPixbuf-Structure.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> <td><a accesskey="n" href="gdk-pixbuf-File-Loading.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> </tr></table> <div class="refentry"> <a name="gdk-pixbuf-Reference-Counting-and-Memory-Mangement"></a><div class="titlepage"></div> <div class="refnamediv"><table width="100%"><tr> <td valign="top"> <h2><span class="refentrytitle"><a name="gdk-pixbuf-Reference-Counting-and-Memory-Mangement.top_of_page"></a>Reference Counting and Memory Mangement</span></h2> <p>Reference Counting and Memory Mangement — Functions for reference counting and memory management on pixbufs.</p> </td> <td class="gallery_image" valign="top" align="right"></td> </tr></table></div> <div class="refsect1"> <a name="gdk-pixbuf-Reference-Counting-and-Memory-Mangement.functions"></a><h2>Functions</h2> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="functions_return"> <col class="functions_name"> </colgroup> <tbody> <tr> <td class="function_type"> <a class="link" href="gdk-pixbuf-The-GdkPixbuf-Structure.html#GdkPixbuf"><span class="returnvalue">GdkPixbuf</span></a> * </td> <td class="function_name"> <a class="link" href="gdk-pixbuf-Reference-Counting-and-Memory-Mangement.html#gdk-pixbuf-ref" title="gdk_pixbuf_ref ()">gdk_pixbuf_ref</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <span class="returnvalue">void</span> </td> <td class="function_name"> <a class="link" href="gdk-pixbuf-Reference-Counting-and-Memory-Mangement.html#gdk-pixbuf-unref" title="gdk_pixbuf_unref ()">gdk_pixbuf_unref</a> <span class="c_punctuation">()</span> </td> </tr> <tr> <td class="function_type"> <span class="returnvalue">void</span> </td> <td class="function_name"> <span class="c_punctuation">(</span><a class="link" href="gdk-pixbuf-Reference-Counting-and-Memory-Mangement.html#GdkPixbufDestroyNotify" title="GdkPixbufDestroyNotify ()">*GdkPixbufDestroyNotify</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> </td> </tr> </tbody> </table></div> </div> <div class="refsect1"> <a name="gdk-pixbuf-Reference-Counting-and-Memory-Mangement.includes"></a><h2>Includes</h2> <pre class="synopsis">#include <gdk-pixbuf/gdk-pixbuf.h> </pre> </div> <div class="refsect1"> <a name="gdk-pixbuf-Reference-Counting-and-Memory-Mangement.description"></a><h2>Description</h2> <p><a class="link" href="gdk-pixbuf-The-GdkPixbuf-Structure.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a> 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 <code class="function">g_object_ref()</code>. When it no longer needs the pixbuf, it should subtract a reference by calling <code class="function">g_object_unref()</code>. The pixbuf will be destroyed when its reference count drops to zero. Newly-created <a class="link" href="gdk-pixbuf-The-GdkPixbuf-Structure.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a> structures start with a reference count of one.</p> <div class="blockquote"><blockquote class="blockquote"><p>As <a class="link" href="gdk-pixbuf-The-GdkPixbuf-Structure.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a> is derived from <span class="type">GObject</span> now, <a class="link" href="gdk-pixbuf-Reference-Counting-and-Memory-Mangement.html#gdk-pixbuf-ref" title="gdk_pixbuf_ref ()"><code class="function">gdk_pixbuf_ref()</code></a> and <a class="link" href="gdk-pixbuf-Reference-Counting-and-Memory-Mangement.html#gdk-pixbuf-unref" title="gdk_pixbuf_unref ()"><code class="function">gdk_pixbuf_unref()</code></a> are deprecated in favour of <code class="function">g_object_ref()</code> and <code class="function">g_object_unref()</code> resp.</p></blockquote></div> <p>Finalizing a pixbuf means to free its pixel data and to free the <a class="link" href="gdk-pixbuf-The-GdkPixbuf-Structure.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a> structure itself. Most of the library functions that create <a class="link" href="gdk-pixbuf-The-GdkPixbuf-Structure.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a> structures create the pixel data by themselves and define the way it should be freed; you do not need to worry about those.</p> <p>To provide preallocated pixel data, use <a class="link" href="gdk-pixbuf-Image-Data-in-Memory.html#gdk-pixbuf-new-from-bytes" title="gdk_pixbuf_new_from_bytes ()"><code class="function">gdk_pixbuf_new_from_bytes()</code></a>. The <a class="link" href="gdk-pixbuf-Image-Data-in-Memory.html#gdk-pixbuf-new-from-data" title="gdk_pixbuf_new_from_data ()"><code class="function">gdk_pixbuf_new_from_data()</code></a> API is an older variant that predates the existence of <span class="type">GBytes</span>.</p> </div> <div class="refsect1"> <a name="gdk-pixbuf-Reference-Counting-and-Memory-Mangement.functions_details"></a><h2>Functions</h2> <div class="refsect2"> <a name="gdk-pixbuf-ref"></a><h3>gdk_pixbuf_ref ()</h3> <pre class="programlisting"><a class="link" href="gdk-pixbuf-The-GdkPixbuf-Structure.html#GdkPixbuf"><span class="returnvalue">GdkPixbuf</span></a> * gdk_pixbuf_ref (<em class="parameter"><code><a class="link" href="gdk-pixbuf-The-GdkPixbuf-Structure.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a> *pixbuf</code></em>);</pre> <div class="warning"> <p><code class="literal">gdk_pixbuf_ref</code> has been deprecated since version 2.0 and should not be used in newly-written code.</p> <p>Use <code class="function">g_object_ref()</code>.</p> </div> <p>Adds a reference to a pixbuf.</p> <p><span class="annotation">[<acronym title="Exposed in C code, not necessarily available in other languages."><span class="acronym">skip</span></acronym>]</span></p> <div class="refsect3"> <a name="gdk-pixbuf-ref.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody><tr> <td class="parameter_name"><p>pixbuf</p></td> <td class="parameter_description"><p>A pixbuf.</p></td> <td class="parameter_annotations"> </td> </tr></tbody> </table></div> </div> <div class="refsect3"> <a name="gdk-pixbuf-ref.returns"></a><h4>Returns</h4> <p> The same as the <em class="parameter"><code>pixbuf</code></em> argument.</p> </div> </div> <hr> <div class="refsect2"> <a name="gdk-pixbuf-unref"></a><h3>gdk_pixbuf_unref ()</h3> <pre class="programlisting"><span class="returnvalue">void</span> gdk_pixbuf_unref (<em class="parameter"><code><a class="link" href="gdk-pixbuf-The-GdkPixbuf-Structure.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a> *pixbuf</code></em>);</pre> <div class="warning"> <p><code class="literal">gdk_pixbuf_unref</code> has been deprecated since version 2.0 and should not be used in newly-written code.</p> <p>Use <code class="function">g_object_unref()</code>.</p> </div> <p>Removes a reference from a pixbuf.</p> <p><span class="annotation">[<acronym title="Exposed in C code, not necessarily available in other languages."><span class="acronym">skip</span></acronym>]</span></p> <div class="refsect3"> <a name="gdk-pixbuf-unref.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody><tr> <td class="parameter_name"><p>pixbuf</p></td> <td class="parameter_description"><p>A pixbuf.</p></td> <td class="parameter_annotations"> </td> </tr></tbody> </table></div> </div> </div> <hr> <div class="refsect2"> <a name="GdkPixbufDestroyNotify"></a><h3>GdkPixbufDestroyNotify ()</h3> <pre class="programlisting"><span class="returnvalue">void</span> <span class="c_punctuation">(</span>*GdkPixbufDestroyNotify<span class="c_punctuation">)</span> (<em class="parameter"><code><span class="type">guchar</span> *pixels</code></em>, <em class="parameter"><code><span class="type">gpointer</span> data</code></em>);</pre> <p>A function of this type is responsible for freeing the pixel array of a pixbuf. The <a class="link" href="gdk-pixbuf-Image-Data-in-Memory.html#gdk-pixbuf-new-from-data" title="gdk_pixbuf_new_from_data ()"><code class="function">gdk_pixbuf_new_from_data()</code></a> 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 <a class="link" href="gdk-pixbuf-Reference-Counting-and-Memory-Mangement.html#GdkPixbufDestroyNotify" title="GdkPixbufDestroyNotify ()"><span class="type">GdkPixbufDestroyNotify</span></a> so that the pixel data can be freed when the pixbuf is finalized.</p> <div class="refsect3"> <a name="GdkPixbufDestroyNotify.parameters"></a><h4>Parameters</h4> <div class="informaltable"><table class="informaltable" width="100%" border="0"> <colgroup> <col width="150px" class="parameters_name"> <col class="parameters_description"> <col width="200px" class="parameters_annotations"> </colgroup> <tbody> <tr> <td class="parameter_name"><p>pixels</p></td> <td class="parameter_description"><p>The pixel array of the pixbuf that is being finalized. </p></td> <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter points to an array of items."><span class="acronym">array</span></acronym>][<acronym title="Generics and defining elements of containers and arrays."><span class="acronym">element-type</span></acronym> guint8]</span></td> </tr> <tr> <td class="parameter_name"><p>data</p></td> <td class="parameter_description"><p>User closure data. </p></td> <td class="parameter_annotations"><span class="annotation">[<acronym title="This parameter is a 'user_data', for callbacks; many bindings can pass NULL here."><span class="acronym">closure</span></acronym>]</span></td> </tr> </tbody> </table></div> </div> </div> </div> <div class="refsect1"> <a name="gdk-pixbuf-Reference-Counting-and-Memory-Mangement.other_details"></a><h2>Types and Values</h2> </div> <div class="refsect1"> <a name="gdk-pixbuf-Reference-Counting-and-Memory-Mangement.see-also"></a><h2>See Also</h2> <p><a class="link" href="gdk-pixbuf-The-GdkPixbuf-Structure.html#GdkPixbuf"><span class="type">GdkPixbuf</span></a>, <a class="link" href="gdk-pixbuf-Image-Data-in-Memory.html#gdk-pixbuf-new-from-data" title="gdk_pixbuf_new_from_data ()"><code class="function">gdk_pixbuf_new_from_data()</code></a>.</p> </div> </div> <div class="footer"> <hr>Generated by GTK-Doc V1.27</div> </body> </html>
[-] gdk-pixbuf-Reference-Counting-and-Memory-Mangement.html
[edit]
[-] license.html
[edit]
[-] gdk-pixbuf-XlibRGB.html
[edit]
[-] gdk-pixbuf-csource.html
[edit]
[-] gdk-pixbuf-Xlib-Rendering.html
[edit]
[-] gdk-pixbuf-Module-Interface.html
[edit]
[-] gdk-pixbuf-Image-Data-in-Memory.html
[edit]
[-] up-insensitive.png
[edit]
[-] gdk-pixbuf-File-saving.html
[edit]
[-] home.png
[edit]
[+]
..
[-] annotation-glossary.html
[edit]
[-] gdk-pixbuf-X-Drawables-to-Pixbufs.html
[edit]
[-] right-insensitive.png
[edit]
[-] left-insensitive.png
[edit]
[-] gdk-pixbuf-File-Loading.html
[edit]
[-] gdk-pixbuf-gdk-pixbuf-Xlib-initialization.html
[edit]
[-] up.png
[edit]
[-] gdk-pixbuf-query-loaders.html
[edit]
[-] right.png
[edit]
[-] index.html
[edit]
[-] api-index-full.html
[edit]
[-] composite.png
[edit]
[-] rn02.html
[edit]
[-] style.css
[edit]
[-] gdk-pixbuf-Animations.html
[edit]
[-] rn01.html
[edit]
[-] gdk-pixbuf-Versioning.html
[edit]
[-] gdk-pixbuf.devhelp2
[edit]
[-] gdk-pixbuf-gdk-pixbuf-from-drawables.html
[edit]
[-] gdk-pixbuf-Utilities.html
[edit]
[-] gdk-pixbuf-The-GdkPixbuf-Structure.html
[edit]
[-] left.png
[edit]
[-] GdkPixbufLoader.html
[edit]
[-] gdk-pixbuf-gdk-pixbuf-rendering.html
[edit]
[-] gdk-pixbuf-Scaling.html
[edit]
[-] gdk-pixbuf-Inline-data.html
[edit]