
@c %start of fragment

@node GdkPixbufLoader
@chapter GdkPixbufLoader
Application-driven progressive image loading.

@section Overview
@code{<gdk-pixbuf-loader>} provides a way for applications to drive the process
of loading an image, by letting them send the image data directly to the loader
instead of having the loader read the data from a file. Applications can use
this functionality instead of @code{gdk-pixbuf-new-from-file} or
@code{gdk-pixbuf-animation-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 @code{<gdk-pixbuf-loader>} to load an image, just create a new one, and
call @code{gdk-pixbuf-loader-write} to send the data to it. When done,
@code{gdk-pixbuf-loader-close} should be called to end the stream and finalize
everything. The loader will emit three important signals throughout the process.
The first, "size_prepared", will be called as soon as the image has enough
information to determine the size of the image to be used. If you want to scale
the image while loading it, you can call @code{gdk-pixbuf-loader-set-size} in
response to this signal.

The second signal, "area_prepared", will be called as soon as the pixbuf of the
desired has been allocated. You can obtain it by calling
@code{gdk-pixbuf-loader-get-pixbuf}. If you want to use it, 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 @code{gdk-pixbuf-loader-get-pixbuf} later and get the same pixbuf.

The last 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.

@section Loading an animation
Loading an animation is almost as easy as loading an image. Once the first
"area_prepared" signal has been emitted, you can call
@code{gdk-pixbuf-loader-get-animation} to get the @code{<gdk-pixbuf-animation>}
struct and @code{gdk-pixbuf-animation-get-iter} to get an
@code{<gdk-pixbuf-animation-iter>} for displaying it.

@section Usage
@include defuns-gdk-pixbuf-loader.xml.texi

@c %end of fragment
