gdk-pixbuf-io.h 12 KB
Newer Older
1 2 3
/* GdkPixbuf library - Io handling.  This is an internal header for 
 * GdkPixbuf. You should never use it unless you are doing development for 
 * GdkPixbuf itself.
4 5 6 7 8 9 10
 *
 * Copyright (C) 1999 The Free Software Foundation
 *
 * Authors: Mark Crichton <crichton@gimp.org>
 *          Miguel de Icaza <miguel@gnu.org>
 *          Federico Mena-Quintero <federico@gimp.org>
 *          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 16 17 18 19 20
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * 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 28 29
#ifndef GDK_PIXBUF_IO_H
#define GDK_PIXBUF_IO_H

30
#if defined(GDK_PIXBUF_DISABLE_SINGLE_INCLUDES) && !defined (GDK_PIXBUF_H_INSIDE) && !defined (GDK_PIXBUF_COMPILATION)
31 32 33
#error "Only <gdk-pixbuf/gdk-pixbuf.h> can be included directly."
#endif

34
#include <stdio.h>
35 36 37 38
#include <glib.h>
#include <gmodule.h>
#include <gdk-pixbuf/gdk-pixbuf-core.h>
#include <gdk-pixbuf/gdk-pixbuf-animation.h>
39

40
G_BEGIN_DECLS
41

42 43
typedef struct _GdkPixbufFormat GdkPixbufFormat;
 
44 45
GType gdk_pixbuf_format_get_type (void) G_GNUC_CONST;

46
GSList    *gdk_pixbuf_get_formats            (void);
47 48 49 50 51 52
gchar     *gdk_pixbuf_format_get_name        (GdkPixbufFormat *format);
gchar     *gdk_pixbuf_format_get_description (GdkPixbufFormat *format);
gchar    **gdk_pixbuf_format_get_mime_types  (GdkPixbufFormat *format);
gchar    **gdk_pixbuf_format_get_extensions  (GdkPixbufFormat *format);
gboolean   gdk_pixbuf_format_is_writable     (GdkPixbufFormat *format);
gboolean   gdk_pixbuf_format_is_scalable     (GdkPixbufFormat *format);
53 54 55 56
gboolean   gdk_pixbuf_format_is_disabled     (GdkPixbufFormat *format);
void       gdk_pixbuf_format_set_disabled    (GdkPixbufFormat *format,
					      gboolean         disabled);
gchar     *gdk_pixbuf_format_get_license     (GdkPixbufFormat *format);
57

58 59 60
GdkPixbufFormat *gdk_pixbuf_get_file_info    (const gchar     *filename,
					      gint            *width, 
					      gint            *height);
61

62 63 64
GdkPixbufFormat *gdk_pixbuf_format_copy (const GdkPixbufFormat *format);
void             gdk_pixbuf_format_free (GdkPixbufFormat       *format);

65
#ifdef GDK_PIXBUF_ENABLE_BACKEND
66

67

68

69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90
/**
 * GdkPixbufModuleSizeFunc:
 * @width: pointer to a location containing the current image width
 * @height: pointer to a location containing the current image height
 * @user_data: the loader.
 * 
 * Defines the type of the function that gets called once the size 
 * of the loaded image is known.
 * 
 * The function is expected to set @width and @height to the desired
 * size to which the image should be scaled. If a module has no efficient 
 * way to achieve the desired scaling during the loading of the image, it may
 * either ignore the size request, or only approximate it -- &gdk-pixbuf; will
 * then perform the required scaling on the completely loaded image. 
 * 
 * If the function sets @width or @height to zero, the module should interpret
 * this as a hint that it will be closed soon and shouldn't allocate further 
 * resources. This convention is used to implement gdk_pixbuf_get_file_info()
 * efficiently.
 * 
 * Since: 2.2
 */
91 92 93 94
typedef void (* GdkPixbufModuleSizeFunc)           (gint *width, 
						    gint *height, 
						    gpointer user_data);

95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
/**
 * GdkPixbufModulePreparedFunc:
 * @pixbuf: the #GdkPixbuf that is currently being loaded.
 * @anim: if an animation is being loaded, the #GdkPixbufAnimation, else %NULL.
 * @user_data: the loader.
 * 
 * Defines the type of the function that gets called once the initial 
 * setup of @pixbuf is done.
 * 
 * #GdkPixbufLoader uses a function of this type to emit the 
 * "<link linkend="GdkPixbufLoader-area-prepared">area_prepared</link>"
 * signal.
 * 
 * Since: 2.2
 */
110 111 112
typedef void (* GdkPixbufModulePreparedFunc) (GdkPixbuf          *pixbuf,
					      GdkPixbufAnimation *anim,
					      gpointer            user_data);
113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131

/**
 * GdkPixbufModuleUpdatedFunc:
 * @pixbuf: the #GdkPixbuf that is currently being loaded.
 * @x: the X origin of the updated area.
 * @y: the Y origin of the updated area.
 * @width: the width of the updated area.
 * @height: the height of the updated area.
 * @user_data: the loader.
 * 
 * Defines the type of the function that gets called every time a region
 * of @pixbuf is updated.
 * 
 * #GdkPixbufLoader uses a function of this type to emit the 
 * "<link linkend="GdkPixbufLoader-area-updated">area_updated</link>"
 * signal.
 * 
 * Since: 2.2
 */
132 133 134 135 136 137 138
typedef void (* GdkPixbufModuleUpdatedFunc)  (GdkPixbuf *pixbuf,
					      int        x,
					      int        y,
					      int        width,
					      int        height,
					      gpointer   user_data);

139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175
/**
 * GdkPixbufModulePattern:
 * @prefix: the prefix for this pattern
 * @mask: mask containing bytes which modify how the prefix is matched against
 *  test data
 * @relevance: relevance of this pattern
 * 
 * The signature of a module is a set of prefixes. Prefixes are encoded as
 * pairs of ordinary strings, where the second string, called the mask, if 
 * not %NULL, must be of the same length as the first one and may contain 
 * ' ', '!', 'x', 'z', and 'n' to indicate bytes that must be matched, 
 * not matched, "don't-care"-bytes, zeros and non-zeros. 
 * Each prefix has an associated integer that describes the relevance of 
 * the prefix, with 0 meaning a mismatch and 100 a "perfect match".
 * 
 * Starting with &gdk-pixbuf; 2.8, the first byte of the mask may be '*', 
 * indicating an unanchored pattern that matches not only at the beginning, 
 * but also in the middle. Versions prior to 2.8 will interpret the '*'
 * like an 'x'. 
 * 
 * The signature of a module is stored as an array of 
 * #GdkPixbufModulePattern<!-- -->s. The array is terminated by a pattern
 * where the @prefix is %NULL.
 * 
 * 
 * <informalexample><programlisting>
 * GdkPixbufModulePattern *signature[] = {
 *   { "abcdx", " !x z", 100 },
 *   { "bla", NULL,  90 },
 *   { NULL, NULL, 0 }
 * };
 * </programlisting>
 * The example matches e.g. "auud\0" with relevance 100, and "blau" with 
 * relevance 90.</informalexample>
 * 
 * Since: 2.2
 */
176 177
typedef struct _GdkPixbufModulePattern GdkPixbufModulePattern;
struct _GdkPixbufModulePattern {
178 179
	char *prefix;
	char *mask;
180 181
	int relevance;
};
Havoc Pennington's avatar
Havoc Pennington committed
182

183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206
/**
 * GdkPixbufModule:
 * @module_name: the name of the module, usually the same as the
 *  usual file extension for images of this type, eg. "xpm", "jpeg" or "png".
 * @module_path: the path from which the module is loaded.
 * @module: the loaded #GModule.
 * @info: a #GdkPixbufFormat holding information about the module.
 * @load: loads an image from a file.
 * @load_xpm_data: loads an image from data in memory.
 * @begin_load: begins an incremental load.
 * @stop_load: stops an incremental load.
 * @load_increment: continues an incremental load.
 * @load_animation: loads an animation from a file.
 * @save: saves a #GdkPixbuf to a file.
 * @save_to_callback: saves a #GdkPixbuf by calling the given #GdkPixbufSaveFunc.
 * 
 * A #GdkPixbufModule contains the necessary functions to load and save 
 * images in a certain file format. 
 * 
 * A #GdkPixbufModule can be loaded dynamically from a #GModule.
 * Each loadable module must contain a #GdkPixbufModuleFillVtableFunc function 
 * named <function>fill_vtable</function>, which will get called when the module
 * is loaded and must set the function pointers of the #GdkPixbufModule. 
 */
207 208
typedef struct _GdkPixbufModule GdkPixbufModule;
struct _GdkPixbufModule {
209
	char *module_name;
210
	char *module_path;
211
	GModule *module;
212 213
	GdkPixbufFormat *info;
	
Havoc Pennington's avatar
Havoc Pennington committed
214 215
        GdkPixbuf *(* load) (FILE    *f,
                             GError **error);
216
        GdkPixbuf *(* load_xpm_data) (const char **data);
Havoc Pennington's avatar
Havoc Pennington committed
217 218

        /* Incremental loading */
219

220 221 222
        gpointer (* begin_load)     (GdkPixbufModuleSizeFunc size_func,
                                     GdkPixbufModulePreparedFunc prepare_func,
                                     GdkPixbufModuleUpdatedFunc update_func,
223 224 225 226
                                     gpointer user_data,
                                     GError **error);
        gboolean (* stop_load)      (gpointer context,
                                     GError **error);
227 228
        gboolean (* load_increment) (gpointer      context,
                                     const guchar *buf,
Havoc Pennington's avatar
Havoc Pennington committed
229 230
                                     guint         size,
                                     GError      **error);
231 232

	/* Animation loading */
Havoc Pennington's avatar
Havoc Pennington committed
233 234
	GdkPixbufAnimation *(* load_animation) (FILE    *f,
                                                GError **error);
235

236
        /* Saving */
237 238 239 240
        gboolean (* save) (FILE      *f,
                           GdkPixbuf *pixbuf,
                           gchar    **param_keys,
                           gchar    **param_values,
Havoc Pennington's avatar
Havoc Pennington committed
241
                           GError   **error);
242 243 244 245 246 247 248

        gboolean (*save_to_callback) (GdkPixbufSaveFunc save_func,
				      gpointer user_data,
				      GdkPixbuf *pixbuf,
				      gchar **option_keys,
				      gchar **option_values,
				      GError **error);
249
  
Matthias Clasen's avatar
Matthias Clasen committed
250
  /*< private >*/
251 252 253 254 255
	void (*_reserved1) (void); 
	void (*_reserved2) (void); 
	void (*_reserved3) (void); 
	void (*_reserved4) (void); 
	void (*_reserved5) (void); 
256

257
};
258

259 260 261 262 263 264 265 266 267 268
/**
 * GdkPixbufModuleFillVtableFunc:
 * @module: a #GdkPixbufModule.
 * 
 * Defines the type of the function used to set the vtable of a 
 * #GdkPixbufModule when it is loaded. 
 * 
 * Since: 2.2
 */

269
typedef void (* GdkPixbufModuleFillVtableFunc) (GdkPixbufModule *module);
270 271 272 273 274 275 276 277 278 279

/**
 * GdkPixbufModuleFillInfoFunc:
 * @info: a #GdkPixbufFormat.
 * 
 * Defines the type of the function used to fill a 
 * #GdkPixbufFormat structure with information about a module.
 * 
 * Since: 2.2
 */
280 281 282 283 284 285 286 287
typedef void (* GdkPixbufModuleFillInfoFunc) (GdkPixbufFormat *info);

/*  key/value pairs that can be attached by the pixbuf loader  */

gboolean gdk_pixbuf_set_option  (GdkPixbuf   *pixbuf,
                                 const gchar *key,
                                 const gchar *value);

288 289 290 291
/**
 * GdkPixbufFormatFlags:
 * @GDK_PIXBUF_FORMAT_WRITABLE: the module can write out images in the format.
 * @GDK_PIXBUF_FORMAT_SCALABLE: the image format is scalable
292 293
 * @GDK_PIXBUF_FORMAT_THREADSAFE: the module is threadsafe. &gdk-pixbuf;
 *     ignores modules that are not marked as threadsafe. (Since 2.28).
294 295 296 297 298 299
 * 
 * Flags which allow a module to specify further details about the supported
 * operations.
 * 
 * Since: 2.2
 */
300 301
typedef enum /*< skip >*/
{
302
  GDK_PIXBUF_FORMAT_WRITABLE = 1 << 0,
303 304
  GDK_PIXBUF_FORMAT_SCALABLE = 1 << 1,
  GDK_PIXBUF_FORMAT_THREADSAFE = 1 << 2
305 306
} GdkPixbufFormatFlags;

307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326
/**
 * GdkPixbufFormat:
 * @name: the name of the image format.
 * @signature: the signature of the module.
 * @domain: the message domain for the @description.
 * @description: a description of the image format.
 * @mime_types: a %NULL-terminated array of MIME types for the image format.
 * @extensions: a %NULL-terminated array of typical filename extensions for the
 *  image format.
 * @flags: a combination of #GdkPixbufFormatFlags.
 * @disabled: a boolean determining whether the loader is disabled.
 * @license: a string containing license information, typically set to 
 *  shorthands like "GPL", "LGPL", etc.
 * 
 * A #GdkPixbufFormat contains information about the image format accepted by a
 * module. Only modules should access the fields directly, applications should
 * use the <function>gdk_pixbuf_format_*</function> functions.
 * 
 * Since: 2.2
 */
327 328 329 330 331 332 333 334
struct _GdkPixbufFormat {
  gchar *name;
  GdkPixbufModulePattern *signature;
  gchar *domain;
  gchar *description;
  gchar **mime_types;
  gchar **extensions;
  guint32 flags;
335 336
  gboolean disabled;
  gchar *license;
337
};
Havoc Pennington's avatar
Havoc Pennington committed
338

339
#endif /* GDK_PIXBUF_ENABLE_BACKEND */
340

341
G_END_DECLS
342

343
#endif /* GDK_PIXBUF_IO_H */