Commit 80ad1d60 authored by Jon Nordby's avatar Jon Nordby

Documentation: Migrate from old tmpl files.

This puts all the docs that existed in tmpl files when
gdk-pixbuf was moved out of gtk into inline comments.

Fixes: https://bugzilla.gnome.org/show_bug.cgi?id=635643
parent aebd6459
......@@ -33,6 +33,22 @@
#include <X11/Xlib.h>
#include <X11/Xutil.h>
/**
* SECTION:gdk-pixbuf-xlib-from-drawables
* @Short_description: Getting parts of an X drawable's image data into a pixbuf.
* @Title: X Drawables to Pixbufs
*
* The functions in this section allow you to take the image data
* from an X drawable and dump it into a #GdkPixbuf. This can be
* used for screenshots and other special effects. Note that these
* operations can be expensive, since the image data has to be
* transferred from the X server to the client program and converted.
*
*
* These functions are analogous to those for the GDK version of
* &gdk-pixbuf;.
*/
#if (G_BYTE_ORDER == G_LITTLE_ENDIAN)
#define LITTLE
#endif
......
......@@ -25,6 +25,19 @@
#include "config.h"
#include "gdk-pixbuf-xlib-private.h"
/**
* SECTION:gdk-pixbuf-xlib-rendering
* @Short_description: Rendering a pixbuf to an X drawable.
* @Title: Xlib Rendering
*
* The &gdk-pixbuf; Xlib library provides several convenience
* functions to render pixbufs to X drawables. It uses XlibRGB to
* render the image data.
*
*
* These functions are analogous to those for the GDK version of
* &gdk-pixbuf;.
*/
/**
......
......@@ -22,6 +22,21 @@
#include <X11/Xlib.h>
#include "gdk-pixbuf-xlib-private.h"
/**
* SECTION:gdk-pixbuf-xlib-init
* @Short_description: Initializing the &gdk-pixbuf; Xlib library.
* @Title: &gdk-pixbuf; Xlib initialization
* @See_also: XlibRGB
*
* In addition to the normal Gdk-specific functions, the &gdk-pixbuf;
* package provides a small library that lets Xlib-only applications
* use #GdkPixbuf structures and render them to X drawables. The
* functions in this section are used to initialize the &gdk-pixbuf;
* Xlib library. This library must be initialized near the beginning
* of the program or before calling any of the other &gdk-pixbuf;
* Xlib functions.
*/
Display *gdk_pixbuf_dpy = NULL;
int gdk_pixbuf_screen = -1;
......
......@@ -47,6 +47,18 @@
* Shawn T. Amundson <amundson@gtk.org>
*/
/**
* SECTION:gdk-pixbuf-xlib-rgb
* @Short_description: Rendering RGB buffers to X drawables.
* @Title: XlibRGB
* @See_also: GdkRGB
*
* The XlibRGB set of functions is a port of the #GdkRGB library to
* use plain Xlib and X drawables. You can use these functions to
* render RGB buffers into drawables very quickly with high-quality
* dithering.
*/
#if HAVE_CONFIG_H
# include <config.h>
# if STDC_HEADERS
......
......@@ -58,8 +58,14 @@ G_BEGIN_DECLS
#include <X11/Xlib.h>
#include <X11/Xutil.h>
/**
* XlibRgbCmap:
* @colors: FIXME.
* @lut: FIXME.
*
* FIXME: Describe this.
*/
typedef struct _XlibRgbCmap XlibRgbCmap;
struct _XlibRgbCmap {
unsigned int colors[256];
unsigned char lut[256]; /* for 8-bit modes */
......@@ -79,6 +85,23 @@ xlib_rgb_gc_set_foreground (GC gc, guint32 rgb);
void
xlib_rgb_gc_set_background (GC gc, guint32 rgb);
/**
* XlibRgbDither:
* @XLIB_RGB_DITHER_NONE: Specifies no dithering.
* @XLIB_RGB_DITHER_NORMAL: Specifies dithering only on pseudocolor
* displays.
* @XLIB_RGB_DITHER_MAX: Specifies dithering on high color displays.
*
* These values are used to specify which dithering method should be
* used. <symbol>XLIB_RGB_DITHER_NONE</symbol> will use no dithering
* and simply map the colors in an RGB buffer to the closest colors
* that the display can provide.
* <symbol>XLIB_RGB_DITHER_NORMAL</symbol> will provide dithering
* only on pseudocolor displays.
* <symbol>XLIB_RGB_DITHER_MAX</symbol> will provide dithering on
* pseudocolor and 16-bit truecolor or &ldquo;high color&rdquo;
* displays.
*/
typedef enum
{
XLIB_RGB_DITHER_NONE,
......
......@@ -29,6 +29,22 @@
#include <glib/gstdio.h>
/**
* SECTION:animation
* @Short_description: Animated images.
* @Title: Animations
* @See_also: #GdkPixbufLoader.
*
* The &gdk-pixbuf; library provides a simple mechanism to load and represent
* animations. An animation is conceptually a series of frames to be displayed
* over time. Each frame is the same size. 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 &gdk-pixbuf; what should be displayed at a given point in time.
*
*/
typedef struct _GdkPixbufNonAnim GdkPixbufNonAnim;
typedef struct _GdkPixbufNonAnimClass GdkPixbufNonAnimClass;
......
......@@ -38,7 +38,20 @@ 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 ())
......@@ -82,6 +95,18 @@ gboolean gdk_pixbuf_animation_iter_advance (Gd
/**
* GdkPixbufAnimationClass:
* @parent_class: the parent class
* @is_static_image: returns whether the given animation is just a static image.
* @get_static_image: returns a static image representing the given animation.
* @get_size: fills @width and @height with the frame size of the animation.
* @get_iter: returns an iterator for the given animation.
*
* Modules supporting animations must derive a type from
* #GdkPixbufAnimation, providing suitable implementations of the
* virtual functions.
*/
typedef struct _GdkPixbufAnimationClass GdkPixbufAnimationClass;
#define GDK_PIXBUF_ANIMATION_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GDK_TYPE_PIXBUF_ANIMATION, GdkPixbufAnimationClass))
......@@ -114,6 +139,21 @@ struct _GdkPixbufAnimationClass {
/**
* GdkPixbufAnimationIterClass:
* @parent_class: the parent class
* @get_delay_time: returns the time in milliseconds that the current frame
* should be shown.
* @get_pixbuf: returns the current frame.
* @on_currently_loading_frame: returns whether the current frame of @iter is
* being loaded.
* @advance: advances the iterator to @current_time, possibly changing the
* current frame.
*
* Modules supporting animations must derive a type from
* #GdkPixbufAnimationIter, providing suitable implementations of the
* virtual functions.
*/
typedef struct _GdkPixbufAnimationIterClass GdkPixbufAnimationIterClass;
#define GDK_PIXBUF_ANIMATION_ITER_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GDK_TYPE_PIXBUF_ANIMATION_ITER, GdkPixbufAnimationIterClass))
......
......@@ -36,15 +36,122 @@
G_BEGIN_DECLS
/* Alpha compositing mode */
/**
* SECTION:gdk-pixbuf
* @Short_description: Information that describes an image.
* @Title: The GdkPixbuf Structure
*
*
* The #GdkPixbuf structure contains
* information that describes an image in memory.
*
*
* <section id="image-data">
* <title>Image Data</title>
* <para>
* 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.
*
*
* <example id="put-pixel">
* <title>put_pixel(<!-- -->) example</title>
* <para>
*
* 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.
*
*
* <programlisting>
* static void
* 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);
*
* 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);
*
* g_assert (x >= 0 && x < width);
* g_assert (y >= 0 && y < height);
*
* rowstride = gdk_pixbuf_get_rowstride (pixbuf);
* pixels = gdk_pixbuf_get_pixels (pixbuf);
*
* p = pixels + y * rowstride + x * n_channels;
* p[0] = red;
* p[1] = green;
* p[2] = blue;
* p[3] = alpha;
* }
* </programlisting>
*
* 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.
* </para>
* </example>
*
* <note>
* 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 <literal>memcpy (dest,
* pixels, rowstride * height)</literal> to copy a whole pixbuf.
* Use gdk_pixbuf_copy() instead, or compute the width in bytes
* of the last row as <literal>width * ((n_channels *
* bits_per_sample + 7) / 8)</literal>.
* </note>
* </para>
* </section>
*/
/**
* GdkPixbufAlphaMode:
* @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
* will be considered fully transparent, and all others will be
* 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_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.
*/
typedef enum
{
GDK_PIXBUF_ALPHA_BILEVEL,
GDK_PIXBUF_ALPHA_FULL
} GdkPixbufAlphaMode;
/* Color spaces; right now only RGB is supported.
* Note that these values are encoded in inline pixbufs
/**
* GdkColorspace:
* @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.
*/
/* Note that these values are encoded in inline pixbufs
* as ints, so don't reorder them
*/
typedef enum {
......@@ -52,6 +159,16 @@ typedef enum {
} GdkColorspace;
/* 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 ())
......@@ -59,11 +176,43 @@ typedef struct _GdkPixbuf GdkPixbuf;
#define GDK_IS_PIXBUF(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), GDK_TYPE_PIXBUF))
/* Handler that must free the pixel array */
/**
* GdkPixbufDestroyNotify:
* @pixels: The pixel array of the pixbuf that is being finalized.
* @data: 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.
*/
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.
*/
#define GDK_PIXBUF_ERROR gdk_pixbuf_error_quark ()
/**
* GdkPixbufError:
* @GDK_PIXBUF_ERROR_CORRUPT_IMAGE: An image file was broken somehow.
* @GDK_PIXBUF_ERROR_INSUFFICIENT_MEMORY: Not enough memory.
* @GDK_PIXBUF_ERROR_BAD_OPTION: A bad option was passed to a pixbuf save module.
* @GDK_PIXBUF_ERROR_UNKNOWN_TYPE: Unknown image type.
* @GDK_PIXBUF_ERROR_UNSUPPORTED_OPERATION: Don't know how to perform the
* given operation on the type of image at hand.
* @GDK_PIXBUF_ERROR_FAILED: Generic failure code, something went wrong.
*
* 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 */
GDK_PIXBUF_ERROR_CORRUPT_IMAGE,
......@@ -182,13 +331,25 @@ gboolean gdk_pixbuf_savev (GdkPixbuf *pixbuf,
/* Saving to a callback function */
/**
* GdkPixbufSaveFunc:
* @buf:
* @count:
* @error: (out):
* @data: (closure):
**/
* @buf: bytes to be written.
* @count: number of bytes in @buf.
* @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()
* will fail with the same error.
*
* Since: 2.4
* Returns: %TRUE if successful, %FALSE (with @error set) if failed.
*/
typedef gboolean (*GdkPixbufSaveFunc) (const gchar *buf,
gsize count,
GError **error,
......
......@@ -5,6 +5,42 @@
#ifndef GDK_PIXBUF_FEATURES_H
#define GDK_PIXBUF_FEATURES_H 1
/**
* 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:
*
* Major version of &gdk-pixbuf; library, that is the first "0" in
* "0.8.0" for example.
*/
/**
* GDK_PIXBUF_MINOR:
*
* Minor version of &gdk-pixbuf; library, that is the "8" in
* "0.8.0" for example.
*/
/**
* GDK_PIXBUF_MICRO:
*
* Micro version of &gdk-pixbuf; library, that is the last "0" in
* "0.8.0" for example.
*/
/**
* GDK_PIXBUF_VERSION:
*
* Contains the full version of the &gdk-pixbuf; header as a string.
* This is the version being compiled against; contrast with
* #gdk_pixbuf_version.
*/
#define GDK_PIXBUF_MAJOR (@GDK_PIXBUF_MAJOR@)
#define GDK_PIXBUF_MINOR (@GDK_PIXBUF_MINOR@)
#define GDK_PIXBUF_MICRO (@GDK_PIXBUF_MICRO@)
......@@ -31,6 +67,49 @@
# define GDK_PIXBUF_VAR extern
#endif /* !G_PLATFORM_WIN32 */
/**
* gdk_pixbuf_major_version:
*
* The major version number of the &gdk-pixbuf; library. (e.g. in
* &gdk-pixbuf; version 1.2.5 this is 1.)
*
*
* 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; headers you have included.
*/
/**
* gdk_pixbuf_minor_version:
*
* The minor version number of the &gdk-pixbuf; library. (e.g. in
* &gdk-pixbuf; version 1.2.5 this is 2.)
*
*
* 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; headers you have included.
*/
/**
* gdk_pixbuf_micro_version:
*
* The micro version number of the &gdk-pixbuf; library. (e.g. in
* &gdk-pixbuf; version 1.2.5 this is 5.)
*
*
* 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; headers you have included.
*/
/**
* gdk_pixbuf_version:
*
* Contains the full version of the &gdk-pixbuf; library as a string.
* This is the version currently in use by a running program.
*/
GDK_PIXBUF_VAR const guint gdk_pixbuf_major_version;
GDK_PIXBUF_VAR const guint gdk_pixbuf_minor_version;
GDK_PIXBUF_VAR const guint gdk_pixbuf_micro_version;
......
......@@ -49,6 +49,93 @@
#define SNIFF_BUFFER_SIZE 4096
#define LOAD_BUFFER_SIZE 65536
/**
* SECTION:file-loading
* @Short_description: Loading a pixbuf from a file.
* @Title: File Loading
* @See_also: #GdkPixbufLoader.
*
* The &gdk-pixbuf; 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.
*
*
* 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. &gdk-pixbuf; 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 &gdk-pixbuf;
* @Title: Module Interface
*
* If &gdk-pixbuf; 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 <function>fill_info</function> and
* a #GdkPixbufModuleFillVtableFunc function named
* <function>fill_vtable</function>.
*
*
* 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 <function>fill_info</function>
* function. An external utility, <command>gdk-pixbuf-query-loaders</command>,
* 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 &gdk-pixbuf; 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
* <function>fill_vtable</function> 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 &gdk-pixbuf; can
* supply a generic #load implementation wrapping the incremental loading.
*
*
* Installing a module is a two-step process:
* <itemizedlist>
* <listitem><para>copy the module file(s) to the loader directory (normally
* <filename><replaceable>libdir</replaceable>/gtk-2.0/<replaceable>version</replaceable>/loaders</filename>,
* unless overridden by the environment variable
* <envar>GDK_PIXBUF_MODULEDIR</envar>)
* </para></listitem>
* <listitem><para>call <command>gdk-pixbuf-query-loaders</command> to update the
* module file (normally
* <filename><replaceable>sysconfdir</replaceable>/gtk-2.0/gdk-pixbuf.loaders</filename>,
* unless overridden by the environment variable
* <envar>GDK_PIXBUF_MODULE_FILE</envar>)
* </para></listitem>
* </itemizedlist>
*
*
* The &gdk-pixbuf; interfaces needed for implementing modules are contained in
* <filename>gdk-pixbuf-io.h</filename> (and
* <filename>gdk-pixbuf-animation.h</filename> if the module supports animations).
* They are not covered by the same stability guarantees as the regular
* &gdk-pixbuf; API. To underline this fact, they are protected by
* <literal>#ifdef GDK_PIXBUF_ENABLE_BACKEND</literal>.
*/
#ifndef GDK_PIXBUF_USE_GIO_MIME
static gint
format_check (GdkPixbufModule *module, guchar *buffer, int size)
......
......@@ -68,13 +68,69 @@ void gdk_pixbuf_format_free (GdkPixbufFormat *format);
/**
* GdkPixbufModuleSizeFunc:
* @width: pointer to a location containing the current image width
* @height: pointer to a location containing the current image height
* @user_data: the loader.
*
* Defines the type of the function that gets called once the size
* of the loaded image is known.
*
* The function is expected to set @width and @height to the desired
* size to which the image should be scaled. If a module has no efficient
* way to achieve the desired scaling during the loading of the image, it may
* either ignore the size request, or only approximate it -- &gdk-pixbuf; will
* then perform the required scaling on the completely loaded image.
*
* If the function sets @width or @height to zero, the module should interpret
* this as a hint that it will be closed soon and shouldn't allocate further
* resources. This convention is used to implement gdk_pixbuf_get_file_info()
* efficiently.
*
* Since: 2.2
*/
typedef void (* GdkPixbufModuleSizeFunc) (gint *width,
gint *height,
gpointer user_data);
/**
* GdkPixbufModulePreparedFunc:
* @pixbuf: the #GdkPixbuf that is currently being loaded.
* @anim: if an animation is being loaded, the #GdkPixbufAnimation, else %NULL.
* @user_data: the loader.
*
* Defines the type of the function that gets called once the initial
* setup of @pixbuf is done.
*
* #GdkPixbufLoader uses a function of this type to emit the
* "<link linkend="GdkPixbufLoader-area-prepared">area_prepared</link>"
* signal.
*
* Since: 2.2
*/
typedef void (* GdkPixbufModulePreparedFunc) (GdkPixbuf *pixbuf,
GdkPixbufAnimation *anim,
gpointer user_data);
/**
* GdkPixbufModuleUpdatedFunc:
* @pixbuf: the #GdkPixbuf that is currently being loaded.
* @x: the X origin of the updated area.
* @y: the Y origin of the updated area.
* @width: the width of the updated area.
* @height: the height of the updated area.
* @user_data: the loader.
*
* Defines the type of the function that gets called every time a region
* of @pixbuf is updated.
*
* #GdkPixbufLoader uses a function of this type to emit the
* "<link linkend="GdkPixbufLoader-area-updated">area_updated</link>"
* signal.
*
* Since: 2.2
*/
typedef void (* GdkPixbufModuleUpdatedFunc) (GdkPixbuf *pixbuf,
int x,
int y,
......@@ -82,6 +138,43 @@ typedef void (* GdkPixbufModuleUpdatedFunc) (GdkPixbuf *pixbuf,
int height,
gpointer user_data);
/**
* GdkPixbufModulePattern:
* @prefix: the prefix for this pattern
* @mask: mask containing bytes which modify how the prefix is matched against
* test data
* @relevance: relevance of this pattern
*
* 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
* ' ', '!', 'x', 'z', and 'n' to indicate bytes that must be matched,
* not matched, "don't-care"-bytes, zeros and non-zeros.
* 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'.
*
* The signature of a module is stored as an array of
* #GdkPixbufModulePattern<!-- -->s. The array is terminated by a pattern
* where the @prefix is %NULL.
*
*
* <informalexample><programlisting>
* 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>
*
* Since: 2.2
*/
typedef struct _GdkPixbufModulePattern GdkPixbufModulePattern;
struct _GdkPixbufModulePattern {
char *prefix;
......@@ -89,6 +182,30 @@ 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.
*
* 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;
......@@ -141,7 +258,27 @@ struct _GdkPixbufModule {