Module Interface Extending &gdk-pixbuf; 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 fill_info and a #GdkPixbufModuleFillVtableFunc function named fill_vtable. 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 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 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 &gdk-pixbuf; can supply a generic #load implementation wrapping the incremental loading. Installing a module is a two-step process: copy the module file(s) to the loader directory (normally libdir/gtk-2.0/version/loaders, unless overridden by the environment variable GDK_PIXBUF_MODULEDIR) call gdk-pixbuf-query-loaders to update the module file (normally sysconfdir/gtk-2.0/gdk-pixbuf.loaders, unless overridden by the environment variable GDK_PIXBUF_MODULE_FILE) The &gdk-pixbuf; 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 &gdk-pixbuf; API. To underline this fact, they are protected by #ifdef GDK_PIXBUF_ENABLE_BACKEND. @pixbuf: @key: @value: @Returns: @Returns: @format: @Returns: @format: @Returns: @format: @Returns: @format: @Returns: @format: @Returns: 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. @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. @Since: 2.2 Flags which allow a module to specify further details about the supported operations. @GDK_PIXBUF_FORMAT_WRITABLE: the module can write out images in the format. @Since: 2.2 The signature of a module is a set of prefixes. Prefixes are encoded as pairs of ordinary strings, where the second string, 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". The signature of a module is stored as an array of #GdkPixbufModulePatterns. The array is terminated by a pattern where the @prefix is %NULL. 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. @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 @Since: 2.2 Defines the type of the function used to set the vtable of a #GdkPixbufModule when it is loaded. @module: a #GdkPixbufModule. @Since: 2.2 Defines the type of the function used to fill a #GdkPixbufFormat structure with information about a module. @info: a #GdkPixbufFormat. @Since: 2.2 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. @width: pointer to a location containing the current image width @height: pointer to a location containing the current image height @user_data: the loader. @Since: 2.2 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 "area_prepared" signal. @pixbuf: the #GdkPixbuf that is currently being loaded. @anim: if an animation is being loaded, the #GdkPixbufAnimation, else %NULL. @user_data: the loader. @Since: 2.2 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 "area_updated" signal. @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. @Since: 2.2 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. @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. Modules supporting animations must derive a type from #GdkPixbufAnimation, providing suitable implementations of the virtual functions. @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 #GdkPixbufAnimationIter, providing suitable implementations of the virtual functions. @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.