:right-sidebar: True

PixbufModule
===================================================================

.. currentmodule:: gi.repository.GdkPixbuf





.. class:: PixbufModule(*args, **kwargs)
   :no-contents-entry:






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

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 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
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 ``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``\)












Fields
------

.. rst-class:: interim-class

.. class:: PixbufModule
   :no-index:
   

   .. attribute:: begin_load

      Begins an incremental load.






   .. attribute:: info

      A ``GdkPixbufFormat`` holding information about the module.






   .. attribute:: is_save_option_supported

      Returns whether a save option key is supported by the module






   .. attribute:: load

      Loads an image from a file.






   .. attribute:: load_animation

      Loads an animation from a file.






   .. attribute:: load_increment

      Continues an incremental load.






   .. attribute:: load_xpm_data

      Loads an image from data in memory.






   .. attribute:: module

      The loaded ``GModule``\.






   .. attribute:: 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".






   .. attribute:: module_path

      The path from which the module is loaded.






   .. attribute:: save

      Saves a ``GdkPixbuf`` to a file.






   .. attribute:: save_to_callback

      Saves a ``GdkPixbuf`` by calling the given ``GdkPixbufSaveFunc``\.






   .. attribute:: stop_load

      Stops an incremental load.