From 0ad5532347210a53490734b9b1dda31f73560a4d Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sat, 20 Mar 2021 22:52:01 +0000 Subject: docs: Port to the gi-docgen syntax and style Drop the gtk-doc SECTION markers, and move documentation to classes or separate documents. --- gdk-pixbuf/gdk-pixbuf-animation.c | 27 +++-- gdk-pixbuf/gdk-pixbuf-animation.h | 11 -- gdk-pixbuf/gdk-pixbuf-core.h | 80 +++++++------ gdk-pixbuf/gdk-pixbuf-features.h.in | 20 +--- gdk-pixbuf/gdk-pixbuf-io.c | 109 ++++++++--------- gdk-pixbuf/gdk-pixbuf-io.h | 76 +++++------- gdk-pixbuf/gdk-pixbuf-loader.c | 83 ++++++------- gdk-pixbuf/gdk-pixbuf-loader.h | 8 +- gdk-pixbuf/gdk-pixbuf-scale.c | 43 ------- gdk-pixbuf/gdk-pixbuf-transform.h | 14 ++- gdk-pixbuf/gdk-pixbuf-util.c | 13 -- gdk-pixbuf/gdk-pixbuf.c | 230 +++++++++++++++++++----------------- 12 files changed, 315 insertions(+), 399 deletions(-) (limited to 'gdk-pixbuf') diff --git a/gdk-pixbuf/gdk-pixbuf-animation.c b/gdk-pixbuf/gdk-pixbuf-animation.c index c8f2695e3..9b7372e00 100644 --- a/gdk-pixbuf/gdk-pixbuf-animation.c +++ b/gdk-pixbuf/gdk-pixbuf-animation.c @@ -30,21 +30,30 @@ #include /** - * 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; diff --git a/gdk-pixbuf/gdk-pixbuf-animation.h b/gdk-pixbuf/gdk-pixbuf-animation.h index ad0c39c3b..cae551edd 100644 --- a/gdk-pixbuf/gdk-pixbuf-animation.h +++ b/gdk-pixbuf/gdk-pixbuf-animation.h @@ -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 ()) diff --git a/gdk-pixbuf/gdk-pixbuf-core.h b/gdk-pixbuf/gdk-pixbuf-core.h index e03357d71..4b8c9b9b2 100644 --- a/gdk-pixbuf/gdk-pixbuf-core.h +++ b/gdk-pixbuf/gdk-pixbuf-core.h @@ -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, diff --git a/gdk-pixbuf/gdk-pixbuf-features.h.in b/gdk-pixbuf/gdk-pixbuf-features.h.in index 7efdc0e39..600d03220 100644 --- a/gdk-pixbuf/gdk-pixbuf-features.h.in +++ b/gdk-pixbuf/gdk-pixbuf-features.h.in @@ -7,15 +7,6 @@ #include -/** - * 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. */ /** diff --git a/gdk-pixbuf/gdk-pixbuf-io.c b/gdk-pixbuf/gdk-pixbuf-io.c index 2dc2ea6da..13bf5af16 100644 --- a/gdk-pixbuf/gdk-pixbuf-io.c +++ b/gdk-pixbuf/gdk-pixbuf-io.c @@ -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) { diff --git a/gdk-pixbuf/gdk-pixbuf-io.h b/gdk-pixbuf/gdk-pixbuf-io.h index 89b0830e1..f8270f52c 100644 --- a/gdk-pixbuf/gdk-pixbuf-io.h +++ b/gdk-pixbuf/gdk-pixbuf-io.h @@ -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`. * - * + * ```c * GdkPixbufModulePattern *signature[] = { * { "abcdx", " !x z", 100 }, * { "bla", NULL, 90 }, * { NULL, NULL, 0 } * }; - * - * The example matches e.g. "auud\0" with relevance 100, and "blau" with - * relevance 90. + * ``` + * + * 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 fill_vtable, 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 gdk_pixbuf_format_* 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 */ diff --git a/gdk-pixbuf/gdk-pixbuf-loader.c b/gdk-pixbuf/gdk-pixbuf-loader.c index 81c5afb75..5ef462d0d 100644 --- a/gdk-pixbuf/gdk-pixbuf-loader.c +++ b/gdk-pixbuf/gdk-pixbuf-loader.c @@ -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 + * ## Loading an animation * - * Loading an animation is almost as easy as loading an image. Once the first - * #GdkPixbufLoader::area-prepared signal has been emitted, you can call - * gdk_pixbuf_loader_get_animation() to get the #GdkPixbufAnimation struct - * and gdk_pixbuf_animation_get_iter() to get a #GdkPixbufAnimationIter for - * displaying it. + * Loading an animation is almost as easy as loading an image. Once the + * first [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been + * emitted, you can call [method@GdkPixbuf.PixbufLoader.get_animation] to + * get the [class@GdkPixbuf.PixbufAnimation] instance, and then call + * and [method@GdkPixbuf.PixbufAnimation.get_iter] to get a + * [class@GdkPixbuf.PixbufAnimationIter] to retrieve the pixbuf for the + * desired time stamp. */ diff --git a/gdk-pixbuf/gdk-pixbuf-loader.h b/gdk-pixbuf/gdk-pixbuf-loader.h index 83648205f..1cc34136b 100644 --- a/gdk-pixbuf/gdk-pixbuf-loader.h +++ b/gdk-pixbuf/gdk-pixbuf-loader.h @@ -43,18 +43,12 @@ G_BEGIN_DECLS #define GDK_IS_PIXBUF_LOADER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GDK_TYPE_PIXBUF_LOADER)) #define GDK_PIXBUF_LOADER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GDK_TYPE_PIXBUF_LOADER, GdkPixbufLoaderClass)) -/** - * GdkPixbufLoader: - * - * The GdkPixbufLoader struct contains only private - * fields. - */ typedef struct _GdkPixbufLoader GdkPixbufLoader; struct _GdkPixbufLoader { + /*< private >*/ GObject parent_instance; - /*< private >*/ gpointer priv; }; diff --git a/gdk-pixbuf/gdk-pixbuf-scale.c b/gdk-pixbuf/gdk-pixbuf-scale.c index 84e8e10c3..863de8b83 100644 --- a/gdk-pixbuf/gdk-pixbuf-scale.c +++ b/gdk-pixbuf/gdk-pixbuf-scale.c @@ -25,49 +25,6 @@ #include "gdk-pixbuf-private.h" #include "pixops/pixops.h" -/** - * SECTION:scaling - * @Short_description: Scaling pixbufs and scaling and alpha blending pixbufs - * @Title: Scaling - * - * The GdkPixBuf contains functions 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 (gdk_pixbuf_scale(), - * gdk_pixbuf_composite(), and gdk_pixbuf_composite_color()) are - * rather complex to use and have many arguments, two simple - * convenience functions are provided, gdk_pixbuf_scale_simple() and - * gdk_pixbuf_composite_color_simple() which create a new pixbuf of a - * given size, scale an original image to fit, and then return the - * new pixbuf. - * - * If the destination pixbuf was created from a readonly 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 gdk-pixbuf 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. - */ - - /** * gdk_pixbuf_scale: * @src: a #GdkPixbuf diff --git a/gdk-pixbuf/gdk-pixbuf-transform.h b/gdk-pixbuf/gdk-pixbuf-transform.h index 24e5ad5ae..2ba28c49f 100644 --- a/gdk-pixbuf/gdk-pixbuf-transform.h +++ b/gdk-pixbuf/gdk-pixbuf-transform.h @@ -59,12 +59,13 @@ G_BEGIN_DECLS * **Deprecated**: this interpolation filter is deprecated, as in reality * it has a lower quality than the @GDK_INTERP_BILINEAR filter * (Since: 2.38) - * - * This enumeration describes the different interpolation modes that - * can be used with the scaling functions. @GDK_INTERP_NEAREST is - * the fastest scaling method, but has horrible quality when - * scaling down. @GDK_INTERP_BILINEAR is the best choice if you - * aren't sure what to choose, it has a good speed/quality balance. + * + * Interpolation modes for scaling functions. + * + * The `GDK_INTERP_NEAREST` mode is the fastest scaling method, but has + * horrible quality when scaling down; `GDK_INTERP_BILINEAR` is the best + * choice if you aren't sure what to choose, it has a good speed/quality + * balance. * * **Note**: Cubic filtering is missing from the list; hyperbolic * interpolation is just as fast and results in higher quality. @@ -84,6 +85,7 @@ typedef enum { * @GDK_PIXBUF_ROTATE_CLOCKWISE: Rotate by 270 degrees. * * The possible rotations which can be passed to gdk_pixbuf_rotate_simple(). + * * To make them easier to use, their numerical values are the actual degrees. */ typedef enum { diff --git a/gdk-pixbuf/gdk-pixbuf-util.c b/gdk-pixbuf/gdk-pixbuf-util.c index db1562b76..89d5a9792 100644 --- a/gdk-pixbuf/gdk-pixbuf-util.c +++ b/gdk-pixbuf/gdk-pixbuf-util.c @@ -26,19 +26,6 @@ #include "gdk-pixbuf-transform.h" #include "gdk-pixbuf-private.h" -/** - * SECTION:util - * @Short_description: Utility and miscellaneous convenience functions. - * @Title: Utilities - * @See_also: #GdkPixbuf - * - * These functions provide miscellaneous utilities for manipulating - * pixbufs. The pixel data in pixbufs may of course be manipulated - * directly by applications, but several common operations can be - * performed by these functions instead. - */ - - /** * gdk_pixbuf_add_alpha: * @pixbuf: A #GdkPixbuf. diff --git a/gdk-pixbuf/gdk-pixbuf.c b/gdk-pixbuf/gdk-pixbuf.c index 2594b99e9..383fe024b 100644 --- a/gdk-pixbuf/gdk-pixbuf.c +++ b/gdk-pixbuf/gdk-pixbuf.c @@ -21,152 +21,162 @@ * License along with this library; if not, see . */ -#include "config.h" - -#include -#include -#include - -#define GDK_PIXBUF_C_COMPILATION -#include "gdk-pixbuf-private.h" -#include "gdk-pixbuf-features.h" -#include "gdk-pixbuf-enum-types.h" - -/* Include the marshallers */ -#include -#include -#include "gdk-pixbuf-marshal.h" - /** - * SECTION:creating - * @Short_description: Creating a pixbuf from image data that is already in memory. - * @Title: Image Data in Memory - * @See_also: gdk_pixbuf_finalize(). + * GdkPixbuf: + * + * A pixel buffer. + * + * `GdkPixbuf` contains information about an 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). + * + * ## Creating new `GdkPixbuf` * * The most basic way to create a pixbuf is to wrap an existing pixel - * buffer with a #GdkPixbuf structure. You can use the - * gdk_pixbuf_new_from_data() function to do this You need to specify - * the destroy notification function that will be called when the - * data buffer needs to be freed; this will happen when a #GdkPixbuf - * is finalized by the reference counting functions 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. + * buffer with a [class@GdkPixbuf.Pixbuf] instance. You can use the + * [`ctor@GdkPixbuf.Pixbuf.new_from_data`] function to do this. * - * 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. + * Every time you create a new `GdkPixbuf` instance for some data, you + * will need to specify the destroy notification function that will be + * called when the data buffer needs to be freed; this will happen when + * a `GdkPixbuf` is finalized by the reference counting functions. 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. * - * As a special case, you can use the gdk_pixbuf_new_from_xpm_data() + * The [`ctor@GdkPixbuf.Pixbuf.new`] constructor 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 [`ctor@GdkPixbuf.Pixbuf.new_from_xpm_data`] * function to create a pixbuf from inline XPM image data. * - * You can also copy an existing pixbuf with the gdk_pixbuf_copy() - * function. This is not the same as just doing a g_object_ref() - * on the old pixbuf; the copy function will actually duplicate the - * pixel data in memory and create a new #GdkPixbuf structure for it. - */ - -/** - * SECTION:refcounting - * @Short_description: Functions for reference counting and memory management on pixbufs. - * @Title: Reference Counting and Memory Mangement - * @See_also: #GdkPixbuf, gdk_pixbuf_new_from_data(). + * You can also copy an existing pixbuf with the [method@Pixbuf.copy] + * function. This is not the same as just acquiring a reference to + * the old pixbuf instance: the copy function will actually duplicate + * the pixel data in memory and create a new [class@Pixbuf] instance + * for it. + * + * ## Reference counting * - * #GdkPixbuf structures are reference counted. This means that an + * `GdkPixbuf` structures are reference counted. This means that an * application can share a single pixbuf among many parts of the - * code. When a piece of the program needs to keep a pointer to a - * pixbuf, it should add a reference to it by calling g_object_ref(). - * When it no longer needs the pixbuf, it should subtract a reference - * by calling g_object_unref(). The pixbuf will be destroyed when - * its reference count drops to zero. Newly-created #GdkPixbuf - * structures start with a reference count of one. - * - * > As #GdkPixbuf is derived from #GObject now, gdk_pixbuf_ref() and - * > gdk_pixbuf_unref() are deprecated in favour of g_object_ref() - * > and g_object_unref() resp. - * - * Finalizing a pixbuf means to free its pixel data and to free the - * #GdkPixbuf structure itself. Most of the library functions that - * create #GdkPixbuf structures create the pixel data by themselves - * and define the way it should be freed; you do not need to worry - * about those. - * - * To provide preallocated pixel data, use - * gdk_pixbuf_new_from_bytes(). The gdk_pixbuf_new_from_data() API is - * an older variant that predates the existence of #GBytes. - */ - -/** - * SECTION:gdk-pixbuf - * @Short_description: Information that describes an image. - * @Title: The GdkPixbuf Structure + * code. When a piece of the program needs to use a pixbuf, it should + * acquire a reference to it by calling `g_object_ref()`; when it no + * longer needs the pixbuf, it should release the reference it acquired + * by calling `g_object_unref()`. The resources associated with a + * `GdkPixbuf` will be freed when its reference count drops to zero. + * Newly-created `GdkPixbuf` instances start with a reference count + * of one. * - * The #GdkPixbuf structure contains - * information that describes an image in memory. + * ## Image Data * - * ## Image Data ## {#image-data} + * Image data in a pixbuf is stored in memory in an uncompressed, + * packed format. Rows in the image are stored top to bottom, and + * in each row pixels are stored from left to right. * - * Image data in a pixbuf is stored in memory in uncompressed, - * packed format. Rows in the image are stored top to bottom, and - * in each row pixels are stored from left to right. There may be - * padding at the end of a row. The "rowstride" value of a pixbuf, - * as returned by gdk_pixbuf_get_rowstride(), indicates the number - * of bytes between rows. + * There may be padding at the end of a row. * - * ## put_pixel() Example ## {#put-pixel} + * The "rowstride" value of a pixbuf, as returned by [`method@GdkPixbuf.Pixbuf.get_rowstride`], + * indicates the number of bytes between rows. * - * The following code illustrates a simple put_pixel() + * **NOTE**: If you are copying raw pixbuf data with `memcpy()` note that the + * last row in the pixbuf may not be as wide as the full rowstride, but rather + * just as wide as the pixel data needs to be; that is: it is unsafe to do + * `memcpy (dest, pixels, rowstride * height)` to copy a whole pixbuf. Use + * [method@GdkPixbuf.Pixbuf.copy] instead, or compute the width in bytes of the + * last row as: + * + * ```c + * last_row = width * ((n_channels * bits_per_sample + 7) / 8); + * ``` + * + * The same rule applies when iterating over each row of a `GdkPixbuf` pixels + * array. + * + * The following code illustrates a simple `put_pixel()` * function for RGB pixbufs with 8 bits per channel with an alpha - * channel. It is not included in the gdk-pixbuf library for - * performance reasons; rather than making several function calls - * for each pixel, your own code can take shortcuts. + * channel. * - * |[ + * ```c * static void - * put_pixel (GdkPixbuf *pixbuf, int x, int y, guchar red, guchar green, guchar blue, guchar alpha) + * put_pixel (GdkPixbuf *pixbuf, + * int x, + * int y, + * guchar red, + * guchar green, + * guchar blue, + * guchar alpha) * { - * int width, height, rowstride, n_channels; - * guchar *pixels, *p; - * - * n_channels = gdk_pixbuf_get_n_channels (pixbuf); + * int n_channels = gdk_pixbuf_get_n_channels (pixbuf); * + * // Ensure that the pixbuf is valid * g_assert (gdk_pixbuf_get_colorspace (pixbuf) == GDK_COLORSPACE_RGB); * g_assert (gdk_pixbuf_get_bits_per_sample (pixbuf) == 8); * g_assert (gdk_pixbuf_get_has_alpha (pixbuf)); * g_assert (n_channels == 4); * - * width = gdk_pixbuf_get_width (pixbuf); - * height = gdk_pixbuf_get_height (pixbuf); + * int width = gdk_pixbuf_get_width (pixbuf); + * int height = gdk_pixbuf_get_height (pixbuf); * + * // Ensure that the coordinates are in a valid range * g_assert (x >= 0 && x < width); * g_assert (y >= 0 && y < height); * - * rowstride = gdk_pixbuf_get_rowstride (pixbuf); - * pixels = gdk_pixbuf_get_pixels (pixbuf); + * int rowstride = gdk_pixbuf_get_rowstride (pixbuf); * - * p = pixels + y * rowstride + x * n_channels; + * // The pixel buffer in the GdkPixbuf instance + * guchar *pixels = gdk_pixbuf_get_pixels (pixbuf); + * + * // The pixel we wish to modify + * guchar *p = pixels + y * rowstride + x * n_channels; * p[0] = red; * p[1] = green; * p[2] = blue; * p[3] = alpha; * } - * ]| - * - * This function will not work for pixbufs with images that are - * other than 8 bits per sample or channel, but it will work for - * most of the pixbufs that GTK+ uses. - * - * If you are doing memcpy() of raw pixbuf data, note that the last row - * in the pixbuf may not be as wide as the full rowstride, but rather - * just as wide as the pixel data needs to be. That is, it is unsafe to - * do `memcpy (dest, pixels, rowstride * height)` to copy a whole pixbuf. - * Use gdk_pixbuf_copy() instead, or compute the width in bytes of the - * last row as `width * ((n_channels * bits_per_sample + 7) / 8)`. + * ``` + * + * ## Loading images + * + * The `GdkPixBuf` class provides a simple mechanism for loading + * an image from a file in synchronous and asynchronous fashion. + * + * For GUI applications, it is recommended to use the asynchronous + * stream API to avoid blocking the control flow of the application. + * + * Additionally, `GdkPixbuf` provides the [class@GdkPixbuf.PixbufLoader`] + * API for progressive image loading. + * + * ## Saving images + * + * The `GdkPixbuf` class provides methods for saving image data 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. */ +#include "config.h" + +#include +#include +#include + +#define GDK_PIXBUF_C_COMPILATION +#include "gdk-pixbuf-private.h" +#include "gdk-pixbuf-features.h" +#include "gdk-pixbuf-enum-types.h" + +/* Include the marshallers */ +#include +#include +#include "gdk-pixbuf-marshal.h" + static void gdk_pixbuf_finalize (GObject *object); static void gdk_pixbuf_set_property (GObject *object, guint prop_id, -- cgit v1.2.1