diff --git a/docs/reference/gdk-pixbuf/Makefile.am b/docs/reference/gdk-pixbuf/Makefile.am index cf2e90cf70..0c43848f9b 100644 --- a/docs/reference/gdk-pixbuf/Makefile.am +++ b/docs/reference/gdk-pixbuf/Makefile.am @@ -16,15 +16,23 @@ HTML_DIR=$(datadir)/gnome/html TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) -tmpl_sources = foo +tmpl_sources = \ + tmpl/creating.sgml \ + tmpl/file-loading.sgml \ + tmpl/gdk-pixbuf-io.sgml \ + tmpl/gdk-pixbuf-loader.sgml \ + tmpl/gdk-pixbuf-unused.sgml \ + tmpl/gdk-pixbuf.sgml \ + tmpl/gnome-canvas-pixbuf.sgml \ + tmpl/refcounting.sgml \ + tmpl/rendering.sgml gdk_pixbuf_docdir = $(HTML_DIR) -gdk_pixbuf_doc_DATA = \ - gdk-pixbuf.html \ - gdk-pixbuf.hierarchy \ - gdk-pixbuf.types \ - gdk-pixbuf-scan.c \ - gdk-pixbuf-decl.txt \ +gdk_pixbuf_doc_DATA = \ + gdk-pixbuf.html \ + gdk-pixbuf.hierarchy \ + gdk-pixbuf.types \ + gdk-pixbuf-decl.txt \ gdk-pixbuf-sections.txt EXTRA_DIST = $(gdk_pixbuf_doc_DATA) diff --git a/docs/reference/gdk-pixbuf/gdk-pixbuf-decl.txt b/docs/reference/gdk-pixbuf/gdk-pixbuf-decl.txt index f74dcff19b..62d0d63a93 100644 --- a/docs/reference/gdk-pixbuf/gdk-pixbuf-decl.txt +++ b/docs/reference/gdk-pixbuf/gdk-pixbuf-decl.txt @@ -24,6 +24,11 @@ GdkPixbufCache *cache,const char *file void GdkPixbuf *pixbuf, gpointer user_data + +ModuleUpdatedNotifyFunc +void +GdkPixbuf *pixbuf, gpointer user_data, guint x, guint y, guint width, guint height + GdkPixbufModule @@ -37,7 +42,7 @@ struct GdkPixbufModule { GdkPixbuf *(* load_xpm_data) (const gchar **data); /* Incremental loading */ - gpointer (* begin_load) (ModulePreparedNotifyFunc func, gpointer user_data); + gpointer (* begin_load) (ModulePreparedNotifyFunc prepare_func, ModuleUpdatedNotifyFunc update_func, gpointer user_data); void (* stop_load) (gpointer context); gboolean (* load_increment)(gpointer context, const gchar *buf, guint size); }; diff --git a/docs/reference/gdk-pixbuf/gdk-pixbuf-sections.txt b/docs/reference/gdk-pixbuf/gdk-pixbuf-sections.txt index 5763e649d1..13fda9c997 100644 --- a/docs/reference/gdk-pixbuf/gdk-pixbuf-sections.txt +++ b/docs/reference/gdk-pixbuf/gdk-pixbuf-sections.txt @@ -75,6 +75,7 @@ GdkPixbufLoader
gdk-pixbuf-io ModulePreparedNotifyFunc +ModuleUpdatedNotifyFunc GdkPixbufModule gdk_pixbuf_get_module gdk_pixbuf_load_module diff --git a/docs/reference/gdk-pixbuf/tmpl/creating.sgml b/docs/reference/gdk-pixbuf/tmpl/creating.sgml index f6c303566f..240e7567c0 100644 --- a/docs/reference/gdk-pixbuf/tmpl/creating.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/creating.sgml @@ -1,18 +1,46 @@ -Creating a Pixbuf from Data in Memory +Image Data in Memory Creating a pixbuf from image data that is already in memory. + 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. + + + 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 gdk_pixbuf_new() function can be used as a convenience to + create a pixbuf with an empty buffer. This is equivalent to + allocating a data buffer using malloc() and then wrapping it with + gdk_pixbuf_new_from_data(). The gdk_pixbuf_new() function will + compute an optimal rowstride so that rendering can be performed + with an efficient algorithm. + + + + As a special case, you can use the gdk_pixbuf_new_from_xpm_data() + function to create a pixbuf from inline XPM image data. - - - + + #ArtPixBuf + @@ -58,7 +86,7 @@ Creating a pixbuf from image data that is already in memory. @data: -@Returns: +@Returns: + + diff --git a/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml b/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml index 9fcf2ea5c8..2546600e6a 100644 --- a/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/file-loading.sgml @@ -31,7 +31,7 @@ Loading a pixbuf from a file. @filename: -@Returns: +@Returns: + + diff --git a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-io.sgml b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-io.sgml index ecb5a5bad7..cc03e4648d 100644 --- a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-io.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-io.sgml @@ -23,6 +23,19 @@ gdk-pixbuf-io @user_data: + + + + + +@pixbuf: +@user_data: +@x: +@y: +@width: +@height: + + diff --git a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml index 0276b40cb9..aac19face4 100644 --- a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml @@ -34,8 +34,8 @@ the image data. -@pixbuf: -@Returns: +@pixbuf: +@Returns: @@ -43,8 +43,8 @@ the image data. -@pixbuf: -@Returns: +@pixbuf: +@Returns: @@ -52,8 +52,8 @@ the image data. -@pixbuf: -@Returns: +@pixbuf: +@Returns: @@ -61,8 +61,8 @@ the image data. -@pixbuf: -@Returns: +@pixbuf: +@Returns: @@ -70,8 +70,8 @@ the image data. -@pixbuf: -@Returns: +@pixbuf: +@Returns: @@ -79,8 +79,8 @@ the image data. -@pixbuf: -@Returns: +@pixbuf: +@Returns: @@ -88,8 +88,8 @@ the image data. -@pixbuf: -@Returns: +@pixbuf: +@Returns: @@ -97,7 +97,7 @@ the image data. -@pixbuf: +@pixbuf: @Returns: + + diff --git a/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml b/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml index 595322a37f..d2e37570f0 100644 --- a/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml @@ -2,46 +2,62 @@ GnomeCanvasPixbuf - +Canvas item to display #GdkPixbuf images. - + + This canvas item displays #GdkPixbuf images. It handles full + affine transformations in both GDK and antialiased modes, and also + supports SVG-like scaling and + translation semantics for absolute pixel values. + - + + #GdkPixbuf structures may be shared among different pixbuf canvas + items; the pixbuf item uses #GdkPixbuf's reference counting + functions for this. + - - - + + #GnomeCanvas, #GdkPixbuf + - + + Casts a #GtkOjbect to a #GnomeCanvasPixbuf. + - - -@obj: +@obj: A GTK+ object. - - - - - - - - + + Contains a pointer to a #GdkPixbuf structure that will be used by + the pixbuf canvas item as an image source. When a pixbuf is set + its reference count is incremented; if the pixbuf item kept a + pointer to another #GdkPixbuf structure, the reference count of + this structure will be decremented. When a pixbuf is queried, a + reference count will not be added to the return value; you must do + this yourself if you intend to keep the pixbuf structure around. + - - - + + Determines whether the + + + + Contains the width of the image in the pixbuf canvas item. + + @@ -57,3 +73,40 @@ GnomeCanvasPixbuf + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml b/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml index 63f1121aea..00b8723097 100644 --- a/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/refcounting.sgml @@ -17,8 +17,7 @@ Functions to perform reference counting on a #GdkPixbuf. - #GdkPixbuf - #ArtPixBuf + #GdkPixbuf, #ArtPixBuf @@ -36,10 +35,11 @@ Functions to perform reference counting on a #GdkPixbuf. @pixbuf: - + + diff --git a/docs/reference/gdk-pixbuf/tmpl/rendering.sgml b/docs/reference/gdk-pixbuf/tmpl/rendering.sgml index e70a79d892..f6b6d9eb47 100644 --- a/docs/reference/gdk-pixbuf/tmpl/rendering.sgml +++ b/docs/reference/gdk-pixbuf/tmpl/rendering.sgml @@ -1,26 +1,48 @@ -rendering +Rendering - +Rendering a Pixbuf to a GDK Drawable. - + + The GdkPixbuf library provides several convenience functions to + render pixbufs to GDK drawables. It uses the GdkRGB to render the + image data. + - + + 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. + - - - + + GdkRGB + - + + These values can be passed to + gdk_pixbuf_render_to_drawable_alpha() to control how the alpha + chanel of an image should be handled. This function can create a + bilevel clipping mask (black and white) and use it while painting + the image. In the future, when the X Window System gets an alpha + channel extension, it will be possible to do full alpha + compositing onto arbitrary drawables. For now both cases fall + back to a bilevel clipping mask. + - - -@GDK_PIXBUF_ALPHA_BILEVEL: -@GDK_PIXBUF_ALPHA_FULL: +@GDK_PIXBUF_ALPHA_BILEVEL: A bilevel clipping mask (black and white) +will be created and used to draw the image. Pixels below 0.5 opacity +will be considered fully transparent, and all others will be +considered fully opaque. +@GDK_PIXBUF_ALPHA_FULL: For now falls back to #GDK_PIXBUF_ALPHA_BILEVEL. +In the future it will do full alpha compositing. @@ -74,6 +96,13 @@ rendering @dest_y: @width: @height: -@alpha_threshold: +@alpha_threshold: + + diff --git a/gdk-pixbuf/ChangeLog b/gdk-pixbuf/ChangeLog index b53e541404..1aa428aead 100644 --- a/gdk-pixbuf/ChangeLog +++ b/gdk-pixbuf/ChangeLog @@ -1,3 +1,9 @@ +1999-11-04 Federico Mena Quintero + + * doc/tmpl/rendering.sgml: Populated. + + * doc/Makefile.am: Added the template files. + 1999-11-04 Havoc Pennington * src/gdk-pixbuf-render.c (gdk_pixbuf_render_to_drawable): In diff --git a/gdk-pixbuf/gdk-pixbuf-data.c b/gdk-pixbuf/gdk-pixbuf-data.c index 0919e94a92..4c3bd36106 100644 --- a/gdk-pixbuf/gdk-pixbuf-data.c +++ b/gdk-pixbuf/gdk-pixbuf-data.c @@ -37,9 +37,9 @@ * drops to zero, or NULL if the data should not be freed. * @dfunc_data: Closure data to pass to the destroy notification function. * - * Creates a new &GdkPixbuf out of in-memory RGB data. + * Creates a new #GdkPixbuf out of in-memory RGB data. * - * Return value: A newly-created &GdkPixbuf structure with a reference count of + * Return value: A newly-created #GdkPixbuf structure with a reference count of * 1. **/ GdkPixbuf * diff --git a/gdk-pixbuf/gdk-pixbuf-loader.c b/gdk-pixbuf/gdk-pixbuf-loader.c index eecc8a605f..73093c6cf0 100644 --- a/gdk-pixbuf/gdk-pixbuf-loader.c +++ b/gdk-pixbuf/gdk-pixbuf-loader.c @@ -89,10 +89,10 @@ gtk_marshal_NONE__INT_INT_INT_INT (GtkObject *object, GtkSignalFunc func, gpoint * gdk_pixbuf_loader_get_type: * @void: * - * Registers the &GdkPixubfLoader class if necessary, and returns the type ID + * Registers the #GdkPixubfLoader class if necessary, and returns the type ID * associated to it. * - * Return value: The type ID of the &GdkPixbufLoader class. + * Return value: The type ID of the #GdkPixbufLoader class. **/ GtkType gdk_pixbuf_loader_get_type (void) diff --git a/gdk-pixbuf/gdk-pixbuf.c b/gdk-pixbuf/gdk-pixbuf.c index b1ff7f6537..6c9b2730eb 100644 --- a/gdk-pixbuf/gdk-pixbuf.c +++ b/gdk-pixbuf/gdk-pixbuf.c @@ -81,9 +81,9 @@ gdk_pixbuf_unref (GdkPixbuf *pixbuf) * gdk_pixbuf_new_from_art_pixbuf: * @art_pixbuf: A libart pixbuf. * - * Creates a &GdkPixbuf by wrapping a libart pixbuf. + * Creates a #GdkPixbuf by wrapping a libart pixbuf. * - * Return value: A newly-created &GdkPixbuf structure with a reference count of + * Return value: A newly-created #GdkPixbuf structure with a reference count of * 1. **/ GdkPixbuf * @@ -119,12 +119,12 @@ free_buffer (gpointer user_data, gpointer data) * @width: Width of image in pixels. * @height: Height of image in pixels. * - * Creates a new &GdkPixbuf structure and allocates a buffer for it. The buffer + * Creates a new #GdkPixbuf structure and allocates a buffer for it. The buffer * has an optimal rowstride. Note that the buffer is not cleared; you will have * to fill it completely. * - * Return value: A newly-created &GdkPixbuf, or NULL if not enough memory - * could be allocated for the image buffer. + * Return value: A newly-created #GdkPixbuf with a reference count of 1, or NULL + * if not enough memory could be allocated for the image buffer. **/ GdkPixbuf * gdk_pixbuf_new (ArtPixFormat format, gboolean has_alpha, int bits_per_sample, diff --git a/gdk-pixbuf/gnome-canvas-pixbuf.c b/gdk-pixbuf/gnome-canvas-pixbuf.c index 2d62153702..52b445d136 100644 --- a/gdk-pixbuf/gnome-canvas-pixbuf.c +++ b/gdk-pixbuf/gnome-canvas-pixbuf.c @@ -108,10 +108,10 @@ static GnomeCanvasItemClass *parent_class; * gnome_canvas_pixbuf_get_type: * @void: * - * Registers the &GnomeCanvasPixbuf class if necessary, and returns the type ID + * Registers the #GnomeCanvasPixbuf class if necessary, and returns the type ID * associated to it. * - * Return value: The type ID of the &GnomeCanvasPixbuf class. + * Return value: The type ID of the #GnomeCanvasPixbuf class. **/ GtkType gnome_canvas_pixbuf_get_type (void) diff --git a/gdk/gdkpixbuf-render.c b/gdk/gdkpixbuf-render.c index 147403c365..f708a107bb 100644 --- a/gdk/gdkpixbuf-render.c +++ b/gdk/gdkpixbuf-render.c @@ -176,10 +176,12 @@ remove_alpha (ArtPixBuf *apb, int x, int y, int width, int height, int *rowstrid * opacity information for images with an alpha channel; the GC must already * have the clipping mask set if you want transparent regions to show through. * - * For an explanation of dither offsets, see the GdkRGB documentation. In brief, the - * dither offset is important when scrolling (so you can redraw half an image but keep the - * dithering "lined up" between the part you drew first and the part you drew previously). - * For unscrolled images, the offset can always be 0. + * For an explanation of dither offsets, see the GdkRGB documentation. In + * brief, the dither offset is important when re-rendering partial regions of an + * image to a rendered version of the full image, or for when the offsets to a + * base position change, as in scrolling. The dither matrix has to be shifted + * for consistent visual results. If you do not have any of these cases, the + * dither offsets can be both zero. **/ void gdk_pixbuf_render_to_drawable (GdkPixbuf *pixbuf, @@ -254,12 +256,13 @@ gdk_pixbuf_render_to_drawable (GdkPixbuf *pixbuf, * Renders a rectangular portion of a pixbuf to a drawable. This is done using * GdkRGB, so the specified drawable must have the GdkRGB visual and colormap. * - * This function has a performance penalty; it makes two synchronous - * round trips to the X server (creating a bitmask and a GC), and it - * draws the contents of the bitmask. If performance is crucial, - * consider handling alpha yourself and using - * gdk_pixbuf_render_to_drawable(). On the other hand it's more convenient - * than gdk_pixbuf_render_to_drawable() because it handles the alpha channel. + * When used with #GDK_PIXBUF_ALPHA_BILEVEL, this function has to create a bitmap + * out of the thresholded alpha channel of the image and, it has to set this + * bitmap as the clipping mask for the GC used for drawing. This can be a + * significant performance penalty depending on the size and the complexity of + * the alpha channel of the image. If performance is crucial, consider handling + * the alpha channel yourself (possibly by caching it in your application) and + * using gdk_pixbuf_render_to_drawable() or GdkRGB directly instead. **/ void gdk_pixbuf_render_to_drawable_alpha (GdkPixbuf *pixbuf, GdkDrawable *drawable, diff --git a/gtk/gdk-pixbuf-loader.c b/gtk/gdk-pixbuf-loader.c index eecc8a605f..73093c6cf0 100644 --- a/gtk/gdk-pixbuf-loader.c +++ b/gtk/gdk-pixbuf-loader.c @@ -89,10 +89,10 @@ gtk_marshal_NONE__INT_INT_INT_INT (GtkObject *object, GtkSignalFunc func, gpoint * gdk_pixbuf_loader_get_type: * @void: * - * Registers the &GdkPixubfLoader class if necessary, and returns the type ID + * Registers the #GdkPixubfLoader class if necessary, and returns the type ID * associated to it. * - * Return value: The type ID of the &GdkPixbufLoader class. + * Return value: The type ID of the #GdkPixbufLoader class. **/ GtkType gdk_pixbuf_loader_get_type (void)