Commit 0ad55323 authored by Emmanuele Bassi's avatar Emmanuele Bassi 👣
Browse files

docs: Port to the gi-docgen syntax and style

Drop the gtk-doc SECTION markers, and move documentation to classes or
separate documents.
parent 0c545e3f
......@@ -40,6 +40,9 @@ content_images = [
'composite.png',
'gnome-gmush-1.png',
]
content_files = [
'scaling-compositing.md',
]
[[object]]
name = "PIXBUF_DEPRECATED_IN_2_0_FOR"
......
......@@ -14,6 +14,7 @@ gidocgen = find_program('gi-docgen', required: get_option('gtk_doc'))
docs_dir = gdk_pixbuf_datadir / 'doc/gdk-pixbuf/reference'
expand_content_md_files = [
'scaling-compositing.md',
]
build_docs = get_option('gtk_doc')
......
Title: Scaling and compositing
----
The `GdkPixBuf` class contains methods to scale pixbufs, to scale
pixbufs and alpha blend against an existing image, and to scale
pixbufs and alpha blend against a solid color or checkerboard.
Alpha blending a checkerboard is a common way to show an image with
an alpha channel in image-viewing and editing software.
Note that in these functions, the terms ‘alpha blending’ and ‘compositing’
are used synonymously.
Since the full-featured functions [method@GdkPixbuf.Pixbuf.scale],
[method@GdkPixbuf.Pixbuf.composite], and [`method@GdkPixbuf.Pixbuf.composite_color`]
are rather complex to use and have many arguments, two simple
convenience functions are provided, [`method@GdkPixbuf.Pixbuf.scale_simple`]
and [`method@GdkPixbuf.Pixbuf.composite_color_simple`] which create a new
pixbuf of a given size, scale an original image to fit, and then return it.
If the destination pixbuf was created from a read only source, these
operations will force a copy into a mutable buffer.
Scaling and alpha blending functions take advantage of MMX hardware
acceleration on systems where MMX is supported. If `GdkPixbuf` is built
with the Sun mediaLib library, these functions are instead accelerated
using mediaLib, which provides hardware acceleration on Intel, AMD,
and Sparc chipsets. If desired, mediaLib support can be turned off by
setting the `GDK_DISABLE_MEDIALIB` environment variable.
The alpha blending function used is:
```
Cd = Cs·As + Cd(1-As)
```
where `Cd` is the destination pixel color, `Cs` is the source pixel color,
and `As` is the source pixel alpha.
**NOTE**: It is recommended to use [Cairo][cairo] for scaling and
compositing, by using the contents of a `GdkPixbuf` pixel buffer as the
data for a Cairo image surface.
[cairo]: https://www.cairographics.org
......@@ -30,21 +30,30 @@
#include <glib/gstdio.h>
/**
* SECTION:animation
* @Short_description: Animated images.
* @Title: Animations
* @See_also: #GdkPixbufLoader.
* GdkPixbufAnimation:
*
* An opaque object representing an animation.
*
* The GdkPixBuf library provides a simple mechanism to load and
* represent animations. An animation is conceptually a series of
* frames to be displayed over time. The animation may not be
* represented as a series of frames internally; for example, it may
* be stored as a sprite and instructions for moving the sprite around
* a background. To display an animation you don't need to understand
* its representation, however; you just ask GdkPixBuf what should
* frames to be displayed over time.
*
* The animation may not be represented as a series of frames
* internally; for example, it may be stored as a sprite and
* instructions for moving the sprite around a background.
*
* To display an animation you don't need to understand its
* representation, however; you just ask `GdkPixbuf` what should
* be displayed at a given point in time.
*/
/**
* GdkPixbufAnimationIter:
*
* An opaque object representing an iterator which points to a
* certain position in an animation.
*/
typedef struct _GdkPixbufNonAnim GdkPixbufNonAnim;
typedef struct _GdkPixbufNonAnimClass GdkPixbufNonAnimClass;
......
......@@ -36,20 +36,9 @@ G_BEGIN_DECLS
/* Animation support */
/**
* GdkPixbufAnimation:
*
* An opaque struct representing an animation.
*/
typedef struct _GdkPixbufAnimation GdkPixbufAnimation;
/**
* GdkPixbufAnimationIter:
*
* An opaque struct representing an iterator which points to a
* certain position in an animation.
*/
typedef struct _GdkPixbufAnimationIter GdkPixbufAnimationIter;
#define GDK_TYPE_PIXBUF_ANIMATION (gdk_pixbuf_animation_get_type ())
......
......@@ -44,17 +44,23 @@ G_BEGIN_DECLS
* 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.
*
* These values can be passed to
* gdk_pixbuf_xlib_render_to_drawable_alpha() to control how the alpha
* channel 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.
*
* Deprecated: 2.42: There is no user of GdkPixbufAlphaMode
* Control the alpha channel for drawables.
*
* These values can be passed to gdk_pixbuf_xlib_render_to_drawable_alpha()
* in gdk-pixbuf-xlib to control how the alpha channel 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.
*
* Deprecated: 2.42: There is no user of GdkPixbufAlphaMode in GdkPixbuf,
* and the Xlib utility functions have been split out to their own
* library, gdk-pixbuf-xlib
*/
typedef enum
{
......@@ -67,7 +73,9 @@ typedef enum
* @GDK_COLORSPACE_RGB: Indicates a red/green/blue additive color space.
*
* This enumeration defines the color spaces that are supported by
* the gdk-pixbuf library. Currently only RGB is supported.
* the gdk-pixbuf library.
*
* Currently only RGB is supported.
*/
/* Note that these values are encoded in inline pixbufs
* as ints, so don't reorder them
......@@ -78,15 +86,6 @@ typedef enum {
/* All of these are opaque structures */
/**
* GdkPixbuf:
*
* This is the main structure in the gdk-pixbuf 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 (the number of bytes between the start of
* one row and the start of the next).
*/
typedef struct _GdkPixbuf GdkPixbuf;
#define GDK_TYPE_PIXBUF (gdk_pixbuf_get_type ())
......@@ -101,20 +100,23 @@ typedef struct _GdkPixbuf GdkPixbuf;
* @data: (closure): User closure data.
*
* 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.
* 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 type `GdkPixbufDestroyNotify` so that
* the pixel data can be freed when the pixbuf is finalized.
*/
typedef void (* GdkPixbufDestroyNotify) (guchar *pixels, gpointer data);
/**
* GDK_PIXBUF_ERROR:
*
* Error domain used for pixbuf operations. Indicates that the error code
* will be in the #GdkPixbufError enumeration. See #GError for
* information on error domains and error codes.
* Error domain used for pixbuf operations.
*
* Indicates that the error code will be in the `GdkPixbufError` enumeration.
*
* See the `GError` for information on error domains and error codes.
*/
#define GDK_PIXBUF_ERROR gdk_pixbuf_error_quark ()
......@@ -129,9 +131,10 @@ typedef void (* GdkPixbufDestroyNotify) (guchar *pixels, gpointer data);
* @GDK_PIXBUF_ERROR_FAILED: Generic failure code, something went wrong.
* @GDK_PIXBUF_ERROR_INCOMPLETE_ANIMATION: Only part of the animation was loaded.
*
* An error code in the #GDK_PIXBUF_ERROR domain. Many gdk-pixbuf
* operations can cause errors in this domain, or in the #G_FILE_ERROR
* domain.
* An error code in the `GDK_PIXBUF_ERROR` domain.
*
* Many gdk-pixbuf operations can cause errors in this domain, or in
* the `G_FILE_ERROR` domain.
*/
typedef enum {
/* image data hosed */
......@@ -347,15 +350,18 @@ gboolean gdk_pixbuf_savev_utf8 (GdkPixbuf *pixbuf,
* @error: (out): A location to return an error.
* @data: (closure): user data passed to gdk_pixbuf_save_to_callback().
*
* Specifies the type of the function passed to
* gdk_pixbuf_save_to_callback(). It is called once for each block of
* bytes that is "written" by gdk_pixbuf_save_to_callback(). If
* successful it should return %TRUE. If an error occurs it should set
* @error and return %FALSE, in which case gdk_pixbuf_save_to_callback()
* Save functions used by [method@GdkPixbuf.Pixbuf.save_to_callback].
*
* This function is called once for each block of bytes that is "written"
* by `gdk_pixbuf_save_to_callback()`.
*
* If successful it should return `TRUE`; if an error occurs it should set
* `error` and return `FALSE`, in which case `gdk_pixbuf_save_to_callback()`
* will fail with the same error.
*
* Returns: `TRUE` if successful, `FALSE` otherwise
*
* Since: 2.4
* Returns: %TRUE if successful, %FALSE (with @error set) if failed.
*/
typedef gboolean (*GdkPixbufSaveFunc) (const gchar *buf,
......
......@@ -7,15 +7,6 @@
#include <glib.h>
/**
* SECTION:initialization_versions
* @Short_description: Library version numbers.
* @Title: Initialization and Versions
*
* These macros and variables let you check the version of gdk-pixbuf
* you're linking against.
*/
/**
* GDK_PIXBUF_MAJOR:
*
......@@ -37,9 +28,10 @@
/**
* GDK_PIXBUF_VERSION:
*
* Contains the full version of the gdk-pixbuf header as a string.
* Contains the full version of GdkPixbuf as a string.
*
* This is the version being compiled against; contrast with
* #gdk_pixbuf_version.
* `gdk_pixbuf_version`.
*/
#define GDK_PIXBUF_MAJOR (@GDK_PIXBUF_MAJOR@)
......@@ -81,7 +73,7 @@
*
* This variable is in the library, so represents the
* gdk-pixbuf library you have linked against. Contrast with the
* #GDK_PIXBUF_MAJOR macro, which represents the major version of the
* `GDK_PIXBUF_MAJOR` macro, which represents the major version of the
* gdk-pixbuf headers you have included.
*/
/**
......@@ -93,7 +85,7 @@
*
* This variable is in the library, so represents the
* gdk-pixbuf library you have linked against. Contrast with the
* #GDK_PIXBUF_MINOR macro, which represents the minor version of the
* `GDK_PIXBUF_MINOR` macro, which represents the minor version of the
* gdk-pixbuf headers you have included.
*/
/**
......@@ -105,7 +97,7 @@
*
* This variable is in the library, so represents the
* gdk-pixbuf library you have linked against. Contrast with the
* #GDK_PIXBUF_MICRO macro, which represents the micro version of the
* `GDK_PIXBUF_MICRO` macro, which represents the micro version of the
* gdk-pixbuf headers you have included.
*/
/**
......
......@@ -48,80 +48,69 @@
#endif
/**
* SECTION:file-loading
* @Short_description: Loading a pixbuf from a file.
* @Title: File Loading
* @See_also: #GdkPixbufLoader.
* GdkPixbufModule:
* @module_name: the name of the module, usually the same as the
* usual file extension for images of this type, eg. "xpm", "jpeg" or "png".
* @module_path: the path from which the module is loaded.
* @module: the loaded #GModule.
* @info: a #GdkPixbufFormat holding information about the module.
* @load: loads an image from a file.
* @load_xpm_data: loads an image from data in memory.
* @begin_load: begins an incremental load.
* @stop_load: stops an incremental load.
* @load_increment: continues an incremental load.
* @load_animation: loads an animation from a file.
* @save: saves a #GdkPixbuf to a file.
* @save_to_callback: saves a #GdkPixbuf by calling the given #GdkPixbufSaveFunc.
* @is_save_option_supported: returns whether a save option key is supported by the module
*
* 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.
* A `GdkPixbufModule` contains the necessary functions to load and save
* images in a certain file format.
*
* If `GdkPixbuf` has been compiled with `GModule` support, it can be extended
* by modules which can load (and perhaps also save) new image and animation
* formats.
*
* ## Implementing modules
*
* This interface can be used by applications in which blocking is
* acceptable while an image is being loaded. It can also be used to
* load small images in general. Applications that need progressive
* loading can use the #GdkPixbufLoader functionality instead.
*/
/**
* SECTION:file-saving
* @Short_description: Saving a pixbuf to a file.
* @Title: File saving
*
* These functions allow to save a #GdkPixbuf in a number of
* file formats. The formatted data can be written to a file
* or to a memory buffer. GdkPixBuf can also call a user-defined
* callback on the data, which allows to e.g. write the image
* to a socket or store it in a database.
*/
/**
* SECTION:module_interface
* @Short_description: Extending GdkPixBuf
* @Title: Module Interface
*
* If GdkPixBuf has been compiled with GModule support, it can be extended by
* modules which can load (and perhaps also save) new image and animation
* formats. Each loadable module must export a
* #GdkPixbufModuleFillInfoFunc function named `fill_info` and
* a #GdkPixbufModuleFillVtableFunc function named
* `fill_vtable`.
* The `GdkPixbuf` interfaces needed for implementing modules are contained in
* `gdk-pixbuf-io.h` (and `gdk-pixbuf-animation.h` if the module supports
* animations). They are not covered by the same stability guarantees as the
* regular GdkPixbuf API. To underline this fact, they are protected by the
* `GDK_PIXBUF_ENABLE_BACKEND` pre-processor symbol.
*
* Each loadable module must contain a `GdkPixbufModuleFillVtableFunc` function
* named `fill_vtable`, which will get called when the module
* is loaded and must set the function pointers of the `GdkPixbufModule`.
*
* In order to make format-checking work before actually loading the modules
* (which may require dlopening image libraries), modules export their
* signatures (and other information) via the `fill_info` function. An
* external utility, gdk-pixbuf-query-loaders, uses this to create a text
* (which may require calling `dlopen` to load image libraries), modules export
* their signatures (and other information) via the `fill_info` function. An
* external utility, `gdk-pixbuf-query-loaders`, uses this to create a text
* file containing a list of all available loaders and their signatures.
* This file is then read at runtime by GdkPixBuf to obtain the list of
* This file is then read at runtime by `GdkPixbuf` to obtain the list of
* available loaders and their signatures.
*
* Modules may only implement a subset of the functionality available via
* #GdkPixbufModule. If a particular functionality is not implemented, the
* `GdkPixbufModule`. If a particular functionality is not implemented, the
* `fill_vtable` function will simply not set the corresponding
* function pointers of the #GdkPixbufModule structure. If a module supports
* incremental loading (i.e. provides #begin_load, #stop_load and
* #load_increment), it doesn't have to implement #load, since GdkPixBuf can
* supply a generic #load implementation wrapping the incremental loading.
* function pointers of the `GdkPixbufModule` structure. If a module supports
* incremental loading (i.e. provides `begin_load`, `stop_load` and
* `load_increment`), it doesn't have to implement `load`, since `GdkPixbuf`
* can supply a generic `load` implementation wrapping the incremental loading.
*
* ## Installing modules
*
* Installing a module is a two-step process:
* - copy the module file(s) to the loader directory (normally
* `$libdir/gdk-pixbuf-2.0/$version/loaders`, unless overridden by the
* environment variable `GDK_PIXBUF_MODULEDIR`)
* - call gdk-pixbuf-query-loaders to update the module file (normally
* `$libdir/gdk-pixbuf-2.0/$version/loaders.cache`, unless overridden by the
* environment variable `GDK_PIXBUF_MODULE_FILE`)
*
* The GdkPixBuf interfaces needed for implementing modules are contained in
* `gdk-pixbuf-io.h` (and `gdk-pixbuf-animation.h` if the module supports
* animations). They are not covered by the same stability guarantees as the
* regular GdkPixBuf API. To underline this fact, they are protected by
* `#ifdef GDK_PIXBUF_ENABLE_BACKEND`.
*
* - copy the module file(s) to the loader directory (normally
* `$libdir/gdk-pixbuf-2.0/$version/loaders`, unless overridden by the
* environment variable `GDK_PIXBUF_MODULEDIR`)
* - call `gdk-pixbuf-query-loaders` to update the module file (normally
* `$libdir/gdk-pixbuf-2.0/$version/loaders.cache`, unless overridden
* by the environment variable `GDK_PIXBUF_MODULE_FILE`)
*/
static gint
format_check (GdkPixbufModule *module, guchar *buffer, int size)
{
......
......@@ -173,34 +173,37 @@ typedef void (* GdkPixbufModuleUpdatedFunc) (GdkPixbuf *pixbuf,
* @mask: mask containing bytes which modify how the prefix is matched against
* test data
* @relevance: relevance of this pattern
*
* The signature prefix for a module.
*
* The signature of a module is a set of prefixes. Prefixes are encoded as
* pairs of ordinary strings, where the second string, called the mask, if
* not %NULL, must be of the same length as the first one and may contain
* not `NULL`, must be of the same length as the first one and may contain
* ' ', '!', 'x', 'z', and 'n' to indicate bytes that must be matched,
* not matched, "don't-care"-bytes, zeros and non-zeros.
* not matched, "don't-care"-bytes, zeros and non-zeros, respectively.
*
* Each prefix has an associated integer that describes the relevance of
* the prefix, with 0 meaning a mismatch and 100 a "perfect match".
*
* Starting with gdk-pixbuf 2.8, the first byte of the mask may be '*',
* indicating an unanchored pattern that matches not only at the beginning,
* but also in the middle. Versions prior to 2.8 will interpret the '*'
* like an 'x'.
* like an 'x'.
*
* The signature of a module is stored as an array of
* #GdkPixbufModulePatterns. The array is terminated by a pattern
* where the @prefix is %NULL.
*
* `GdkPixbufModulePatterns`. The array is terminated by a pattern
* where the `prefix` is `NULL`.
*
* <informalexample><programlisting>
* ```c
* GdkPixbufModulePattern *signature[] = {
* { "abcdx", " !x z", 100 },
* { "bla", NULL, 90 },
* { NULL, NULL, 0 }
* };
* </programlisting>
* The example matches e.g. "auud\0" with relevance 100, and "blau" with
* relevance 90.</informalexample>
* ```
*
* In the example above, the signature matches e.g. "auud\0" with
* relevance 100, and "blau" with relevance 90.
*
* Since: 2.2
*/
......@@ -211,31 +214,6 @@ struct _GdkPixbufModulePattern {
int relevance;
};
/**
* GdkPixbufModule:
* @module_name: the name of the module, usually the same as the
* usual file extension for images of this type, eg. "xpm", "jpeg" or "png".
* @module_path: the path from which the module is loaded.
* @module: the loaded #GModule.
* @info: a #GdkPixbufFormat holding information about the module.
* @load: loads an image from a file.
* @load_xpm_data: loads an image from data in memory.
* @begin_load: begins an incremental load.
* @stop_load: stops an incremental load.
* @load_increment: continues an incremental load.
* @load_animation: loads an animation from a file.
* @save: saves a #GdkPixbuf to a file.
* @save_to_callback: saves a #GdkPixbuf by calling the given #GdkPixbufSaveFunc.
* @is_save_option_supported: returns whether a save option key is supported by the module
*
* A #GdkPixbufModule contains the necessary functions to load and save
* images in a certain file format.
*
* A #GdkPixbufModule can be loaded dynamically from a #GModule.
* Each loadable module must contain a #GdkPixbufModuleFillVtableFunc function
* named <function>fill_vtable</function>, which will get called when the module
* is loaded and must set the function pointers of the #GdkPixbufModule.
*/
typedef struct _GdkPixbufModule GdkPixbufModule;
struct _GdkPixbufModule {
char *module_name;
......@@ -332,21 +310,23 @@ typedef enum /*< skip >*/
/**
* GdkPixbufFormat:
* @name: the name of the image format.
* @signature: the signature of the module.
* @domain: the message domain for the @description.
* @description: a description of the image format.
* @mime_types: a %NULL-terminated array of MIME types for the image format.
* @extensions: a %NULL-terminated array of typical filename extensions for the
* image format.
* @flags: a combination of #GdkPixbufFormatFlags.
* @disabled: a boolean determining whether the loader is disabled.
* @name: the name of the image format
* @signature: the signature of the module
* @domain: the message domain for the `description`
* @description: a description of the image format
* @mime_types: (array zero-terminated=1): the MIME types for the image format
* @extensions: (array zero-terminated=1): typical filename extensions for the
* image format
* @flags: a combination of `GdkPixbufFormatFlags`
* @disabled: a boolean determining whether the loader is disabled`
* @license: a string containing license information, typically set to
* shorthands like "GPL", "LGPL", etc.
* shorthands like "GPL", "LGPL", etc.
*
* A #GdkPixbufFormat contains information about the image format accepted by a
* module. Only modules should access the fields directly, applications should
* use the <function>gdk_pixbuf_format_*</function> functions.
* A `GdkPixbufFormat` contains information about the image format accepted
* by a module.
*
* Only modules should access the fields directly, applications should
* use the `gdk_pixbuf_format_*` family of functions.
*
* Since: 2.2
*/
......
......@@ -32,52 +32,53 @@
#include "gdk-pixbuf-marshal.h"
/**
* SECTION:gdk-pixbuf-loader
* @Short_description: Application-driven progressive image loading.
* @Title: GdkPixbufLoader
* @See_also: gdk_pixbuf_new_from_file(), gdk_pixbuf_animation_new_from_file()
* GdkPixbufLoader:
*
* Incremental image loader.
*
* #GdkPixbufLoader provides a way for applications to drive the
* `GdkPixbufLoader` 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
* gdk_pixbuf_new_from_file() or 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 #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 three important signals
* throughout the process. The first, #GdkPixbufLoader::size-prepared,
* will be emitted 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 gdk_pixbuf_loader_set_size()
* in response to this signal.
*
*
* The second signal, #GdkPixbufLoader::area-prepared, will be emitted as
* soon as the pixbuf of the desired has been allocated. You can obtain it
* by calling gdk_pixbuf_loader_get_pixbuf(). If you want to use it, simply
* ref it. You can also call gdk_pixbuf_loader_get_pixbuf() later and get
* the same pixbuf.
*
* The last signal, #GdkPixbufLoader::area-updated, gets emitted 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 updated area. For example, in an interlaced image, you need to
* make several passes before the image is done loading.
* from a file. Applications can use this functionality instead of
* `gdk_pixbuf_new_from_file()` or `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 `GdkPixbufLoader` to load an image, create a new instance,
* and call [method@GdkPixbuf.PixbufLoader.write] to send the data
* to it. When done, [method@GdkPixbuf.PixbufLoader.close] should be
* called to end the stream and finalize everything.
*
* The loader will emit three important signals throughout the process:
*
* - [signal@GdkPixbuf.PixbufLoader::size-prepared] will be emitted 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 [method@GdkPixbuf.PixbufLoader.set_size] in
* response to this signal.
* - [signal@GdkPixbuf.PixbufLoader::area-prepared] will be emitted as
* soon as the pixbuf of the desired has been allocated. You can obtain
* the `GdkPixbuf` instance by calling [method@GdkPixbuf.PixbufLoader.get_pixbuf].
* If you want to use it, simply acquire a reference to it. You can
* also call `gdk_pixbuf_loader_get_pixbuf()` later to get the same
* pixbuf.
* - [signal@GdkPixbuf.PixbufLoader::area-updated] will be emitted 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 updated area. For example, in an
* interlaced image you will need to make several passes before the
* image is done loading.
*
* # Loading an animation