module_interface.sgml 10.6 KB
Newer Older
1
<!-- ##### SECTION Title ##### -->
2
Module Interface
3 4

<!-- ##### SECTION Short_Description ##### -->
Matthias Clasen's avatar
Matthias Clasen committed
5
Extending &gdk-pixbuf;
6 7 8

<!-- ##### SECTION Long_Description ##### -->
<para>
9 10 11 12 13 14 15 16 17 18 19 20
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>
21 22
function. An external utility, <command>gdk-pixbuf-query-loaders</command>, 
uses this to create a text file containing a list of all available loaders and 
23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
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-2.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</command> to update the
module file (normally
<filename><replaceable>sysconfdir</replaceable>/gtk-2.0/gdk-pixbuf.loaders</filename>,
unless overridden by the environment variable
<envar>GDK_PIXBUF_MODULE_FILE</envar>)
</para></listitem>
</itemizedlist>
</para>
53

54 55 56 57 58 59 60
<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>.
61 62 63 64 65 66 67
</para>

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

</para>

Soeren Sandmann's avatar
Soeren Sandmann committed
68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131
<!-- ##### FUNCTION gdk_pixbuf_set_option ##### -->
<para>

</para>

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


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

</para>

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


Matthias Clasen's avatar
Matthias Clasen committed
132 133 134 135 136 137 138 139 140
<!-- ##### FUNCTION gdk_pixbuf_format_is_scalable ##### -->
<para>

</para>

@format: 
@Returns: 


141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167
<!-- ##### 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: 


Soeren Sandmann's avatar
Soeren Sandmann committed
168 169 170
<!-- ##### STRUCT GdkPixbufFormat ##### -->
<para>
A #GdkPixbufFormat contains information about the image format accepted by a
Matthias Clasen's avatar
Matthias Clasen committed
171 172
module. Only modules should access the fields directly, applications should
use the <function>gdk_pixbuf_format_*</function> functions.
Soeren Sandmann's avatar
Soeren Sandmann committed
173 174
</para>

Matthias Clasen's avatar
Matthias Clasen committed
175 176 177 178
@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.
Soeren Sandmann's avatar
Soeren Sandmann committed
179 180 181
@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.
Matthias Clasen's avatar
Matthias Clasen committed
182
@flags: a combination of #GdkPixbufFormatFlags.
Matthias Clasen's avatar
Updates  
Matthias Clasen committed
183 184 185
@disabled: a boolean determining whether the loader is disabled.
@license: a string containing license information, typically set to 
 shorthands like "GPL", "LGPL", etc.
Matthias Clasen's avatar
Matthias Clasen committed
186
@Since: 2.2
Soeren Sandmann's avatar
Soeren Sandmann committed
187 188 189

<!-- ##### ENUM GdkPixbufFormatFlags ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
190 191
Flags which allow a module to specify further details about the supported
operations.
Soeren Sandmann's avatar
Soeren Sandmann committed
192 193
</para>

Matthias Clasen's avatar
Matthias Clasen committed
194
@GDK_PIXBUF_FORMAT_WRITABLE: the module can write out images in the format.
Matthias Clasen's avatar
Updates  
Matthias Clasen committed
195
@GDK_PIXBUF_FORMAT_SCALABLE: the image format is scalable
196 197 198
@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)
Matthias Clasen's avatar
Matthias Clasen committed
199
@Since: 2.2
Soeren Sandmann's avatar
Soeren Sandmann committed
200 201 202 203

<!-- ##### STRUCT GdkPixbufModulePattern ##### -->
<para>
The signature of a module is a set of prefixes. Prefixes are encoded as
204 205 206 207
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.
Soeren Sandmann's avatar
Soeren Sandmann committed
208 209 210 211 212 213
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>
The signature of a module is stored as an array of 
214 215 216 217 218 219 220 221 222 223 224 225 226
#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>
Soeren Sandmann's avatar
Soeren Sandmann committed
227 228 229 230 231

@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
Matthias Clasen's avatar
Matthias Clasen committed
232 233
@Since: 2.2

Soeren Sandmann's avatar
Soeren Sandmann committed
234 235 236 237 238 239 240
<!-- ##### 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.
Matthias Clasen's avatar
Matthias Clasen committed
241 242
@Since: 2.2

Soeren Sandmann's avatar
Soeren Sandmann committed
243 244 245 246 247 248 249 250

<!-- ##### 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.
Matthias Clasen's avatar
Matthias Clasen committed
251 252
@Since: 2.2

Soeren Sandmann's avatar
Soeren Sandmann committed
253 254 255 256 257 258 259 260 261 262 263 264 265

<!-- ##### 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>
266 267 268 269 270 271
<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>
Soeren Sandmann's avatar
Soeren Sandmann committed
272 273 274 275

@width: pointer to a location containing the current image width
@height: pointer to a location containing the current image height
@user_data: the loader.
Matthias Clasen's avatar
Matthias Clasen committed
276 277
@Since: 2.2

Soeren Sandmann's avatar
Soeren Sandmann committed
278 279 280 281 282 283 284 285 286 287 288 289 290 291 292

<!-- ##### 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.
Matthias Clasen's avatar
Matthias Clasen committed
293 294
@Since: 2.2

Soeren Sandmann's avatar
Soeren Sandmann committed
295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312

<!-- ##### 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.
Matthias Clasen's avatar
Matthias Clasen committed
313 314
@Since: 2.2

Soeren Sandmann's avatar
Soeren Sandmann committed
315

316 317
<!-- ##### STRUCT GdkPixbufModule ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
318 319 320 321 322
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.
323 324 325
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. 
326 327
</para>

Matthias Clasen's avatar
Matthias Clasen committed
328 329
@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".
330
@module_path: the path from which the module is loaded.
331
@module: the loaded #GModule.
332
@info: a #GdkPixbufFormat holding information about the module.
Matthias Clasen's avatar
Matthias Clasen committed
333 334
@load: loads an image from a file.
@load_xpm_data: loads an image from data in memory.
335
@begin_load: begins an incremental load.
Matthias Clasen's avatar
Matthias Clasen committed
336 337 338 339
@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.
Jonathan Blandford's avatar
Jonathan Blandford committed
340
@save_to_callback: 
341

Soeren Sandmann's avatar
Soeren Sandmann committed
342 343
<!-- ##### STRUCT GdkPixbufAnimationClass ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
344 345 346
Modules supporting animations must derive a type from 
#GdkPixbufAnimation, providing suitable implementations of the 
virtual functions.
Soeren Sandmann's avatar
Soeren Sandmann committed
347 348
</para>

Jonathan Blandford's avatar
Jonathan Blandford committed
349
@parent_class: 
Matthias Clasen's avatar
Matthias Clasen committed
350 351 352 353
@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.
Soeren Sandmann's avatar
Soeren Sandmann committed
354 355 356

<!-- ##### STRUCT GdkPixbufAnimationIterClass ##### -->
<para>
Matthias Clasen's avatar
Matthias Clasen committed
357 358 359
Modules supporting animations must derive a type from 
#GdkPixbufAnimationIter, providing suitable implementations of the 
virtual functions.
Soeren Sandmann's avatar
Soeren Sandmann committed
360 361
</para>

Jonathan Blandford's avatar
Jonathan Blandford committed
362
@parent_class: 
Matthias Clasen's avatar
Matthias Clasen committed
363 364 365 366 367 368 369
@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.
Soeren Sandmann's avatar
Soeren Sandmann committed
370