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