gdk-pixbuf-Module-Interface: Module Interface
Detailed Description
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 fillInfo
and
a GdkPixbufModuleFillVtableFunc
function named
fillVtable
. 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 fillInfo
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
fillVtable
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,
unless overridden by the environment variable
GDK_PIXBUF_MODULEDIR)
- call
gdk-pixbuf-query-loaders
to update the
module file (normally
sysconfdir,
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
.User Functions
GdkPixbufModuleFillVtableFunc(module)
-
Defines the type of the function used to set the vtable of a
GdkPixbufModule
when it is loaded.
Since 2.2
GdkPixbufModuleFillInfoFunc(info)
-
Defines the type of the function used to fill a
GdkPixbufFormat
structure with information about a module.
Since 2.2
GdkPixbufModuleSizeFunc(width, height, user.data)
-
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 gdkPixbufGetFileInfo
efficiently.
Since 2.2
width
- pointer to a location containing the current image width
height
- pointer to a location containing the current image height
user.data
- the loader.
GdkPixbufModulePreparedFunc(pixbuf, anim, user.data)
-
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.
Since 2.2
pixbuf
- the
GdkPixbuf
that is currently being loaded. anim
- if an animation is being loaded, the
GdkPixbufAnimation
, else NULL
. user.data
- the loader.
GdkPixbufModuleUpdatedFunc(pixbuf, x, y, width, height, user.data)
-
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.
Since 2.2
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.