[~andy/gtk] / docs / reference / gdk-pixbuf / tmpl / module_interface.sgml

<!-- ##### SECTION Title ##### -->
Module Interface

<!-- ##### SECTION Short_Description ##### -->
Extending &gdk-pixbuf;

<!-- ##### SECTION Long_Description ##### -->
<para>
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>.
</para>

<para>
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-3.0</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.
</para>

<para>
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.
</para>

<para>
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-3.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-3.0</command> to update the
module file (normally
<filename><replaceable>libdir</replaceable>/gtk-3.0/<replaceable>version</replaceable>/loaders.cache</filename>,
unless overridden by the environment variable
<envar>GDK_PIXBUF_MODULE_FILE</envar>)
</para></listitem>
</itemizedlist>
</para>

<para>
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>.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### SECTION Image ##### -->


<!-- ##### FUNCTION gdk_pixbuf_set_option ##### -->
<para>

</para>

@pixbuf: 
@key: 
@value: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_get_formats ##### -->
<para>

</para>

@void: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_format_get_name ##### -->
<para>

</para>

@format: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_format_get_description ##### -->
<para>

</para>

@format: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_format_get_mime_types ##### -->
<para>

</para>

@format: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_format_get_extensions ##### -->
<para>

</para>

@format: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_format_is_writable ##### -->
<para>

</para>

@format: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_format_is_scalable ##### -->
<para>

</para>

@format: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_format_is_disabled ##### -->
<para>

</para>

@format: 
@Returns: 


<!-- ##### FUNCTION gdk_pixbuf_format_set_disabled ##### -->
<para>

</para>

@format: 
@disabled: 


<!-- ##### FUNCTION gdk_pixbuf_format_get_license ##### -->
<para>

</para>

@format: 
@Returns: 


<!-- ##### STRUCT GdkPixbufFormat ##### -->
<para>
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.
</para>

@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.
@license: a string containing license information, typically set to
 shorthands like "GPL", "LGPL", etc.
@Since: 2.2

<!-- ##### ENUM GdkPixbufFormatFlags ##### -->
<para>
Flags which allow a module to specify further details about the supported
operations.
</para>

@GDK_PIXBUF_FORMAT_WRITABLE: the module can write out images in the format.
@GDK_PIXBUF_FORMAT_SCALABLE: the image format is scalable
@GDK_PIXBUF_FORMAT_THREADSAFE: the module is threadsafe. If this flag is not
  set, &gdk-pixbuf; will use a lock to prevent multiple threads from using
  this module at the same time. (Since 2.6)
@Since: 2.2

<!-- ##### STRUCT GdkPixbufModulePattern ##### -->
<para>
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".
</para>
<para>
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'.
</para>
<para>
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.
</para>

<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>

@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

<!-- ##### USER_FUNCTION GdkPixbufModuleFillVtableFunc ##### -->
<para>
Defines the type of the function used to set the vtable of a
#GdkPixbufModule when it is loaded.
</para>

@module: a #GdkPixbufModule.
@Since: 2.2


<!-- ##### USER_FUNCTION GdkPixbufModuleFillInfoFunc ##### -->
<para>
Defines the type of the function used to fill a
#GdkPixbufFormat structure with information about a module.
</para>

@info: a #GdkPixbufFormat.
@Since: 2.2


<!-- ##### USER_FUNCTION GdkPixbufModuleSizeFunc ##### -->
<para>
Defines the type of the function that gets called once the size
of the loaded image is known.
</para>
<para>
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.
</para>
<para>
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.
</para>

@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


<!-- ##### USER_FUNCTION GdkPixbufModulePreparedFunc ##### -->
<para>
Defines the type of the function that gets called once the initial
setup of @pixbuf is done.
</para>
<para>
#GdkPixbufLoader uses a function of this type to emit the
"<link linkend="GdkPixbufLoader-area-prepared">area_prepared</link>"
signal.
</para>

@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


<!-- ##### USER_FUNCTION GdkPixbufModuleUpdatedFunc ##### -->
<para>
Defines the type of the function that gets called every time a region
of @pixbuf is updated.
</para>
<para>
#GdkPixbufLoader uses a function of this type to emit the
"<link linkend="GdkPixbufLoader-area-updated">area_updated</link>"
signal.
</para>

@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


<!-- ##### STRUCT GdkPixbufModule ##### -->
<para>
A #GdkPixbufModule contains the necessary functions to load and save
images in a certain file format.
</para>
<para>
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.
</para>

@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.

<!-- ##### STRUCT GdkPixbufAnimationClass ##### -->
<para>
Modules supporting animations must derive a type from
#GdkPixbufAnimation, providing suitable implementations of the
virtual functions.
</para>

@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.

<!-- ##### STRUCT GdkPixbufAnimationIterClass ##### -->
<para>
Modules supporting animations must derive a type from
#GdkPixbufAnimationIter, providing suitable implementations of the
virtual functions.
</para>

@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.