
@c %start of fragment

@node Reference Counting and Memory Mangement
@chapter Reference Counting and Memory Mangement
Functions for reference counting and memory management on pixbufs.

@section Overview
@code{<gdk-pixbuf>} 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{g-object-ref}. When it no longer needs the pixbuf, it should
subtract a reference by calling @code{g-object-unref}. The pixbuf will be
destroyed when its reference count drops to zero. Newly-created
@code{<gdk-pixbuf>} structures start with a reference count of one.

As @code{<gdk-pixbuf>} is derived from @code{<gobject>} now,
@code{gdk-pixbuf-ref} and @code{gdk-pixbuf-unref} are deprecated in favour of
@code{g-object-ref} and @code{g-object-unref} resp.

@emph{Finalizing} a pixbuf means to free its pixel data and to free the
@code{<gdk-pixbuf>} structure itself. Most of the library functions that create
@code{<gdk-pixbuf>} structures create the pixel data by themselves and define
the way it should be freed; you do not need to worry about those. The only
function that lets you specify how to free the pixel data is
@code{gdk-pixbuf-new-from-data}. Since you pass it a pre-allocated pixel buffer,
you must also specify a way to free that data. This is done with a function of
type @code{<gdk-pixbuf-destroy-notify>}. When a pixbuf created with
@code{gdk-pixbuf-new-from-data} is finalized, your destroy notification function
will be called, and it is its responsibility to free the pixel array.

@section Usage
@include defuns-refcounting.xml.texi

@c %end of fragment
