1/* GdkPixbuf library - GdkPixbuf data structure
2 *
3 * Copyright (C) 2003 The Free Software Foundation
4 *
5 * Authors: Mark Crichton <crichton@gimp.org>
6 * Miguel de Icaza <miguel@gnu.org>
7 * Federico Mena-Quintero <federico@gimp.org>
8 * Havoc Pennington <hp@redhat.com>
9 *
10 * This library is free software; you can redistribute it and/or
11 * modify it under the terms of the GNU Lesser General Public
12 * License as published by the Free Software Foundation; either
13 * version 2 of the License, or (at your option) any later version.
14 *
15 * This library is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 * Lesser General Public License for more details.
19 *
20 * You should have received a copy of the GNU Lesser General Public
21 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
22 */
23
24#ifndef GDK_PIXBUF_CORE_H
25#define GDK_PIXBUF_CORE_H
26
27#if defined(GDK_PIXBUF_DISABLE_SINGLE_INCLUDES) && !defined (GDK_PIXBUF_H_INSIDE) && !defined (GDK_PIXBUF_COMPILATION)
28#error "Only <gdk-pixbuf/gdk-pixbuf.h> can be included directly."
29#endif
30
31#include <glib.h>
32#include <glib-object.h>
33#include <gio/gio.h>
34
35#include <gdk-pixbuf/gdk-pixbuf-macros.h>
36
37G_BEGIN_DECLS
38
39/**
40 * GdkPixbufAlphaMode:
41 * @GDK_PIXBUF_ALPHA_BILEVEL: A bilevel clipping mask (black and white)
42 * will be created and used to draw the image. Pixels below 0.5 opacity
43 * will be considered fully transparent, and all others will be
44 * considered fully opaque.
45 * @GDK_PIXBUF_ALPHA_FULL: For now falls back to #GDK_PIXBUF_ALPHA_BILEVEL.
46 * In the future it will do full alpha compositing.
47 *
48 * Control the alpha channel for drawables.
49 *
50 * These values can be passed to gdk_pixbuf_xlib_render_to_drawable_alpha()
51 * in gdk-pixbuf-xlib to control how the alpha channel of an image should
52 * be handled.
53 *
54 * This function can create a bilevel clipping mask (black and white) and use
55 * it while painting the image.
56 *
57 * In the future, when the X Window System gets an alpha channel extension,
58 * it will be possible to do full alpha compositing onto arbitrary drawables.
59 * For now both cases fall back to a bilevel clipping mask.
60 *
61 * Deprecated: 2.42: There is no user of GdkPixbufAlphaMode in GdkPixbuf,
62 * and the Xlib utility functions have been split out to their own
63 * library, gdk-pixbuf-xlib
64 */
65typedef enum
66{
67 GDK_PIXBUF_ALPHA_BILEVEL,
68 GDK_PIXBUF_ALPHA_FULL
69} GdkPixbufAlphaMode;
70
71/**
72 * GdkColorspace:
73 * @GDK_COLORSPACE_RGB: Indicates a red/green/blue additive color space.
74 *
75 * This enumeration defines the color spaces that are supported by
76 * the gdk-pixbuf library.
77 *
78 * Currently only RGB is supported.
79 */
80/* Note that these values are encoded in inline pixbufs
81 * as ints, so don't reorder them
82 */
83typedef enum {
84 GDK_COLORSPACE_RGB
85} GdkColorspace;
86
87/* All of these are opaque structures */
88
89typedef struct _GdkPixbuf GdkPixbuf;
90
91#define GDK_TYPE_PIXBUF (gdk_pixbuf_get_type ())
92#define GDK_PIXBUF(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), GDK_TYPE_PIXBUF, GdkPixbuf))
93#define GDK_IS_PIXBUF(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), GDK_TYPE_PIXBUF))
94
95
96/**
97 * GdkPixbufDestroyNotify:
98 * @pixels: (array) (element-type guint8): The pixel array of the pixbuf
99 * that is being finalized.
100 * @data: (closure): User closure data.
101 *
102 * A function of this type is responsible for freeing the pixel array
103 * of a pixbuf.
104 *
105 * The gdk_pixbuf_new_from_data() function lets you pass in a pre-allocated
106 * pixel array so that a pixbuf can be created from it; in this case you
107 * will need to pass in a function of type `GdkPixbufDestroyNotify` so that
108 * the pixel data can be freed when the pixbuf is finalized.
109 */
110typedef void (* GdkPixbufDestroyNotify) (guchar *pixels, gpointer data);
111
112/**
113 * GDK_PIXBUF_ERROR:
114 *
115 * Error domain used for pixbuf operations.
116 *
117 * Indicates that the error code will be in the `GdkPixbufError` enumeration.
118 *
119 * See the `GError` for information on error domains and error codes.
120 */
121#define GDK_PIXBUF_ERROR gdk_pixbuf_error_quark ()
122
123/**
124 * GdkPixbufError:
125 * @GDK_PIXBUF_ERROR_CORRUPT_IMAGE: An image file was broken somehow.
126 * @GDK_PIXBUF_ERROR_INSUFFICIENT_MEMORY: Not enough memory.
127 * @GDK_PIXBUF_ERROR_BAD_OPTION: A bad option was passed to a pixbuf save module.
128 * @GDK_PIXBUF_ERROR_UNKNOWN_TYPE: Unknown image type.
129 * @GDK_PIXBUF_ERROR_UNSUPPORTED_OPERATION: Don't know how to perform the
130 * given operation on the type of image at hand.
131 * @GDK_PIXBUF_ERROR_FAILED: Generic failure code, something went wrong.
132 * @GDK_PIXBUF_ERROR_INCOMPLETE_ANIMATION: Only part of the animation was loaded.
133 *
134 * An error code in the `GDK_PIXBUF_ERROR` domain.
135 *
136 * Many gdk-pixbuf operations can cause errors in this domain, or in
137 * the `G_FILE_ERROR` domain.
138 */
139typedef enum {
140 /* image data hosed */
141 GDK_PIXBUF_ERROR_CORRUPT_IMAGE,
142 /* no mem to load image */
143 GDK_PIXBUF_ERROR_INSUFFICIENT_MEMORY,
144 /* bad option passed to save routine */
145 GDK_PIXBUF_ERROR_BAD_OPTION,
146 /* unsupported image type (sort of an ENOSYS) */
147 GDK_PIXBUF_ERROR_UNKNOWN_TYPE,
148 /* unsupported operation (load, save) for image type */
149 GDK_PIXBUF_ERROR_UNSUPPORTED_OPERATION,
150 GDK_PIXBUF_ERROR_FAILED,
151 GDK_PIXBUF_ERROR_INCOMPLETE_ANIMATION
152} GdkPixbufError;
153
154GDK_PIXBUF_AVAILABLE_IN_ALL
155GQuark gdk_pixbuf_error_quark (void);
156
157
158
159GDK_PIXBUF_AVAILABLE_IN_ALL
160GType gdk_pixbuf_get_type (void) G_GNUC_CONST;
161
162/* Reference counting */
163
164#ifndef GDK_PIXBUF_DISABLE_DEPRECATED
165GDK_PIXBUF_DEPRECATED_IN_2_0_FOR(g_object_ref)
166GdkPixbuf *gdk_pixbuf_ref (GdkPixbuf *pixbuf);
167GDK_PIXBUF_DEPRECATED_IN_2_0_FOR(g_object_unref)
168void gdk_pixbuf_unref (GdkPixbuf *pixbuf);
169#endif
170
171/* GdkPixbuf accessors */
172
173GDK_PIXBUF_AVAILABLE_IN_ALL
174GdkColorspace gdk_pixbuf_get_colorspace (const GdkPixbuf *pixbuf);
175GDK_PIXBUF_AVAILABLE_IN_ALL
176int gdk_pixbuf_get_n_channels (const GdkPixbuf *pixbuf);
177GDK_PIXBUF_AVAILABLE_IN_ALL
178gboolean gdk_pixbuf_get_has_alpha (const GdkPixbuf *pixbuf);
179GDK_PIXBUF_AVAILABLE_IN_ALL
180int gdk_pixbuf_get_bits_per_sample (const GdkPixbuf *pixbuf);
181GDK_PIXBUF_AVAILABLE_IN_ALL
182guchar *gdk_pixbuf_get_pixels (const GdkPixbuf *pixbuf);
183GDK_PIXBUF_AVAILABLE_IN_ALL
184int gdk_pixbuf_get_width (const GdkPixbuf *pixbuf);
185GDK_PIXBUF_AVAILABLE_IN_ALL
186int gdk_pixbuf_get_height (const GdkPixbuf *pixbuf);
187GDK_PIXBUF_AVAILABLE_IN_ALL
188int gdk_pixbuf_get_rowstride (const GdkPixbuf *pixbuf);
189GDK_PIXBUF_AVAILABLE_IN_2_26
190gsize gdk_pixbuf_get_byte_length (const GdkPixbuf *pixbuf);
191
192GDK_PIXBUF_AVAILABLE_IN_2_26
193guchar *gdk_pixbuf_get_pixels_with_length (const GdkPixbuf *pixbuf,
194 guint *length);
195
196GDK_PIXBUF_AVAILABLE_IN_2_32
197const guint8* gdk_pixbuf_read_pixels (const GdkPixbuf *pixbuf);
198GDK_PIXBUF_AVAILABLE_IN_2_32
199GBytes * gdk_pixbuf_read_pixel_bytes (const GdkPixbuf *pixbuf);
200
201
202
203/* Create a blank pixbuf with an optimal rowstride and a new buffer */
204
205GDK_PIXBUF_AVAILABLE_IN_ALL
206GdkPixbuf *gdk_pixbuf_new (GdkColorspace colorspace, gboolean has_alpha, int bits_per_sample,
207 int width, int height);
208
209GDK_PIXBUF_AVAILABLE_IN_2_36
210gint gdk_pixbuf_calculate_rowstride (GdkColorspace colorspace,
211 gboolean has_alpha,
212 int bits_per_sample,
213 int width,
214 int height);
215
216/* Copy a pixbuf */
217GDK_PIXBUF_AVAILABLE_IN_ALL
218GdkPixbuf *gdk_pixbuf_copy (const GdkPixbuf *pixbuf);
219
220/* Create a pixbuf which points to the pixels of another pixbuf */
221GDK_PIXBUF_AVAILABLE_IN_ALL
222GdkPixbuf *gdk_pixbuf_new_subpixbuf (GdkPixbuf *src_pixbuf,
223 int src_x,
224 int src_y,
225 int width,
226 int height);
227
228/* Simple loading */
229
230#ifdef G_OS_WIN32
231/* In previous versions these _utf8 variants where exported and linked to
232 * by default. Export them here for ABI (and gi API) compat.
233 */
234
235GDK_PIXBUF_AVAILABLE_IN_ALL
236GdkPixbuf *gdk_pixbuf_new_from_file_utf8 (const char *filename,
237 GError **error);
238GDK_PIXBUF_AVAILABLE_IN_2_4
239GdkPixbuf *gdk_pixbuf_new_from_file_at_size_utf8 (const char *filename,
240 int width,
241 int height,
242 GError **error);
243GDK_PIXBUF_AVAILABLE_IN_2_6
244GdkPixbuf *gdk_pixbuf_new_from_file_at_scale_utf8 (const char *filename,
245 int width,
246 int height,
247 gboolean preserve_aspect_ratio,
248 GError **error);
249#endif
250
251GDK_PIXBUF_AVAILABLE_IN_ALL
252GdkPixbuf *gdk_pixbuf_new_from_file (const char *filename,
253 GError **error);
254GDK_PIXBUF_AVAILABLE_IN_2_4
255GdkPixbuf *gdk_pixbuf_new_from_file_at_size (const char *filename,
256 int width,
257 int height,
258 GError **error);
259GDK_PIXBUF_AVAILABLE_IN_2_6
260GdkPixbuf *gdk_pixbuf_new_from_file_at_scale (const char *filename,
261 int width,
262 int height,
263 gboolean preserve_aspect_ratio,
264 GError **error);
265GDK_PIXBUF_AVAILABLE_IN_2_26
266GdkPixbuf *gdk_pixbuf_new_from_resource (const char *resource_path,
267 GError **error);
268GDK_PIXBUF_AVAILABLE_IN_2_26
269GdkPixbuf *gdk_pixbuf_new_from_resource_at_scale (const char *resource_path,
270 int width,
271 int height,
272 gboolean preserve_aspect_ratio,
273 GError **error);
274
275GDK_PIXBUF_AVAILABLE_IN_ALL
276GdkPixbuf *gdk_pixbuf_new_from_data (const guchar *data,
277 GdkColorspace colorspace,
278 gboolean has_alpha,
279 int bits_per_sample,
280 int width, int height,
281 int rowstride,
282 GdkPixbufDestroyNotify destroy_fn,
283 gpointer destroy_fn_data);
284
285GDK_PIXBUF_AVAILABLE_IN_2_32
286GdkPixbuf *gdk_pixbuf_new_from_bytes (GBytes *data,
287 GdkColorspace colorspace,
288 gboolean has_alpha,
289 int bits_per_sample,
290 int width, int height,
291 int rowstride);
292
293GDK_PIXBUF_AVAILABLE_IN_ALL
294GdkPixbuf *gdk_pixbuf_new_from_xpm_data (const char **data);
295
296#ifndef GDK_PIXBUF_DISABLE_DEPRECATED
297GDK_PIXBUF_DEPRECATED_IN_2_32
298GdkPixbuf* gdk_pixbuf_new_from_inline (gint data_length,
299 const guint8 *data,
300 gboolean copy_pixels,
301 GError **error);
302#endif
303
304/* Mutations */
305GDK_PIXBUF_AVAILABLE_IN_ALL
306void gdk_pixbuf_fill (GdkPixbuf *pixbuf,
307 guint32 pixel);
308
309/* Saving */
310
311#ifndef __GTK_DOC_IGNORE__
312#ifdef G_OS_WIN32
313/* DLL ABI stability hack. */
314#define gdk_pixbuf_save gdk_pixbuf_save_utf8
315#endif
316#endif
317
318GDK_PIXBUF_AVAILABLE_IN_ALL
319gboolean gdk_pixbuf_save (GdkPixbuf *pixbuf,
320 const char *filename,
321 const char *type,
322 GError **error,
323 ...) G_GNUC_NULL_TERMINATED;
324
325GDK_PIXBUF_AVAILABLE_IN_ALL
326gboolean gdk_pixbuf_savev (GdkPixbuf *pixbuf,
327 const char *filename,
328 const char *type,
329 char **option_keys,
330 char **option_values,
331 GError **error);
332
333#ifdef G_OS_WIN32
334GDK_PIXBUF_AVAILABLE_IN_ALL
335gboolean gdk_pixbuf_savev_utf8 (GdkPixbuf *pixbuf,
336 const char *filename,
337 const char *type,
338 char **option_keys,
339 char **option_values,
340 GError **error);
341#endif
342
343/* Saving to a callback function */
344
345
346/**
347 * GdkPixbufSaveFunc:
348 * @buf: (array length=count) (element-type guint8): bytes to be written.
349 * @count: number of bytes in @buf.
350 * @error: (out): A location to return an error.
351 * @data: (closure): user data passed to gdk_pixbuf_save_to_callback().
352 *
353 * Save functions used by [method@GdkPixbuf.Pixbuf.save_to_callback].
354 *
355 * This function is called once for each block of bytes that is "written"
356 * by `gdk_pixbuf_save_to_callback()`.
357 *
358 * If successful it should return `TRUE`; if an error occurs it should set
359 * `error` and return `FALSE`, in which case `gdk_pixbuf_save_to_callback()`
360 * will fail with the same error.
361 *
362 * Returns: `TRUE` if successful, `FALSE` otherwise
363 *
364 * Since: 2.4
365 */
366
367typedef gboolean (*GdkPixbufSaveFunc) (const gchar *buf,
368 gsize count,
369 GError **error,
370 gpointer data);
371
372GDK_PIXBUF_AVAILABLE_IN_2_4
373gboolean gdk_pixbuf_save_to_callback (GdkPixbuf *pixbuf,
374 GdkPixbufSaveFunc save_func,
375 gpointer user_data,
376 const char *type,
377 GError **error,
378 ...) G_GNUC_NULL_TERMINATED;
379
380GDK_PIXBUF_AVAILABLE_IN_2_4
381gboolean gdk_pixbuf_save_to_callbackv (GdkPixbuf *pixbuf,
382 GdkPixbufSaveFunc save_func,
383 gpointer user_data,
384 const char *type,
385 char **option_keys,
386 char **option_values,
387 GError **error);
388
389/* Saving into a newly allocated char array */
390
391GDK_PIXBUF_AVAILABLE_IN_2_4
392gboolean gdk_pixbuf_save_to_buffer (GdkPixbuf *pixbuf,
393 gchar **buffer,
394 gsize *buffer_size,
395 const char *type,
396 GError **error,
397 ...) G_GNUC_NULL_TERMINATED;
398
399GDK_PIXBUF_AVAILABLE_IN_2_4
400gboolean gdk_pixbuf_save_to_bufferv (GdkPixbuf *pixbuf,
401 gchar **buffer,
402 gsize *buffer_size,
403 const char *type,
404 char **option_keys,
405 char **option_values,
406 GError **error);
407
408GDK_PIXBUF_AVAILABLE_IN_2_14
409GdkPixbuf *gdk_pixbuf_new_from_stream (GInputStream *stream,
410 GCancellable *cancellable,
411 GError **error);
412
413GDK_PIXBUF_AVAILABLE_IN_ALL
414void gdk_pixbuf_new_from_stream_async (GInputStream *stream,
415 GCancellable *cancellable,
416 GAsyncReadyCallback callback,
417 gpointer user_data);
418
419GDK_PIXBUF_AVAILABLE_IN_ALL
420GdkPixbuf *gdk_pixbuf_new_from_stream_finish (GAsyncResult *async_result,
421 GError **error);
422
423GDK_PIXBUF_AVAILABLE_IN_2_14
424GdkPixbuf *gdk_pixbuf_new_from_stream_at_scale (GInputStream *stream,
425 gint width,
426 gint height,
427 gboolean preserve_aspect_ratio,
428 GCancellable *cancellable,
429 GError **error);
430
431GDK_PIXBUF_AVAILABLE_IN_ALL
432void gdk_pixbuf_new_from_stream_at_scale_async (GInputStream *stream,
433 gint width,
434 gint height,
435 gboolean preserve_aspect_ratio,
436 GCancellable *cancellable,
437 GAsyncReadyCallback callback,
438 gpointer user_data);
439
440GDK_PIXBUF_AVAILABLE_IN_2_14
441gboolean gdk_pixbuf_save_to_stream (GdkPixbuf *pixbuf,
442 GOutputStream *stream,
443 const char *type,
444 GCancellable *cancellable,
445 GError **error,
446 ...);
447
448GDK_PIXBUF_AVAILABLE_IN_ALL
449void gdk_pixbuf_save_to_stream_async (GdkPixbuf *pixbuf,
450 GOutputStream *stream,
451 const gchar *type,
452 GCancellable *cancellable,
453 GAsyncReadyCallback callback,
454 gpointer user_data,
455 ...);
456
457GDK_PIXBUF_AVAILABLE_IN_ALL
458gboolean gdk_pixbuf_save_to_stream_finish (GAsyncResult *async_result,
459 GError **error);
460
461GDK_PIXBUF_AVAILABLE_IN_2_36
462void gdk_pixbuf_save_to_streamv_async (GdkPixbuf *pixbuf,
463 GOutputStream *stream,
464 const gchar *type,
465 gchar **option_keys,
466 gchar **option_values,
467 GCancellable *cancellable,
468 GAsyncReadyCallback callback,
469 gpointer user_data);
470
471GDK_PIXBUF_AVAILABLE_IN_2_36
472gboolean gdk_pixbuf_save_to_streamv (GdkPixbuf *pixbuf,
473 GOutputStream *stream,
474 const char *type,
475 char **option_keys,
476 char **option_values,
477 GCancellable *cancellable,
478 GError **error);
479
480/* Adding an alpha channel */
481GDK_PIXBUF_AVAILABLE_IN_ALL
482GdkPixbuf *gdk_pixbuf_add_alpha (const GdkPixbuf *pixbuf, gboolean substitute_color,
483 guchar r, guchar g, guchar b);
484
485/* Copy an area of a pixbuf onto another one */
486GDK_PIXBUF_AVAILABLE_IN_ALL
487void gdk_pixbuf_copy_area (const GdkPixbuf *src_pixbuf,
488 int src_x, int src_y,
489 int width, int height,
490 GdkPixbuf *dest_pixbuf,
491 int dest_x, int dest_y);
492
493/* Brighten/darken and optionally make it pixelated-looking */
494GDK_PIXBUF_AVAILABLE_IN_ALL
495void gdk_pixbuf_saturate_and_pixelate (const GdkPixbuf *src,
496 GdkPixbuf *dest,
497 gfloat saturation,
498 gboolean pixelate);
499
500/* Transform an image to agree with its embedded orientation option / tag */
501GDK_PIXBUF_AVAILABLE_IN_2_12
502GdkPixbuf *gdk_pixbuf_apply_embedded_orientation (GdkPixbuf *src);
503
504/* key/value pairs that can be attached by the pixbuf loader */
505GDK_PIXBUF_AVAILABLE_IN_ALL
506gboolean gdk_pixbuf_set_option (GdkPixbuf *pixbuf,
507 const gchar *key,
508 const gchar *value);
509GDK_PIXBUF_AVAILABLE_IN_ALL
510const gchar * gdk_pixbuf_get_option (GdkPixbuf *pixbuf,
511 const gchar *key);
512GDK_PIXBUF_AVAILABLE_IN_2_36
513gboolean gdk_pixbuf_remove_option (GdkPixbuf *pixbuf,
514 const gchar *key);
515GDK_PIXBUF_AVAILABLE_IN_2_32
516GHashTable * gdk_pixbuf_get_options (GdkPixbuf *pixbuf);
517GDK_PIXBUF_AVAILABLE_IN_2_36
518gboolean gdk_pixbuf_copy_options (GdkPixbuf *src_pixbuf,
519 GdkPixbuf *dest_pixbuf);
520
521
522G_END_DECLS
523
524
525#endif /* GDK_PIXBUF_CORE_H */
526