Pileus Git - ~andy/gtk/blob - docs/reference/gdk-pixbuf/tmpl/module_interface.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Module Interface
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Extending &gdk-pixbuf;
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 If &gdk-pixbuf; has been compiled with GModule support, it can be extended by
  10 modules which can load (and perhaps also save) new image and animation
  11 formats. Each loadable module must export a
  12 #GdkPixbufModuleFillInfoFunc function named <function>fill_info</function> and
  13 a #GdkPixbufModuleFillVtableFunc function named
  14 <function>fill_vtable</function>.
  15 </para>
  16
  17 <para>
  18 In order to make format-checking work before actually loading the modules
  19 (which may require dlopening image libraries), modules export their
  20 signatures (and other information) via the <function>fill_info</function>
  21 function. An external utility, <command>gdk-pixbuf-query-loaders</command>,
  22 uses this to create a text file containing a list of all available loaders and
  23 their signatures. This file is then read at runtime by &gdk-pixbuf; to obtain
  24 the list of available loaders and their signatures.
  25 </para>
  26
  27 <para>
  28 Modules may only implement a subset of the functionality available via
  29 #GdkPixbufModule. If a particular functionality is not implemented, the
  30 <function>fill_vtable</function> function will simply not set the corresponding
  31 function pointers of the #GdkPixbufModule structure. If a module supports
  32 incremental loading (i.e. provides #begin_load, #stop_load and
  33 #load_increment), it doesn't have to implement #load, since &gdk-pixbuf; can
  34 supply a generic #load implementation wrapping the incremental loading.
  35 </para>
  36
  37 <para>
  38 Installing a module is a two-step process:
  39 <itemizedlist>
  40 <listitem><para>copy the module file(s) to the loader directory (normally
  41 <filename><replaceable>libdir</replaceable>/gtk-2.0/<replaceable>version</replaceable>/loaders</filename>,
  42 unless overridden by the environment variable
  43 <envar>GDK_PIXBUF_MODULEDIR</envar>)
  44 </para></listitem>
  45 <listitem><para>call <command>gdk-pixbuf-query-loaders</command> to update the
  46 module file (normally
  47 <filename><replaceable>sysconfdir</replaceable>/gtk-2.0/gdk-pixbuf.loaders</filename>,
  48 unless overridden by the environment variable
  49 <envar>GDK_PIXBUF_MODULE_FILE</envar>)
  50 </para></listitem>
  51 </itemizedlist>
  52 </para>
  53
  54 <para>
  55 The &gdk-pixbuf; interfaces needed for implementing modules are contained in
  56 <filename>gdk-pixbuf-io.h</filename> (and
  57 <filename>gdk-pixbuf-animation.h</filename> if the module supports animations).
  58 They are not covered by the same stability guarantees as the regular
  59 &gdk-pixbuf; API. To underline this fact, they are protected by
  60 <literal>#ifdef GDK_PIXBUF_ENABLE_BACKEND</literal>.
  61 </para>
  62
  63 <!-- ##### SECTION See_Also ##### -->
  64 <para>
  65
  66 </para>
  67
  68 <!-- ##### SECTION Stability_Level ##### -->
  69
  70
  71 <!-- ##### FUNCTION gdk_pixbuf_set_option ##### -->
  72 <para>
  73
  74 </para>
  75
  76 @pixbuf:
  77 @key:
  78 @value:
  79 @Returns:
  80
  81
  82 <!-- ##### FUNCTION gdk_pixbuf_get_formats ##### -->
  83 <para>
  84
  85 </para>
  86
  87 @Returns:
  88
  89
  90 <!-- ##### FUNCTION gdk_pixbuf_format_get_name ##### -->
  91 <para>
  92
  93 </para>
  94
  95 @format:
  96 @Returns:
  97
  98
  99 <!-- ##### FUNCTION gdk_pixbuf_format_get_description ##### -->
 100 <para>
 101
 102 </para>
 103
 104 @format:
 105 @Returns:
 106
 107
 108 <!-- ##### FUNCTION gdk_pixbuf_format_get_mime_types ##### -->
 109 <para>
 110
 111 </para>
 112
 113 @format:
 114 @Returns:
 115
 116
 117 <!-- ##### FUNCTION gdk_pixbuf_format_get_extensions ##### -->
 118 <para>
 119
 120 </para>
 121
 122 @format:
 123 @Returns:
 124
 125
 126 <!-- ##### FUNCTION gdk_pixbuf_format_is_writable ##### -->
 127 <para>
 128
 129 </para>
 130
 131 @format:
 132 @Returns:
 133
 134
 135 <!-- ##### FUNCTION gdk_pixbuf_format_is_scalable ##### -->
 136 <para>
 137
 138 </para>
 139
 140 @format:
 141 @Returns:
 142
 143
 144 <!-- ##### FUNCTION gdk_pixbuf_format_is_disabled ##### -->
 145 <para>
 146
 147 </para>
 148
 149 @format:
 150 @Returns:
 151
 152
 153 <!-- ##### FUNCTION gdk_pixbuf_format_set_disabled ##### -->
 154 <para>
 155
 156 </para>
 157
 158 @format:
 159 @disabled:
 160
 161
 162 <!-- ##### FUNCTION gdk_pixbuf_format_get_license ##### -->
 163 <para>
 164
 165 </para>
 166
 167 @format:
 168 @Returns:
 169
 170
 171 <!-- ##### STRUCT GdkPixbufFormat ##### -->
 172 <para>
 173 A #GdkPixbufFormat contains information about the image format accepted by a
 174 module. Only modules should access the fields directly, applications should
 175 use the <function>gdk_pixbuf_format_*</function> functions.
 176 </para>
 177
 178 @name: the name of the image format.
 179 @signature: the signature of the module.
 180 @domain: the message domain for the @description.
 181 @description: a description of the image format.
 182 @mime_types: a %NULL-terminated array of MIME types for the image format.
 183 @extensions: a %NULL-terminated array of typical filename extensions for the
 184 image format.
 185 @flags: a combination of #GdkPixbufFormatFlags.
 186 @disabled: a boolean determining whether the loader is disabled.
 187 @license: a string containing license information, typically set to
 188  shorthands like "GPL", "LGPL", etc.
 189 @Since: 2.2
 190
 191 <!-- ##### ENUM GdkPixbufFormatFlags ##### -->
 192 <para>
 193 Flags which allow a module to specify further details about the supported
 194 operations.
 195 </para>
 196
 197 @GDK_PIXBUF_FORMAT_WRITABLE: the module can write out images in the format.
 198 @GDK_PIXBUF_FORMAT_SCALABLE: the image format is scalable
 199 @GDK_PIXBUF_FORMAT_THREADSAFE: the module is threadsafe. If this flag is not
 200   set, &gdk-pixbuf; will use a lock to prevent multiple threads from using
 201   this module at the same time. (Since 2.6)
 202 @Since: 2.2
 203
 204 <!-- ##### STRUCT GdkPixbufModulePattern ##### -->
 205 <para>
 206 The signature of a module is a set of prefixes. Prefixes are encoded as
 207 pairs of ordinary strings, where the second string, called the mask, if
 208 not %NULL, must be of the same length as the first one and may contain
 209 ' ', '!', 'x', 'z', and 'n' to indicate bytes that must be matched,
 210 not matched, "don't-care"-bytes, zeros and non-zeros.
 211 Each prefix has an associated integer that describes the relevance of
 212 the prefix, with 0 meaning a mismatch and 100 a "perfect match".
 213 </para>
 214 <para>
 215 Starting with &gdk-pixbuf; 2.8, the first byte of the mask may be '*',
 216 indicating an unanchored pattern that matches not only at the beginning,
 217 but also in the middle. Versions prior to 2.8 will interpret the '*'
 218 like an 'x'.
 219 </para>
 220 <para>
 221 The signature of a module is stored as an array of
 222 #GdkPixbufModulePattern<!-- -->s. The array is terminated by a pattern
 223 where the @prefix is %NULL.
 224 </para>
 225
 226 <informalexample><programlisting>
 227 GdkPixbufModulePattern *signature[] = {
 228   { "abcdx", " !x z", 100 },
 229   { "bla", NULL,  90 },
 230   { NULL, NULL, 0 }
 231 };
 232 </programlisting>
 233 The example matches e.g. "auud\0" with relevance 100, and "blau" with
 234 relevance 90.</informalexample>
 235
 236 @prefix: the prefix for this pattern
 237 @mask: mask containing bytes which modify how the prefix is matched against
 238   test data
 239 @relevance: relevance of this pattern
 240 @Since: 2.2
 241
 242 <!-- ##### USER_FUNCTION GdkPixbufModuleFillVtableFunc ##### -->
 243 <para>
 244 Defines the type of the function used to set the vtable of a
 245 #GdkPixbufModule when it is loaded.
 246 </para>
 247
 248 @module: a #GdkPixbufModule.
 249 @Since: 2.2
 250
 251
 252 <!-- ##### USER_FUNCTION GdkPixbufModuleFillInfoFunc ##### -->
 253 <para>
 254 Defines the type of the function used to fill a
 255 #GdkPixbufFormat structure with information about a module.
 256 </para>
 257
 258 @info: a #GdkPixbufFormat.
 259 @Since: 2.2
 260
 261
 262 <!-- ##### USER_FUNCTION GdkPixbufModuleSizeFunc ##### -->
 263 <para>
 264 Defines the type of the function that gets called once the size
 265 of the loaded image is known.
 266 </para>
 267 <para>
 268 The function is expected to set @width and @height to the desired
 269 size to which the image should be scaled. If a module has no efficient
 270 way to achieve the desired scaling during the loading of the image, it may
 271 either ignore the size request, or only approximate it -- &gdk-pixbuf; will
 272 then perform the required scaling on the completely loaded image.
 273 </para>
 274 <para>
 275 If the function sets @width or @height to zero, the module should interpret
 276 this as a hint that it will be closed soon and shouldn't allocate further
 277 resources. This convention is used to implement gdk_pixbuf_get_file_info()
 278 efficiently.
 279 </para>
 280
 281 @width: pointer to a location containing the current image width
 282 @height: pointer to a location containing the current image height
 283 @user_data: the loader.
 284 @Since: 2.2
 285
 286
 287 <!-- ##### USER_FUNCTION GdkPixbufModulePreparedFunc ##### -->
 288 <para>
 289 Defines the type of the function that gets called once the initial
 290 setup of @pixbuf is done.
 291 </para>
 292 <para>
 293 #GdkPixbufLoader uses a function of this type to emit the
 294 "<link linkend="GdkPixbufLoader-area-prepared">area_prepared</link>"
 295 signal.
 296 </para>
 297
 298 @pixbuf: the #GdkPixbuf that is currently being loaded.
 299 @anim: if an animation is being loaded, the #GdkPixbufAnimation, else %NULL.
 300 @user_data: the loader.
 301 @Since: 2.2
 302
 303
 304 <!-- ##### USER_FUNCTION GdkPixbufModuleUpdatedFunc ##### -->
 305 <para>
 306 Defines the type of the function that gets called every time a region
 307 of @pixbuf is updated.
 308 </para>
 309 <para>
 310 #GdkPixbufLoader uses a function of this type to emit the
 311 "<link linkend="GdkPixbufLoader-area-updated">area_updated</link>"
 312 signal.
 313 </para>
 314
 315 @pixbuf: the #GdkPixbuf that is currently being loaded.
 316 @x: the X origin of the updated area.
 317 @y: the Y origin of the updated area.
 318 @width: the width of the updated area.
 319 @height: the height of the updated area.
 320 @user_data: the loader.
 321 @Since: 2.2
 322
 323
 324 <!-- ##### STRUCT GdkPixbufModule ##### -->
 325 <para>
 326 A #GdkPixbufModule contains the necessary functions to load and save
 327 images in a certain file format.
 328 </para>
 329 <para>
 330 A #GdkPixbufModule can be loaded dynamically from a #GModule.
 331 Each loadable module must contain a #GdkPixbufModuleFillVtableFunc function
 332 named <function>fill_vtable</function>, which will get called when the module
 333 is loaded and must set the function pointers of the #GdkPixbufModule.
 334 </para>
 335
 336 @module_name: the name of the module, usually the same as the
 337   usual file extension for images of this type, eg. "xpm", "jpeg" or "png".
 338 @module_path: the path from which the module is loaded.
 339 @module: the loaded #GModule.
 340 @info: a #GdkPixbufFormat holding information about the module.
 341 @load: loads an image from a file.
 342 @load_xpm_data: loads an image from data in memory.
 343 @begin_load: begins an incremental load.
 344 @stop_load: stops an incremental load.
 345 @load_increment: continues an incremental load.
 346 @load_animation: loads an animation from a file.
 347 @save: saves a #GdkPixbuf to a file.
 348 @save_to_callback: saves a #GdkPixbuf by calling the given #GdkPixbufSaveFunc.
 349
 350 <!-- ##### STRUCT GdkPixbufAnimationClass ##### -->
 351 <para>
 352 Modules supporting animations must derive a type from
 353 #GdkPixbufAnimation, providing suitable implementations of the
 354 virtual functions.
 355 </para>
 356
 357 @parent_class:
 358 @is_static_image: returns whether the given animation is just a static image.
 359 @get_static_image: returns a static image representing the given animation.
 360 @get_size: fills @width and @height with the frame size of the animation.
 361 @get_iter: returns an iterator for the given animation.
 362
 363 <!-- ##### STRUCT GdkPixbufAnimationIterClass ##### -->
 364 <para>
 365 Modules supporting animations must derive a type from
 366 #GdkPixbufAnimationIter, providing suitable implementations of the
 367 virtual functions.
 368 </para>
 369
 370 @parent_class:
 371 @get_delay_time: returns the time in milliseconds that the current frame
 372   should be shown.
 373 @get_pixbuf: returns the current frame.
 374 @on_currently_loading_frame: returns whether the current frame of @iter is
 375 being loaded.
 376 @advance: advances the iterator to @current_time, possibly changing the
 377 current frame.
 378