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 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 */
207typedef struct _GdkPixbufModulePattern GdkPixbufModulePattern;
208struct _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 */
239typedef struct _GdkPixbufModule GdkPixbufModule;
240struct _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
301typedef 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 */
312typedef 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 */
326typedef 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 */
353struct _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
367G_END_DECLS
368
369#endif /* GDK_PIXBUF_IO_H */
370