diff --git a/docs/reference/gdk-pixbuf/tmpl/animation.sgml b/docs/reference/gdk-pixbuf/tmpl/animation.sgml
index ff23a56321..07b392bb89 100644
--- a/docs/reference/gdk-pixbuf/tmpl/animation.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/animation.sgml
@@ -22,11 +22,11 @@ Animations as multi-frame structures.
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
+ 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
+ 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
+ it is marked as #GDK_PIXBUF_FRAME_REVERT, then the animation is
reverted to the first image before continuing.
diff --git a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml
index 5638a1f345..e152937007 100644
--- a/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml
+++ b/docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-loader.sgml
@@ -2,17 +2,58 @@
GdkPixbufLoader
-Application-driven image loading.
+Application-driven progressive image loading.
#GdkPixbufLoader provides a way for applications to drive the
- process of loading an image. Applications can use this
- functionality instead of gdk_pixbuf_new_from_file() when they need
- to parse image data in small chunks, such as when reading it from
- a network connection.
+ process of loading an image, by letting them send the image data
+ directly. 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.
-
+
+ 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.
+
+
+ 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.
+
+
+ Loading an animation
+
+ 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
+ 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.
+
+
gdk_pixbuf_new_from_file()
diff --git a/gdk-pixbuf/ChangeLog b/gdk-pixbuf/ChangeLog
index a70ac3822a..620cdf5210 100644
--- a/gdk-pixbuf/ChangeLog
+++ b/gdk-pixbuf/ChangeLog
@@ -1,3 +1,8 @@
+2000-01-07 Jonathan Blandford
+
+ * doc/tmpl/gdk-pixbuf-loader.sgml: much longer long description
+ added.
+
2000-01-05 Owen Taylor
* gdk-pixbuf/pixops/pixops.c (pixops_process): Fix computation of end of run indices.