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 | |