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
35G_BEGIN_DECLS
36
37/**
38 * SECTION:gdk-pixbuf
39 * @Short_description: Information that describes an image.
40 * @Title: The GdkPixbuf Structure
41 *
42 * The #GdkPixbuf structure contains
43 * information that describes an image in memory.
44 *
45 * ## Image Data ## {#image-data}
46 *
47 * Image data in a pixbuf is stored in memory in uncompressed,
48 * packed format. Rows in the image are stored top to bottom, and
49 * in each row pixels are stored from left to right. There may be
50 * padding at the end of a row. The "rowstride" value of a pixbuf,
51 * as returned by gdk_pixbuf_get_rowstride(), indicates the number
52 * of bytes between rows.
53 *
54 * ## put_pixel() Example ## {#put-pixel}
55 *
56 * The following code illustrates a simple put_pixel()
57 * function for RGB pixbufs with 8 bits per channel with an alpha
58 * channel. It is not included in the gdk-pixbuf library for
59 * performance reasons; rather than making several function calls
60 * for each pixel, your own code can take shortcuts.
61 *
62 * |[<!-- language="C" -->
63 * static void
64 * put_pixel (GdkPixbuf *pixbuf, int x, int y, guchar red, guchar green, guchar blue, guchar alpha)
65 * {
66 * int width, height, rowstride, n_channels;
67 * guchar *pixels, *p;
68 *
69 * n_channels = gdk_pixbuf_get_n_channels (pixbuf);
70 *
71 * g_assert (gdk_pixbuf_get_colorspace (pixbuf) == GDK_COLORSPACE_RGB);
72 * g_assert (gdk_pixbuf_get_bits_per_sample (pixbuf) == 8);
73 * g_assert (gdk_pixbuf_get_has_alpha (pixbuf));
74 * g_assert (n_channels == 4);
75 *
76 * width = gdk_pixbuf_get_width (pixbuf);
77 * height = gdk_pixbuf_get_height (pixbuf);
78 *
79 * g_assert (x >= 0 && x < width);
80 * g_assert (y >= 0 && y < height);
81 *
82 * rowstride = gdk_pixbuf_get_rowstride (pixbuf);
83 * pixels = gdk_pixbuf_get_pixels (pixbuf);
84 *
85 * p = pixels + y * rowstride + x * n_channels;
86 * p[0] = red;
87 * p[1] = green;
88 * p[2] = blue;
89 * p[3] = alpha;
90 * }
91 * ]|
92 *
93 * This function will not work for pixbufs with images that are
94 * other than 8 bits per sample or channel, but it will work for
95 * most of the pixbufs that GTK+ uses.
96 *
97 * If you are doing memcpy() of raw pixbuf data, note that the last row
98 * in the pixbuf may not be as wide as the full rowstride, but rather
99 * just as wide as the pixel data needs to be. That is, it is unsafe to
100 * do `memcpy (dest, pixels, rowstride * height)` to copy a whole pixbuf.
101 * Use gdk_pixbuf_copy() instead, or compute the width in bytes of the
102 * last row as `width * ((n_channels * bits_per_sample + 7) / 8)`.
103 */
104
105
106/**
107 * GdkPixbufAlphaMode:
108 * @GDK_PIXBUF_ALPHA_BILEVEL: A bilevel clipping mask (black and white)
109 * will be created and used to draw the image. Pixels below 0.5 opacity
110 * will be considered fully transparent, and all others will be
111 * considered fully opaque.
112 * @GDK_PIXBUF_ALPHA_FULL: For now falls back to #GDK_PIXBUF_ALPHA_BILEVEL.
113 * In the future it will do full alpha compositing.
114 *
115 * These values can be passed to
116 * gdk_pixbuf_render_to_drawable_alpha() to control how the alpha
117 * channel of an image should be handled. This function can create a
118 * bilevel clipping mask (black and white) and use it while painting
119 * the image. In the future, when the X Window System gets an alpha
120 * channel extension, it will be possible to do full alpha
121 * compositing onto arbitrary drawables. For now both cases fall
122 * back to a bilevel clipping mask.
123 */
124typedef enum
125{
126 GDK_PIXBUF_ALPHA_BILEVEL,
127 GDK_PIXBUF_ALPHA_FULL
128} GdkPixbufAlphaMode;
129
130/**
131 * GdkColorspace:
132 * @GDK_COLORSPACE_RGB: Indicates a red/green/blue additive color space.
133 *
134 * This enumeration defines the color spaces that are supported by
135 * the gdk-pixbuf library. Currently only RGB is supported.
136 */
137/* Note that these values are encoded in inline pixbufs
138 * as ints, so don't reorder them
139 */
140typedef enum {
141 GDK_COLORSPACE_RGB
142} GdkColorspace;
143
144/* All of these are opaque structures */
145
146/**
147 * GdkPixbuf:
148 *
149 * This is the main structure in the gdk-pixbuf library. It is
150 * used to represent images. It contains information about the
151 * image's pixel data, its color space, bits per sample, width and
152 * height, and the rowstride (the number of bytes between the start of
153 * one row and the start of the next).
154 */
155typedef struct _GdkPixbuf GdkPixbuf;
156
157#define GDK_TYPE_PIXBUF (gdk_pixbuf_get_type ())
158#define GDK_PIXBUF(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), GDK_TYPE_PIXBUF, GdkPixbuf))
159#define GDK_IS_PIXBUF(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), GDK_TYPE_PIXBUF))
160
161
162/**
163 * GdkPixbufDestroyNotify:
164 * @pixels: (array) (element-type guint8): The pixel array of the pixbuf
165 * that is being finalized.
166 * @data: (closure): User closure data.
167 *
168 * A function of this type is responsible for freeing the pixel array
169 * of a pixbuf. The gdk_pixbuf_new_from_data() function lets you
170 * pass in a pre-allocated pixel array so that a pixbuf can be
171 * created from it; in this case you will need to pass in a function
172 * of #GdkPixbufDestroyNotify so that the pixel data can be freed
173 * when the pixbuf is finalized.
174 */
175typedef void (* GdkPixbufDestroyNotify) (guchar *pixels, gpointer data);
176
177/**
178 * GDK_PIXBUF_ERROR:
179 *
180 * Error domain used for pixbuf operations. Indicates that the error code
181 * will be in the #GdkPixbufError enumeration. See #GError for
182 * information on error domains and error codes.
183 */
184#define GDK_PIXBUF_ERROR gdk_pixbuf_error_quark ()
185
186/**
187 * GdkPixbufError:
188 * @GDK_PIXBUF_ERROR_CORRUPT_IMAGE: An image file was broken somehow.
189 * @GDK_PIXBUF_ERROR_INSUFFICIENT_MEMORY: Not enough memory.
190 * @GDK_PIXBUF_ERROR_BAD_OPTION: A bad option was passed to a pixbuf save module.
191 * @GDK_PIXBUF_ERROR_UNKNOWN_TYPE: Unknown image type.
192 * @GDK_PIXBUF_ERROR_UNSUPPORTED_OPERATION: Don't know how to perform the
193 * given operation on the type of image at hand.
194 * @GDK_PIXBUF_ERROR_FAILED: Generic failure code, something went wrong.
195 * @GDK_PIXBUF_ERROR_INCOMPLETE_ANIMATION: Only part of the animation was loaded.
196 *
197 * An error code in the #GDK_PIXBUF_ERROR domain. Many gdk-pixbuf
198 * operations can cause errors in this domain, or in the #G_FILE_ERROR
199 * domain.
200 */
201typedef enum {
202 /* image data hosed */
203 GDK_PIXBUF_ERROR_CORRUPT_IMAGE,
204 /* no mem to load image */
205 GDK_PIXBUF_ERROR_INSUFFICIENT_MEMORY,
206 /* bad option passed to save routine */
207 GDK_PIXBUF_ERROR_BAD_OPTION,
208 /* unsupported image type (sort of an ENOSYS) */
209 GDK_PIXBUF_ERROR_UNKNOWN_TYPE,
210 /* unsupported operation (load, save) for image type */
211 GDK_PIXBUF_ERROR_UNSUPPORTED_OPERATION,
212 GDK_PIXBUF_ERROR_FAILED,
213 GDK_PIXBUF_ERROR_INCOMPLETE_ANIMATION
214} GdkPixbufError;
215
216GQuark gdk_pixbuf_error_quark (void);
217
218
219
220GType gdk_pixbuf_get_type (void) G_GNUC_CONST;
221
222/* Reference counting */
223
224#ifndef GDK_PIXBUF_DISABLE_DEPRECATED
225G_DEPRECATED_FOR(g_object_ref)
226GdkPixbuf *gdk_pixbuf_ref (GdkPixbuf *pixbuf);
227G_DEPRECATED_FOR(g_object_unref)
228void gdk_pixbuf_unref (GdkPixbuf *pixbuf);
229#endif
230
231/* GdkPixbuf accessors */
232
233GdkColorspace gdk_pixbuf_get_colorspace (const GdkPixbuf *pixbuf);
234int gdk_pixbuf_get_n_channels (const GdkPixbuf *pixbuf);
235gboolean gdk_pixbuf_get_has_alpha (const GdkPixbuf *pixbuf);
236int gdk_pixbuf_get_bits_per_sample (const GdkPixbuf *pixbuf);
237guchar *gdk_pixbuf_get_pixels (const GdkPixbuf *pixbuf);
238int gdk_pixbuf_get_width (const GdkPixbuf *pixbuf);
239int gdk_pixbuf_get_height (const GdkPixbuf *pixbuf);
240int gdk_pixbuf_get_rowstride (const GdkPixbuf *pixbuf);
241gsize gdk_pixbuf_get_byte_length (const GdkPixbuf *pixbuf);
242
243guchar *gdk_pixbuf_get_pixels_with_length (const GdkPixbuf *pixbuf,
244 guint *length);
245
246const guint8* gdk_pixbuf_read_pixels (const GdkPixbuf *pixbuf);
247GBytes * gdk_pixbuf_read_pixel_bytes (const GdkPixbuf *pixbuf);
248
249
250
251/* Create a blank pixbuf with an optimal rowstride and a new buffer */
252GdkPixbuf *gdk_pixbuf_new (GdkColorspace colorspace, gboolean has_alpha, int bits_per_sample,
253 int width, int height);
254
255/* Copy a pixbuf */
256
257GdkPixbuf *gdk_pixbuf_copy (const GdkPixbuf *pixbuf);
258
259/* Create a pixbuf which points to the pixels of another pixbuf */
260GdkPixbuf *gdk_pixbuf_new_subpixbuf (GdkPixbuf *src_pixbuf,
261 int src_x,
262 int src_y,
263 int width,
264 int height);
265
266/* Simple loading */
267
268#ifndef __GTK_DOC_IGNORE__
269#ifdef G_OS_WIN32
270/* DLL ABI stability hack. */
271#define gdk_pixbuf_new_from_file gdk_pixbuf_new_from_file_utf8
272#define gdk_pixbuf_new_from_file_at_size gdk_pixbuf_new_from_file_at_size_utf8
273#define gdk_pixbuf_new_from_file_at_scale gdk_pixbuf_new_from_file_at_scale_utf8
274#endif
275#endif
276
277GdkPixbuf *gdk_pixbuf_new_from_file (const char *filename,
278 GError **error);
279GdkPixbuf *gdk_pixbuf_new_from_file_at_size (const char *filename,
280 int width,
281 int height,
282 GError **error);
283GdkPixbuf *gdk_pixbuf_new_from_file_at_scale (const char *filename,
284 int width,
285 int height,
286 gboolean preserve_aspect_ratio,
287 GError **error);
288GdkPixbuf *gdk_pixbuf_new_from_resource (const char *resource_path,
289 GError **error);
290GdkPixbuf *gdk_pixbuf_new_from_resource_at_scale (const char *resource_path,
291 int width,
292 int height,
293 gboolean preserve_aspect_ratio,
294 GError **error);
295
296GdkPixbuf *gdk_pixbuf_new_from_data (const guchar *data,
297 GdkColorspace colorspace,
298 gboolean has_alpha,
299 int bits_per_sample,
300 int width, int height,
301 int rowstride,
302 GdkPixbufDestroyNotify destroy_fn,
303 gpointer destroy_fn_data);
304
305GdkPixbuf *gdk_pixbuf_new_from_bytes (GBytes *data,
306 GdkColorspace colorspace,
307 gboolean has_alpha,
308 int bits_per_sample,
309 int width, int height,
310 int rowstride);
311
312GdkPixbuf *gdk_pixbuf_new_from_xpm_data (const char **data);
313
314#ifndef GDK_PIXBUF_DISABLE_DEPRECATED
315G_DEPRECATED
316GdkPixbuf* gdk_pixbuf_new_from_inline (gint data_length,
317 const guint8 *data,
318 gboolean copy_pixels,
319 GError **error);
320#endif
321
322/* Mutations */
323void gdk_pixbuf_fill (GdkPixbuf *pixbuf,
324 guint32 pixel);
325
326/* Saving */
327
328#ifndef __GTK_DOC_IGNORE__
329#ifdef G_OS_WIN32
330/* DLL ABI stability hack. */
331#define gdk_pixbuf_save gdk_pixbuf_save_utf8
332#define gdk_pixbuf_savev gdk_pixbuf_savev_utf8
333#endif
334#endif
335
336gboolean gdk_pixbuf_save (GdkPixbuf *pixbuf,
337 const char *filename,
338 const char *type,
339 GError **error,
340 ...) G_GNUC_NULL_TERMINATED;
341
342gboolean gdk_pixbuf_savev (GdkPixbuf *pixbuf,
343 const char *filename,
344 const char *type,
345 char **option_keys,
346 char **option_values,
347 GError **error);
348
349/* Saving to a callback function */
350
351
352/**
353 * GdkPixbufSaveFunc:
354 * @buf: (array length=count) (element-type guint8): bytes to be written.
355 * @count: number of bytes in @buf.
356 * @error: (out): A location to return an error.
357 * @data: (closure): user data passed to gdk_pixbuf_save_to_callback().
358 *
359 * Specifies the type of the function passed to
360 * gdk_pixbuf_save_to_callback(). It is called once for each block of
361 * bytes that is "written" by gdk_pixbuf_save_to_callback(). If
362 * successful it should return %TRUE. If an error occurs it should set
363 * @error and return %FALSE, in which case gdk_pixbuf_save_to_callback()
364 * will fail with the same error.
365 *
366 * Since: 2.4
367 * Returns: %TRUE if successful, %FALSE (with @error set) if failed.
368 */
369
370typedef gboolean (*GdkPixbufSaveFunc) (const gchar *buf,
371 gsize count,
372 GError **error,
373 gpointer data);
374
375gboolean gdk_pixbuf_save_to_callback (GdkPixbuf *pixbuf,
376 GdkPixbufSaveFunc save_func,
377 gpointer user_data,
378 const char *type,
379 GError **error,
380 ...) G_GNUC_NULL_TERMINATED;
381
382gboolean gdk_pixbuf_save_to_callbackv (GdkPixbuf *pixbuf,
383 GdkPixbufSaveFunc save_func,
384 gpointer user_data,
385 const char *type,
386 char **option_keys,
387 char **option_values,
388 GError **error);
389
390/* Saving into a newly allocated char array */
391
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
399gboolean gdk_pixbuf_save_to_bufferv (GdkPixbuf *pixbuf,
400 gchar **buffer,
401 gsize *buffer_size,
402 const char *type,
403 char **option_keys,
404 char **option_values,
405 GError **error);
406
407GdkPixbuf *gdk_pixbuf_new_from_stream (GInputStream *stream,
408 GCancellable *cancellable,
409 GError **error);
410
411void gdk_pixbuf_new_from_stream_async (GInputStream *stream,
412 GCancellable *cancellable,
413 GAsyncReadyCallback callback,
414 gpointer user_data);
415
416GdkPixbuf *gdk_pixbuf_new_from_stream_finish (GAsyncResult *async_result,
417 GError **error);
418
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
426void gdk_pixbuf_new_from_stream_at_scale_async (GInputStream *stream,
427 gint width,
428 gint height,
429 gboolean preserve_aspect_ratio,
430 GCancellable *cancellable,
431 GAsyncReadyCallback callback,
432 gpointer user_data);
433
434gboolean gdk_pixbuf_save_to_stream (GdkPixbuf *pixbuf,
435 GOutputStream *stream,
436 const char *type,
437 GCancellable *cancellable,
438 GError **error,
439 ...);
440
441void gdk_pixbuf_save_to_stream_async (GdkPixbuf *pixbuf,
442 GOutputStream *stream,
443 const gchar *type,
444 GCancellable *cancellable,
445 GAsyncReadyCallback callback,
446 gpointer user_data,
447 ...);
448
449gboolean gdk_pixbuf_save_to_stream_finish (GAsyncResult *async_result,
450 GError **error);
451
452/* Adding an alpha channel */
453GdkPixbuf *gdk_pixbuf_add_alpha (const GdkPixbuf *pixbuf, gboolean substitute_color,
454 guchar r, guchar g, guchar b);
455
456/* Copy an area of a pixbuf onto another one */
457void gdk_pixbuf_copy_area (const GdkPixbuf *src_pixbuf,
458 int src_x, int src_y,
459 int width, int height,
460 GdkPixbuf *dest_pixbuf,
461 int dest_x, int dest_y);
462
463/* Brighten/darken and optionally make it pixelated-looking */
464void gdk_pixbuf_saturate_and_pixelate (const GdkPixbuf *src,
465 GdkPixbuf *dest,
466 gfloat saturation,
467 gboolean pixelate);
468
469/* Transform an image to agree with its embedded orientation option / tag */
470GdkPixbuf *gdk_pixbuf_apply_embedded_orientation (GdkPixbuf *src);
471
472const gchar * gdk_pixbuf_get_option (GdkPixbuf *pixbuf,
473 const gchar *key);
474GHashTable * gdk_pixbuf_get_options (GdkPixbuf *pixbuf);
475
476
477G_END_DECLS
478
479
480#endif /* GDK_PIXBUF_CORE_H */
481