mirror of
https://gitlab.gnome.org/GNOME/gtk.git
synced 2024-10-03 20:47:32 +00:00
37ac7d593e
Your eyes are bloodshot. Your mouth starts to foam. Your hands are shaking. You know your need your fix. NEED MORE ABSTRACTION! 2000-04-12 Federico Mena Quintero <federico@helixcode.com> This comes from an excellent idea by Tim Janik (timj@gtk.org) to hook to the last unref operation. * gdk-pixbuf/gdk-pixbuf.c (gdk_pixbuf_set_last_unref_handler): New function to set the last unref handler for a pixbuf. (gdk_pixbuf_finalize): New function to actually finalize a pixbuf. It calls the pixbuf's destroy notification function and frees the GdkPixbuf structure itself. (gdk_pixbuf_unref): Use the last unref function of the pixbuf if available. * gdk-pixbuf/gdk-pixbuf-private.h (struct _GdkPixbuf): New fields for the last unref handler and its user data. * gdk-pixbuf/gdk-pixbuf-data.c (gdk_pixbuf_new_from_data): Use g_new0() to allocate the pixbuf. * gdk-pixbuf/gdk-pixbuf-loader.c (gdk_pixbuf_loader_class_init): Fixed the call to gtk_signal_new() for the "frame_done" signal; it was not specifying the `frame' argument. * gdk-pixbuf/gdk-pixbuf-animation.c (gdk_pixbuf_animation_get_width): Fixed docstring. (gdk_pixbuf_animation_get_height): Likewise. (gdk_pixbuf_animation_get_num_frames): Likewise. (gdk_pixbuf_animation_get_frames): Likewise. * doc/gdk-pixbuf-sections.txt: Updated with the new functions and types. * doc/tmpl/gdk-pixbuf.sgml: Added the description for GdkColorspace. * doc/tmpl/scaling.sgml: Added the description for GdkInterpType. * doc/tmpl/refcounting.sgml: Updated with the information about the last unref handler. * doc/tmpl/*.sgml: Markup tweaks. * gdk-pixbuf/Makefile.am (libgnomecanvaspixbuf_la_LDFLAGS): Sigh, update the libtool version number for libgnomecanvaspixbuf as well. (libpixbufloader_*_la_LDFLAGS): The loaders need to be versioned as well, or the old ones won't work with the new stuff. Also, renamed the modules as follows. * gdk-pixbuf/gdk-pixbuf-io.c (gdk_pixbuf_load_module): Now the modules are called "libpixbufloader-<format>.so" instead of "libpixbuf-<format>.so". They needed renaming so that the new loaders won't overwrite the old ones; even with the versioning stuff, the new .so symlink to the .so.1.0.0 would overwrite the old real .so file.
129 lines
4.0 KiB
Plaintext
129 lines
4.0 KiB
Plaintext
<!-- ##### SECTION Title ##### -->
|
|
Reference Counting and Memory Mangement
|
|
|
|
<!-- ##### SECTION Short_Description ##### -->
|
|
|
|
Functions to perform reference counting and memory management on a
|
|
#GdkPixbuf.
|
|
|
|
<!-- ##### SECTION Long_Description ##### -->
|
|
<para>
|
|
#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. When it no longer needs
|
|
the pixbuf, it should subtract a reference. The pixbuf will be
|
|
destroyed when its reference count drops to zero. Newly-created
|
|
#GdkPixbuf structures start with a reference count of one.
|
|
</para>
|
|
|
|
<para>
|
|
<emphasis>Finalizing</emphasis> 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.
|
|
</para>
|
|
|
|
<para>
|
|
As an extension to traditional reference counting, #GdkPixbuf
|
|
structures support defining a handler for the last unref
|
|
operation. If gdk_pixbuf_unref() is called on a #GdkPixbuf
|
|
structure that has a reference count of 1, i.e. its last
|
|
reference, then the pixbuf's last unref handler function will be
|
|
called. It is up to this function to determine whether to
|
|
finalize the pixbuf using gdk_pixbuf_finalize() or to just
|
|
continue execution. This can be used to implement a pixbuf cache
|
|
efficiently; please see the programmer's documentation for
|
|
details.
|
|
</para>
|
|
|
|
<!-- FIXME: link the last sentence above to the relevant section of
|
|
the programmer's docs.
|
|
-->
|
|
|
|
<!-- ##### SECTION See_Also ##### -->
|
|
<para>
|
|
#GdkPixbuf, gdk_pixbuf_new_from_data().
|
|
</para>
|
|
|
|
<!-- ##### USER_FUNCTION GdkPixbufDestroyNotify ##### -->
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
@pixels: The pixel array of the pixbuf that is being finalized.
|
|
@data: User closure data.
|
|
|
|
|
|
<!-- ##### USER_FUNCTION GdkPixbufLastUnref ##### -->
|
|
<para>
|
|
A function of this type can be used to override the default
|
|
operation when a pixbuf loses its last reference, i.e. when
|
|
gdk_pixbuf_unref() is called on a #GdkPixbuf structure that has a
|
|
reference count of 1. This function should determine whether to
|
|
finalize the pixbuf by calling gdk_pixbuf_finalize(), or whether
|
|
to just resume normal execution. The last unref handler for a
|
|
#GdkPixbuf can be set using the
|
|
gdk_pixbuf_set_last_unref_handler() function. By default, pixbufs
|
|
will be finalized automatically if no last unref handler has been
|
|
defined.
|
|
</para>
|
|
|
|
@pixbuf: The pixbuf that is losing its last reference.
|
|
@data: User closure data.
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_pixbuf_ref ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@pixbuf:
|
|
@Returns:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_pixbuf_unref ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@pixbuf:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_pixbuf_set_last_unref_handler ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@pixbuf:
|
|
@last_unref_fn:
|
|
@last_unref_fn_data:
|
|
|
|
|
|
<!-- ##### FUNCTION gdk_pixbuf_finalize ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@pixbuf:
|
|
|
|
<!--
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
|
|
End:
|
|
-->
|