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.
<appendix id="compiling">
- <title>Compiling the gdk-pixbuf library</title>
+ <title>Compiling the <application>gdk-pixbuf</application>
+ library</title>
<para>
This appendix describes the special options you can use while
- compiling the gdk-pixbuf library.
+ compiling the <application>gdk-pixbuf</application> library.
</para>
<sect1 id="building">
<title>Building the Library</title>
<para>
- The gdk-pixbuf library uses the standard GNU build system,
- using <productname>autoconf</productname> for package
- configuration and resolving portability issues,
- <productname>automake</productname> for building makefiles
+ The <application>gdk-pixbuf</application> library uses the
+ standard GNU build system, using
+ <application>autoconf</application> for package configuration
+ and resolving portability issues,
+ <application>automake</application> for building makefiles
that comply with the GNU Coding Standards, and
- <productname>libtool</productname> for building shared
+ <application>libtool</application> for building shared
libraries on multiple platforms. The normal sequence for
- compiling and installing the gdk-pixbuf library is thus:
+ compiling and installing the
+ <application>gdk-pixbuf</application> library is thus:
<literallayout>
<userinput>./configure</userinput>
</para>
<para>
- The standard options provided by <productname>GNU
- autoconf</productname> may be passed to the
+ The standard options provided by <application>GNU
+ autoconf</application> may be passed to the
<command>configure</command> script. Please see the
- <productname>autoconf</productname> documentation or run
+ <application>autoconf</application> documentation or run
<command>./configure --help</command> for information about
the standard options.
</para>
<para>
In addition to the normal options, the
- <command>configure</command> script in the gdk-pixbuf library
- supports these additional arguments:
+ <command>configure</command> script in the
+ <application>gdk-pixbuf</application> library supports these
+ additional arguments:
<cmdsynopsis>
<command>configure</command>
<systemitem>--enable-modules</systemitem></title>
<para>
- Normally gdk-pixbuf will try to build the image file format
- loaders as little shared libraries that are loaded on
- demand. The <systemitem>--disable-modules</systemitem>
- argument indicates that they should all be built statically
- into the gdk-pixbuf library instead. This is useful for
- people who need to produce statically-linked binaries. If
- neither <systemitem>--disable-modules</systemitem> nor
+ Normally <application>gdk-pixbuf</application> will try to
+ build the image file format loaders as little shared
+ libraries that are loaded on demand. The
+ <systemitem>--disable-modules</systemitem> argument
+ indicates that they should all be built statically into the
+ <application>gdk-pixbuf</application> library instead. This
+ is useful for people who need to produce statically-linked
+ binaries. If neither
+ <systemitem>--disable-modules</systemitem> nor
<systemitem>--enable-modules</systemitem> is specified, then
the <command>configure</command> script will try to
auto-detect whether shared modules work on your system.
<para>
By default the <command>configure</command> script will try
to auto-detect whether the
- <productname>gtk-doc</productname> package is installed. If
+ <application>gtk-doc</application> package is installed. If
it is, then it will use it to extract and build the
- documentation for the gdk-pixbuf library. These options can
- be used to explicitly control whether gtk-doc should be used
- or not. If it is not used, the distributed, pre-generated
- HTML files will be installed instead of building them on
- your machine.
+ documentation for the <application>gdk-pixbuf</application>
+ library. These options can be used to explicitly control
+ whether gtk-doc should be used or not. If it is not used,
+ the distributed, pre-generated HTML files will be installed
+ instead of building them on your machine.
</para>
</formalpara>
</sect1>
<RETURNS>void </RETURNS>
GdkPixbufLoader *loader
</FUNCTION>
+<ENUM>
+<NAME>GdkColorspace</NAME>
+typedef enum {
+ GDK_COLORSPACE_RGB
+} GdkColorspace;
+</ENUM>
<STRUCT>
<NAME>GdkPixbuf</NAME>
</STRUCT>
<STRUCT>
<NAME>GdkPixbufAnimation</NAME>
</STRUCT>
-<STRUCT>
-<NAME>GdkPixbuf</NAME>
-struct GdkPixbuf {
- /* Reference count */
- int ref_count;
-
- /* Libart pixbuf */
- ArtPixBuf *art_pixbuf;
-};
-</STRUCT>
-<ENUM>
-<NAME>GdkPixbufFrameAction</NAME>
-typedef enum {
- GDK_PIXBUF_FRAME_RETAIN,
- GDK_PIXBUF_FRAME_DISPOSE,
- GDK_PIXBUF_FRAME_REVERT
-} GdkPixbufFrameAction;
-</ENUM>
-<STRUCT>
-<NAME>GdkPixbufFrame</NAME>
-struct GdkPixbufFrame {
- /* The pixbuf with this frame's image data */
- GdkPixbuf *pixbuf;
-
- /* Offsets for overlaying onto the animation's area */
- int x_offset;
- int y_offset;
-
- /* Frame duration in ms */
- int delay_time;
-
- /* Overlay mode */
- GdkPixbufFrameAction action;
-};
-</STRUCT>
-<STRUCT>
-<NAME>GdkPixbufAnimation</NAME>
-struct GdkPixbufAnimation {
- /* Reference count */
- int ref_count;
-
- /* Number of frames */
- int n_frames;
-
- /* List of GdkPixbufFrame structures */
- GList *frames;
-};
-</STRUCT>
+<USER_FUNCTION>
+<NAME>GdkPixbufDestroyNotify</NAME>
+<RETURNS>void </RETURNS>
+guchar *pixels, gpointer data
+</USER_FUNCTION>
+<USER_FUNCTION>
+<NAME>GdkPixbufLastUnref</NAME>
+<RETURNS>void </RETURNS>
+GdkPixbuf *pixbuf, gpointer data
+</USER_FUNCTION>
+<FUNCTION>
+<NAME>gdk_pixbuf_ref</NAME>
+<RETURNS>GdkPixbuf *</RETURNS>
+GdkPixbuf *pixbuf
+</FUNCTION>
<FUNCTION>
-<NAME>gdk_pixbuf_get_format</NAME>
-<RETURNS>ArtPixFormat </RETURNS>
+<NAME>gdk_pixbuf_unref</NAME>
+<RETURNS>void </RETURNS>
+GdkPixbuf *pixbuf
+</FUNCTION>
+<FUNCTION>
+<NAME>gdk_pixbuf_set_last_unref_handler</NAME>
+<RETURNS>void </RETURNS>
+GdkPixbuf *pixbuf,GdkPixbufLastUnref last_unref_fn,gpointer last_unref_fn_data
+</FUNCTION>
+<FUNCTION>
+<NAME>gdk_pixbuf_finalize</NAME>
+<RETURNS>void </RETURNS>
GdkPixbuf *pixbuf
</FUNCTION>
<FUNCTION>
+<NAME>gdk_pixbuf_get_colorspace</NAME>
+<RETURNS>GdkColorspace </RETURNS>
+const GdkPixbuf *pixbuf
+</FUNCTION>
+<FUNCTION>
<NAME>gdk_pixbuf_get_n_channels</NAME>
<RETURNS>int </RETURNS>
-GdkPixbuf *pixbuf
+const GdkPixbuf *pixbuf
</FUNCTION>
<FUNCTION>
<NAME>gdk_pixbuf_get_has_alpha</NAME>
-<RETURNS>int </RETURNS>
-GdkPixbuf *pixbuf
+<RETURNS>gboolean </RETURNS>
+const GdkPixbuf *pixbuf
</FUNCTION>
<FUNCTION>
<NAME>gdk_pixbuf_get_bits_per_sample</NAME>
<RETURNS>int </RETURNS>
-GdkPixbuf *pixbuf
+const GdkPixbuf *pixbuf
</FUNCTION>
<FUNCTION>
<NAME>gdk_pixbuf_get_pixels</NAME>
-<RETURNS>guchar *</RETURNS>
-GdkPixbuf *pixbuf
+<RETURNS>guchar *</RETURNS>
+const GdkPixbuf *pixbuf
</FUNCTION>
<FUNCTION>
<NAME>gdk_pixbuf_get_width</NAME>
<RETURNS>int </RETURNS>
-GdkPixbuf *pixbuf
+const GdkPixbuf *pixbuf
</FUNCTION>
<FUNCTION>
<NAME>gdk_pixbuf_get_height</NAME>
<RETURNS>int </RETURNS>
-GdkPixbuf *pixbuf
+const GdkPixbuf *pixbuf
</FUNCTION>
<FUNCTION>
<NAME>gdk_pixbuf_get_rowstride</NAME>
<RETURNS>int </RETURNS>
-GdkPixbuf *pixbuf
+const GdkPixbuf *pixbuf
</FUNCTION>
<FUNCTION>
-<NAME>gdk_pixbuf_ref</NAME>
-<RETURNS>GdkPixbuf *</RETURNS>
-GdkPixbuf *pixbuf
-</FUNCTION>
-<FUNCTION>
-<NAME>gdk_pixbuf_unref</NAME>
-<RETURNS>void </RETURNS>
-GdkPixbuf *pixbuf
-</FUNCTION>
-<FUNCTION>
-<NAME>gdk_pixbuf_new_from_art_pixbuf</NAME>
+<NAME>gdk_pixbuf_new</NAME>
<RETURNS>GdkPixbuf *</RETURNS>
-ArtPixBuf *art_pixbuf
+GdkColorspace colorspace, gboolean has_alpha, int bits_per_sample,int width, int height
</FUNCTION>
<FUNCTION>
-<NAME>gdk_pixbuf_new</NAME>
+<NAME>gdk_pixbuf_copy</NAME>
<RETURNS>GdkPixbuf *</RETURNS>
-ArtPixFormat format, gboolean has_alpha, int bits_per_sample,int width, int height
+const GdkPixbuf *pixbuf
</FUNCTION>
<FUNCTION>
<NAME>gdk_pixbuf_new_from_file</NAME>
<FUNCTION>
<NAME>gdk_pixbuf_new_from_data</NAME>
<RETURNS>GdkPixbuf *</RETURNS>
-guchar *data,ArtPixFormat format,gboolean has_alpha,int width, int height,int rowstride,ArtDestroyNotify dfunc,gpointer dfunc_data
+const guchar *data,GdkColorspace colorspace,gboolean has_alpha,int bits_per_sample,int width, int height,int rowstride,GdkPixbufDestroyNotify destroy_fn,gpointer destroy_fn_data
</FUNCTION>
<FUNCTION>
<NAME>gdk_pixbuf_new_from_xpm_data</NAME>
<FUNCTION>
<NAME>gdk_pixbuf_add_alpha</NAME>
<RETURNS>GdkPixbuf *</RETURNS>
-GdkPixbuf *pixbuf, gboolean substitute_color,guchar r, guchar g, guchar b
+const GdkPixbuf *pixbuf, gboolean substitute_color,guchar r, guchar g, guchar b
+</FUNCTION>
+<FUNCTION>
+<NAME>gdk_pixbuf_copy_area</NAME>
+<RETURNS>void </RETURNS>
+const GdkPixbuf *src_pixbuf,int src_x, int src_y,int width, int height,GdkPixbuf *dest_pixbuf,int dest_x, int dest_y
</FUNCTION>
<ENUM>
<NAME>GdkPixbufAlphaMode</NAME>
<RETURNS>GdkPixbuf *</RETURNS>
GdkPixbuf *dest,GdkDrawable *src, GdkColormap *cmap,int src_x, int src_y,int dest_x, int dest_y,int width, int height
</FUNCTION>
-<FUNCTION>
-<NAME>gdk_pixbuf_copy_area</NAME>
-<RETURNS>void </RETURNS>
-GdkPixbuf *src_pixbuf,int src_x, int src_y,int width, int height,GdkPixbuf *dest_pixbuf,int dest_x, int dest_y
-</FUNCTION>
+<ENUM>
+<NAME>GdkInterpType</NAME>
+typedef enum {
+ GDK_INTERP_NEAREST,
+ GDK_INTERP_TILES,
+ GDK_INTERP_BILINEAR,
+ GDK_INTERP_HYPER
+} GdkInterpType;
+</ENUM>
<FUNCTION>
<NAME>gdk_pixbuf_scale</NAME>
<RETURNS>void </RETURNS>
-GdkPixbuf *src,GdkPixbuf *dest,int dest_x,int dest_y,int dest_width,int dest_height,double offset_x,double offset_y,double scale_x,double scale_y,ArtFilterLevel filter_level
+const GdkPixbuf *src,GdkPixbuf *dest,int dest_x,int dest_y,int dest_width,int dest_height,double offset_x,double offset_y,double scale_x,double scale_y,GdkInterpType interp_type
</FUNCTION>
<FUNCTION>
<NAME>gdk_pixbuf_composite</NAME>
<RETURNS>void </RETURNS>
-GdkPixbuf *src,GdkPixbuf *dest,int dest_x,int dest_y,int dest_width,int dest_height,double offset_x,double offset_y,double scale_x,double scale_y,ArtFilterLevel filter_level,int overall_alpha
+const GdkPixbuf *src,GdkPixbuf *dest,int dest_x,int dest_y,int dest_width,int dest_height,double offset_x,double offset_y,double scale_x,double scale_y,GdkInterpType interp_type,int overall_alpha
</FUNCTION>
<FUNCTION>
<NAME>gdk_pixbuf_composite_color</NAME>
<RETURNS>void </RETURNS>
-GdkPixbuf *src,GdkPixbuf *dest,int dest_x,int dest_y,int dest_width,int dest_height,double offset_x,double offset_y,double scale_x,double scale_y,ArtFilterLevel filter_level,int overall_alpha,int check_x,int check_y,int check_size,art_u32 color1,art_u32 color2
+const GdkPixbuf *src,GdkPixbuf *dest,int dest_x,int dest_y,int dest_width,int dest_height,double offset_x,double offset_y,double scale_x,double scale_y,GdkInterpType interp_type,int overall_alpha,int check_x,int check_y,int check_size,guint32 color1,guint32 color2
</FUNCTION>
<FUNCTION>
<NAME>gdk_pixbuf_scale_simple</NAME>
<RETURNS>GdkPixbuf *</RETURNS>
-GdkPixbuf *src,int dest_width,int dest_height,ArtFilterLevel filter_level
+const GdkPixbuf *src,int dest_width,int dest_height,GdkInterpType interp_type
</FUNCTION>
<FUNCTION>
<NAME>gdk_pixbuf_composite_color_simple</NAME>
<RETURNS>GdkPixbuf *</RETURNS>
-GdkPixbuf *src,int dest_width,int dest_height,ArtFilterLevel filter_level,int overall_alpha,int check_size,art_u32 color1,art_u32 color2
+const GdkPixbuf *src,int dest_width,int dest_height,GdkInterpType interp_type,int overall_alpha,int check_size,guint32 color1,guint32 color2
</FUNCTION>
+<ENUM>
+<NAME>GdkPixbufFrameAction</NAME>
+typedef enum {
+ GDK_PIXBUF_FRAME_RETAIN,
+ GDK_PIXBUF_FRAME_DISPOSE,
+ GDK_PIXBUF_FRAME_REVERT
+} GdkPixbufFrameAction;
+</ENUM>
<FUNCTION>
<NAME>gdk_pixbuf_animation_new_from_file</NAME>
<RETURNS>GdkPixbufAnimation *</RETURNS>
-const char *filename
+const char *filename
</FUNCTION>
<FUNCTION>
<NAME>gdk_pixbuf_animation_ref</NAME>
GdkPixbufAnimation *animation
</FUNCTION>
<FUNCTION>
+<NAME>gdk_pixbuf_animation_get_width</NAME>
+<RETURNS>int </RETURNS>
+GdkPixbufAnimation *animation
+</FUNCTION>
+<FUNCTION>
+<NAME>gdk_pixbuf_animation_get_height</NAME>
+<RETURNS>int </RETURNS>
+GdkPixbufAnimation *animation
+</FUNCTION>
+<FUNCTION>
+<NAME>gdk_pixbuf_animation_get_frames</NAME>
+<RETURNS>GList *</RETURNS>
+GdkPixbufAnimation *animation
+</FUNCTION>
+<FUNCTION>
+<NAME>gdk_pixbuf_animation_get_num_frames</NAME>
+<RETURNS>int </RETURNS>
+GdkPixbufAnimation *animation
+</FUNCTION>
+<FUNCTION>
+<NAME>gdk_pixbuf_frame_get_pixbuf</NAME>
+<RETURNS>GdkPixbuf *</RETURNS>
+GdkPixbufFrame *frame
+</FUNCTION>
+<FUNCTION>
+<NAME>gdk_pixbuf_frame_get_x_offset</NAME>
+<RETURNS>int </RETURNS>
+GdkPixbufFrame *frame
+</FUNCTION>
+<FUNCTION>
+<NAME>gdk_pixbuf_frame_get_y_offset</NAME>
+<RETURNS>int </RETURNS>
+GdkPixbufFrame *frame
+</FUNCTION>
+<FUNCTION>
+<NAME>gdk_pixbuf_frame_get_delay_time</NAME>
+<RETURNS>int </RETURNS>
+GdkPixbufFrame *frame
+</FUNCTION>
+<FUNCTION>
+<NAME>gdk_pixbuf_frame_get_action</NAME>
+<RETURNS>GdkPixbufFrameAction </RETURNS>
+GdkPixbufFrame *frame
+</FUNCTION>
+<FUNCTION>
<NAME>gdk_pixbuf_preinit</NAME>
<RETURNS>void </RETURNS>
gpointer app, gpointer modinfo
</MACRO>
<MACRO>
<NAME>GDK_PIXBUF_MINOR</NAME>
-#define GDK_PIXBUF_MINOR (4)
+#define GDK_PIXBUF_MINOR (7)
</MACRO>
<MACRO>
<NAME>GDK_PIXBUF_MICRO</NAME>
</MACRO>
<MACRO>
<NAME>GDK_PIXBUF_VERSION</NAME>
-#define GDK_PIXBUF_VERSION "0.4.0"
+#define GDK_PIXBUF_VERSION "0.7.0"
</MACRO>
<VARIABLE>
<NAME>gdk_pixbuf_version</NAME>
extern const char *gdk_pixbuf_version;
</VARIABLE>
+<STRUCT>
+<NAME>GdkPixbuf</NAME>
+struct GdkPixbuf {
+ /* Reference count */
+ int ref_count;
+
+ /* Color space */
+ GdkColorspace colorspace;
+
+ /* Number of channels, alpha included */
+ int n_channels;
+
+ /* Bits per channel */
+ int bits_per_sample;
+
+ /* Size */
+ int width, height;
+
+ /* Offset between rows */
+ int rowstride;
+
+ /* The pixel array */
+ guchar *pixels;
+
+ /* Destroy notification function; it is supposed to free the pixel array */
+ GdkPixbufDestroyNotify destroy_fn;
+
+ /* User data for the destroy notification function */
+ gpointer destroy_fn_data;
+
+ /* Last unref handler, determines whether the pixbuf should be finalized */
+ GdkPixbufLastUnref last_unref_fn;
+
+ /* User data for the last unref handler */
+ gpointer last_unref_fn_data;
+
+ /* Do we have an alpha channel? */
+ guint has_alpha : 1;
+};
+</STRUCT>
+<STRUCT>
+<NAME>GdkPixbufFrame</NAME>
+struct GdkPixbufFrame {
+ /* The pixbuf with this frame's image data */
+ GdkPixbuf *pixbuf;
+
+ /* Offsets for overlaying onto the animation's area */
+ int x_offset;
+ int y_offset;
+
+ /* Frame duration in ms */
+ int delay_time;
+
+ /* Overlay mode */
+ GdkPixbufFrameAction action;
+};
+</STRUCT>
+<STRUCT>
+<NAME>GdkPixbufAnimation</NAME>
+struct GdkPixbufAnimation {
+ /* Reference count */
+ int ref_count;
+
+ /* Number of frames */
+ int n_frames;
+
+ /* List of GdkPixbufFrame structures */
+ GList *frames;
+
+ /* bounding box size */
+ int width, height;
+};
+</STRUCT>
<SECTION>
<FILE>gdk-pixbuf</FILE>
+GdkColorspace
GdkPixbuf
-gdk_pixbuf_get_format
+gdk_pixbuf_get_colorspace
gdk_pixbuf_get_n_channels
gdk_pixbuf_get_has_alpha
gdk_pixbuf_get_bits_per_sample
<SECTION>
<FILE>refcounting</FILE>
+GdkPixbufDestroyNotify
+GdkPixbufLastUnref
gdk_pixbuf_ref
gdk_pixbuf_unref
+gdk_pixbuf_set_last_unref_handler
+gdk_pixbuf_finalize
</SECTION>
<SECTION>
<SECTION>
<FILE>creating</FILE>
-gdk_pixbuf_new_from_art_pixbuf
gdk_pixbuf_new
gdk_pixbuf_new_from_data
gdk_pixbuf_new_from_xpm_data
+gdk_pixbuf_copy
</SECTION>
<SECTION>
gdk_pixbuf_animation_new_from_file
gdk_pixbuf_animation_ref
gdk_pixbuf_animation_unref
+gdk_pixbuf_animation_get_frames
+gdk_pixbuf_animation_get_width
+gdk_pixbuf_animation_get_num_frames
+gdk_pixbuf_animation_get_height
+gdk_pixbuf_frame_get_pixbuf
+gdk_pixbuf_frame_get_action
+gdk_pixbuf_frame_get_y_offset
+gdk_pixbuf_frame_get_delay_time
+gdk_pixbuf_frame_get_x_offset
</SECTION>
<SECTION>
<FILE>scaling</FILE>
+GdkInterpType
gdk_pixbuf_scale
gdk_pixbuf_composite
gdk_pixbuf_composite_color
<book>
<bookinfo>
- <title>The GdkPixbuf Library</title>
+ <title>The <application>gdk-pixbuf</application> Library</title>
<authorgroup>
<author>
<partintro>
<para>
This part presents the class and function reference for the
- GdkPixbuf library. Classes are described together with their
- methods; individual functions are grouped by functional group.
+ <application>gdk-pixbuf</application> library. Classes are
+ described together with their methods; individual functions
+ are grouped by functional group.
</para>
</partintro>
<NAME>GdkPixbufLoader::frame-done</NAME>
<RETURNS>void</RETURNS>
GdkPixbufLoader *gdkpixbufloader
+gpointer arg1
</SIGNAL>
<SIGNAL>
<!-- ##### SECTION Long_Description ##### -->
<para>
- The GdkPixbuf library provides a simple mechanism to load and
- represent animations, primarily animated GIF files. Animations
- are represented as lists of #GdkPixbufFrame structures. Each
- frame structure contains a #GdkPixbuf structure and information
- about the frame's overlay mode and duration.
+ The <application>gdk-pixbuf</application> library provides a
+ simple mechanism to load and represent animations, primarily
+ animated GIF files. Animations are represented as lists of
+ #GdkPixbufFrame structures. Each frame structure contains a
+ #GdkPixbuf structure and information about the frame's overlay
+ mode and duration.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### ENUM GdkPixbufFrameAction ##### -->
<para>
Each animation frame can have several things happen to it when the
- next frame is displayed. The #GdkPixbufFrameAction determines this.
- If a frame as marked as #GDK_PIXBUF_FRAME_RETAIN, then the image
- will remain displayed, and will be potentially occluded by the next
- frame. If it is marked as #GDK_PIXBUF_FRAME_DISPOSE, then the
- animation is reverted to the setting before the frame was shown. If
- it is marked as #GDK_PIXBUF_FRAME_REVERT, then the animation is
- reverted to the first image before continuing.
+ next frame is displayed. The #GdkPixbufFrameAction determines
+ this. These are essentially the overlay modes supported by GIF
+ animations.
</para>
-@GDK_PIXBUF_FRAME_RETAIN:
-@GDK_PIXBUF_FRAME_DISPOSE:
-@GDK_PIXBUF_FRAME_REVERT:
+@GDK_PIXBUF_FRAME_RETAIN: The previous image should remain displayed,
+and will potentially be occluded by the new frame.
+
+@GDK_PIXBUF_FRAME_DISPOSE: The animation will be reverted to the state
+before the frame was shown.
+
+@GDK_PIXBUF_FRAME_REVERT: The animation will be reverted to the first
+frame.
<!-- ##### STRUCT GdkPixbufFrame ##### -->
<para>
action.
</para>
-@pixbuf: The frame's image contents.
-@x_offset: X offset of the frame inside the animation's bounding box.
-@y_offset: Y offset of the frame inside the animation's bounding box.
-@delay_time: Duration of the frame in milliseconds.
-@action: Overlay mode.
-
<!-- ##### STRUCT GdkPixbufAnimation ##### -->
<para>
This structure describes an animation, which is represented as a
list of #GdkPixbufFrame structures.
</para>
-@ref_count: Reference count.
-@n_frames: Number of frames in the animation.
-@frames: List of #GdkPixbufFrame structures.
-
<!-- ##### FUNCTION gdk_pixbuf_animation_new_from_file ##### -->
<para>
</para>
-@animation: <!--
+@animation:
+
+
+<!-- ##### FUNCTION gdk_pixbuf_animation_get_frames ##### -->
+<para>
+
+</para>
+
+@animation:
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_pixbuf_animation_get_width ##### -->
+<para>
+
+</para>
+
+@animation:
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_pixbuf_animation_get_num_frames ##### -->
+<para>
+
+</para>
+
+@animation:
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_pixbuf_animation_get_height ##### -->
+<para>
+
+</para>
+
+@animation:
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_pixbuf_frame_get_pixbuf ##### -->
+<para>
+
+</para>
+
+@frame:
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_pixbuf_frame_get_action ##### -->
+<para>
+
+</para>
+
+@frame:
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_pixbuf_frame_get_y_offset ##### -->
+<para>
+
+</para>
+
+@frame:
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_pixbuf_frame_get_delay_time ##### -->
+<para>
+
+</para>
+
+@frame:
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_pixbuf_frame_get_x_offset ##### -->
+<para>
+
+</para>
+
+@frame:
+@Returns:
+
+<!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
-
-
<!-- ##### SECTION Long_Description ##### -->
<para>
- The most basic way to create a pixbuf is to wrap an existing
- #ArtPixBuf structure with a #GdkPixbuf to add reference counting
- capabilities to it. The gdk_pixbuf_new_from_art_pixbuf() performs
- this operation.
- </para>
-
- <para>
- As a convenience, you can use the gdk_pixbuf_new_from_data()
- function to wrap an existing data buffer with a #GdkPixbuf. You
- need to specify the destroy notification function that will be
- called when the data buffer needs to be freed; this will happen
- when the pixbuf's reference count drops to zero and thus the
- #ArtPixBuf needs to be destroyed. If you have a chunk of static
- data compiled into your application, you can pass in #NULL as the
- destroy notification function so that the data will not be freed.
+ The most basic way to create a pixbuf is to wrap an existing pixel
+ buffer with a #GdkPixbuf structure. You can use the
+ gdk_pixbuf_new_from_data() function to do this You need to specify
+ the destroy notification function that will be called when the
+ data buffer needs to be freed; this will happen when a #GdkPixbuf
+ is finalized by the reference counting functions If you have a
+ chunk of static data compiled into your application, you can pass
+ in #NULL as the destroy notification function so that the data
+ will not be freed.
</para>
<para>
function to create a pixbuf from inline XPM image data.
</para>
-<!-- ##### SECTION See_Also ##### -->
<para>
- #ArtPixBuf
+ You can also copy an existing pixbuf with the gdk_pixbuf_copy()
+ function. This is not the same as just doing a gdk_pixbuf_ref()
+ on the old pixbuf; the copy function will actually duplicate the
+ pixel data in memory and create a new #GdkPixbuf structure for it.
</para>
-<!-- ##### FUNCTION gdk_pixbuf_new_from_art_pixbuf ##### -->
-<para>
-
-</para>
-
-@art_pixbuf:
-@Returns:
-
+<!-- ##### SECTION See_Also ##### -->
+ <para>
+ gdk_pixbuf_finalize().
+ </para>
<!-- ##### FUNCTION gdk_pixbuf_new ##### -->
<para>
</para>
-@format:
+@colorspace:
@has_alpha:
@bits_per_sample:
@width:
</para>
@data:
-@format:
+@colorspace:
@has_alpha:
+@bits_per_sample:
@width:
@height:
@rowstride:
-@dfunc:
-@dfunc_data:
+@destroy_fn:
+@destroy_fn_data:
@Returns:
</para>
@data:
-@Returns: <!--
+@Returns:
+
+
+<!-- ##### FUNCTION gdk_pixbuf_copy ##### -->
+<para>
+
+</para>
+
+@pixbuf:
+@Returns:
+
+<!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
<!-- ##### SECTION Long_Description ##### -->
<para>
- The GdkPixbuf library provides a simple mechanism for loading an
- image from a file in synchronous fashion. This means that the
- library takes control of the application while the file is being
- loaded; from the user's point of view, the application will block
- until the image is done loading.
+ The <application>gdk-pixbuf</application> library provides a
+ simple mechanism for loading an image from a file in synchronous
+ fashion. This means that the library takes control of the
+ application while the file is being loaded; from the user's point
+ of view, the application will block until the image is done
+ loading.
</para>
<para>
<!-- ##### SECTION See_Also ##### -->
<para>
- #GdkPixbufLoader
+ #GdkPixbufLoader.
</para>
<!-- ##### FUNCTION gdk_pixbuf_new_from_file ##### -->
</para>
@filename:
-@Returns: <!--
+@Returns:
+<!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
<!-- ##### SECTION See_Also ##### -->
<para>
- #GdkPixbuf, gdk_image_get()
+ gdk_image_get().
</para>
<!-- ##### FUNCTION gdk_pixbuf_get_from_drawable ##### -->
@dest_y:
@width:
@height:
-@Returns: <!--
+@Returns:
+<!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
<para>
#GdkPixbufLoader provides a way for applications to drive the
process of loading an image, by letting them send the image data
- directly. Applications can use this functionality instead of
+ directly to the loader instead of having the loader read the data
+ from a file. Applications can use this functionality instead of
gdk_pixbuf_new_from_file() when they need to parse image data in
- small chunks. For example, it should be used when reading an image
- from a (potentially) slow network connection, or when loading an
- extremely large file.
+ small chunks. For example, it should be used when reading an
+ image from a (potentially) slow network connection, or when
+ loading an extremely large file.
</para>
+
<para>
- To use #GdkPixbufLoader to load an image, just create a new one, and
- call gdk_pixbuf_loader_write() to send the data to it. When done,
- gdk_pixbuf_loader_close() should be called to end the stream and
- finalize everything. The loader will emit two important signals
- throughout the process. The first, #"area_prepared", will be called
- as soon as the image has enough information to determine the size of
- the image to be used. It will pass a @GdkPixbuf in. If you want to
- use it, you can simply ref it. In addition, no actual information
- will be passed in yet, so the pixbuf can be safely filled with any
- temporary graphics (or an initial color) as needed. You can also
- call the gdk_pixbuf_loader_get_pixbuf() once this signal has been
- emitted and get the same pixbuf.
+ To use #GdkPixbufLoader to load an image, just create a new one,
+ and call gdk_pixbuf_loader_write() to send the data to it. When
+ done, gdk_pixbuf_loader_close() should be called to end the stream
+ and finalize everything. The loader will emit two important
+ signals throughout the process. The first, "<link
+ linkend="GdkPixbufLoader-area-prepared">area_prepared</link>",
+ will be called as soon as the image has enough information to
+ determine the size of the image to be used. It will pass a
+ @GdkPixbuf in. If you want to use it, you can simply ref it. In
+ addition, no actual information will be passed in yet, so the
+ pixbuf can be safely filled with any temporary graphics (or an
+ initial color) as needed. You can also call the
+ gdk_pixbuf_loader_get_pixbuf() once this signal has been emitted
+ and get the same pixbuf.
</para>
+
<para>
- The other signal, #"area_updated" gets called every
- time a region is updated. This way you can update a partially
- completed image. Note that you do not know anything about the
- completeness of an image from the area updated. For example, in an
- interlaced image, you need to make several passes before the image
- is done loading.
+ The other signal, "<link
+ linkend="GdkPixbufLoader-area-updated">area_updated</link>" gets
+ called every time a region is updated. This way you can update a
+ partially completed image. Note that you do not know anything
+ about the completeness of an image from the area updated. For
+ example, in an interlaced image, you need to make several passes
+ before the image is done loading.
</para>
+
<refsect2>
- <title>Loading an animation</title>
+ <title>Loading an animation</title>
+
<para>
Loading an animation is a little more complex then loading an
- image. In addition to the above signals, there is also a
- #"frame_done" signal, as well as an #"animation_done" signal. The
- first lets the application know that it is dealing with an
- animation, instead of a static image. It also passes a
- #GdkPixbufFrame in the signal. As before, if you want to keep the
- frame, you need to ref it. Once the first #"frame_done" signal
+ image. In addition to the above signals, there is also a "<link
+ linkend="GdkPixbufLoader-frame-done">frame_done</link>" signal,
+ as well as an "<link
+ linkend="GdkPixbufLoader-animation-done">animation_done</link>"
+ signal. The first lets the application know that it is dealing
+ with an animation, instead of a static image. It also passes a
+ #GdkPixbufFrame in the signal. As before, if you want to keep
+ the frame, you need to ref it. Once the first "<link
+ linkend="GdkPixbufLoader-frame-done">frame_done</link>" signal
has been emitted, you can call gdk_pixbuf_loader_get_animation()
- to get the #GdkPixbufAnimation struct. Each subsequent frame goes
- through a similar lifecycle. For example #"area_prepared" is
- re-emitted. Then #"area_updated" is emitted as many times as
- necessary. Finally, #"animation_done" is emitted as soon as all
- frames are done.
- </para>
+ to get the #GdkPixbufAnimation struct. Each subsequent frame
+ goes through a similar lifecycle. For example "<link
+ linkend="GdkPixbufLoader-area-prepared">area_prepared</link>" is
+ re-emitted. Then "<link
+ linkend="GdkPixbufLoader-area-updated">area_updated</link>" is
+ emitted as many times as necessary. Finally, "<link
+ linkend="GdkPixbufLoader-animation-done">animation_done</link>"
+ is emitted as soon as all frames are done.
+ </para>
</refsect2>
<!-- ##### SECTION See_Also ##### -->
areas of an image that is being loaded.
</para>
-@gdkpixbufloader: the object which received the signal.
-@arg1:
-@arg2:
-@arg3:
-@arg4:
-<!-- # Unused Parameters # -->
@loader: Loader which emitted the signal.
@x: X offset of upper-left corner of the updated area.
@y: Y offset of upper-left corner of the updated area.
fetch the partially-loaded pixbuf.
</para>
-@gdkpixbufloader: the object which received the signal.
-<!-- # Unused Parameters # -->
@loader: Loader which emitted the signal.
<!-- ##### SIGNAL GdkPixbufLoader::frame-done ##### -->
-<para>
-
-</para>
+ <para>
+ This signal is emitted when a frame is done loading. It will be
+ emitted for each frame in an animation data stream.
+ </para>
-@gdkpixbufloader: the object which received the signal.
+@loader: Loader which emitted the signal.
+@frame: Frame which just completed loading.
<!-- ##### SIGNAL GdkPixbufLoader::animation-done ##### -->
-<para>
-
-</para>
+ This signal is emitted when an animation is done loading.
+ </para>
-@gdkpixbufloader: the object which received the signal.
+@loader: Loader which emitted the signal.
<!-- ##### SIGNAL GdkPixbufLoader::closed ##### -->
<para>
drives it.
</para>
-@gdkpixbufloader: the object which received the signal.
-<!-- # Unused Parameters # -->
@loader: Loader which emitted the signal.
<!--
-<!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:See_Also ##### -->
-<para>
-
-</para>
-
-
<!-- ##### FUNCTION gdk_pixbuf_load_module ##### -->
<para>
-<!-- ##### ARG GnomeCanvasPixbuf:height_pixels ##### -->
-<para>
-
-</para>
-
-
<!-- ##### STRUCT GdkPixbufModule ##### -->
<para>
@stop_load:
@load_increment:
+<!-- ##### ARG GnomeCanvasPixbuf:x_set ##### -->
+ <para>
+ Determines whether the <link
+ linkend="GnomeCanvasPixbuf--x">x</link> argument is used to
+ translate the pixbuf from its logical origin in item-relative
+ coordinates.
+ </para>
+
+
+<!-- ##### USER_FUNCTION ModulePreparedNotifyFunc ##### -->
+<para>
+
+</para>
+
+@pixbuf:
+@user_data:
+
+<!-- ##### FUNCTION gdk_pixbuf_get_module ##### -->
+<para>
+
+</para>
+
+@buffer:
+@size:
+@Returns:
+
+<!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### FUNCTION gdk_pixbuf_new_from_art_pixbuf ##### -->
+<para>
+
+</para>
+
+@art_pixbuf:
+@Returns:
+
+<!-- ##### ARG GnomeCanvasPixbuf:height_pixels ##### -->
+<para>
+
+</para>
+
+
<!-- ##### ARG GnomeCanvasPixbuf:y_pixels ##### -->
<para>
gdk-pixbuf-io
-<!-- ##### ARG GnomeCanvasPixbuf:x_set ##### -->
- <para>
- Determines whether the <link
- linkend="GnomeCanvasPixbuf--x">x</link> argument is used to
- translate the pixbuf from its logical origin in item-relative
- coordinates.
- </para>
-
-
<!-- ##### ARG GnomeCanvasPixbuf:y_set ##### -->
<para>
Determines whether the <link
</para>
-<!-- ##### USER_FUNCTION ModulePreparedNotifyFunc ##### -->
-<para>
-
-</para>
-
-@pixbuf:
-@user_data:
-
<!-- ##### ARG GnomeCanvasPixbuf:x_pixels ##### -->
<para>
</para>
-<!-- ##### FUNCTION gdk_pixbuf_get_module ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_get_format ##### -->
<para>
</para>
-@buffer:
-@size:
+@pixbuf:
@Returns:
<!-- ##### ARG GnomeCanvasPixbuf:width_pixels ##### -->
<para>
The <structname>GdkPixbuf</structname> structure contains
- information that describes an image in memory. It is actually a
- simple wrapper that adds reference counting capabilities to an
- #ArtPixBuf structure.
+ information that describes an image in memory.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
- #ArtPixBuf
</para>
-<!-- ##### STRUCT GdkPixbuf ##### -->
+<!-- ##### ENUM GdkColorspace ##### -->
<para>
- This is the main structure in the GdkPixbuf library. This
- structure adds reference counting capabilities to an #ArtPixBuf
- structure.
+ This enumeration defines the color spaces that are supported by
+ the <application>gdk-pixbuf</application> library. Currently only
+ RGB is supported.
</para>
-@ref_count: Reference count.
-@art_pixbuf: An #ArtPixBuf that actually contains the description of
-the image data.
+@GDK_COLORSPACE_RGB: Indicates a red/green/blue additive color space.
+
+<!-- ##### STRUCT GdkPixbuf ##### -->
+ <para>
+ This is the main structure in the
+ <application>gdk-pixbuf</application> library. It is used to
+ represent images. It contains information about the image's pixel
+ data, its color space, bits per sample, width and height, and the
+ rowstride or number of bytes between rows.
+ </para>
-<!-- ##### FUNCTION gdk_pixbuf_get_format ##### -->
+<!-- ##### FUNCTION gdk_pixbuf_get_colorspace ##### -->
<para>
</para>
</para>
@pixbuf:
-@Returns: <!--
+@Returns:
+
+<!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
-
-
Determines whether the <link
linkend="GnomeCanvasPixbuf--width">width</link> argument is taken
into account when scaling the pixbuf item. If this argument is
- %FALSE, then the width value of the pixbuf's #ArtPixBuf will be
- used instead. This argument is %FALSE by default.
+ %FALSE, then the width value of the pixbuf will be used instead.
+ This argument is %FALSE by default.
</para>
<!-- ##### ARG GnomeCanvasPixbuf:width_in_pixels ##### -->
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
-
<!-- ##### SECTION Title ##### -->
-Reference Counting
+Reference Counting and Memory Mangement
<!-- ##### SECTION Short_Description ##### -->
-Functions to perform reference counting on a #GdkPixbuf.
+
+Functions to perform reference counting and memory management on a
+#GdkPixbuf.
<!-- ##### SECTION Long_Description ##### -->
<para>
#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, #ArtPixBuf
+ #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: <!--
+@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:
-->
-
-
<!-- ##### SECTION Long_Description ##### -->
<para>
- The GdkPixbuf library provides several convenience functions to
- render pixbufs to GDK drawables. It uses the GdkRGB to render the
- image data.
+ The <application>gdk-pixbuf</application> library provides several
+ convenience functions to render pixbufs to GDK drawables. It uses
+ the GdkRGB to render the image data.
</para>
<para>
At this point there is not a standard alpha channel extension for
the X Window System, so it is not possible to use full opacity
information when painting images to arbitrary drawables. The
- GdkPixbuf convenience functions will threshold the opacity
- information to create a bi-level clipping mask (black and white),
- and use that to draw the image onto a drawable.
+ <application>gdk-pixbuf</application> convenience functions will
+ threshold the opacity information to create a bi-level clipping
+ mask (black and white), and use that to draw the image onto a
+ drawable.
</para>
<important>
@dest_y:
@width:
@height:
-@alpha_threshold: <!--
-Local variables:
-mode: sgml
-sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
-End:
--->
-
+@alpha_threshold:
<!-- ##### FUNCTION gdk_pixbuf_render_pixmap_and_mask ##### -->
<para>
@alpha_threshold:
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
Scaling pixbufs and scaling and compositing pixbufs
<!-- ##### SECTION Long_Description ##### -->
-<para>
-gdk-pixbuf contains functions to scale pixbufs, to scale pixbufs and
-composite against an existing image, and to scale pixbufs and
-composite against a solid color or checkerboard. (Compositing a
-checkerboard is a common way to show an image with an alpha-channel in
-image-viewing and editing software.)
-</para>
-<para>
-Since the full-featured functions (gdk_pixbuf_scale(),
-gdk_pixbuf_composite(), and gdk_pixbuf_composite_color()) are
-rather complex to use and have many arguments, two simple
-convenience functions are provided, gdk_pixbuf_scale_simple()
-and gdk_pixbuf_composite_color_simple() which create a
-new pixbuf of a given size, scale an original image to fit,
-and then return the new pixmap.
-</para>
-
-<para>
-The following example demonstrates handling an expose event by
-rendering the appropriate area of a source image (which is scaled to
-fit the widget) onto the widget's window. The source image is
-rendered against a checkerboard, which provides a visual
-representation of the alpha channel if the image has one. If the image
-doesn't have an alpha channel, calling gdk_pixbuf_composite_color()
-function has exactly the same effect as calling gdk_pixbuf_scale().
-</para>
-
-<programlisting>
+ <para>
+ The <application>gdk-pixbuf</application> contains functions to
+ scale pixbufs, to scale pixbufs and composite against an existing
+ image, and to scale pixbufs and composite against a solid color or
+ checkerboard. Compositing a checkerboard is a common way to show
+ an image with an alpha channel in image-viewing and editing
+ software.
+ </para>
+
+ <para>
+ Since the full-featured functions (gdk_pixbuf_scale(),
+ gdk_pixbuf_composite(), and gdk_pixbuf_composite_color()) are
+ rather complex to use and have many arguments, two simple
+ convenience functions are provided, gdk_pixbuf_scale_simple() and
+ gdk_pixbuf_composite_color_simple() which create a new pixbuf of a
+ given size, scale an original image to fit, and then return the
+ new pixmap.
+ </para>
+
+ <para>
+ The following example demonstrates handling an expose event by
+ rendering the appropriate area of a source image (which is scaled
+ to fit the widget) onto the widget's window. The source image is
+ rendered against a checkerboard, which provides a visual
+ representation of the alpha channel if the image has one. If the
+ image doesn't have an alpha channel, calling
+ gdk_pixbuf_composite_color() function has exactly the same effect
+ as calling gdk_pixbuf_scale().
+ </para>
+
+ <programlisting>
gboolean
expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data)
{
gdk_window_set_back_pixmap (widget->window, NULL, FALSE);
- dest = gdk_pixbuf_new (ART_PIX_RGB, FALSE, 8, event->area.width, event->area.height);
+ dest = gdk_pixbuf_new (GDK_COLORSPACE_RGB, FALSE, 8, event->area.width, event->area.height);
gdk_pixbuf_composite_color (pixbuf, dest,
0, 0, event->area.width, event->area.height,
-event->area.x, -event->area.y,
- (double) widget->allocation.width / pixbuf->art_pixbuf->width,
- (double) widget->allocation.height / pixbuf->art_pixbuf->height,
- filter_level, 255,
- event->area.x, event->area.y, 16, 0xaaaaaa, 0x555555);
+ (double) widget->allocation.width / gdk_pixbuf_get_width (pixbuf),
+ (double) widget->allocation.height / gdk_pixbuf_get_height (pixbuf),
+ GDK_INTERP_BILINEAR, 255,
+ event->area.x, event->area.y, 16, 0xaaaaaa, 0x555555);
gdk_pixbuf_render_to_drawable (dest, widget->window, widget->style->fg_gc[GTK_STATE_NORMAL],
0, 0, event->area.x, event->area.y,
return TRUE;
}
-</programlisting>
+ </programlisting>
<!-- ##### SECTION See_Also ##### -->
-<para>
-
-</para>
+ <para>
+ GdkRGB
+ </para>
+
+<!-- ##### ENUM GdkInterpType ##### -->
+ <para>
+ This enumeration describes the different interpolation modes that
+ can be used with the scaling functions.
+
+ <note>
+ <para>
+ Cubic filtering is missing from the list; hyperbolic
+ interpolation is just as fast and results in higher quality.
+ </para>
+ </note>
+ </para>
+
+@GDK_INTERP_NEAREST: Nearest neighbor sampling; this is the fastest
+and lowest quality mode.
+
+@GDK_INTERP_TILES: This is an accurate simulation of the PostScript
+image operator without any interpolation enabled. Each pixel is
+rendered as a tiny parallelogram of solid color, the edges of which
+are implemented with antialiasing. It resembles nearest neighbor for
+enlargement, and bilinear for reduction.
+
+@GDK_INTERP_BILINEAR: Bilinear interpolation. For enlargement, it is
+equivalent to point-sampling the ideal bilinear-interpolated image.
+For reduction, it is equivalent to laying down small tiles and
+integrating over the coverage area.
+
+@GDK_INTERP_HYPER: This is the slowest and highest quality
+reconstruction function. It is derived from the hyperbolic filters in
+Wolberg's "Digital Image Warping", and is formally defined as the
+hyperbolic-filter sampling the ideal hyperbolic-filter interpolated
+image (the filter is designed to be idempotent for 1:1 pixel mapping).
<!-- ##### FUNCTION gdk_pixbuf_scale ##### -->
<para>
@offset_y:
@scale_x:
@scale_y:
-@filter_level:
+@interp_type:
<!-- ##### FUNCTION gdk_pixbuf_composite ##### -->
@offset_y:
@scale_x:
@scale_y:
-@filter_level:
+@interp_type:
@overall_alpha:
@offset_y:
@scale_x:
@scale_y:
-@filter_level:
+@interp_type:
@overall_alpha:
@check_x:
@check_y:
@src:
@dest_width:
@dest_height:
-@filter_level:
+@interp_type:
@Returns:
@src:
@dest_width:
@dest_height:
-@filter_level:
+@interp_type:
@overall_alpha:
@check_size:
@color1:
@color2:
-@Returns: <!--
+@Returns:
+
+
+<!--
Local variables:
mode: sgml
sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
End:
-->
-
-
@r:
@g:
@b:
-@Returns: <!--
-Local variables:
-mode: sgml
-sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
-End:
--->
-
+@Returns:
<!-- ##### FUNCTION gdk_pixbuf_copy_area ##### -->
<para>
@dest_y:
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
+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.
+
2000-04-12 Paolo Molaro <lupus@debian.org>
* .cvsignore, src/.cvsignore: shut up cvs.
libgdk_pixbuf.la \
$(CANVAS_PIXBUF_LIB)
-libgnomecanvaspixbuf_la_LDFLAGS = $(EXTRA_GNOME_LIBS)
+libgnomecanvaspixbuf_la_LDFLAGS = -version-info 1:0:0 $(EXTRA_GNOME_LIBS)
libexecdir = $(libdir)/gdk-pixbuf/loaders
#
# The PNG plugin.
#
-libpixbuf_png_la_SOURCES = io-png.c
-libpixbuf_png_la_LDFLAGS = -avoid-version -module
-libpixbuf_png_la_LIBADD = $(LIBPNG)
+libpixbufloader_png_la_SOURCES = io-png.c
+libpixbufloader_png_la_LDFLAGS = -version-info 1:0:0 -module
+libpixbufloader_png_la_LIBADD = $(LIBPNG)
#
# The JPEG loader
#
-libpixbuf_jpeg_la_SOURCES = io-jpeg.c
-libpixbuf_jpeg_la_LDFLAGS = -avoid-version -module
-libpixbuf_jpeg_la_LIBADD = $(LIBJPEG)
+libpixbufloader_jpeg_la_SOURCES = io-jpeg.c
+libpixbufloader_jpeg_la_LDFLAGS = -version-info 1:0:0 -module
+libpixbufloader_jpeg_la_LIBADD = $(LIBJPEG)
#
# The XPM loader
#
-libpixbuf_xpm_la_SOURCES = io-xpm.c
-libpixbuf_xpm_la_LDFLAGS = -avoid-version -module
-libpixbuf_xpm_la_LIBADD =
+libpixbufloader_xpm_la_SOURCES = io-xpm.c
+libpixbufloader_xpm_la_LDFLAGS = -version-info 1:0:0 -module
+libpixbufloader_xpm_la_LIBADD =
#
# The GIF loader
#
-libpixbuf_gif_la_SOURCES = io-gif.c
-libpixbuf_gif_la_LDFLAGS = -avoid-version -module
-libpixbuf_gif_la_LIBADD =
+libpixbufloader_gif_la_SOURCES = io-gif.c
+libpixbufloader_gif_la_LDFLAGS = -version-info 1:0:0 -module
+libpixbufloader_gif_la_LIBADD =
#
# The ICO loader
#
-libpixbuf_ico_la_SOURCES = io-ico.c
-libpixbuf_ico_la_LDFLAGS = -avoid-version -module
-libpixbuf_ico_la_LIBADD =
+libpixbufloader_ico_la_SOURCES = io-ico.c
+libpixbufloader_ico_la_LDFLAGS = -version-info 1:0:0 -module
+libpixbufloader_ico_la_LIBADD =
#
# The RAS loader
#
-libpixbuf_ras_la_SOURCES = io-ras.c
-libpixbuf_ras_la_LDFLAGS = -avoid-version -module
-libpixbuf_ras_la_LIBADD =
+libpixbufloader_ras_la_SOURCES = io-ras.c
+libpixbufloader_ras_la_LDFLAGS = -version-info 1:0:0 -module
+libpixbufloader_ras_la_LIBADD =
#
# The TIFF loader
#
-libpixbuf_tiff_la_SOURCES = io-tiff.c
-libpixbuf_tiff_la_LDFLAGS = -avoid-version -module
-libpixbuf_tiff_la_LIBADD = $(LIBTIFF)
+libpixbufloader_tiff_la_SOURCES = io-tiff.c
+libpixbufloader_tiff_la_LDFLAGS = -version-info 1:0:0 -module
+libpixbufloader_tiff_la_LIBADD = $(LIBTIFF)
#
# The PNM loader
#
-libpixbuf_pnm_la_SOURCES = io-pnm.c
-libpixbuf_pnm_la_LDFLAGS = -avoid-version -module
-libpixbuf_pnm_la_LIBADD =
+libpixbufloader_pnm_la_SOURCES = io-pnm.c
+libpixbufloader_pnm_la_LDFLAGS = -version-info 1:0:0 -module
+libpixbufloader_pnm_la_LIBADD =
#
# The BMP loader
#
-libpixbuf_bmp_la_SOURCES = io-bmp.c
-libpixbuf_bmp_la_LDFLAGS = -avoid-version -module
-libpixbuf_bmp_la_LIBADD =
+libpixbufloader_bmp_la_SOURCES = io-bmp.c
+libpixbufloader_bmp_la_LDFLAGS = -version-info 1:0:0 -module
+libpixbufloader_bmp_la_LIBADD =
if HAVE_PNG
-PNG_LIB = libpixbuf-png.la
+PNG_LIB = libpixbufloader-png.la
endif
if HAVE_JPEG
-JPEG_LIB = libpixbuf-jpeg.la
+JPEG_LIB = libpixbufloader-jpeg.la
endif
-GIF_LIB = libpixbuf-gif.la
+GIF_LIB = libpixbufloader-gif.la
-ICO_LIB = libpixbuf-ico.la
+ICO_LIB = libpixbufloader-ico.la
-RAS_LIB = libpixbuf-ras.la
+RAS_LIB = libpixbufloader-ras.la
if HAVE_TIFF
-TIFF_LIB = libpixbuf-tiff.la
+TIFF_LIB = libpixbufloader-tiff.la
endif
-XPM_LIB = libpixbuf-xpm.la
+XPM_LIB = libpixbufloader-xpm.la
-PNM_LIB = libpixbuf-pnm.la
+PNM_LIB = libpixbufloader-pnm.la
-BMP_LIB = libpixbuf-bmp.la
+BMP_LIB = libpixbufloader-bmp.la
if BUILD_DYNAMIC_MODULES
else
libexec_LTLIBRARIES =
-extra_sources = $(libpixbuf_png_la_SOURCES) \
- $(libpixbuf_jpeg_la_SOURCES) \
- $(libpixbuf_xpm_la_SOURCES) \
- $(libpixbuf_gif_la_SOURCES) \
- $(libpixbuf_ico_la_SOURCES) \
- $(libpixbuf_ras_la_SOURCES) \
- $(libpixbuf_tiff_la_SOURCES) \
- $(libpixbuf_pnm_la_SOURCES) \
- $(libpixbuf_bmp_la_SOURCES)
+extra_sources = $(libpixbufloader_png_la_SOURCES) \
+ $(libpixbufloader_jpeg_la_SOURCES) \
+ $(libpixbufloader_xpm_la_SOURCES) \
+ $(libpixbufloader_gif_la_SOURCES) \
+ $(libpixbufloader_ico_la_SOURCES) \
+ $(libpixbufloader_ras_la_SOURCES) \
+ $(libpixbufloader_tiff_la_SOURCES) \
+ $(libpixbufloader_pnm_la_SOURCES) \
+ $(libpixbufloader_bmp_la_SOURCES)
builtin_libraries =
endif
/**
* gdk_pixbuf_animation_get_width:
* @animation: An animation.
+ *
+ * Queries the width of the bounding box of a pixbuf animation.
*
- * Return the width of @animation.
+ * Return value: Width of the bounding box of the animation.
**/
int
gdk_pixbuf_animation_get_width (GdkPixbufAnimation *animation)
{
- g_return_val_if_fail (animation != NULL, 0);
- g_return_val_if_fail (animation->ref_count > 0, 0);
+ g_return_val_if_fail (animation != NULL, -1);
return animation->width;
}
/**
* gdk_pixbuf_animation_get_height:
* @animation: An animation.
+ *
+ * Queries the height of the bounding box of a pixbuf animation.
*
- * Return the height of @animation.
+ * Return value: Height of the bounding box of the animation.
**/
int
gdk_pixbuf_animation_get_height (GdkPixbufAnimation *animation)
{
- g_return_val_if_fail (animation != NULL, 0);
- g_return_val_if_fail (animation->ref_count > 0, 0);
+ g_return_val_if_fail (animation != NULL, -1);
return animation->height;
}
/**
* gdk_pixbuf_animation_get_num_frames:
* @animation: An animation.
+ *
+ * Queries the number of frames in a pixbuf animation.
*
- * Return the number of frames in @animation.
+ * Return value: Number of frames in the animation.
**/
int
gdk_pixbuf_animation_get_num_frames (GdkPixbufAnimation *animation)
{
- g_return_val_if_fail (animation != NULL, 0);
- g_return_val_if_fail (animation->ref_count > 0, 0);
+ g_return_val_if_fail (animation != NULL, -1);
return animation->n_frames;
}
/**
* gdk_pixbuf_animation_get_frames:
* @animation: An animation.
+ *
+ * Queries the list of frames of an animation.
*
- * Return the frames of @animation as a list of
- * GdkPixbufAnimationFrame objects.
+ * Return value: List of frames in the animation; this is a #GList of
+ * #GdkPixbufFrame structures.
**/
GList *
gdk_pixbuf_animation_get_frames (GdkPixbufAnimation *animation)
{
- g_return_val_if_fail (animation != NULL, 0);
- g_return_val_if_fail (animation->ref_count > 0, 0);
+ g_return_val_if_fail (animation != NULL, NULL);
return animation->frames;
}
g_return_val_if_fail (width > 0, NULL);
g_return_val_if_fail (height > 0, NULL);
- pixbuf = g_new (GdkPixbuf, 1);
+ pixbuf = g_new0 (GdkPixbuf, 1);
pixbuf->ref_count = 1;
pixbuf->colorspace = colorspace;
pixbuf->n_channels = has_alpha ? 4 : 3;
name = image_module->module_name;
- module_name = g_strconcat ("pixbuf-", name, NULL);
+ module_name = g_strconcat ("pixbufloader-", name, NULL);
path = g_module_build_path (PIXBUF_LIBDIR, module_name);
module = g_module_open (path, G_MODULE_BIND_LAZY);
GTK_RUN_LAST,
parent_class->type,
GTK_SIGNAL_OFFSET (GdkPixbufLoaderClass, frame_done),
- gtk_marshal_NONE__NONE,
- GTK_TYPE_NONE, 0);
+ gtk_marshal_NONE__POINTER,
+ GTK_TYPE_NONE, 1,
+ GTK_TYPE_POINTER);
pixbuf_loader_signals[ANIMATION_DONE] =
gtk_signal_new ("animation_done",
/* User data for the destroy notification function */
gpointer destroy_fn_data;
+ /* Last unref handler, determines whether the pixbuf should be finalized */
+ GdkPixbufLastUnref last_unref_fn;
+
+ /* User data for the last unref handler */
+ gpointer last_unref_fn_data;
+
/* Do we have an alpha channel? */
guint has_alpha : 1;
};
* gdk_pixbuf_unref:
* @pixbuf: A pixbuf.
*
- * Removes a reference from a pixbuf, which will be destroyed when the reference
- * count drops to zero.
+ * Removes a reference from a pixbuf. If this is the last reference for the
+ * @pixbuf, then its last unref handler function will be called; if no handler
+ * has been defined, then the pixbuf will be finalized.
+ *
+ * See also: gdk_pixbuf_set_last_unref_handler().
**/
void
gdk_pixbuf_unref (GdkPixbuf *pixbuf)
g_return_if_fail (pixbuf != NULL);
g_return_if_fail (pixbuf->ref_count > 0);
- pixbuf->ref_count--;
+ if (pixbuf->ref_count > 1)
+ pixbuf->ref_count--;
+ else if (pixbuf->last_unref_fn)
+ (* pixbuf->last_unref_fn) (pixbuf, pixbuf->last_unref_fn_data);
+ else
+ gdk_pixbuf_finalize (pixbuf);
+}
+
+/**
+ * gdk_pixbuf_set_last_unref_handler:
+ * @pixbuf: A pixbuf.
+ * @last_unref_fn: Handler function for the last unref.
+ * @last_unref_fn_data: Closure data to pass to the last unref handler function.
+ *
+ * Sets the handler function for the @pixbuf's last unref handler. When
+ * gdk_pixbuf_unref() is called on this pixbuf and it has a reference count of
+ * 1, i.e. its last reference, then the last unref handler will be called. This
+ * function should determine whether to finalize the pixbuf or just continue.
+ * If it wishes to finalize the pixbuf, it should do so by calling
+ * gdk_pixbuf_finalize().
+ *
+ * See also: gdk_pixbuf_finalize().
+ **/
+void
+gdk_pixbuf_set_last_unref_handler (GdkPixbuf *pixbuf, GdkPixbufLastUnref last_unref_fn,
+ gpointer last_unref_fn_data)
+{
+ g_return_if_fail (pixbuf != NULL);
+
+ pixbuf->last_unref_fn = last_unref_fn;
+ pixbuf->last_unref_fn_data = last_unref_fn_data;
+}
+
+/**
+ * gdk_pixbuf_finalize:
+ * @pixbuf: A pixbuf with a reference count of 1.
+ *
+ * Finalizes a pixbuf by calling its destroy notification function to free the
+ * pixel data and freeing the pixbuf itself. This function is meant to be
+ * called only from within a #GdkPixbufLastUnref handler function, and the
+ * specified @pixbuf must have a reference count of 1, i.e. its last reference.
+ **/
+void
+gdk_pixbuf_finalize (GdkPixbuf *pixbuf)
+{
+ g_return_if_fail (pixbuf != NULL);
+ g_return_if_fail (pixbuf->ref_count == 1);
- if (pixbuf->ref_count == 0) {
- if (pixbuf->destroy_fn)
- (* pixbuf->destroy_fn) (pixbuf->pixels, pixbuf->destroy_fn_data);
+ if (pixbuf->destroy_fn)
+ (* pixbuf->destroy_fn) (pixbuf->pixels, pixbuf->destroy_fn_data);
- g_free (pixbuf);
- }
+ g_free (pixbuf);
}
\f
typedef struct _GdkPixbufFrame GdkPixbufFrame;
typedef struct _GdkPixbufAnimation GdkPixbufAnimation;
+/* Handler that must free the pixel array */
typedef void (* GdkPixbufDestroyNotify) (guchar *pixels, gpointer data);
+/* Handler for the last unref operation */
+typedef void (* GdkPixbufLastUnref) (GdkPixbuf *pixbuf, gpointer data);
+
\f
/* Reference counting */
-GdkPixbuf *gdk_pixbuf_ref (GdkPixbuf *pixbuf);
-void gdk_pixbuf_unref (GdkPixbuf *pixbuf);
+GdkPixbuf *gdk_pixbuf_ref (GdkPixbuf *pixbuf);
+void gdk_pixbuf_unref (GdkPixbuf *pixbuf);
+
+void gdk_pixbuf_set_last_unref_handler (GdkPixbuf *pixbuf,
+ GdkPixbufLastUnref last_unref_fn,
+ gpointer last_unref_fn_data);
+
+void gdk_pixbuf_finalize (GdkPixbuf *pixbuf);
/* GdkPixbuf accessors */
GTK_RUN_LAST,
parent_class->type,
GTK_SIGNAL_OFFSET (GdkPixbufLoaderClass, frame_done),
- gtk_marshal_NONE__NONE,
- GTK_TYPE_NONE, 0);
+ gtk_marshal_NONE__POINTER,
+ GTK_TYPE_NONE, 1,
+ GTK_TYPE_POINTER);
pixbuf_loader_signals[ANIMATION_DONE] =
gtk_signal_new ("animation_done",
projects / ~andy / gtk / commitdiff