## Module Interface

Module Interface — Extending GdkPixBuf

## Functions

gboolean | gdk_pixbuf_init_modules ()
GSList * | gdk_pixbuf_get_formats ()
GdkPixbufFormat * | gdk_pixbuf_format_copy ()
void | gdk_pixbuf_format_free ()
gchar * | gdk_pixbuf_format_get_name ()
gchar * | gdk_pixbuf_format_get_description ()
gchar ** | gdk_pixbuf_format_get_mime_types ()
gchar ** | gdk_pixbuf_format_get_extensions ()
gboolean | gdk_pixbuf_format_is_save_option_supported ()
gboolean | gdk_pixbuf_format_is_writable ()
gboolean | gdk_pixbuf_format_is_scalable ()
gboolean | gdk_pixbuf_format_is_disabled ()
void | gdk_pixbuf_format_set_disabled ()
gchar * | gdk_pixbuf_format_get_license ()
void | (*GdkPixbufModuleFillVtableFunc) ()
void | (*GdkPixbufModuleFillInfoFunc) ()
void | (*GdkPixbufModuleSizeFunc) ()
void | (*GdkPixbufModulePreparedFunc) ()
void | (*GdkPixbufModuleUpdatedFunc) ()

## Types and Values

struct | GdkPixbufFormat
enum | GdkPixbufFormatFlags
struct | GdkPixbufModulePattern
struct | GdkPixbufModule
struct | GdkPixbufAnimationClass
struct | GdkPixbufAnimationIterClass

## Object Hierarchy

        GBoxed
        ╰── GdkPixbufFormat

## Includes

    #include <gdk-pixbuf/gdk-pixdata.h>

## Description

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

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 `#ifdef GDK_PIXBUF_ENABLE_BACKEND`.

## Functions

### gdk_pixbuf_init_modules ()

    gboolean
    gdk_pixbuf_init_modules (const char *path,
                             GError **error);

Initalizes the gdk-pixbuf loader modules referenced by the loaders.cache file present inside that directory.

This is to be used by applications that want to ship certain loaders in a different location from the system ones.

This is needed when the OS or runtime ships a minimal number of loaders so as to reduce the potential attack surface of carefully crafted image files, especially for uncommon file types. Applications that require broader image file types coverage, such as image viewers, would be expected to ship the gdk-pixbuf modules in a separate location, bundled with the application in a separate directory from the OS or runtime- provided modules.

#### Parameters

path | Path to directory where the loaders.cache is installed |
error | return location for a GError |

Since: 2.40

### gdk_pixbuf_get_formats ()

    GSList *
    gdk_pixbuf_get_formats (void);

Obtains the available information about the image formats supported by GdkPixbuf.

#### Returns

A list of GdkPixbufFormats describing the supported image formats. The list should be freed when it is no longer needed, but the structures themselves are owned by GdkPixbuf and should not be freed.

[transfer container][element-type GdkPixbufFormat]

Since: 2.2

### gdk_pixbuf_format_copy ()

    GdkPixbufFormat *
    gdk_pixbuf_format_copy (const GdkPixbufFormat *format);

Creates a copy of `format`

#### Parameters

format | a GdkPixbufFormat |

#### Returns

the newly allocated copy of a GdkPixbufFormat. Use `gdk_pixbuf_format_free()` to free the resources when done

Since: 2.22

### gdk_pixbuf_format_free ()

    void
    gdk_pixbuf_format_free (GdkPixbufFormat *format);

Frees the resources allocated when copying a GdkPixbufFormat using `gdk_pixbuf_format_copy()`

#### Parameters

format | a GdkPixbufFormat |

Since: 2.22

### gdk_pixbuf_format_get_name ()

    gchar *
    gdk_pixbuf_format_get_name (GdkPixbufFormat *format);

Returns the name of the format.

#### Parameters

format | a GdkPixbufFormat |

#### Returns

the name of the format.

Since: 2.2

### gdk_pixbuf_format_get_description ()

    gchar *
    gdk_pixbuf_format_get_description (GdkPixbufFormat *format);

Returns a description of the format.

#### Parameters

format | a GdkPixbufFormat |

#### Returns

a description of the format.

Since: 2.2

### gdk_pixbuf_format_get_mime_types ()

    gchar **
    gdk_pixbuf_format_get_mime_types (GdkPixbufFormat *format);

Returns the mime types supported by the format.

#### Parameters

format | a GdkPixbufFormat |

#### Returns

a `NULL`-terminated array of mime types which must be freed with `g_strfreev()` when it is no longer needed.

[transfer full]

Since: 2.2

### gdk_pixbuf_format_get_extensions ()

    gchar **
    gdk_pixbuf_format_get_extensions (GdkPixbufFormat *format);

Returns the filename extensions typically used for files in the given format.

#### Parameters

format | a GdkPixbufFormat |

#### Returns

a `NULL`-terminated array of filename extensions which must be freed with `g_strfreev()` when it is no longer needed.

[transfer full]

Since: 2.2

### gdk_pixbuf_format_is_save_option_supported ()

    gboolean
    gdk_pixbuf_format_is_save_option_supported
                                   (GdkPixbufFormat *format,
                                    const gchar *option_key);

Returns `TRUE` if the save option specified by `option_key` is supported when saving a pixbuf using the module implementing `format` . See `gdk_pixbuf_save()` for more information about option keys.

#### Parameters

format | a GdkPixbufFormat |
option_key | the name of an option |

#### Returns

`TRUE` if the specified option is supported

Since: 2.36

### gdk_pixbuf_format_is_writable ()

    gboolean
    gdk_pixbuf_format_is_writable (GdkPixbufFormat *format);

Returns whether pixbufs can be saved in the given format.

#### Parameters

format | a GdkPixbufFormat |

#### Returns

whether pixbufs can be saved in the given format.

Since: 2.2

### gdk_pixbuf_format_is_scalable ()

    gboolean
    gdk_pixbuf_format_is_scalable (GdkPixbufFormat *format);

Returns whether this image format is scalable. If a file is in a scalable format, it is preferable to load it at the desired size, rather than loading it at the default size and scaling the resulting pixbuf to the desired size.

#### Parameters

format | a GdkPixbufFormat |

#### Returns

whether this image format is scalable.

Since: 2.6

### gdk_pixbuf_format_is_disabled ()

    gboolean
    gdk_pixbuf_format_is_disabled (GdkPixbufFormat *format);

Returns whether this image format is disabled. See `gdk_pixbuf_format_set_disabled()`.

#### Parameters

format | a GdkPixbufFormat |

#### Returns

whether this image format is disabled.

Since: 2.6

### gdk_pixbuf_format_set_disabled ()

    void
    gdk_pixbuf_format_set_disabled (GdkPixbufFormat *format,
                                    gboolean disabled);

Disables or enables an image format. If a format is disabled, gdk-pixbuf won't use the image loader for this format to load images. Applications can use this to avoid using image loaders with an inappropriate license, see `gdk_pixbuf_format_get_license()`.

#### Parameters

format | a GdkPixbufFormat |
disabled | `TRUE` to disable the format `format` |

Since: 2.6

### gdk_pixbuf_format_get_license ()

    gchar *
    gdk_pixbuf_format_get_license (GdkPixbufFormat *format);

Returns information about the license of the image loader for the format. The returned string should be a shorthand for a wellknown license, e.g. "LGPL", "GPL", "QPL", "GPL/QPL", or "other" to indicate some other license. This string should be freed with `g_free()` when it's no longer needed.

#### Parameters

format | a GdkPixbufFormat |

#### Returns

a string describing the license of `format` .

Since: 2.6

### GdkPixbufModuleFillVtableFunc ()

    void
    (*GdkPixbufModuleFillVtableFunc) (GdkPixbufModule *module);

Defines the type of the function used to set the vtable of a GdkPixbufModule when it is loaded.

#### Parameters

module | a GdkPixbufModule. |

Since: 2.2

### GdkPixbufModuleFillInfoFunc ()

    void
    (*GdkPixbufModuleFillInfoFunc) (GdkPixbufFormat *info);

Defines the type of the function used to fill a GdkPixbufFormat structure with information about a module.

#### Parameters

info | a GdkPixbufFormat. |

Since: 2.2

### GdkPixbufModuleSizeFunc ()

    void
    (*GdkPixbufModuleSizeFunc) (gint *width,
                                gint *height,
                                gpointer 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 `gdk_pixbuf_get_file_info()` efficiently.

#### Parameters

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

### GdkPixbufModulePreparedFunc ()

    void
    (*GdkPixbufModulePreparedFunc) (GdkPixbuf *pixbuf,
                                    GdkPixbufAnimation *anim,
                                    gpointer 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.

#### Parameters

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

### GdkPixbufModuleUpdatedFunc ()

    void
    (*GdkPixbufModuleUpdatedFunc) (GdkPixbuf *pixbuf,
                                   int x,
                                   int y,
                                   int width,
                                   int height,
                                   gpointer 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.

#### Parameters

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

## Types and Values

### struct GdkPixbufFormat

    struct GdkPixbufFormat {
      gchar *name;
      GdkPixbufModulePattern *signature;
      gchar *domain;
      gchar *description;
      gchar **mime_types;
      gchar **extensions;
      guint32 flags;
      gboolean disabled;
      gchar *license;
    };

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.

#### Members

gchar *`name`; | the name of the image format. |
GdkPixbufModulePattern *`signature`; | the signature of the module. |
gchar *`domain`; | the message domain for the `description` . |
gchar *`description`; | a description of the image format. |
gchar **`mime_types`; | a `NULL`-terminated array of MIME types for the image format. |
gchar **`extensions`; | a `NULL`-terminated array of typical filename extensions for the image format. |
guint32 `flags`; | a combination of GdkPixbufFormatFlags. |
gboolean `disabled`; | a boolean determining whether the loader is disabled. |
gchar *`license`; | a string containing license information, typically set to shorthands like "GPL", "LGPL", etc. |

Since: 2.2

### enum GdkPixbufFormatFlags

Flags which allow a module to specify further details about the supported operations.

#### Members

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. gdk-pixbuf ignores modules that are not marked as threadsafe. (Since 2.28). |

Since: 2.2

### struct GdkPixbufModulePattern

    struct GdkPixbufModulePattern {
    	char *prefix;
    	char *mask;
    	int relevance;
    };

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

#### Members

char *`prefix`; | the prefix for this pattern |
char *`mask`; | mask containing bytes which modify how the prefix is matched against test data |
int `relevance`; | relevance of this pattern |

Since: 2.2

### struct GdkPixbufModule

    struct GdkPixbufModule {
    	char *module_name;
    	char *module_path;
    	GModule *module;
    	GdkPixbufFormat *info;

            GdkPixbuf *(* load) (FILE    *f,
                                 GError **error);
            GdkPixbuf *(* load_xpm_data) (const char **data);

            /* Incremental loading */

            gpointer (* begin_load)     (GdkPixbufModuleSizeFunc size_func,
                                         GdkPixbufModulePreparedFunc prepare_func,
                                         GdkPixbufModuleUpdatedFunc update_func,
                                         gpointer user_data,
                                         GError **error);
            gboolean (* stop_load)      (gpointer context,
                                         GError **error);
            gboolean (* load_increment) (gpointer      context,
                                         const guchar *buf,
                                         guint         size,
                                         GError      **error);

    	/* Animation loading */
    	GdkPixbufAnimation *(* load_animation) (FILE    *f,
                                                    GError **error);

            /* Saving */
            gboolean (* save) (FILE      *f,
                               GdkPixbuf *pixbuf,
                               gchar    **param_keys,
                               gchar    **param_values,
                               GError   **error);

            gboolean (*save_to_callback) (GdkPixbufSaveFunc save_func,
    				      gpointer user_data,
    				      GdkPixbuf *pixbuf,
    				      gchar **option_keys,
    				      gchar **option_values,
    				      GError **error);

            gboolean (* is_save_option_supported) (const gchar *option_key);
    };

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.

#### Members

char *`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". |
char *`module_path`; | the path from which the module is loaded. |
GModule *`module`; | the loaded GModule. |
GdkPixbufFormat *`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. |
`is_save_option_supported` () | returns whether a save option key is supported by the module |

### struct GdkPixbufAnimationClass

    struct GdkPixbufAnimationClass {
            GObjectClass parent_class;

            gboolean                (*is_static_image)  (GdkPixbufAnimation *anim);

            GdkPixbuf*              (*get_static_image) (GdkPixbufAnimation *anim);

            void                    (*get_size) (GdkPixbufAnimation *anim,
                                                 int                 *width,
                                                 int                 *height);

            GdkPixbufAnimationIter* (*get_iter) (GdkPixbufAnimation *anim,
                                                 const GTimeVal     *start_time);
    };

Modules supporting animations must derive a type from GdkPixbufAnimation, providing suitable implementations of the virtual functions.

#### Members

`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

    struct GdkPixbufAnimationIterClass {
            GObjectClass parent_class;

            int        (*get_delay_time)   (GdkPixbufAnimationIter *iter);

            GdkPixbuf* (*get_pixbuf)       (GdkPixbufAnimationIter *iter);

            gboolean   (*on_currently_loading_frame) (GdkPixbufAnimationIter *iter);

            gboolean   (*advance)          (GdkPixbufAnimationIter *iter,
                                            const GTimeVal         *current_time);
    };

Modules supporting animations must derive a type from GdkPixbufAnimationIter, providing suitable implementations of the virtual functions.

#### Members

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