diff options
27 files changed, 922 insertions, 435 deletions
diff --git a/docs/reference/gdk-pixbuf/compiling.sgml b/docs/reference/gdk-pixbuf/compiling.sgml index 5bc123fef..dc335ef6d 100644 --- a/docs/reference/gdk-pixbuf/compiling.sgml +++ b/docs/reference/gdk-pixbuf/compiling.sgml @@ -1,22 +1,25 @@ <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> @@ -26,10 +29,10 @@ </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> @@ -40,8 +43,9 @@ <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> @@ -63,13 +67,15 @@ <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. @@ -83,13 +89,13 @@ <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> diff --git a/docs/reference/gdk-pixbuf/gdk-pixbuf-decl.txt b/docs/reference/gdk-pixbuf/gdk-pixbuf-decl.txt index 560f696be..dc8992a95 100644 --- a/docs/reference/gdk-pixbuf/gdk-pixbuf-decl.txt +++ b/docs/reference/gdk-pixbuf/gdk-pixbuf-decl.txt @@ -125,6 +125,12 @@ GdkPixbufLoader *loader <RETURNS>void </RETURNS> GdkPixbufLoader *loader </FUNCTION> +<ENUM> +<NAME>GdkColorspace</NAME> +typedef enum { + GDK_COLORSPACE_RGB +} GdkColorspace; +</ENUM> <STRUCT> <NAME>GdkPixbuf</NAME> </STRUCT> @@ -134,113 +140,85 @@ GdkPixbufLoader *loader <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> @@ -250,7 +228,7 @@ const char *filename <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> @@ -260,7 +238,12 @@ const char **data <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> @@ -294,40 +277,52 @@ GdkPixbuf *pixbuf,GdkPixmap **pixmap_return, GdkBitmap **mask_return,int alpha_t <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> @@ -340,6 +335,51 @@ GdkPixbufAnimation *animation 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 @@ -398,7 +438,7 @@ void </MACRO> <MACRO> <NAME>GDK_PIXBUF_MINOR</NAME> -#define GDK_PIXBUF_MINOR (4) +#define GDK_PIXBUF_MINOR (7) </MACRO> <MACRO> <NAME>GDK_PIXBUF_MICRO</NAME> @@ -406,9 +446,82 @@ void </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> diff --git a/docs/reference/gdk-pixbuf/gdk-pixbuf-sections.txt b/docs/reference/gdk-pixbuf/gdk-pixbuf-sections.txt index 82673441b..e00f520fe 100644 --- a/docs/reference/gdk-pixbuf/gdk-pixbuf-sections.txt +++ b/docs/reference/gdk-pixbuf/gdk-pixbuf-sections.txt @@ -2,8 +2,9 @@ <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 @@ -15,8 +16,12 @@ gdk_pixbuf_get_rowstride <SECTION> <FILE>refcounting</FILE> +GdkPixbufDestroyNotify +GdkPixbufLastUnref gdk_pixbuf_ref gdk_pixbuf_unref +gdk_pixbuf_set_last_unref_handler +gdk_pixbuf_finalize </SECTION> <SECTION> @@ -26,10 +31,10 @@ gdk_pixbuf_new_from_file <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> @@ -60,10 +65,20 @@ GdkPixbufAnimation 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 diff --git a/docs/reference/gdk-pixbuf/gdk-pixbuf.sgml b/docs/reference/gdk-pixbuf/gdk-pixbuf.sgml index 900f4edb5..bafc2669f 100644 --- a/docs/reference/gdk-pixbuf/gdk-pixbuf.sgml +++ b/docs/reference/gdk-pixbuf/gdk-pixbuf.sgml @@ -15,7 +15,7 @@ <book> <bookinfo> - <title>The GdkPixbuf Library</title> + <title>The <application>gdk-pixbuf</application> Library</title> <authorgroup> <author> @@ -41,8 +41,9 @@ <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> diff --git a/docs/reference/gdk-pixbuf/gdk-pixbuf.signals b/docs/reference/gdk-pixbuf/gdk-pixbuf.signals index 7ac8646de..b3db0835e 100644 --- a/docs/reference/gdk-pixbuf/gdk-pixbuf.signals +++ b/docs/reference/gdk-pixbuf/gdk-pixbuf.signals @@ -18,6 +18,7 @@ GdkPixbufLoader *gdkpixbufloader <NAME>GdkPixbufLoader::frame-done</NAME> <RETURNS>void</RETURNS> GdkPixbufLoader *gdkpixbufloader +gpointer arg1 </SIGNAL> <SIGNAL> diff --git a/docs/reference/gdk-pixbuf/tmpl/animation.sgml b/docs/reference/gdk-pixbuf/tmpl/animation.sgml index 2ce521ac8..500758f17 100644 --- a/docs/reference/gdk-pixbuf/tmpl/animation.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/animation.sgml @@ -6,11 +6,12 @@ Animations as multi-frame structures. <!-- ##### 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 ##### --> @@ -21,18 +22,19 @@ Animations as multi-frame structures. <!-- ##### 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> @@ -42,22 +44,12 @@ Animations as multi-frame structures. 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> @@ -81,11 +73,92 @@ Animations as multi-frame structures. </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: --> - - diff --git a/docs/reference/gdk-pixbuf/tmpl/creating.sgml b/docs/reference/gdk-pixbuf/tmpl/creating.sgml index 3c06008c9..c8c3f7581 100644 --- a/docs/reference/gdk-pixbuf/tmpl/creating.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/creating.sgml @@ -6,21 +6,15 @@ Creating a pixbuf from image data that is already in memory. <!-- ##### 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> @@ -37,26 +31,24 @@ Creating a pixbuf from image data that is already in memory. 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: @@ -70,13 +62,14 @@ Creating a pixbuf from image data that is already in memory. </para> @data: -@format: +@colorspace: @has_alpha: +@bits_per_sample: @width: @height: @rowstride: -@dfunc: -@dfunc_data: +@destroy_fn: +@destroy_fn_data: @Returns: @@ -86,7 +79,18 @@ Creating a pixbuf from image data that is already in memory. </para> @data: -@Returns: <!-- +@Returns: + + +<!-- ##### FUNCTION gdk_pixbuf_copy ##### --> +<para> + +</para> + +@pixbuf: +@Returns: + +<!-- Local variables: mode: sgml sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "") diff --git a/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml b/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml index 5659bc445..0d917c829 100644 --- a/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml @@ -6,11 +6,12 @@ Loading a pixbuf from a file. <!-- ##### 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> @@ -22,7 +23,7 @@ Loading a pixbuf from a file. <!-- ##### SECTION See_Also ##### --> <para> - #GdkPixbufLoader + #GdkPixbufLoader. </para> <!-- ##### FUNCTION gdk_pixbuf_new_from_file ##### --> @@ -31,7 +32,8 @@ Loading a pixbuf from a file. </para> @filename: -@Returns: <!-- +@Returns: +<!-- Local variables: mode: sgml sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "") diff --git a/docs/reference/gdk-pixbuf/tmpl/from-drawables.sgml b/docs/reference/gdk-pixbuf/tmpl/from-drawables.sgml index 252d57bfa..c182f3d97 100644 --- a/docs/reference/gdk-pixbuf/tmpl/from-drawables.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/from-drawables.sgml @@ -15,7 +15,7 @@ Getting parts of a drawable's image data into a pixbuf. <!-- ##### SECTION See_Also ##### --> <para> - #GdkPixbuf, gdk_image_get() + gdk_image_get(). </para> <!-- ##### FUNCTION gdk_pixbuf_get_from_drawable ##### --> @@ -32,7 +32,8 @@ Getting parts of a drawable's image data into a pixbuf. @dest_y: @width: @height: -@Returns: <!-- +@Returns: +<!-- Local variables: mode: sgml sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "") diff --git a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml index ed5a432cf..8cef09628 100644 --- a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml @@ -8,51 +8,65 @@ Application-driven progressive image loading. <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 ##### --> @@ -122,12 +136,6 @@ Application-driven progressive image loading. 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. @@ -143,23 +151,23 @@ Application-driven progressive image loading. 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> + <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> @@ -169,8 +177,6 @@ Application-driven progressive image loading. drives it. </para> -@gdkpixbufloader: the object which received the signal. -<!-- # Unused Parameters # --> @loader: Loader which emitted the signal. <!-- diff --git a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-unused.sgml b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-unused.sgml index 788c92fbc..850e45fd9 100644 --- a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-unused.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-unused.sgml @@ -1,9 +1,3 @@ -<!-- ##### SECTION ./tmpl/gdk-pixbuf-io.sgml:See_Also ##### --> -<para> - -</para> - - <!-- ##### FUNCTION gdk_pixbuf_load_module ##### --> <para> @@ -15,12 +9,6 @@ -<!-- ##### ARG GnomeCanvasPixbuf:height_pixels ##### --> -<para> - -</para> - - <!-- ##### STRUCT GdkPixbufModule ##### --> <para> @@ -35,6 +23,52 @@ @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> @@ -63,15 +97,6 @@ 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 @@ -83,27 +108,18 @@ gdk-pixbuf-io </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 ##### --> diff --git a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml index ff31dacb1..111c921fd 100644 --- a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml @@ -8,28 +8,32 @@ Information that describes an image. <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> @@ -98,11 +102,11 @@ the image data. </para> @pixbuf: -@Returns: <!-- +@Returns: + +<!-- Local variables: mode: sgml sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "") End: --> - - diff --git a/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml b/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml index 21a51eef6..75cc31ea3 100644 --- a/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml @@ -217,8 +217,8 @@ Canvas item to display #GdkPixbuf images. 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 ##### --> @@ -299,4 +299,3 @@ mode: sgml sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "") End: --> - diff --git a/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml b/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml index 9593e7210..5a6824810 100644 --- a/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml @@ -1,8 +1,10 @@ <!-- ##### 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> @@ -15,11 +17,75 @@ Functions to perform reference counting on a #GdkPixbuf. #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> @@ -34,11 +100,29 @@ Functions to perform reference counting on a #GdkPixbuf. </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: --> - - diff --git a/docs/reference/gdk-pixbuf/tmpl/rendering.sgml b/docs/reference/gdk-pixbuf/tmpl/rendering.sgml index 4af655d54..2fffd57bc 100644 --- a/docs/reference/gdk-pixbuf/tmpl/rendering.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/rendering.sgml @@ -6,18 +6,19 @@ Rendering a pixbuf to a GDK drawable. <!-- ##### 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> @@ -104,13 +105,7 @@ In the future it will do full alpha compositing. @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> @@ -123,3 +118,9 @@ End: @alpha_threshold: +<!-- +Local variables: +mode: sgml +sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "") +End: +--> diff --git a/docs/reference/gdk-pixbuf/tmpl/scaling.sgml b/docs/reference/gdk-pixbuf/tmpl/scaling.sgml index 37411cd4f..996b51807 100644 --- a/docs/reference/gdk-pixbuf/tmpl/scaling.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/scaling.sgml @@ -5,34 +5,37 @@ Scaling 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) { @@ -40,15 +43,15 @@ 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, @@ -59,12 +62,45 @@ expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data) 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> @@ -81,7 +117,7 @@ expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data) @offset_y: @scale_x: @scale_y: -@filter_level: +@interp_type: <!-- ##### FUNCTION gdk_pixbuf_composite ##### --> @@ -99,7 +135,7 @@ expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data) @offset_y: @scale_x: @scale_y: -@filter_level: +@interp_type: @overall_alpha: @@ -118,7 +154,7 @@ expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data) @offset_y: @scale_x: @scale_y: -@filter_level: +@interp_type: @overall_alpha: @check_x: @check_y: @@ -135,7 +171,7 @@ expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data) @src: @dest_width: @dest_height: -@filter_level: +@interp_type: @Returns: @@ -147,16 +183,17 @@ expose_cb (GtkWidget *widget, GdkEventExpose *event, gpointer data) @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: --> - - diff --git a/docs/reference/gdk-pixbuf/tmpl/util.sgml b/docs/reference/gdk-pixbuf/tmpl/util.sgml index 2d29c7505..43942cc61 100644 --- a/docs/reference/gdk-pixbuf/tmpl/util.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/util.sgml @@ -27,13 +27,7 @@ Utility and miscellaneous convenience functions. @r: @g: @b: -@Returns: <!-- -Local variables: -mode: sgml -sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "") -End: ---> - +@Returns: <!-- ##### FUNCTION gdk_pixbuf_copy_area ##### --> <para> @@ -50,3 +44,9 @@ End: @dest_y: +<!-- +Local variables: +mode: sgml +sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "") +End: +--> diff --git a/gdk-pixbuf/ChangeLog b/gdk-pixbuf/ChangeLog index 124e53fb0..fed90a3df 100644 --- a/gdk-pixbuf/ChangeLog +++ b/gdk-pixbuf/ChangeLog @@ -1,3 +1,58 @@ +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. diff --git a/gdk-pixbuf/Makefile.am b/gdk-pixbuf/Makefile.am index 64419f792..8cac5be34 100644 --- a/gdk-pixbuf/Makefile.am +++ b/gdk-pixbuf/Makefile.am @@ -15,96 +15,96 @@ lib_LTLIBRARIES = \ 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 @@ -125,15 +125,15 @@ extra_sources = 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 diff --git a/gdk-pixbuf/gdk-pixbuf-animation.c b/gdk-pixbuf/gdk-pixbuf-animation.c index b2fbbb8f4..beb5b2939 100644 --- a/gdk-pixbuf/gdk-pixbuf-animation.c +++ b/gdk-pixbuf/gdk-pixbuf-animation.c @@ -167,14 +167,15 @@ gdk_pixbuf_animation_unref (GdkPixbufAnimation *animation) /** * 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; } @@ -182,14 +183,15 @@ gdk_pixbuf_animation_get_width (GdkPixbufAnimation *animation) /** * 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; } @@ -197,14 +199,15 @@ gdk_pixbuf_animation_get_height (GdkPixbufAnimation *animation) /** * 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; } @@ -212,15 +215,16 @@ gdk_pixbuf_animation_get_num_frames (GdkPixbufAnimation *animation) /** * 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; } diff --git a/gdk-pixbuf/gdk-pixbuf-data.c b/gdk-pixbuf/gdk-pixbuf-data.c index e94aea7da..1ad122bc1 100644 --- a/gdk-pixbuf/gdk-pixbuf-data.c +++ b/gdk-pixbuf/gdk-pixbuf-data.c @@ -60,7 +60,7 @@ gdk_pixbuf_new_from_data (const guchar *data, GdkColorspace colorspace, gboolean 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; diff --git a/gdk-pixbuf/gdk-pixbuf-io.c b/gdk-pixbuf/gdk-pixbuf-io.c index cb88dd2de..f5ba1ecd0 100644 --- a/gdk-pixbuf/gdk-pixbuf-io.c +++ b/gdk-pixbuf/gdk-pixbuf-io.c @@ -210,7 +210,7 @@ gdk_pixbuf_load_module (GdkPixbufModule *image_module) 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); diff --git a/gdk-pixbuf/gdk-pixbuf-loader.c b/gdk-pixbuf/gdk-pixbuf-loader.c index 5648258aa..5165c71ba 100644 --- a/gdk-pixbuf/gdk-pixbuf-loader.c +++ b/gdk-pixbuf/gdk-pixbuf-loader.c @@ -156,8 +156,9 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class) 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", diff --git a/gdk-pixbuf/gdk-pixbuf-private.h b/gdk-pixbuf/gdk-pixbuf-private.h index 278298c23..4595785a0 100644 --- a/gdk-pixbuf/gdk-pixbuf-private.h +++ b/gdk-pixbuf/gdk-pixbuf-private.h @@ -59,6 +59,12 @@ struct _GdkPixbuf { /* 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; }; diff --git a/gdk-pixbuf/gdk-pixbuf.c b/gdk-pixbuf/gdk-pixbuf.c index be67197bc..d42cfd159 100644 --- a/gdk-pixbuf/gdk-pixbuf.c +++ b/gdk-pixbuf/gdk-pixbuf.c @@ -55,8 +55,11 @@ gdk_pixbuf_ref (GdkPixbuf *pixbuf) * 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) @@ -64,14 +67,58 @@ 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); } diff --git a/gdk-pixbuf/gdk-pixbuf.h b/gdk-pixbuf/gdk-pixbuf.h index 5b82e086b..70eebcf65 100644 --- a/gdk-pixbuf/gdk-pixbuf.h +++ b/gdk-pixbuf/gdk-pixbuf.h @@ -46,14 +46,24 @@ typedef struct _GdkPixbuf GdkPixbuf; 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); + /* 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 */ diff --git a/gtk/gdk-pixbuf-loader.c b/gtk/gdk-pixbuf-loader.c index 5648258aa..5165c71ba 100644 --- a/gtk/gdk-pixbuf-loader.c +++ b/gtk/gdk-pixbuf-loader.c @@ -156,8 +156,9 @@ gdk_pixbuf_loader_class_init (GdkPixbufLoaderClass *class) 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", |