Pileus Git - ~andy/gtk/blob - docs/reference/gdk-pixbuf/tmpl/refcounting.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Reference Counting and Memory Mangement
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5
   6 Functions for reference counting and memory management on pixbufs.
   7
   8 <!-- ##### SECTION Long_Description ##### -->
   9   <para>
  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.
  18   </para>
  19
  20   <note>
  21     <para>
  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.
  25     </para>
  26   </note>
  27
  28   <para>
  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.
  41   </para>
  42
  43 <!-- ##### SECTION See_Also ##### -->
  44   <para>
  45     #GdkPixbuf, gdk_pixbuf_new_from_data().
  46   </para>
  47
  48 <!-- ##### SECTION Stability_Level ##### -->
  49
  50
  51 <!-- ##### SECTION Image ##### -->
  52
  53
  54 <!-- ##### USER_FUNCTION GdkPixbufDestroyNotify ##### -->
  55   <para>
  56     A function of this type is responsible for freeing the pixel array
  57     of a pixbuf.  The gdk_pixbuf_new_from_data() function lets you
  58     pass in a pre-allocated pixel array so that a pixbuf can be
  59     created from it; in this case you will need to pass in a function
  60     of #GdkPixbufDestroyNotify so that the pixel data can be freed
  61     when the pixbuf is finalized.
  62   </para>
  63
  64 @pixels: The pixel array of the pixbuf that is being finalized.
  65 @data: User closure data.
  66
  67