1 /* GdkPixbuf library - Io handling. This is an internal header for 2 * GdkPixbuf. You should never use it unless you are doing development for 3 * GdkPixbuf itself. 4 * 5 * Copyright (C) 1999 The Free Software Foundation 6 * 7 * Authors: Mark Crichton <crichton@gimp.org> 8 * Miguel de Icaza <miguel@gnu.org> 9 * Federico Mena-Quintero <federico@gimp.org> 10 * Jonathan Blandford <jrb@redhat.com> 11 * Michael Fulbright <drmike@redhat.com> 12 * 13 * This library is free software; you can redistribute it and/or 14 * modify it under the terms of the GNU Lesser General Public 15 * License as published by the Free Software Foundation; either 16 * version 2 of the License, or (at your option) any later version. 17 * 18 * This library is distributed in the hope that it will be useful, 19 * but WITHOUT ANY WARRANTY; without even the implied warranty of 20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 21 * Lesser General Public License for more details. 22 * 23 * You should have received a copy of the GNU Lesser General Public 24 * License along with this library; if not, see <http://www.gnu.org/licenses/>. 25 */ 26 27 #ifndef GDK_PIXBUF_IO_H 28 #define GDK_PIXBUF_IO_H 29 30 #if defined(GDK_PIXBUF_DISABLE_SINGLE_INCLUDES) && !defined (GDK_PIXBUF_H_INSIDE) && !defined (GDK_PIXBUF_COMPILATION) 31 #error "Only <gdk-pixbuf/gdk-pixbuf.h> can be included directly." 32 #endif 33 34 #include <stdio.h> 35 #include <glib.h> 36 #include <gmodule.h> 37 #include <gdk-pixbuf/gdk-pixbuf-core.h> 38 #include <gdk-pixbuf/gdk-pixbuf-animation.h> 39 40 G_BEGIN_DECLS 41 42 typedef struct _GdkPixbufFormat GdkPixbufFormat; 43 44 GDK_PIXBUF_AVAILABLE_IN_2_40 45 gboolean gdk_pixbuf_init_modules (const char *path, 46 GError **error); 47 48 GDK_PIXBUF_AVAILABLE_IN_ALL 49 GType gdk_pixbuf_format_get_type (void) G_GNUC_CONST; 50 51 GDK_PIXBUF_AVAILABLE_IN_ALL 52 GSList *gdk_pixbuf_get_formats (void); 53 GDK_PIXBUF_AVAILABLE_IN_2_2 54 gchar *gdk_pixbuf_format_get_name (GdkPixbufFormat *format); 55 GDK_PIXBUF_AVAILABLE_IN_2_2 56 gchar *gdk_pixbuf_format_get_description (GdkPixbufFormat *format); 57 GDK_PIXBUF_AVAILABLE_IN_2_2 58 gchar **gdk_pixbuf_format_get_mime_types (GdkPixbufFormat *format); 59 GDK_PIXBUF_AVAILABLE_IN_2_2 60 gchar **gdk_pixbuf_format_get_extensions (GdkPixbufFormat *format); 61 GDK_PIXBUF_AVAILABLE_IN_2_36 62 gboolean gdk_pixbuf_format_is_save_option_supported (GdkPixbufFormat *format, 63 const gchar *option_key); 64 GDK_PIXBUF_AVAILABLE_IN_2_2 65 gboolean gdk_pixbuf_format_is_writable (GdkPixbufFormat *format); 66 GDK_PIXBUF_AVAILABLE_IN_2_6 67 gboolean gdk_pixbuf_format_is_scalable (GdkPixbufFormat *format); 68 GDK_PIXBUF_AVAILABLE_IN_2_6 69 gboolean gdk_pixbuf_format_is_disabled (GdkPixbufFormat *format); 70 GDK_PIXBUF_AVAILABLE_IN_2_6 71 void gdk_pixbuf_format_set_disabled (GdkPixbufFormat *format, 72 gboolean disabled); 73 GDK_PIXBUF_AVAILABLE_IN_2_6 74 gchar *gdk_pixbuf_format_get_license (GdkPixbufFormat *format); 75 76 GDK_PIXBUF_AVAILABLE_IN_2_4 77 GdkPixbufFormat *gdk_pixbuf_get_file_info (const gchar *filename, 78 gint *width, 79 gint *height); 80 GDK_PIXBUF_AVAILABLE_IN_2_32 81 void gdk_pixbuf_get_file_info_async (const gchar *filename, 82 GCancellable *cancellable, 83 GAsyncReadyCallback callback, 84 gpointer user_data); 85 GDK_PIXBUF_AVAILABLE_IN_2_32 86 GdkPixbufFormat *gdk_pixbuf_get_file_info_finish (GAsyncResult *async_result, 87 gint *width, 88 gint *height, 89 GError **error); 90 91 GDK_PIXBUF_AVAILABLE_IN_ALL 92 GdkPixbufFormat *gdk_pixbuf_format_copy (const GdkPixbufFormat *format); 93 GDK_PIXBUF_AVAILABLE_IN_ALL 94 void gdk_pixbuf_format_free (GdkPixbufFormat *format); 95 96 #ifdef GDK_PIXBUF_ENABLE_BACKEND 97 98 99 100 /** 101 * GdkPixbufModuleSizeFunc: 102 * @width: pointer to a location containing the current image width 103 * @height: pointer to a location containing the current image height 104 * @user_data: the loader. 105 * 106 * Defines the type of the function that gets called once the size 107 * of the loaded image is known. 108 * 109 * The function is expected to set @width and @height to the desired 110 * size to which the image should be scaled. If a module has no efficient 111 * way to achieve the desired scaling during the loading of the image, it may 112 * either ignore the size request, or only approximate it - gdk-pixbuf will 113 * then perform the required scaling on the completely loaded image. 114 * 115 * If the function sets @width or @height to zero, the module should interpret 116 * this as a hint that it will be closed soon and shouldn't allocate further 117 * resources. This convention is used to implement gdk_pixbuf_get_file_info() 118 * efficiently. 119 * 120 * Since: 2.2 121 */ 122 typedef void (* GdkPixbufModuleSizeFunc) (gint *width, 123 gint *height, 124 gpointer user_data); 125 126 /** 127 * GdkPixbufModulePreparedFunc: 128 * @pixbuf: the #GdkPixbuf that is currently being loaded. 129 * @anim: if an animation is being loaded, the #GdkPixbufAnimation, else %NULL. 130 * @user_data: the loader. 131 * 132 * Defines the type of the function that gets called once the initial 133 * setup of @pixbuf is done. 134 * 135 * #GdkPixbufLoader uses a function of this type to emit the 136 * "<link linkend="GdkPixbufLoader-area-prepared">area_prepared</link>" 137 * signal. 138 * 139 * Since: 2.2 140 */ 141 typedef void (* GdkPixbufModulePreparedFunc) (GdkPixbuf *pixbuf, 142 GdkPixbufAnimation *anim, 143 gpointer user_data); 144 145 /** 146 * GdkPixbufModuleUpdatedFunc: 147 * @pixbuf: the #GdkPixbuf that is currently being loaded. 148 * @x: the X origin of the updated area. 149 * @y: the Y origin of the updated area. 150 * @width: the width of the updated area. 151 * @height: the height of the updated area. 152 * @user_data: the loader. 153 * 154 * Defines the type of the function that gets called every time a region 155 * of @pixbuf is updated. 156 * 157 * #GdkPixbufLoader uses a function of this type to emit the 158 * "<link linkend="GdkPixbufLoader-area-updated">area_updated</link>" 159 * signal. 160 * 161 * Since: 2.2 162 */ 163 typedef void (* GdkPixbufModuleUpdatedFunc) (GdkPixbuf *pixbuf, 164 int x, 165 int y, 166 int width, 167 int height, 168 gpointer user_data); 169 170 /** 171 * GdkPixbufModulePattern: 172 * @prefix: the prefix for this pattern 173 * @mask: mask containing bytes which modify how the prefix is matched against 174 * test data 175 * @relevance: relevance of this pattern 176 * 177 * The signature of a module is a set of prefixes. Prefixes are encoded as 178 * pairs of ordinary strings, where the second string, called the mask, if 179 * not %NULL, must be of the same length as the first one and may contain 180 * ' ', '!', 'x', 'z', and 'n' to indicate bytes that must be matched, 181 * not matched, "don't-care"-bytes, zeros and non-zeros. 182 * Each prefix has an associated integer that describes the relevance of 183 * the prefix, with 0 meaning a mismatch and 100 a "perfect match". 184 * 185 * Starting with gdk-pixbuf 2.8, the first byte of the mask may be '*', 186 * indicating an unanchored pattern that matches not only at the beginning, 187 * but also in the middle. Versions prior to 2.8 will interpret the '*' 188 * like an 'x'. 189 * 190 * The signature of a module is stored as an array of 191 * #GdkPixbufModulePatterns. The array is terminated by a pattern 192 * where the @prefix is %NULL. 193 * 194 * 195 * <informalexample><programlisting> 196 * GdkPixbufModulePattern *signature[] = { 197 * { "abcdx", " !x z", 100 }, 198 * { "bla", NULL, 90 }, 199 * { NULL, NULL, 0 } 200 * }; 201 * </programlisting> 202 * The example matches e.g. "auud\0" with relevance 100, and "blau" with 203 * relevance 90.</informalexample> 204 * 205 * Since: 2.2 206 */ 207 typedef struct _GdkPixbufModulePattern GdkPixbufModulePattern; 208 struct _GdkPixbufModulePattern { 209 char *prefix; 210 char *mask; 211 int relevance; 212 }; 213 214 /** 215 * GdkPixbufModule: 216 * @module_name: the name of the module, usually the same as the 217 * usual file extension for images of this type, eg. "xpm", "jpeg" or "png". 218 * @module_path: the path from which the module is loaded. 219 * @module: the loaded #GModule. 220 * @info: a #GdkPixbufFormat holding information about the module. 221 * @load: loads an image from a file. 222 * @load_xpm_data: loads an image from data in memory. 223 * @begin_load: begins an incremental load. 224 * @stop_load: stops an incremental load. 225 * @load_increment: continues an incremental load. 226 * @load_animation: loads an animation from a file. 227 * @save: saves a #GdkPixbuf to a file. 228 * @save_to_callback: saves a #GdkPixbuf by calling the given #GdkPixbufSaveFunc. 229 * @is_save_option_supported: returns whether a save option key is supported by the module 230 * 231 * A #GdkPixbufModule contains the necessary functions to load and save 232 * images in a certain file format. 233 * 234 * A #GdkPixbufModule can be loaded dynamically from a #GModule. 235 * Each loadable module must contain a #GdkPixbufModuleFillVtableFunc function 236 * named <function>fill_vtable</function>, which will get called when the module 237 * is loaded and must set the function pointers of the #GdkPixbufModule. 238 */ 239 typedef struct _GdkPixbufModule GdkPixbufModule; 240 struct _GdkPixbufModule { 241 char *module_name; 242 char *module_path; 243 GModule *module; 244 GdkPixbufFormat *info; 245 246 GdkPixbuf *(* load) (FILE *f, 247 GError **error); 248 GdkPixbuf *(* load_xpm_data) (const char **data); 249 250 /* Incremental loading */ 251 252 gpointer (* begin_load) (GdkPixbufModuleSizeFunc size_func, 253 GdkPixbufModulePreparedFunc prepare_func, 254 GdkPixbufModuleUpdatedFunc update_func, 255 gpointer user_data, 256 GError **error); 257 gboolean (* stop_load) (gpointer context, 258 GError **error); 259 gboolean (* load_increment) (gpointer context, 260 const guchar *buf, 261 guint size, 262 GError **error); 263 264 /* Animation loading */ 265 GdkPixbufAnimation *(* load_animation) (FILE *f, 266 GError **error); 267 268 /* Saving */ 269 gboolean (* save) (FILE *f, 270 GdkPixbuf *pixbuf, 271 gchar **param_keys, 272 gchar **param_values, 273 GError **error); 274 275 gboolean (*save_to_callback) (GdkPixbufSaveFunc save_func, 276 gpointer user_data, 277 GdkPixbuf *pixbuf, 278 gchar **option_keys, 279 gchar **option_values, 280 GError **error); 281 282 gboolean (* is_save_option_supported) (const gchar *option_key); 283 284 /*< private >*/ 285 void (*_reserved1) (void); 286 void (*_reserved2) (void); 287 void (*_reserved3) (void); 288 void (*_reserved4) (void); 289 }; 290 291 /** 292 * GdkPixbufModuleFillVtableFunc: 293 * @module: a #GdkPixbufModule. 294 * 295 * Defines the type of the function used to set the vtable of a 296 * #GdkPixbufModule when it is loaded. 297 * 298 * Since: 2.2 299 */ 300 301 typedef void (* GdkPixbufModuleFillVtableFunc) (GdkPixbufModule *module); 302 303 /** 304 * GdkPixbufModuleFillInfoFunc: 305 * @info: a #GdkPixbufFormat. 306 * 307 * Defines the type of the function used to fill a 308 * #GdkPixbufFormat structure with information about a module. 309 * 310 * Since: 2.2 311 */ 312 typedef void (* GdkPixbufModuleFillInfoFunc) (GdkPixbufFormat *info); 313 314 /** 315 * GdkPixbufFormatFlags: 316 * @GDK_PIXBUF_FORMAT_WRITABLE: the module can write out images in the format. 317 * @GDK_PIXBUF_FORMAT_SCALABLE: the image format is scalable 318 * @GDK_PIXBUF_FORMAT_THREADSAFE: the module is threadsafe. gdk-pixbuf 319 * ignores modules that are not marked as threadsafe. (Since 2.28). 320 * 321 * Flags which allow a module to specify further details about the supported 322 * operations. 323 * 324 * Since: 2.2 325 */ 326 typedef enum /*< skip >*/ 327 { 328 GDK_PIXBUF_FORMAT_WRITABLE = 1 << 0, 329 GDK_PIXBUF_FORMAT_SCALABLE = 1 << 1, 330 GDK_PIXBUF_FORMAT_THREADSAFE = 1 << 2 331 } GdkPixbufFormatFlags; 332 333 /** 334 * GdkPixbufFormat: 335 * @name: the name of the image format. 336 * @signature: the signature of the module. 337 * @domain: the message domain for the @description. 338 * @description: a description of the image format. 339 * @mime_types: a %NULL-terminated array of MIME types for the image format. 340 * @extensions: a %NULL-terminated array of typical filename extensions for the 341 * image format. 342 * @flags: a combination of #GdkPixbufFormatFlags. 343 * @disabled: a boolean determining whether the loader is disabled. 344 * @license: a string containing license information, typically set to 345 * shorthands like "GPL", "LGPL", etc. 346 * 347 * A #GdkPixbufFormat contains information about the image format accepted by a 348 * module. Only modules should access the fields directly, applications should 349 * use the <function>gdk_pixbuf_format_*</function> functions. 350 * 351 * Since: 2.2 352 */ 353 struct _GdkPixbufFormat { 354 gchar *name; 355 GdkPixbufModulePattern *signature; 356 gchar *domain; 357 gchar *description; 358 gchar **mime_types; 359 gchar **extensions; 360 guint32 flags; 361 gboolean disabled; 362 gchar *license; 363 }; 364 365 #endif /* GDK_PIXBUF_ENABLE_BACKEND */ 366 367 G_END_DECLS 368 369 #endif /* GDK_PIXBUF_IO_H */ 370