More docs work - Federico

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_doc_DATA =			\
-	gdk-pixbuf.html		\
+	gdk-pixbuf.html			\
-	gdk-pixbuf.hierarchy	\
+	gdk-pixbuf.hierarchy		\
-	gdk-pixbuf.types	\
+	gdk-pixbuf.types		\
-	gdk-pixbuf-scan.c	\
+	gdk-pixbuf-decl.txt		\
-	gdk-pixbuf-decl.txt	\
 	gdk-pixbuf-sections.txt
 
 EXTRA_DIST = $(gdk_pixbuf_doc_DATA)

docs/reference/gdk-pixbuf/gdk-pixbuf-decl.txt

@@ -24,6 +24,11 @@ GdkPixbufCache *cache,const char *file
 <RETURNS>void </RETURNS>
 GdkPixbuf *pixbuf, gpointer user_data
 </USER_FUNCTION>
+<USER_FUNCTION>
+<NAME>ModuleUpdatedNotifyFunc</NAME>
+<RETURNS>void </RETURNS>
+GdkPixbuf *pixbuf, gpointer user_data, guint x, guint y, guint width, guint height
+</USER_FUNCTION>
 <STRUCT>
 <NAME>GdkPixbufModule</NAME>
 </STRUCT>
@@ -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);
 };

docs/reference/gdk-pixbuf/gdk-pixbuf-sections.txt

@@ -75,6 +75,7 @@ GdkPixbufLoader
 <SECTION>
 <FILE>gdk-pixbuf-io</FILE>
 ModulePreparedNotifyFunc
+ModuleUpdatedNotifyFunc
 GdkPixbufModule
 gdk_pixbuf_get_module
 gdk_pixbuf_load_module

docs/reference/gdk-pixbuf/tmpl/creating.sgml

@@ -1,18 +1,46 @@
 <!-- ##### SECTION Title ##### -->
-Creating a Pixbuf from Data in Memory
+Image Data in Memory
 
 <!-- ##### SECTION Short_Description ##### -->
 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.
+  </para>
+
+  <para>
+    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.
+  </para>
+
+  <para>
+    As a special case, you can use the gdk_pixbuf_new_from_xpm_data()
+    function to create a pixbuf from inline XPM image data.
   </para>
 
 <!-- ##### SECTION See_Also ##### -->
-<para>
+  <para>
-
+    #ArtPixBuf
-</para>
+  </para>
 
 <!-- ##### FUNCTION gdk_pixbuf_new_from_art_pixbuf ##### -->
 <para>
@@ -58,7 +86,7 @@ Creating a pixbuf from image data that is already in memory.
 </para>
 
 @data: 
-@Returns: 
+@Returns:
 
 <!--
 Local variables:
@@ -66,3 +94,5 @@ mode: sgml
 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
 End:
 -->
+
+

docs/reference/gdk-pixbuf/tmpl/file-loading.sgml

@@ -31,7 +31,7 @@ Loading a pixbuf from a file.
 </para>
 
 @filename: 
-@Returns: 
+@Returns:
 
 <!--
 Local variables:
@@ -39,3 +39,5 @@ mode: sgml
 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
 End:
 -->
+
+

docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-io.sgml

@@ -23,6 +23,19 @@ gdk-pixbuf-io
 @user_data: 
 
 
+<!-- ##### USER_FUNCTION ModuleUpdatedNotifyFunc ##### -->
+<para>
+
+</para>
+
+@pixbuf: 
+@user_data: 
+@x: 
+@y: 
+@width: 
+@height: 
+
+
 <!-- ##### STRUCT GdkPixbufModule ##### -->
 <para>
 

docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf.sgml

@@ -34,8 +34,8 @@ the image data.
 
 </para>
 
-@pixbuf:
+@pixbuf: 
-@Returns:
+@Returns: 
 
 
 <!-- ##### FUNCTION gdk_pixbuf_get_n_channels ##### -->
@@ -43,8 +43,8 @@ the image data.
 
 </para>
 
-@pixbuf:
+@pixbuf: 
-@Returns:
+@Returns: 
 
 
 <!-- ##### FUNCTION gdk_pixbuf_get_has_alpha ##### -->
@@ -52,8 +52,8 @@ the image data.
 
 </para>
 
-@pixbuf:
+@pixbuf: 
-@Returns:
+@Returns: 
 
 
 <!-- ##### FUNCTION gdk_pixbuf_get_bits_per_sample ##### -->
@@ -61,8 +61,8 @@ the image data.
 
 </para>
 
-@pixbuf:
+@pixbuf: 
-@Returns:
+@Returns: 
 
 
 <!-- ##### FUNCTION gdk_pixbuf_get_pixels ##### -->
@@ -70,8 +70,8 @@ the image data.
 
 </para>
 
-@pixbuf:
+@pixbuf: 
-@Returns:
+@Returns: 
 
 
 <!-- ##### FUNCTION gdk_pixbuf_get_width ##### -->
@@ -79,8 +79,8 @@ the image data.
 
 </para>
 
-@pixbuf:
+@pixbuf: 
-@Returns:
+@Returns: 
 
 
 <!-- ##### FUNCTION gdk_pixbuf_get_height ##### -->
@@ -88,8 +88,8 @@ the image data.
 
 </para>
 
-@pixbuf:
+@pixbuf: 
-@Returns:
+@Returns: 
 
 
 <!-- ##### FUNCTION gdk_pixbuf_get_rowstride ##### -->
@@ -97,7 +97,7 @@ the image data.
 
 </para>
 
-@pixbuf:
+@pixbuf: 
 @Returns:
 
 <!--
@@ -106,3 +106,5 @@ mode: sgml
 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
 End:
 -->
+
+

docs/reference/gdk-pixbuf/tmpl/gnome-canvas-pixbuf.sgml

@@ -2,46 +2,62 @@
 GnomeCanvasPixbuf
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Canvas item to display #GdkPixbuf images.
 
 <!-- ##### SECTION Long_Description ##### -->
-<para>
+  <para>
+    This canvas item displays #GdkPixbuf images.  It handles full
+    affine transformations in both GDK and antialiased modes, and also
+    supports <ulink
+    url="http://www.w3.org/Graphics/SVG/">SVG</ulink>-like scaling and
+    translation semantics for absolute pixel values.
+  </para>
 
-</para>
+  <para>
+    #GdkPixbuf structures may be shared among different pixbuf canvas
+    items; the pixbuf item uses #GdkPixbuf's reference counting
+    functions for this.
+  </para>
 
 <!-- ##### SECTION See_Also ##### -->
-<para>
+  <para>
-
+    #GnomeCanvas, #GdkPixbuf
-</para>
+  </para>
 
 <!-- ##### MACRO GNOME_CANVAS_PIXBUF ##### -->
-<para>
+  <para>
+    Casts a #GtkOjbect to a #GnomeCanvasPixbuf.
+  </para>
 
-</para>
+@obj: A GTK+ object.
-
-@obj: 
 
 
 <!-- ##### ARG GnomeCanvasPixbuf:pixbuf ##### -->
-<para>
+  <para>
-
+    Contains a pointer to a #GdkPixbuf structure that will be used by
-</para>
+    the pixbuf canvas item as an image source.  When a pixbuf is set
-
+    its reference count is incremented; if the pixbuf item kept a
-<!-- ##### ARG GnomeCanvasPixbuf:width ##### -->
+    pointer to another #GdkPixbuf structure, the reference count of
-<para>
+    this structure will be decremented.  When a pixbuf is queried, a
-
+    reference count will not be added to the return value; you must do
-</para>
+    this yourself if you intend to keep the pixbuf structure around.
+  </para>
 
 <!-- ##### ARG GnomeCanvasPixbuf:width_set ##### -->
-<para>
+  <para>
-
+    Determines whether the 
-</para>
+  </para>
 
 <!-- ##### ARG GnomeCanvasPixbuf:width_pixels ##### -->
 <para>
 
 </para>
 
+<!-- ##### ARG GnomeCanvasPixbuf:width ##### -->
+  <para>
+    Contains the width of the image in the pixbuf canvas item.  
+  </para>
+
 <!-- ##### ARG GnomeCanvasPixbuf:height ##### -->
 <para>
 
@@ -57,3 +73,40 @@ GnomeCanvasPixbuf
 
 </para>
 
+<!-- ##### ARG GnomeCanvasPixbuf:x ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GnomeCanvasPixbuf:x_set ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GnomeCanvasPixbuf:x_pixels ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GnomeCanvasPixbuf:y ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GnomeCanvasPixbuf:y_set ##### -->
+<para>
+
+</para>
+
+<!-- ##### ARG GnomeCanvasPixbuf:y_pixels ##### -->
+<para>
+
+</para>
+
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->

docs/reference/gdk-pixbuf/tmpl/refcounting.sgml

@@ -17,8 +17,7 @@ Functions to perform reference counting on a #GdkPixbuf.
 
 <!-- ##### SECTION See_Also ##### -->
   <para>
-    #GdkPixbuf
+    #GdkPixbuf, #ArtPixBuf
-    #ArtPixBuf
   </para>
 
 <!-- ##### FUNCTION gdk_pixbuf_ref ##### -->
@@ -36,10 +35,11 @@ Functions to perform reference counting on a #GdkPixbuf.
 
 @pixbuf: 
 
-
 <!--
 Local variables:
 mode: sgml
 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
 End:
 -->
+
+

docs/reference/gdk-pixbuf/tmpl/rendering.sgml

@@ -1,26 +1,48 @@
 <!-- ##### SECTION Title ##### -->
-rendering
+Rendering
 
 <!-- ##### SECTION Short_Description ##### -->
-
+Rendering a Pixbuf to a GDK Drawable.
 
 <!-- ##### SECTION Long_Description ##### -->
-<para>
+  <para>
+    The GdkPixbuf library provides several convenience functions to
+    render pixbufs to GDK drawables.  It uses the GdkRGB to render the
+    image data.
+  </para>
 
-</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.
+  </para>
 
 <!-- ##### SECTION See_Also ##### -->
-<para>
+  <para>
-
+    GdkRGB
-</para>
+  </para>
 
 <!-- ##### ENUM GdkPixbufAlphaMode ##### -->
-<para>
+  <para>
+    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.
+  </para>
 
-</para>
+@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
-@GDK_PIXBUF_ALPHA_BILEVEL: 
+will be considered fully transparent, and all others will be
-@GDK_PIXBUF_ALPHA_FULL: 
+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.
 
 <!-- ##### FUNCTION gdk_pixbuf_render_to_drawable_alpha ##### -->
 <para>
@@ -74,6 +96,13 @@ rendering
 @dest_y: 
 @width: 
 @height: 
-@alpha_threshold: 
+@alpha_threshold:
+
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
+End:
+-->
 
 

gdk-pixbuf/ChangeLog

@@ -1,3 +1,9 @@
+1999-11-04  Federico Mena Quintero  <federico@redhat.com>
+
+	* doc/tmpl/rendering.sgml: Populated.
+
+	* doc/Makefile.am: Added the template files.
+
 1999-11-04  Havoc Pennington  <hp@pobox.com>
 
 	* src/gdk-pixbuf-render.c (gdk_pixbuf_render_to_drawable): In

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 *

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)

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
+ * Return value: A newly-created #GdkPixbuf with a reference count of 1, or NULL
- * could be allocated for the image buffer.
+ * if not enough memory could be allocated for the image buffer.
  **/
 GdkPixbuf *
 gdk_pixbuf_new (ArtPixFormat format, gboolean has_alpha, int bits_per_sample,

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)

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
+ * For an explanation of dither offsets, see the GdkRGB documentation.  In
- * dither offset is important when scrolling (so you can redraw half an image but keep the
+ * brief, the dither offset is important when re-rendering partial regions of an
- * dithering "lined up" between the part you drew first and the part you drew previously).
+ * image to a rendered version of the full image, or for when the offsets to a
- * For unscrolled images, the offset can always be 0.
+ * 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
+ * When used with #GDK_PIXBUF_ALPHA_BILEVEL, this function has to create a bitmap
- * round trips to the X server (creating a bitmask and a GC), and it
+ * out of the thresholded alpha channel of the image and, it has to set this
- * draws the contents of the bitmask. If performance is crucial,
+ * bitmap as the clipping mask for the GC used for drawing.  This can be a
- * consider handling alpha yourself and using
+ * significant performance penalty depending on the size and the complexity of
- * gdk_pixbuf_render_to_drawable(). On the other hand it's more convenient
+ * the alpha channel of the image.  If performance is crucial, consider handling
- * than gdk_pixbuf_render_to_drawable() because it handles the alpha channel.
+ * 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,

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)