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
164GDK_PIXBUF_DEPRECATED_IN_2_0_FOR(g_object_ref)
165GdkPixbuf *gdk_pixbuf_ref (GdkPixbuf *pixbuf);
166GDK_PIXBUF_DEPRECATED_IN_2_0_FOR(g_object_unref)
167void gdk_pixbuf_unref (GdkPixbuf *pixbuf);
168
169/* GdkPixbuf accessors */
170
171GDK_PIXBUF_AVAILABLE_IN_ALL
172GdkColorspace gdk_pixbuf_get_colorspace (const GdkPixbuf *pixbuf);
173GDK_PIXBUF_AVAILABLE_IN_ALL
174int gdk_pixbuf_get_n_channels (const GdkPixbuf *pixbuf);
175GDK_PIXBUF_AVAILABLE_IN_ALL
176gboolean gdk_pixbuf_get_has_alpha (const GdkPixbuf *pixbuf);
177GDK_PIXBUF_AVAILABLE_IN_ALL
178int gdk_pixbuf_get_bits_per_sample (const GdkPixbuf *pixbuf);
179GDK_PIXBUF_AVAILABLE_IN_ALL
180guchar *gdk_pixbuf_get_pixels (const GdkPixbuf *pixbuf);
181GDK_PIXBUF_AVAILABLE_IN_ALL
182int gdk_pixbuf_get_width (const GdkPixbuf *pixbuf);
183GDK_PIXBUF_AVAILABLE_IN_ALL
184int gdk_pixbuf_get_height (const GdkPixbuf *pixbuf);
185GDK_PIXBUF_AVAILABLE_IN_ALL
186int gdk_pixbuf_get_rowstride (const GdkPixbuf *pixbuf);
187GDK_PIXBUF_AVAILABLE_IN_2_26
188gsize gdk_pixbuf_get_byte_length (const GdkPixbuf *pixbuf);
189
190GDK_PIXBUF_AVAILABLE_IN_2_26
191guchar *gdk_pixbuf_get_pixels_with_length (const GdkPixbuf *pixbuf,
192 guint *length);
193
194GDK_PIXBUF_AVAILABLE_IN_2_32
195const guint8* gdk_pixbuf_read_pixels (const GdkPixbuf *pixbuf);
196GDK_PIXBUF_AVAILABLE_IN_2_32
197GBytes * gdk_pixbuf_read_pixel_bytes (const GdkPixbuf *pixbuf);
198
199
200
201/* Create a blank pixbuf with an optimal rowstride and a new buffer */
202
203GDK_PIXBUF_AVAILABLE_IN_ALL
204GdkPixbuf *gdk_pixbuf_new (GdkColorspace colorspace, gboolean has_alpha, int bits_per_sample,
205 int width, int height);
206
207GDK_PIXBUF_AVAILABLE_IN_2_36
208gint gdk_pixbuf_calculate_rowstride (GdkColorspace colorspace,
209 gboolean has_alpha,
210 int bits_per_sample,
211 int width,
212 int height);
213
214/* Copy a pixbuf */
215GDK_PIXBUF_AVAILABLE_IN_ALL
216GdkPixbuf *gdk_pixbuf_copy (const GdkPixbuf *pixbuf);
217
218/* Create a pixbuf which points to the pixels of another pixbuf */
219GDK_PIXBUF_AVAILABLE_IN_ALL
220GdkPixbuf *gdk_pixbuf_new_subpixbuf (GdkPixbuf *src_pixbuf,
221 int src_x,
222 int src_y,
223 int width,
224 int height);
225
226/* Simple loading */
227
228#ifdef G_OS_WIN32
229/* In previous versions these _utf8 variants where exported and linked to
230 * by default. Export them here for ABI (and gi API) compat.
231 */
232
233GDK_PIXBUF_AVAILABLE_IN_ALL
234GdkPixbuf *gdk_pixbuf_new_from_file_utf8 (const char *filename,
235 GError **error);
236GDK_PIXBUF_AVAILABLE_IN_2_4
237GdkPixbuf *gdk_pixbuf_new_from_file_at_size_utf8 (const char *filename,
238 int width,
239 int height,
240 GError **error);
241GDK_PIXBUF_AVAILABLE_IN_2_6
242GdkPixbuf *gdk_pixbuf_new_from_file_at_scale_utf8 (const char *filename,
243 int width,
244 int height,
245 gboolean preserve_aspect_ratio,
246 GError **error);
247#endif
248
249GDK_PIXBUF_AVAILABLE_IN_ALL
250GdkPixbuf *gdk_pixbuf_new_from_file (const char *filename,
251 GError **error);
252GDK_PIXBUF_AVAILABLE_IN_2_4
253GdkPixbuf *gdk_pixbuf_new_from_file_at_size (const char *filename,
254 int width,
255 int height,
256 GError **error);
257GDK_PIXBUF_AVAILABLE_IN_2_6
258GdkPixbuf *gdk_pixbuf_new_from_file_at_scale (const char *filename,
259 int width,
260 int height,
261 gboolean preserve_aspect_ratio,
262 GError **error);
263GDK_PIXBUF_AVAILABLE_IN_2_26
264GdkPixbuf *gdk_pixbuf_new_from_resource (const char *resource_path,
265 GError **error);
266GDK_PIXBUF_AVAILABLE_IN_2_26
267GdkPixbuf *gdk_pixbuf_new_from_resource_at_scale (const char *resource_path,
268 int width,
269 int height,
270 gboolean preserve_aspect_ratio,
271 GError **error);
272
273GDK_PIXBUF_AVAILABLE_IN_ALL
274GdkPixbuf *gdk_pixbuf_new_from_data (const guchar *data,
275 GdkColorspace colorspace,
276 gboolean has_alpha,
277 int bits_per_sample,
278 int width, int height,
279 int rowstride,
280 GdkPixbufDestroyNotify destroy_fn,
281 gpointer destroy_fn_data);
282
283GDK_PIXBUF_AVAILABLE_IN_2_32
284GdkPixbuf *gdk_pixbuf_new_from_bytes (GBytes *data,
285 GdkColorspace colorspace,
286 gboolean has_alpha,
287 int bits_per_sample,
288 int width, int height,
289 int rowstride);
290
291GDK_PIXBUF_DEPRECATED_IN_2_44
292GdkPixbuf *gdk_pixbuf_new_from_xpm_data (const char **data);
293
294GDK_PIXBUF_DEPRECATED_IN_2_32
295GdkPixbuf* gdk_pixbuf_new_from_inline (gint data_length,
296 const guint8 *data,
297 gboolean copy_pixels,
298 GError **error);
299/* Mutations */
300GDK_PIXBUF_AVAILABLE_IN_ALL
301void gdk_pixbuf_fill (GdkPixbuf *pixbuf,
302 guint32 pixel);
303
304/* Saving */
305
306#ifndef __GTK_DOC_IGNORE__
307#ifdef G_OS_WIN32
308/* DLL ABI stability hack. */
309#define gdk_pixbuf_save gdk_pixbuf_save_utf8
310#endif
311#endif
312
313GDK_PIXBUF_AVAILABLE_IN_ALL
314gboolean gdk_pixbuf_save (GdkPixbuf *pixbuf,
315 const char *filename,
316 const char *type,
317 GError **error,
318 ...) G_GNUC_NULL_TERMINATED;
319
320GDK_PIXBUF_AVAILABLE_IN_ALL
321gboolean gdk_pixbuf_savev (GdkPixbuf *pixbuf,
322 const char *filename,
323 const char *type,
324 char **option_keys,
325 char **option_values,
326 GError **error);
327
328#ifdef G_OS_WIN32
329GDK_PIXBUF_AVAILABLE_IN_ALL
330gboolean gdk_pixbuf_savev_utf8 (GdkPixbuf *pixbuf,
331 const char *filename,
332 const char *type,
333 char **option_keys,
334 char **option_values,
335 GError **error);
336#endif
337
338/* Saving to a callback function */
339
340
341/**
342 * GdkPixbufSaveFunc:
343 * @buf: (array length=count) (element-type guint8): bytes to be written.
344 * @count: number of bytes in @buf.
345 * @error: (out): A location to return an error.
346 * @data: (closure): user data passed to gdk_pixbuf_save_to_callback().
347 *
348 * Save functions used by [method@GdkPixbuf.Pixbuf.save_to_callback].
349 *
350 * This function is called once for each block of bytes that is "written"
351 * by `gdk_pixbuf_save_to_callback()`.
352 *
353 * If successful it should return `TRUE`; if an error occurs it should set
354 * `error` and return `FALSE`, in which case `gdk_pixbuf_save_to_callback()`
355 * will fail with the same error.
356 *
357 * Returns: `TRUE` if successful, `FALSE` otherwise
358 *
359 * Since: 2.4
360 */
361
362typedef gboolean (*GdkPixbufSaveFunc) (const gchar *buf,
363 gsize count,
364 GError **error,
365 gpointer data);
366
367GDK_PIXBUF_AVAILABLE_IN_2_4
368gboolean gdk_pixbuf_save_to_callback (GdkPixbuf *pixbuf,
369 GdkPixbufSaveFunc save_func,
370 gpointer user_data,
371 const char *type,
372 GError **error,
373 ...) G_GNUC_NULL_TERMINATED;
374
375GDK_PIXBUF_AVAILABLE_IN_2_4
376gboolean gdk_pixbuf_save_to_callbackv (GdkPixbuf *pixbuf,
377 GdkPixbufSaveFunc save_func,
378 gpointer user_data,
379 const char *type,
380 char **option_keys,
381 char **option_values,
382 GError **error);
383
384/* Saving into a newly allocated char array */
385
386GDK_PIXBUF_AVAILABLE_IN_2_4
387gboolean gdk_pixbuf_save_to_buffer (GdkPixbuf *pixbuf,
388 gchar **buffer,
389 gsize *buffer_size,
390 const char *type,
391 GError **error,
392 ...) G_GNUC_NULL_TERMINATED;
393
394GDK_PIXBUF_AVAILABLE_IN_2_4
395gboolean gdk_pixbuf_save_to_bufferv (GdkPixbuf *pixbuf,
396 gchar **buffer,
397 gsize *buffer_size,
398 const char *type,
399 char **option_keys,
400 char **option_values,
401 GError **error);
402
403GDK_PIXBUF_AVAILABLE_IN_2_14
404GdkPixbuf *gdk_pixbuf_new_from_stream (GInputStream *stream,
405 GCancellable *cancellable,
406 GError **error);
407
408GDK_PIXBUF_AVAILABLE_IN_ALL
409void gdk_pixbuf_new_from_stream_async (GInputStream *stream,
410 GCancellable *cancellable,
411 GAsyncReadyCallback callback,
412 gpointer user_data);
413
414GDK_PIXBUF_AVAILABLE_IN_ALL
415GdkPixbuf *gdk_pixbuf_new_from_stream_finish (GAsyncResult *async_result,
416 GError **error);
417
418GDK_PIXBUF_AVAILABLE_IN_2_14
419GdkPixbuf *gdk_pixbuf_new_from_stream_at_scale (GInputStream *stream,
420 gint width,
421 gint height,
422 gboolean preserve_aspect_ratio,
423 GCancellable *cancellable,
424 GError **error);
425
426GDK_PIXBUF_AVAILABLE_IN_ALL
427void gdk_pixbuf_new_from_stream_at_scale_async (GInputStream *stream,
428 gint width,
429 gint height,
430 gboolean preserve_aspect_ratio,
431 GCancellable *cancellable,
432 GAsyncReadyCallback callback,
433 gpointer user_data);
434
435GDK_PIXBUF_AVAILABLE_IN_2_14
436gboolean gdk_pixbuf_save_to_stream (GdkPixbuf *pixbuf,
437 GOutputStream *stream,
438 const char *type,
439 GCancellable *cancellable,
440 GError **error,
441 ...);
442
443GDK_PIXBUF_AVAILABLE_IN_ALL
444void gdk_pixbuf_save_to_stream_async (GdkPixbuf *pixbuf,
445 GOutputStream *stream,
446 const gchar *type,
447 GCancellable *cancellable,
448 GAsyncReadyCallback callback,
449 gpointer user_data,
450 ...);
451
452GDK_PIXBUF_AVAILABLE_IN_ALL
453gboolean gdk_pixbuf_save_to_stream_finish (GAsyncResult *async_result,
454 GError **error);
455
456GDK_PIXBUF_AVAILABLE_IN_2_36
457void gdk_pixbuf_save_to_streamv_async (GdkPixbuf *pixbuf,
458 GOutputStream *stream,
459 const gchar *type,
460 gchar **option_keys,
461 gchar **option_values,
462 GCancellable *cancellable,
463 GAsyncReadyCallback callback,
464 gpointer user_data);
465
466GDK_PIXBUF_AVAILABLE_IN_2_36
467gboolean gdk_pixbuf_save_to_streamv (GdkPixbuf *pixbuf,
468 GOutputStream *stream,
469 const char *type,
470 char **option_keys,
471 char **option_values,
472 GCancellable *cancellable,
473 GError **error);
474
475/* Adding an alpha channel */
476GDK_PIXBUF_AVAILABLE_IN_ALL
477GdkPixbuf *gdk_pixbuf_add_alpha (const GdkPixbuf *pixbuf, gboolean substitute_color,
478 guchar r, guchar g, guchar b);
479
480/* Copy an area of a pixbuf onto another one */
481GDK_PIXBUF_AVAILABLE_IN_ALL
482void gdk_pixbuf_copy_area (const GdkPixbuf *src_pixbuf,
483 int src_x, int src_y,
484 int width, int height,
485 GdkPixbuf *dest_pixbuf,
486 int dest_x, int dest_y);
487
488/* Brighten/darken and optionally make it pixelated-looking */
489GDK_PIXBUF_AVAILABLE_IN_ALL
490void gdk_pixbuf_saturate_and_pixelate (const GdkPixbuf *src,
491 GdkPixbuf *dest,
492 gfloat saturation,
493 gboolean pixelate);
494
495/* Transform an image to agree with its embedded orientation option / tag */
496GDK_PIXBUF_AVAILABLE_IN_2_12
497GdkPixbuf *gdk_pixbuf_apply_embedded_orientation (GdkPixbuf *src);
498
499/* key/value pairs that can be attached by the pixbuf loader */
500GDK_PIXBUF_AVAILABLE_IN_ALL
501gboolean gdk_pixbuf_set_option (GdkPixbuf *pixbuf,
502 const gchar *key,
503 const gchar *value);
504GDK_PIXBUF_AVAILABLE_IN_ALL
505const gchar * gdk_pixbuf_get_option (GdkPixbuf *pixbuf,
506 const gchar *key);
507GDK_PIXBUF_AVAILABLE_IN_2_36
508gboolean gdk_pixbuf_remove_option (GdkPixbuf *pixbuf,
509 const gchar *key);
510GDK_PIXBUF_AVAILABLE_IN_2_32
511GHashTable * gdk_pixbuf_get_options (GdkPixbuf *pixbuf);
512GDK_PIXBUF_AVAILABLE_IN_2_36
513gboolean gdk_pixbuf_copy_options (GdkPixbuf *src_pixbuf,
514 GdkPixbuf *dest_pixbuf);
515
516
517G_DEFINE_AUTOPTR_CLEANUP_FUNC(GdkPixbuf, g_object_unref)
518
519G_END_DECLS
520
521#endif /* GDK_PIXBUF_CORE_H */
522