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
40G_BEGIN_DECLS
41
42typedef struct _GdkPixbufFormat GdkPixbufFormat;
43
44GDK_PIXBUF_AVAILABLE_IN_2_40
45gboolean gdk_pixbuf_init_modules (const char *path,
46 GError **error);
47
48GDK_PIXBUF_AVAILABLE_IN_ALL
49GType gdk_pixbuf_format_get_type (void) G_GNUC_CONST;
50
51GDK_PIXBUF_AVAILABLE_IN_ALL
52GSList *gdk_pixbuf_get_formats (void);
53GDK_PIXBUF_AVAILABLE_IN_2_2
54gchar *gdk_pixbuf_format_get_name (GdkPixbufFormat *format);
55GDK_PIXBUF_AVAILABLE_IN_2_2
56gchar *gdk_pixbuf_format_get_description (GdkPixbufFormat *format);
57GDK_PIXBUF_AVAILABLE_IN_2_2
58gchar **gdk_pixbuf_format_get_mime_types (GdkPixbufFormat *format);
59GDK_PIXBUF_AVAILABLE_IN_2_2
60gchar **gdk_pixbuf_format_get_extensions (GdkPixbufFormat *format);
61GDK_PIXBUF_AVAILABLE_IN_2_36
62gboolean gdk_pixbuf_format_is_save_option_supported (GdkPixbufFormat *format,
63 const gchar *option_key);
64GDK_PIXBUF_AVAILABLE_IN_2_2
65gboolean gdk_pixbuf_format_is_writable (GdkPixbufFormat *format);
66GDK_PIXBUF_AVAILABLE_IN_2_6
67gboolean gdk_pixbuf_format_is_scalable (GdkPixbufFormat *format);
68GDK_PIXBUF_AVAILABLE_IN_2_6
69gboolean gdk_pixbuf_format_is_disabled (GdkPixbufFormat *format);
70GDK_PIXBUF_AVAILABLE_IN_2_6
71void gdk_pixbuf_format_set_disabled (GdkPixbufFormat *format,
72 gboolean disabled);
73GDK_PIXBUF_AVAILABLE_IN_2_6
74gchar *gdk_pixbuf_format_get_license (GdkPixbufFormat *format);
75
76GDK_PIXBUF_AVAILABLE_IN_2_4
77GdkPixbufFormat *gdk_pixbuf_get_file_info (const gchar *filename,
78 gint *width,
79 gint *height);
80GDK_PIXBUF_AVAILABLE_IN_2_32
81void gdk_pixbuf_get_file_info_async (const gchar *filename,
82 GCancellable *cancellable,
83 GAsyncReadyCallback callback,
84 gpointer user_data);
85GDK_PIXBUF_AVAILABLE_IN_2_32
86GdkPixbufFormat *gdk_pixbuf_get_file_info_finish (GAsyncResult *async_result,
87 gint *width,
88 gint *height,
89 GError **error);
90
91GDK_PIXBUF_AVAILABLE_IN_ALL
92GdkPixbufFormat *gdk_pixbuf_format_copy (const GdkPixbufFormat *format);
93GDK_PIXBUF_AVAILABLE_IN_ALL
94void 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 */
122typedef 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 */
141typedef 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 */
163typedef 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 prefix for a module.
178 *
179 * The signature of a module is a set of prefixes. Prefixes are encoded as
180 * pairs of ordinary strings, where the second string, called the mask, if
181 * not `NULL`, must be of the same length as the first one and may contain
182 * ' ', '!', 'x', 'z', and 'n' to indicate bytes that must be matched,
183 * not matched, "don't-care"-bytes, zeros and non-zeros, respectively.
184 *
185 * Each prefix has an associated integer that describes the relevance of
186 * the prefix, with 0 meaning a mismatch and 100 a "perfect match".
187 *
188 * Starting with gdk-pixbuf 2.8, the first byte of the mask may be '*',
189 * indicating an unanchored pattern that matches not only at the beginning,
190 * but also in the middle. Versions prior to 2.8 will interpret the '*'
191 * like an 'x'.
192 *
193 * The signature of a module is stored as an array of
194 * `GdkPixbufModulePatterns`. The array is terminated by a pattern
195 * where the `prefix` is `NULL`.
196 *
197 * ```c
198 * GdkPixbufModulePattern *signature[] = {
199 * { "abcdx", " !x z", 100 },
200 * { "bla", NULL, 90 },
201 * { NULL, NULL, 0 }
202 * };
203 * ```
204 *
205 * In the example above, the signature matches e.g. "auud\0" with
206 * relevance 100, and "blau" with relevance 90.
207 *
208 * Since: 2.2
209 */
210typedef struct _GdkPixbufModulePattern GdkPixbufModulePattern;
211struct _GdkPixbufModulePattern {
212 char *prefix;
213 char *mask;
214 int relevance;
215};
216
217/**
218 * GdkPixbufModuleLoadFunc:
219 * @f: the file stream from which the image should be loaded
220 * @error: return location for a loading error
221 *
222 * Loads a file from a standard C file stream into a new `GdkPixbuf`.
223 *
224 * In case of error, this function should return `NULL` and set the `error` argument.
225 *
226 * Returns: (transfer full): a newly created `GdkPixbuf` for the contents of the file
227 */
228typedef GdkPixbuf *(* GdkPixbufModuleLoadFunc) (FILE *f,
229 GError **error);
230
231/**
232 * GdkPixbufModuleLoadXpmDataFunc:
233 * @data: (array zero-terminated=1): the XPM data
234 *
235 * Loads XPM data into a new `GdkPixbuf`.
236 *
237 * Returns: (transfer full): a newly created `GdkPixbuf` for the XPM data
238 */
239typedef GdkPixbuf *(* GdkPixbufModuleLoadXpmDataFunc) (const char **data);
240
241/**
242 * GdkPixbufModuleLoadAnimationFunc:
243 * @f: the file stream from which the image should be loaded
244 * @error: return location for a loading error
245 *
246 * Loads a file from a standard C file stream into a new `GdkPixbufAnimation`.
247 *
248 * In case of error, this function should return `NULL` and set the `error` argument.
249 *
250 * Returns: (transfer full): a newly created `GdkPixbufAnimation` for the contents of the file
251 */
252typedef GdkPixbufAnimation *(* GdkPixbufModuleLoadAnimationFunc) (FILE *f,
253 GError **error);
254
255/**
256 * GdkPixbufModuleBeginLoadFunc:
257 * @size_func: the function to be called when the size is known
258 * @prepared_func: the function to be called when the data has been prepared
259 * @updated_func: the function to be called when the data has been updated
260 * @user_data: the data to be passed to the functions
261 * @error: return location for a loading error
262 *
263 * Sets up the image loading state.
264 *
265 * The image loader is responsible for storing the given function pointers
266 * and user data, and call them when needed.
267 *
268 * The image loader should set up an internal state object, and return it
269 * from this function; the state object will then be updated from the
270 * [callback@GdkPixbuf.PixbufModuleIncrementLoadFunc] callback, and will be freed
271 * by [callback@GdkPixbuf.PixbufModuleStopLoadFunc] callback.
272 *
273 * Returns: (transfer full): the data to be passed to
274 * [callback@GdkPixbuf.PixbufModuleIncrementLoadFunc]
275 * and [callback@GdkPixbuf.PixbufModuleStopLoadFunc], or `NULL` in case of error
276 */
277typedef gpointer (* GdkPixbufModuleBeginLoadFunc) (GdkPixbufModuleSizeFunc size_func,
278 GdkPixbufModulePreparedFunc prepared_func,
279 GdkPixbufModuleUpdatedFunc updated_func,
280 gpointer user_data,
281 GError **error);
282
283/**
284 * GdkPixbufModuleStopLoadFunc:
285 * @context: (transfer full): the state object created by [callback@GdkPixbuf.PixbufModuleBeginLoadFunc]
286 * @error: return location for a loading error
287 *
288 * Finalizes the image loading state.
289 *
290 * This function is called on success and error states.
291 *
292 * Returns: `TRUE` if the loading operation was successful
293 */
294typedef gboolean (* GdkPixbufModuleStopLoadFunc) (gpointer context,
295 GError **error);
296
297/**
298 * GdkPixbufModuleIncrementLoadFunc:
299 * @context: (transfer none): the state object created by [callback@GdkPixbuf.PixbufModuleBeginLoadFunc]
300 * @buf: (array length=size) (element-type guint8): the data to load
301 * @size: the length of the data to load
302 * @error: return location for a loading error
303 *
304 * Incrementally loads a buffer into the image data.
305 *
306 * Returns: `TRUE` if the incremental load was successful
307 */
308typedef gboolean (* GdkPixbufModuleIncrementLoadFunc) (gpointer context,
309 const guchar *buf,
310 guint size,
311 GError **error);
312
313/**
314 * GdkPixbufModuleSaveFunc:
315 * @f: the file stream into which the image should be saved
316 * @pixbuf: the image to save
317 * @param_keys: (nullable) (array zero-terminated=1): parameter keys to save
318 * @param_values: (nullable) (array zero-terminated=1): parameter values to save
319 * @error: return location for a saving error
320 *
321 * Saves a `GdkPixbuf` into a standard C file stream.
322 *
323 * The optional `param_keys` and `param_values` arrays contain the keys and
324 * values (in the same order) for attributes to be saved alongside the image
325 * data.
326 *
327 * Returns: `TRUE` on success; in case of failure, `FALSE` is returned and
328 * the `error` is set
329 */
330typedef gboolean (* GdkPixbufModuleSaveFunc) (FILE *f,
331 GdkPixbuf *pixbuf,
332 gchar **param_keys,
333 gchar **param_values,
334 GError **error);
335
336/**
337 * GdkPixbufModuleSaveCallbackFunc:
338 * @save_func: the function to call when saving
339 * @user_data: (closure): the data to pass to @save_func
340 * @pixbuf: the `GdkPixbuf` to save
341 * @option_keys: (nullable) (array zero-terminated=1): an array of option names
342 * @option_values: (nullable) (array zero-terminated=1): an array of option values
343 * @error: return location for a save error
344 *
345 * Saves a `GdkPixbuf` by calling the provided function.
346 *
347 * The optional `option_keys` and `option_values` arrays contain the keys and
348 * values (in the same order) for attributes to be saved alongside the image
349 * data.
350 *
351 * Returns: `TRUE` on success; in case of failure, `FALSE` is returned and
352 * the `error` is set
353 */
354typedef gboolean (* GdkPixbufModuleSaveCallbackFunc) (GdkPixbufSaveFunc save_func,
355 gpointer user_data,
356 GdkPixbuf *pixbuf,
357 gchar **option_keys,
358 gchar **option_values,
359 GError **error);
360
361/**
362 * GdkPixbufModuleSaveOptionSupportedFunc:
363 * @option_key: the option key to check
364 *
365 * Checks whether the given `option_key` is supported when saving.
366 *
367 * Returns: `TRUE` if the option is supported
368 */
369typedef gboolean (* GdkPixbufModuleSaveOptionSupportedFunc) (const gchar *option_key);
370
371typedef struct _GdkPixbufModule GdkPixbufModule;
372struct _GdkPixbufModule {
373 char *module_name;
374 char *module_path;
375 GModule *module;
376 GdkPixbufFormat *info;
377
378 /* Atomic loading */
379 GdkPixbufModuleLoadFunc load;
380 GdkPixbufModuleLoadXpmDataFunc load_xpm_data;
381
382 /* Incremental loading */
383 GdkPixbufModuleBeginLoadFunc begin_load;
384 GdkPixbufModuleStopLoadFunc stop_load;
385 GdkPixbufModuleIncrementLoadFunc load_increment;
386
387 /* Animation loading */
388 GdkPixbufModuleLoadAnimationFunc load_animation;
389
390 /* Saving */
391 GdkPixbufModuleSaveFunc save;
392 GdkPixbufModuleSaveCallbackFunc save_to_callback;
393 GdkPixbufModuleSaveOptionSupportedFunc is_save_option_supported;
394
395 /*< private >*/
396 void (*_reserved1) (void);
397 void (*_reserved2) (void);
398 void (*_reserved3) (void);
399 void (*_reserved4) (void);
400};
401
402/**
403 * GdkPixbufModuleFillVtableFunc:
404 * @module: a #GdkPixbufModule.
405 *
406 * Defines the type of the function used to set the vtable of a
407 * #GdkPixbufModule when it is loaded.
408 *
409 * Since: 2.2
410 */
411typedef void (* GdkPixbufModuleFillVtableFunc) (GdkPixbufModule *module);
412
413/**
414 * GdkPixbufModuleFillInfoFunc:
415 * @info: a #GdkPixbufFormat.
416 *
417 * Defines the type of the function used to fill a
418 * #GdkPixbufFormat structure with information about a module.
419 *
420 * Since: 2.2
421 */
422typedef void (* GdkPixbufModuleFillInfoFunc) (GdkPixbufFormat *info);
423
424/**
425 * GdkPixbufFormatFlags:
426 * @GDK_PIXBUF_FORMAT_WRITABLE: the module can write out images in the format.
427 * @GDK_PIXBUF_FORMAT_SCALABLE: the image format is scalable
428 * @GDK_PIXBUF_FORMAT_THREADSAFE: the module is threadsafe. gdk-pixbuf
429 * ignores modules that are not marked as threadsafe. (Since 2.28).
430 *
431 * Flags which allow a module to specify further details about the supported
432 * operations.
433 *
434 * Since: 2.2
435 */
436typedef enum /*< skip >*/
437{
438 GDK_PIXBUF_FORMAT_WRITABLE = 1 << 0,
439 GDK_PIXBUF_FORMAT_SCALABLE = 1 << 1,
440 GDK_PIXBUF_FORMAT_THREADSAFE = 1 << 2
441} GdkPixbufFormatFlags;
442
443/**
444 * GdkPixbufFormat:
445 * @name: the name of the image format
446 * @signature: the signature of the module
447 * @domain: the message domain for the `description`
448 * @description: a description of the image format
449 * @mime_types: (array zero-terminated=1): the MIME types for the image format
450 * @extensions: (array zero-terminated=1): typical filename extensions for the
451 * image format
452 * @flags: a combination of `GdkPixbufFormatFlags`
453 * @disabled: a boolean determining whether the loader is disabled`
454 * @license: a string containing license information, typically set to
455 * shorthands like "GPL", "LGPL", etc.
456 *
457 * A `GdkPixbufFormat` contains information about the image format accepted
458 * by a module.
459 *
460 * Only modules should access the fields directly, applications should
461 * use the `gdk_pixbuf_format_*` family of functions.
462 *
463 * Since: 2.2
464 */
465struct _GdkPixbufFormat {
466 gchar *name;
467 GdkPixbufModulePattern *signature;
468 gchar *domain;
469 gchar *description;
470 gchar **mime_types;
471 gchar **extensions;
472 guint32 flags;
473 gboolean disabled;
474 gchar *license;
475};
476
477#endif /* GDK_PIXBUF_ENABLE_BACKEND */
478
479G_END_DECLS
480
481#endif /* GDK_PIXBUF_IO_H */
482