Reference Counting and Memory Mangement

## Reference Counting and Memory Mangement Reference Counting and Memory Mangement — Functions for reference counting and memory management on pixbufs. |

## Synopsis

    #include <gdk-pixbuf/gdk-pixbuf.h>

    GdkPixbuf *         gdk_pixbuf_ref                      (GdkPixbuf *pixbuf);
    void                gdk_pixbuf_unref                    (GdkPixbuf *pixbuf);
    void                (*GdkPixbufDestroyNotify)           (guchar *pixels,
                                                             gpointer data);

## Description

GdkPixbuf 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 `g_object_ref()`. When it no longer needs the pixbuf, it should subtract a reference by calling `g_object_unref()`. The pixbuf will be destroyed when its reference count drops to zero. Newly-created GdkPixbuf structures start with a reference count of one.

### Note

As GdkPixbuf is derived from GObject now, `gdk_pixbuf_ref()` and `gdk_pixbuf_unref()` are deprecated in favour of `g_object_ref()` and `g_object_unref()` resp.

Finalizing a pixbuf means to free its pixel data and to free the GdkPixbuf structure itself. Most of the library functions that create GdkPixbuf 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 `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 GdkPixbufDestroyNotify. When a pixbuf created with `gdk_pixbuf_new_from_data()` is finalized, your destroy notification function will be called, and it is its responsibility to free the pixel array.

## Details

### gdk_pixbuf_ref ()

    GdkPixbuf *         gdk_pixbuf_ref                      (GdkPixbuf *pixbuf);

### Warning

`gdk_pixbuf_ref` has been deprecated since version 2.0 and should not be used in newly-written code. Use `g_object_ref()`.

Adds a reference to a pixbuf.

`pixbuf` : | A pixbuf.
Returns : | The same as the `pixbuf` argument.

### gdk_pixbuf_unref ()

    void                gdk_pixbuf_unref                    (GdkPixbuf *pixbuf);

### Warning

`gdk_pixbuf_unref` has been deprecated since version 2.0 and should not be used in newly-written code. Use `g_object_unref()`.

Removes a reference from a pixbuf.

`pixbuf` : | A pixbuf.

### GdkPixbufDestroyNotify ()

    void                (*GdkPixbufDestroyNotify)           (guchar *pixels,
                                                             gpointer data);

A function of this type is responsible for freeing the pixel array of a pixbuf. The `gdk_pixbuf_new_from_data()` 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 GdkPixbufDestroyNotify so that the pixel data can be freed when the pixbuf is finalized.

`pixels` : | The pixel array of the pixbuf that is being finalized. [array][element-type guint8]
`data` : | User closure data. [closure]

## See Also

GdkPixbuf, `gdk_pixbuf_new_from_data()`.