diff options
Diffstat (limited to 'docs')
17 files changed, 723 insertions, 360 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: +--> |