1/* cairo - a vector graphics library with display and print output
2 *
3 * Copyright © 2002 University of Southern California
4 * Copyright © 2005 Red Hat, Inc.
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it either under the terms of the GNU Lesser General Public
8 * License version 2.1 as published by the Free Software Foundation
9 * (the "LGPL") or, at your option, under the terms of the Mozilla
10 * Public License Version 1.1 (the "MPL"). If you do not alter this
11 * notice, a recipient may use your version of this file under either
12 * the MPL or the LGPL.
13 *
14 * You should have received a copy of the LGPL along with this library
15 * in the file COPYING-LGPL-2.1; if not, write to the Free Software
16 * Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA
17 * You should have received a copy of the MPL along with this library
18 * in the file COPYING-MPL-1.1
19 *
20 * The contents of this file are subject to the Mozilla Public License
21 * Version 1.1 (the "License"); you may not use this file except in
22 * compliance with the License. You may obtain a copy of the License at
23 * http://www.mozilla.org/MPL/
24 *
25 * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
26 * OF ANY KIND, either express or implied. See the LGPL or the MPL for
27 * the specific language governing rights and limitations.
28 *
29 * The Original Code is the cairo graphics library.
30 *
31 * The Initial Developer of the Original Code is University of Southern
32 * California.
33 *
34 * Contributor(s):
35 * Carl D. Worth <cworth@cworth.org>
36 */
37
38#ifndef CAIRO_H
39#define CAIRO_H
40
41#include "cairo-version.h"
42#include "cairo-features.h"
43#include "cairo-deprecated.h"
44
45#ifdef __cplusplus
46# define CAIRO_BEGIN_DECLS extern "C" {
47# define CAIRO_END_DECLS }
48#else
49# define CAIRO_BEGIN_DECLS
50# define CAIRO_END_DECLS
51#endif
52
53#ifndef cairo_public
54# if defined (_MSC_VER) && ! defined (CAIRO_WIN32_STATIC_BUILD)
55# define cairo_public __declspec(dllimport)
56# else
57# define cairo_public
58# endif
59#endif
60
61CAIRO_BEGIN_DECLS
62
63#define CAIRO_VERSION_ENCODE(major, minor, micro) ( \
64 ((major) * 10000) \
65 + ((minor) * 100) \
66 + ((micro) * 1))
67
68#define CAIRO_VERSION CAIRO_VERSION_ENCODE( \
69 CAIRO_VERSION_MAJOR, \
70 CAIRO_VERSION_MINOR, \
71 CAIRO_VERSION_MICRO)
72
73
74#define CAIRO_VERSION_STRINGIZE_(major, minor, micro) \
75 #major"."#minor"."#micro
76#define CAIRO_VERSION_STRINGIZE(major, minor, micro) \
77 CAIRO_VERSION_STRINGIZE_(major, minor, micro)
78
79#define CAIRO_VERSION_STRING CAIRO_VERSION_STRINGIZE( \
80 CAIRO_VERSION_MAJOR, \
81 CAIRO_VERSION_MINOR, \
82 CAIRO_VERSION_MICRO)
83
84
85cairo_public int
86cairo_version (void);
87
88cairo_public const char*
89cairo_version_string (void);
90
91/**
92 * cairo_bool_t:
93 *
94 * #cairo_bool_t is used for boolean values. Returns of type
95 * #cairo_bool_t will always be either 0 or 1, but testing against
96 * these values explicitly is not encouraged; just use the
97 * value as a boolean condition.
98 *
99 * <informalexample><programlisting>
100 * if (cairo_in_stroke (cr, x, y)) {
101 * /<!-- -->* do something *<!-- -->/
102 * }
103 * </programlisting></informalexample>
104 *
105 * Since: 1.0
106 **/
107typedef int cairo_bool_t;
108
109/**
110 * cairo_t:
111 *
112 * A #cairo_t contains the current state of the rendering device,
113 * including coordinates of yet to be drawn shapes.
114 *
115 * Cairo contexts, as #cairo_t objects are named, are central to
116 * cairo and all drawing with cairo is always done to a #cairo_t
117 * object.
118 *
119 * Memory management of #cairo_t is done with
120 * cairo_reference() and cairo_destroy().
121 *
122 * Since: 1.0
123 **/
124typedef struct _cairo cairo_t;
125
126/**
127 * cairo_surface_t:
128 *
129 * A #cairo_surface_t represents an image, either as the destination
130 * of a drawing operation or as source when drawing onto another
131 * surface. To draw to a #cairo_surface_t, create a cairo context
132 * with the surface as the target, using cairo_create().
133 *
134 * There are different subtypes of #cairo_surface_t for
135 * different drawing backends; for example, cairo_image_surface_create()
136 * creates a bitmap image in memory.
137 * The type of a surface can be queried with cairo_surface_get_type().
138 *
139 * The initial contents of a surface after creation depend upon the manner
140 * of its creation. If cairo creates the surface and backing storage for
141 * the user, it will be initially cleared; for example,
142 * cairo_image_surface_create() and cairo_surface_create_similar().
143 * Alternatively, if the user passes in a reference to some backing storage
144 * and asks cairo to wrap that in a #cairo_surface_t, then the contents are
145 * not modified; for example, cairo_image_surface_create_for_data() and
146 * cairo_xlib_surface_create().
147 *
148 * Memory management of #cairo_surface_t is done with
149 * cairo_surface_reference() and cairo_surface_destroy().
150 *
151 * Since: 1.0
152 **/
153typedef struct _cairo_surface cairo_surface_t;
154
155/**
156 * cairo_device_t:
157 *
158 * A #cairo_device_t represents the driver interface for drawing
159 * operations to a #cairo_surface_t. There are different subtypes of
160 * #cairo_device_t for different drawing backends; for example,
161 * cairo_egl_device_create() creates a device that wraps an EGL display and
162 * context.
163 *
164 * The type of a device can be queried with cairo_device_get_type().
165 *
166 * Memory management of #cairo_device_t is done with
167 * cairo_device_reference() and cairo_device_destroy().
168 *
169 * Since: 1.10
170 **/
171typedef struct _cairo_device cairo_device_t;
172
173/**
174 * cairo_matrix_t:
175 * @xx: xx component of the affine transformation
176 * @yx: yx component of the affine transformation
177 * @xy: xy component of the affine transformation
178 * @yy: yy component of the affine transformation
179 * @x0: X translation component of the affine transformation
180 * @y0: Y translation component of the affine transformation
181 *
182 * A #cairo_matrix_t holds an affine transformation, such as a scale,
183 * rotation, shear, or a combination of those. The transformation of
184 * a point (x, y) is given by:
185 * <programlisting>
186 * x_new = xx * x + xy * y + x0;
187 * y_new = yx * x + yy * y + y0;
188 * </programlisting>
189 *
190 * Since: 1.0
191 **/
192typedef struct _cairo_matrix {
193 double xx; double yx;
194 double xy; double yy;
195 double x0; double y0;
196} cairo_matrix_t;
197
198/**
199 * cairo_pattern_t:
200 *
201 * A #cairo_pattern_t represents a source when drawing onto a
202 * surface. There are different subtypes of #cairo_pattern_t,
203 * for different types of sources; for example,
204 * cairo_pattern_create_rgb() creates a pattern for a solid
205 * opaque color.
206 *
207 * Other than various
208 * <function>cairo_pattern_create_<emphasis>type</emphasis>()</function>
209 * functions, some of the pattern types can be implicitly created using various
210 * <function>cairo_set_source_<emphasis>type</emphasis>()</function> functions;
211 * for example cairo_set_source_rgb().
212 *
213 * The type of a pattern can be queried with cairo_pattern_get_type().
214 *
215 * Memory management of #cairo_pattern_t is done with
216 * cairo_pattern_reference() and cairo_pattern_destroy().
217 *
218 * Since: 1.0
219 **/
220typedef struct _cairo_pattern cairo_pattern_t;
221
222/**
223 * cairo_destroy_func_t:
224 * @data: The data element being destroyed.
225 *
226 * #cairo_destroy_func_t the type of function which is called when a
227 * data element is destroyed. It is passed the pointer to the data
228 * element and should free any memory and resources allocated for it.
229 *
230 * Since: 1.0
231 **/
232typedef void (*cairo_destroy_func_t) (void *data);
233
234/**
235 * cairo_user_data_key_t:
236 * @unused: not used; ignore.
237 *
238 * #cairo_user_data_key_t is used for attaching user data to cairo
239 * data structures. The actual contents of the struct is never used,
240 * and there is no need to initialize the object; only the unique
241 * address of a #cairo_data_key_t object is used. Typically, you
242 * would just use the address of a static #cairo_data_key_t object.
243 *
244 * Since: 1.0
245 **/
246typedef struct _cairo_user_data_key {
247 int unused;
248} cairo_user_data_key_t;
249
250/**
251 * cairo_status_t:
252 * @CAIRO_STATUS_SUCCESS: no error has occurred (Since 1.0)
253 * @CAIRO_STATUS_NO_MEMORY: out of memory (Since 1.0)
254 * @CAIRO_STATUS_INVALID_RESTORE: cairo_restore() called without matching cairo_save() (Since 1.0)
255 * @CAIRO_STATUS_INVALID_POP_GROUP: no saved group to pop, i.e. cairo_pop_group() without matching cairo_push_group() (Since 1.0)
256 * @CAIRO_STATUS_NO_CURRENT_POINT: no current point defined (Since 1.0)
257 * @CAIRO_STATUS_INVALID_MATRIX: invalid matrix (not invertible) (Since 1.0)
258 * @CAIRO_STATUS_INVALID_STATUS: invalid value for an input #cairo_status_t (Since 1.0)
259 * @CAIRO_STATUS_NULL_POINTER: %NULL pointer (Since 1.0)
260 * @CAIRO_STATUS_INVALID_STRING: input string not valid UTF-8 (Since 1.0)
261 * @CAIRO_STATUS_INVALID_PATH_DATA: input path data not valid (Since 1.0)
262 * @CAIRO_STATUS_READ_ERROR: error while reading from input stream (Since 1.0)
263 * @CAIRO_STATUS_WRITE_ERROR: error while writing to output stream (Since 1.0)
264 * @CAIRO_STATUS_SURFACE_FINISHED: target surface has been finished (Since 1.0)
265 * @CAIRO_STATUS_SURFACE_TYPE_MISMATCH: the surface type is not appropriate for the operation (Since 1.0)
266 * @CAIRO_STATUS_PATTERN_TYPE_MISMATCH: the pattern type is not appropriate for the operation (Since 1.0)
267 * @CAIRO_STATUS_INVALID_CONTENT: invalid value for an input #cairo_content_t (Since 1.0)
268 * @CAIRO_STATUS_INVALID_FORMAT: invalid value for an input #cairo_format_t (Since 1.0)
269 * @CAIRO_STATUS_INVALID_VISUAL: invalid value for an input Visual* (Since 1.0)
270 * @CAIRO_STATUS_FILE_NOT_FOUND: file not found (Since 1.0)
271 * @CAIRO_STATUS_INVALID_DASH: invalid value for a dash setting (Since 1.0)
272 * @CAIRO_STATUS_INVALID_DSC_COMMENT: invalid value for a DSC comment (Since 1.2)
273 * @CAIRO_STATUS_INVALID_INDEX: invalid index passed to getter (Since 1.4)
274 * @CAIRO_STATUS_CLIP_NOT_REPRESENTABLE: clip region not representable in desired format (Since 1.4)
275 * @CAIRO_STATUS_TEMP_FILE_ERROR: error creating or writing to a temporary file (Since 1.6)
276 * @CAIRO_STATUS_INVALID_STRIDE: invalid value for stride (Since 1.6)
277 * @CAIRO_STATUS_FONT_TYPE_MISMATCH: the font type is not appropriate for the operation (Since 1.8)
278 * @CAIRO_STATUS_USER_FONT_IMMUTABLE: the user-font is immutable (Since 1.8)
279 * @CAIRO_STATUS_USER_FONT_ERROR: error occurred in a user-font callback function (Since 1.8)
280 * @CAIRO_STATUS_NEGATIVE_COUNT: negative number used where it is not allowed (Since 1.8)
281 * @CAIRO_STATUS_INVALID_CLUSTERS: input clusters do not represent the accompanying text and glyph array (Since 1.8)
282 * @CAIRO_STATUS_INVALID_SLANT: invalid value for an input #cairo_font_slant_t (Since 1.8)
283 * @CAIRO_STATUS_INVALID_WEIGHT: invalid value for an input #cairo_font_weight_t (Since 1.8)
284 * @CAIRO_STATUS_INVALID_SIZE: invalid value (typically too big) for the size of the input (surface, pattern, etc.) (Since 1.10)
285 * @CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED: user-font method not implemented (Since 1.10)
286 * @CAIRO_STATUS_DEVICE_TYPE_MISMATCH: the device type is not appropriate for the operation (Since 1.10)
287 * @CAIRO_STATUS_DEVICE_ERROR: an operation to the device caused an unspecified error (Since 1.10)
288 * @CAIRO_STATUS_INVALID_MESH_CONSTRUCTION: a mesh pattern
289 * construction operation was used outside of a
290 * cairo_mesh_pattern_begin_patch()/cairo_mesh_pattern_end_patch()
291 * pair (Since 1.12)
292 * @CAIRO_STATUS_DEVICE_FINISHED: target device has been finished (Since 1.12)
293 * @CAIRO_STATUS_JBIG2_GLOBAL_MISSING: %CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID has been used on at least one image
294 * but no image provided %CAIRO_MIME_TYPE_JBIG2_GLOBAL (Since 1.14)
295 * @CAIRO_STATUS_LAST_STATUS: this is a special value indicating the number of
296 * status values defined in this enumeration. When using this value, note
297 * that the version of cairo at run-time may have additional status values
298 * defined than the value of this symbol at compile-time. (Since 1.10)
299 *
300 * #cairo_status_t is used to indicate errors that can occur when
301 * using Cairo. In some cases it is returned directly by functions.
302 * but when using #cairo_t, the last error, if any, is stored in
303 * the context and can be retrieved with cairo_status().
304 *
305 * New entries may be added in future versions. Use cairo_status_to_string()
306 * to get a human-readable representation of an error message.
307 *
308 * Since: 1.0
309 **/
310typedef enum _cairo_status {
311 CAIRO_STATUS_SUCCESS = 0,
312
313 CAIRO_STATUS_NO_MEMORY,
314 CAIRO_STATUS_INVALID_RESTORE,
315 CAIRO_STATUS_INVALID_POP_GROUP,
316 CAIRO_STATUS_NO_CURRENT_POINT,
317 CAIRO_STATUS_INVALID_MATRIX,
318 CAIRO_STATUS_INVALID_STATUS,
319 CAIRO_STATUS_NULL_POINTER,
320 CAIRO_STATUS_INVALID_STRING,
321 CAIRO_STATUS_INVALID_PATH_DATA,
322 CAIRO_STATUS_READ_ERROR,
323 CAIRO_STATUS_WRITE_ERROR,
324 CAIRO_STATUS_SURFACE_FINISHED,
325 CAIRO_STATUS_SURFACE_TYPE_MISMATCH,
326 CAIRO_STATUS_PATTERN_TYPE_MISMATCH,
327 CAIRO_STATUS_INVALID_CONTENT,
328 CAIRO_STATUS_INVALID_FORMAT,
329 CAIRO_STATUS_INVALID_VISUAL,
330 CAIRO_STATUS_FILE_NOT_FOUND,
331 CAIRO_STATUS_INVALID_DASH,
332 CAIRO_STATUS_INVALID_DSC_COMMENT,
333 CAIRO_STATUS_INVALID_INDEX,
334 CAIRO_STATUS_CLIP_NOT_REPRESENTABLE,
335 CAIRO_STATUS_TEMP_FILE_ERROR,
336 CAIRO_STATUS_INVALID_STRIDE,
337 CAIRO_STATUS_FONT_TYPE_MISMATCH,
338 CAIRO_STATUS_USER_FONT_IMMUTABLE,
339 CAIRO_STATUS_USER_FONT_ERROR,
340 CAIRO_STATUS_NEGATIVE_COUNT,
341 CAIRO_STATUS_INVALID_CLUSTERS,
342 CAIRO_STATUS_INVALID_SLANT,
343 CAIRO_STATUS_INVALID_WEIGHT,
344 CAIRO_STATUS_INVALID_SIZE,
345 CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED,
346 CAIRO_STATUS_DEVICE_TYPE_MISMATCH,
347 CAIRO_STATUS_DEVICE_ERROR,
348 CAIRO_STATUS_INVALID_MESH_CONSTRUCTION,
349 CAIRO_STATUS_DEVICE_FINISHED,
350 CAIRO_STATUS_JBIG2_GLOBAL_MISSING,
351
352 CAIRO_STATUS_LAST_STATUS
353} cairo_status_t;
354
355/**
356 * cairo_content_t:
357 * @CAIRO_CONTENT_COLOR: The surface will hold color content only. (Since 1.0)
358 * @CAIRO_CONTENT_ALPHA: The surface will hold alpha content only. (Since 1.0)
359 * @CAIRO_CONTENT_COLOR_ALPHA: The surface will hold color and alpha content. (Since 1.0)
360 *
361 * #cairo_content_t is used to describe the content that a surface will
362 * contain, whether color information, alpha information (translucence
363 * vs. opacity), or both.
364 *
365 * Note: The large values here are designed to keep #cairo_content_t
366 * values distinct from #cairo_format_t values so that the
367 * implementation can detect the error if users confuse the two types.
368 *
369 * Since: 1.0
370 **/
371typedef enum _cairo_content {
372 CAIRO_CONTENT_COLOR = 0x1000,
373 CAIRO_CONTENT_ALPHA = 0x2000,
374 CAIRO_CONTENT_COLOR_ALPHA = 0x3000
375} cairo_content_t;
376
377/**
378 * cairo_format_t:
379 * @CAIRO_FORMAT_INVALID: no such format exists or is supported.
380 * @CAIRO_FORMAT_ARGB32: each pixel is a 32-bit quantity, with
381 * alpha in the upper 8 bits, then red, then green, then blue.
382 * The 32-bit quantities are stored native-endian. Pre-multiplied
383 * alpha is used. (That is, 50% transparent red is 0x80800000,
384 * not 0x80ff0000.) (Since 1.0)
385 * @CAIRO_FORMAT_RGB24: each pixel is a 32-bit quantity, with
386 * the upper 8 bits unused. Red, Green, and Blue are stored
387 * in the remaining 24 bits in that order. (Since 1.0)
388 * @CAIRO_FORMAT_A8: each pixel is a 8-bit quantity holding
389 * an alpha value. (Since 1.0)
390 * @CAIRO_FORMAT_A1: each pixel is a 1-bit quantity holding
391 * an alpha value. Pixels are packed together into 32-bit
392 * quantities. The ordering of the bits matches the
393 * endianess of the platform. On a big-endian machine, the
394 * first pixel is in the uppermost bit, on a little-endian
395 * machine the first pixel is in the least-significant bit. (Since 1.0)
396 * @CAIRO_FORMAT_RGB16_565: each pixel is a 16-bit quantity
397 * with red in the upper 5 bits, then green in the middle
398 * 6 bits, and blue in the lower 5 bits. (Since 1.2)
399 * @CAIRO_FORMAT_RGB30: like RGB24 but with 10bpc. (Since 1.12)
400 *
401 * #cairo_format_t is used to identify the memory format of
402 * image data.
403 *
404 * New entries may be added in future versions.
405 *
406 * Since: 1.0
407 **/
408typedef enum _cairo_format {
409 CAIRO_FORMAT_INVALID = -1,
410 CAIRO_FORMAT_ARGB32 = 0,
411 CAIRO_FORMAT_RGB24 = 1,
412 CAIRO_FORMAT_A8 = 2,
413 CAIRO_FORMAT_A1 = 3,
414 CAIRO_FORMAT_RGB16_565 = 4,
415 CAIRO_FORMAT_RGB30 = 5
416} cairo_format_t;
417
418
419/**
420 * cairo_write_func_t:
421 * @closure: the output closure
422 * @data: the buffer containing the data to write
423 * @length: the amount of data to write
424 *
425 * #cairo_write_func_t is the type of function which is called when a
426 * backend needs to write data to an output stream. It is passed the
427 * closure which was specified by the user at the time the write
428 * function was registered, the data to write and the length of the
429 * data in bytes. The write function should return
430 * %CAIRO_STATUS_SUCCESS if all the data was successfully written,
431 * %CAIRO_STATUS_WRITE_ERROR otherwise.
432 *
433 * Returns: the status code of the write operation
434 *
435 * Since: 1.0
436 **/
437typedef cairo_status_t (*cairo_write_func_t) (void *closure,
438 const unsigned char *data,
439 unsigned int length);
440
441/**
442 * cairo_read_func_t:
443 * @closure: the input closure
444 * @data: the buffer into which to read the data
445 * @length: the amount of data to read
446 *
447 * #cairo_read_func_t is the type of function which is called when a
448 * backend needs to read data from an input stream. It is passed the
449 * closure which was specified by the user at the time the read
450 * function was registered, the buffer to read the data into and the
451 * length of the data in bytes. The read function should return
452 * %CAIRO_STATUS_SUCCESS if all the data was successfully read,
453 * %CAIRO_STATUS_READ_ERROR otherwise.
454 *
455 * Returns: the status code of the read operation
456 *
457 * Since: 1.0
458 **/
459typedef cairo_status_t (*cairo_read_func_t) (void *closure,
460 unsigned char *data,
461 unsigned int length);
462
463/**
464 * cairo_rectangle_int_t:
465 * @x: X coordinate of the left side of the rectangle
466 * @y: Y coordinate of the the top side of the rectangle
467 * @width: width of the rectangle
468 * @height: height of the rectangle
469 *
470 * A data structure for holding a rectangle with integer coordinates.
471 *
472 * Since: 1.10
473 **/
474
475typedef struct _cairo_rectangle_int {
476 int x, y;
477 int width, height;
478} cairo_rectangle_int_t;
479
480
481/* Functions for manipulating state objects */
482cairo_public cairo_t *
483cairo_create (cairo_surface_t *target);
484
485cairo_public cairo_t *
486cairo_reference (cairo_t *cr);
487
488cairo_public void
489cairo_destroy (cairo_t *cr);
490
491cairo_public unsigned int
492cairo_get_reference_count (cairo_t *cr);
493
494cairo_public void *
495cairo_get_user_data (cairo_t *cr,
496 const cairo_user_data_key_t *key);
497
498cairo_public cairo_status_t
499cairo_set_user_data (cairo_t *cr,
500 const cairo_user_data_key_t *key,
501 void *user_data,
502 cairo_destroy_func_t destroy);
503
504cairo_public void
505cairo_save (cairo_t *cr);
506
507cairo_public void
508cairo_restore (cairo_t *cr);
509
510cairo_public void
511cairo_push_group (cairo_t *cr);
512
513cairo_public void
514cairo_push_group_with_content (cairo_t *cr, cairo_content_t content);
515
516cairo_public cairo_pattern_t *
517cairo_pop_group (cairo_t *cr);
518
519cairo_public void
520cairo_pop_group_to_source (cairo_t *cr);
521
522/* Modify state */
523
524/**
525 * cairo_operator_t:
526 * @CAIRO_OPERATOR_CLEAR: clear destination layer (bounded) (Since 1.0)
527 * @CAIRO_OPERATOR_SOURCE: replace destination layer (bounded) (Since 1.0)
528 * @CAIRO_OPERATOR_OVER: draw source layer on top of destination layer
529 * (bounded) (Since 1.0)
530 * @CAIRO_OPERATOR_IN: draw source where there was destination content
531 * (unbounded) (Since 1.0)
532 * @CAIRO_OPERATOR_OUT: draw source where there was no destination
533 * content (unbounded) (Since 1.0)
534 * @CAIRO_OPERATOR_ATOP: draw source on top of destination content and
535 * only there (Since 1.0)
536 * @CAIRO_OPERATOR_DEST: ignore the source (Since 1.0)
537 * @CAIRO_OPERATOR_DEST_OVER: draw destination on top of source (Since 1.0)
538 * @CAIRO_OPERATOR_DEST_IN: leave destination only where there was
539 * source content (unbounded) (Since 1.0)
540 * @CAIRO_OPERATOR_DEST_OUT: leave destination only where there was no
541 * source content (Since 1.0)
542 * @CAIRO_OPERATOR_DEST_ATOP: leave destination on top of source content
543 * and only there (unbounded) (Since 1.0)
544 * @CAIRO_OPERATOR_XOR: source and destination are shown where there is only
545 * one of them (Since 1.0)
546 * @CAIRO_OPERATOR_ADD: source and destination layers are accumulated (Since 1.0)
547 * @CAIRO_OPERATOR_SATURATE: like over, but assuming source and dest are
548 * disjoint geometries (Since 1.0)
549 * @CAIRO_OPERATOR_MULTIPLY: source and destination layers are multiplied.
550 * This causes the result to be at least as dark as the darker inputs. (Since 1.10)
551 * @CAIRO_OPERATOR_SCREEN: source and destination are complemented and
552 * multiplied. This causes the result to be at least as light as the lighter
553 * inputs. (Since 1.10)
554 * @CAIRO_OPERATOR_OVERLAY: multiplies or screens, depending on the
555 * lightness of the destination color. (Since 1.10)
556 * @CAIRO_OPERATOR_DARKEN: replaces the destination with the source if it
557 * is darker, otherwise keeps the source. (Since 1.10)
558 * @CAIRO_OPERATOR_LIGHTEN: replaces the destination with the source if it
559 * is lighter, otherwise keeps the source. (Since 1.10)
560 * @CAIRO_OPERATOR_COLOR_DODGE: brightens the destination color to reflect
561 * the source color. (Since 1.10)
562 * @CAIRO_OPERATOR_COLOR_BURN: darkens the destination color to reflect
563 * the source color. (Since 1.10)
564 * @CAIRO_OPERATOR_HARD_LIGHT: Multiplies or screens, dependent on source
565 * color. (Since 1.10)
566 * @CAIRO_OPERATOR_SOFT_LIGHT: Darkens or lightens, dependent on source
567 * color. (Since 1.10)
568 * @CAIRO_OPERATOR_DIFFERENCE: Takes the difference of the source and
569 * destination color. (Since 1.10)
570 * @CAIRO_OPERATOR_EXCLUSION: Produces an effect similar to difference, but
571 * with lower contrast. (Since 1.10)
572 * @CAIRO_OPERATOR_HSL_HUE: Creates a color with the hue of the source
573 * and the saturation and luminosity of the target. (Since 1.10)
574 * @CAIRO_OPERATOR_HSL_SATURATION: Creates a color with the saturation
575 * of the source and the hue and luminosity of the target. Painting with
576 * this mode onto a gray area produces no change. (Since 1.10)
577 * @CAIRO_OPERATOR_HSL_COLOR: Creates a color with the hue and saturation
578 * of the source and the luminosity of the target. This preserves the gray
579 * levels of the target and is useful for coloring monochrome images or
580 * tinting color images. (Since 1.10)
581 * @CAIRO_OPERATOR_HSL_LUMINOSITY: Creates a color with the luminosity of
582 * the source and the hue and saturation of the target. This produces an
583 * inverse effect to @CAIRO_OPERATOR_HSL_COLOR. (Since 1.10)
584 *
585 * #cairo_operator_t is used to set the compositing operator for all cairo
586 * drawing operations.
587 *
588 * The default operator is %CAIRO_OPERATOR_OVER.
589 *
590 * The operators marked as <firstterm>unbounded</firstterm> modify their
591 * destination even outside of the mask layer (that is, their effect is not
592 * bound by the mask layer). However, their effect can still be limited by
593 * way of clipping.
594 *
595 * To keep things simple, the operator descriptions here
596 * document the behavior for when both source and destination are either fully
597 * transparent or fully opaque. The actual implementation works for
598 * translucent layers too.
599 * For a more detailed explanation of the effects of each operator, including
600 * the mathematical definitions, see
601 * <ulink url="http://cairographics.org/operators/">http://cairographics.org/operators/</ulink>.
602 *
603 * Since: 1.0
604 **/
605typedef enum _cairo_operator {
606 CAIRO_OPERATOR_CLEAR,
607
608 CAIRO_OPERATOR_SOURCE,
609 CAIRO_OPERATOR_OVER,
610 CAIRO_OPERATOR_IN,
611 CAIRO_OPERATOR_OUT,
612 CAIRO_OPERATOR_ATOP,
613
614 CAIRO_OPERATOR_DEST,
615 CAIRO_OPERATOR_DEST_OVER,
616 CAIRO_OPERATOR_DEST_IN,
617 CAIRO_OPERATOR_DEST_OUT,
618 CAIRO_OPERATOR_DEST_ATOP,
619
620 CAIRO_OPERATOR_XOR,
621 CAIRO_OPERATOR_ADD,
622 CAIRO_OPERATOR_SATURATE,
623
624 CAIRO_OPERATOR_MULTIPLY,
625 CAIRO_OPERATOR_SCREEN,
626 CAIRO_OPERATOR_OVERLAY,
627 CAIRO_OPERATOR_DARKEN,
628 CAIRO_OPERATOR_LIGHTEN,
629 CAIRO_OPERATOR_COLOR_DODGE,
630 CAIRO_OPERATOR_COLOR_BURN,
631 CAIRO_OPERATOR_HARD_LIGHT,
632 CAIRO_OPERATOR_SOFT_LIGHT,
633 CAIRO_OPERATOR_DIFFERENCE,
634 CAIRO_OPERATOR_EXCLUSION,
635 CAIRO_OPERATOR_HSL_HUE,
636 CAIRO_OPERATOR_HSL_SATURATION,
637 CAIRO_OPERATOR_HSL_COLOR,
638 CAIRO_OPERATOR_HSL_LUMINOSITY
639} cairo_operator_t;
640
641cairo_public void
642cairo_set_operator (cairo_t *cr, cairo_operator_t op);
643
644cairo_public void
645cairo_set_source (cairo_t *cr, cairo_pattern_t *source);
646
647cairo_public void
648cairo_set_source_rgb (cairo_t *cr, double red, double green, double blue);
649
650cairo_public void
651cairo_set_source_rgba (cairo_t *cr,
652 double red, double green, double blue,
653 double alpha);
654
655cairo_public void
656cairo_set_source_surface (cairo_t *cr,
657 cairo_surface_t *surface,
658 double x,
659 double y);
660
661cairo_public void
662cairo_set_tolerance (cairo_t *cr, double tolerance);
663
664/**
665 * cairo_antialias_t:
666 * @CAIRO_ANTIALIAS_DEFAULT: Use the default antialiasing for
667 * the subsystem and target device, since 1.0
668 * @CAIRO_ANTIALIAS_NONE: Use a bilevel alpha mask, since 1.0
669 * @CAIRO_ANTIALIAS_GRAY: Perform single-color antialiasing (using
670 * shades of gray for black text on a white background, for example), since 1.0
671 * @CAIRO_ANTIALIAS_SUBPIXEL: Perform antialiasing by taking
672 * advantage of the order of subpixel elements on devices
673 * such as LCD panels, since 1.0
674 * @CAIRO_ANTIALIAS_FAST: Hint that the backend should perform some
675 * antialiasing but prefer speed over quality, since 1.12
676 * @CAIRO_ANTIALIAS_GOOD: The backend should balance quality against
677 * performance, since 1.12
678 * @CAIRO_ANTIALIAS_BEST: Hint that the backend should render at the highest
679 * quality, sacrificing speed if necessary, since 1.12
680 *
681 * Specifies the type of antialiasing to do when rendering text or shapes.
682 *
683 * As it is not necessarily clear from the above what advantages a particular
684 * antialias method provides, since 1.12, there is also a set of hints:
685 * @CAIRO_ANTIALIAS_FAST: Allow the backend to degrade raster quality for speed
686 * @CAIRO_ANTIALIAS_GOOD: A balance between speed and quality
687 * @CAIRO_ANTIALIAS_BEST: A high-fidelity, but potentially slow, raster mode
688 *
689 * These make no guarantee on how the backend will perform its rasterisation
690 * (if it even rasterises!), nor that they have any differing effect other
691 * than to enable some form of antialiasing. In the case of glyph rendering,
692 * @CAIRO_ANTIALIAS_FAST and @CAIRO_ANTIALIAS_GOOD will be mapped to
693 * @CAIRO_ANTIALIAS_GRAY, with @CAIRO_ANTALIAS_BEST being equivalent to
694 * @CAIRO_ANTIALIAS_SUBPIXEL.
695 *
696 * The interpretation of @CAIRO_ANTIALIAS_DEFAULT is left entirely up to
697 * the backend, typically this will be similar to @CAIRO_ANTIALIAS_GOOD.
698 *
699 * Since: 1.0
700 **/
701typedef enum _cairo_antialias {
702 CAIRO_ANTIALIAS_DEFAULT,
703
704 /* method */
705 CAIRO_ANTIALIAS_NONE,
706 CAIRO_ANTIALIAS_GRAY,
707 CAIRO_ANTIALIAS_SUBPIXEL,
708
709 /* hints */
710 CAIRO_ANTIALIAS_FAST,
711 CAIRO_ANTIALIAS_GOOD,
712 CAIRO_ANTIALIAS_BEST
713} cairo_antialias_t;
714
715cairo_public void
716cairo_set_antialias (cairo_t *cr, cairo_antialias_t antialias);
717
718/**
719 * cairo_fill_rule_t:
720 * @CAIRO_FILL_RULE_WINDING: If the path crosses the ray from
721 * left-to-right, counts +1. If the path crosses the ray
722 * from right to left, counts -1. (Left and right are determined
723 * from the perspective of looking along the ray from the starting
724 * point.) If the total count is non-zero, the point will be filled. (Since 1.0)
725 * @CAIRO_FILL_RULE_EVEN_ODD: Counts the total number of
726 * intersections, without regard to the orientation of the contour. If
727 * the total number of intersections is odd, the point will be
728 * filled. (Since 1.0)
729 *
730 * #cairo_fill_rule_t is used to select how paths are filled. For both
731 * fill rules, whether or not a point is included in the fill is
732 * determined by taking a ray from that point to infinity and looking
733 * at intersections with the path. The ray can be in any direction,
734 * as long as it doesn't pass through the end point of a segment
735 * or have a tricky intersection such as intersecting tangent to the path.
736 * (Note that filling is not actually implemented in this way. This
737 * is just a description of the rule that is applied.)
738 *
739 * The default fill rule is %CAIRO_FILL_RULE_WINDING.
740 *
741 * New entries may be added in future versions.
742 *
743 * Since: 1.0
744 **/
745typedef enum _cairo_fill_rule {
746 CAIRO_FILL_RULE_WINDING,
747 CAIRO_FILL_RULE_EVEN_ODD
748} cairo_fill_rule_t;
749
750cairo_public void
751cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule);
752
753cairo_public void
754cairo_set_line_width (cairo_t *cr, double width);
755
756/**
757 * cairo_line_cap_t:
758 * @CAIRO_LINE_CAP_BUTT: start(stop) the line exactly at the start(end) point (Since 1.0)
759 * @CAIRO_LINE_CAP_ROUND: use a round ending, the center of the circle is the end point (Since 1.0)
760 * @CAIRO_LINE_CAP_SQUARE: use squared ending, the center of the square is the end point (Since 1.0)
761 *
762 * Specifies how to render the endpoints of the path when stroking.
763 *
764 * The default line cap style is %CAIRO_LINE_CAP_BUTT.
765 *
766 * Since: 1.0
767 **/
768typedef enum _cairo_line_cap {
769 CAIRO_LINE_CAP_BUTT,
770 CAIRO_LINE_CAP_ROUND,
771 CAIRO_LINE_CAP_SQUARE
772} cairo_line_cap_t;
773
774cairo_public void
775cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap);
776
777/**
778 * cairo_line_join_t:
779 * @CAIRO_LINE_JOIN_MITER: use a sharp (angled) corner, see
780 * cairo_set_miter_limit() (Since 1.0)
781 * @CAIRO_LINE_JOIN_ROUND: use a rounded join, the center of the circle is the
782 * joint point (Since 1.0)
783 * @CAIRO_LINE_JOIN_BEVEL: use a cut-off join, the join is cut off at half
784 * the line width from the joint point (Since 1.0)
785 *
786 * Specifies how to render the junction of two lines when stroking.
787 *
788 * The default line join style is %CAIRO_LINE_JOIN_MITER.
789 *
790 * Since: 1.0
791 **/
792typedef enum _cairo_line_join {
793 CAIRO_LINE_JOIN_MITER,
794 CAIRO_LINE_JOIN_ROUND,
795 CAIRO_LINE_JOIN_BEVEL
796} cairo_line_join_t;
797
798cairo_public void
799cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join);
800
801cairo_public void
802cairo_set_dash (cairo_t *cr,
803 const double *dashes,
804 int num_dashes,
805 double offset);
806
807cairo_public void
808cairo_set_miter_limit (cairo_t *cr, double limit);
809
810cairo_public void
811cairo_translate (cairo_t *cr, double tx, double ty);
812
813cairo_public void
814cairo_scale (cairo_t *cr, double sx, double sy);
815
816cairo_public void
817cairo_rotate (cairo_t *cr, double angle);
818
819cairo_public void
820cairo_transform (cairo_t *cr,
821 const cairo_matrix_t *matrix);
822
823cairo_public void
824cairo_set_matrix (cairo_t *cr,
825 const cairo_matrix_t *matrix);
826
827cairo_public void
828cairo_identity_matrix (cairo_t *cr);
829
830cairo_public void
831cairo_user_to_device (cairo_t *cr, double *x, double *y);
832
833cairo_public void
834cairo_user_to_device_distance (cairo_t *cr, double *dx, double *dy);
835
836cairo_public void
837cairo_device_to_user (cairo_t *cr, double *x, double *y);
838
839cairo_public void
840cairo_device_to_user_distance (cairo_t *cr, double *dx, double *dy);
841
842/* Path creation functions */
843cairo_public void
844cairo_new_path (cairo_t *cr);
845
846cairo_public void
847cairo_move_to (cairo_t *cr, double x, double y);
848
849cairo_public void
850cairo_new_sub_path (cairo_t *cr);
851
852cairo_public void
853cairo_line_to (cairo_t *cr, double x, double y);
854
855cairo_public void
856cairo_curve_to (cairo_t *cr,
857 double x1, double y1,
858 double x2, double y2,
859 double x3, double y3);
860
861cairo_public void
862cairo_arc (cairo_t *cr,
863 double xc, double yc,
864 double radius,
865 double angle1, double angle2);
866
867cairo_public void
868cairo_arc_negative (cairo_t *cr,
869 double xc, double yc,
870 double radius,
871 double angle1, double angle2);
872
873/* XXX: NYI
874cairo_public void
875cairo_arc_to (cairo_t *cr,
876 double x1, double y1,
877 double x2, double y2,
878 double radius);
879*/
880
881cairo_public void
882cairo_rel_move_to (cairo_t *cr, double dx, double dy);
883
884cairo_public void
885cairo_rel_line_to (cairo_t *cr, double dx, double dy);
886
887cairo_public void
888cairo_rel_curve_to (cairo_t *cr,
889 double dx1, double dy1,
890 double dx2, double dy2,
891 double dx3, double dy3);
892
893cairo_public void
894cairo_rectangle (cairo_t *cr,
895 double x, double y,
896 double width, double height);
897
898/* XXX: NYI
899cairo_public void
900cairo_stroke_to_path (cairo_t *cr);
901*/
902
903cairo_public void
904cairo_close_path (cairo_t *cr);
905
906cairo_public void
907cairo_path_extents (cairo_t *cr,
908 double *x1, double *y1,
909 double *x2, double *y2);
910
911/* Painting functions */
912cairo_public void
913cairo_paint (cairo_t *cr);
914
915cairo_public void
916cairo_paint_with_alpha (cairo_t *cr,
917 double alpha);
918
919cairo_public void
920cairo_mask (cairo_t *cr,
921 cairo_pattern_t *pattern);
922
923cairo_public void
924cairo_mask_surface (cairo_t *cr,
925 cairo_surface_t *surface,
926 double surface_x,
927 double surface_y);
928
929cairo_public void
930cairo_stroke (cairo_t *cr);
931
932cairo_public void
933cairo_stroke_preserve (cairo_t *cr);
934
935cairo_public void
936cairo_fill (cairo_t *cr);
937
938cairo_public void
939cairo_fill_preserve (cairo_t *cr);
940
941cairo_public void
942cairo_copy_page (cairo_t *cr);
943
944cairo_public void
945cairo_show_page (cairo_t *cr);
946
947/* Insideness testing */
948cairo_public cairo_bool_t
949cairo_in_stroke (cairo_t *cr, double x, double y);
950
951cairo_public cairo_bool_t
952cairo_in_fill (cairo_t *cr, double x, double y);
953
954cairo_public cairo_bool_t
955cairo_in_clip (cairo_t *cr, double x, double y);
956
957/* Rectangular extents */
958cairo_public void
959cairo_stroke_extents (cairo_t *cr,
960 double *x1, double *y1,
961 double *x2, double *y2);
962
963cairo_public void
964cairo_fill_extents (cairo_t *cr,
965 double *x1, double *y1,
966 double *x2, double *y2);
967
968/* Clipping */
969cairo_public void
970cairo_reset_clip (cairo_t *cr);
971
972cairo_public void
973cairo_clip (cairo_t *cr);
974
975cairo_public void
976cairo_clip_preserve (cairo_t *cr);
977
978cairo_public void
979cairo_clip_extents (cairo_t *cr,
980 double *x1, double *y1,
981 double *x2, double *y2);
982
983/**
984 * cairo_rectangle_t:
985 * @x: X coordinate of the left side of the rectangle
986 * @y: Y coordinate of the the top side of the rectangle
987 * @width: width of the rectangle
988 * @height: height of the rectangle
989 *
990 * A data structure for holding a rectangle.
991 *
992 * Since: 1.4
993 **/
994typedef struct _cairo_rectangle {
995 double x, y, width, height;
996} cairo_rectangle_t;
997
998/**
999 * cairo_rectangle_list_t:
1000 * @status: Error status of the rectangle list
1001 * @rectangles: Array containing the rectangles
1002 * @num_rectangles: Number of rectangles in this list
1003 *
1004 * A data structure for holding a dynamically allocated
1005 * array of rectangles.
1006 *
1007 * Since: 1.4
1008 **/
1009typedef struct _cairo_rectangle_list {
1010 cairo_status_t status;
1011 cairo_rectangle_t *rectangles;
1012 int num_rectangles;
1013} cairo_rectangle_list_t;
1014
1015cairo_public cairo_rectangle_list_t *
1016cairo_copy_clip_rectangle_list (cairo_t *cr);
1017
1018cairo_public void
1019cairo_rectangle_list_destroy (cairo_rectangle_list_t *rectangle_list);
1020
1021/* Font/Text functions */
1022
1023/**
1024 * cairo_scaled_font_t:
1025 *
1026 * A #cairo_scaled_font_t is a font scaled to a particular size and device
1027 * resolution. A #cairo_scaled_font_t is most useful for low-level font
1028 * usage where a library or application wants to cache a reference
1029 * to a scaled font to speed up the computation of metrics.
1030 *
1031 * There are various types of scaled fonts, depending on the
1032 * <firstterm>font backend</firstterm> they use. The type of a
1033 * scaled font can be queried using cairo_scaled_font_get_type().
1034 *
1035 * Memory management of #cairo_scaled_font_t is done with
1036 * cairo_scaled_font_reference() and cairo_scaled_font_destroy().
1037 *
1038 * Since: 1.0
1039 **/
1040typedef struct _cairo_scaled_font cairo_scaled_font_t;
1041
1042/**
1043 * cairo_font_face_t:
1044 *
1045 * A #cairo_font_face_t specifies all aspects of a font other
1046 * than the size or font matrix (a font matrix is used to distort
1047 * a font by sheering it or scaling it unequally in the two
1048 * directions) . A font face can be set on a #cairo_t by using
1049 * cairo_set_font_face(); the size and font matrix are set with
1050 * cairo_set_font_size() and cairo_set_font_matrix().
1051 *
1052 * There are various types of font faces, depending on the
1053 * <firstterm>font backend</firstterm> they use. The type of a
1054 * font face can be queried using cairo_font_face_get_type().
1055 *
1056 * Memory management of #cairo_font_face_t is done with
1057 * cairo_font_face_reference() and cairo_font_face_destroy().
1058 *
1059 * Since: 1.0
1060 **/
1061typedef struct _cairo_font_face cairo_font_face_t;
1062
1063/**
1064 * cairo_glyph_t:
1065 * @index: glyph index in the font. The exact interpretation of the
1066 * glyph index depends on the font technology being used.
1067 * @x: the offset in the X direction between the origin used for
1068 * drawing or measuring the string and the origin of this glyph.
1069 * @y: the offset in the Y direction between the origin used for
1070 * drawing or measuring the string and the origin of this glyph.
1071 *
1072 * The #cairo_glyph_t structure holds information about a single glyph
1073 * when drawing or measuring text. A font is (in simple terms) a
1074 * collection of shapes used to draw text. A glyph is one of these
1075 * shapes. There can be multiple glyphs for a single character
1076 * (alternates to be used in different contexts, for example), or a
1077 * glyph can be a <firstterm>ligature</firstterm> of multiple
1078 * characters. Cairo doesn't expose any way of converting input text
1079 * into glyphs, so in order to use the Cairo interfaces that take
1080 * arrays of glyphs, you must directly access the appropriate
1081 * underlying font system.
1082 *
1083 * Note that the offsets given by @x and @y are not cumulative. When
1084 * drawing or measuring text, each glyph is individually positioned
1085 * with respect to the overall origin
1086 *
1087 * Since: 1.0
1088 **/
1089typedef struct {
1090 unsigned long index;
1091 double x;
1092 double y;
1093} cairo_glyph_t;
1094
1095cairo_public cairo_glyph_t *
1096cairo_glyph_allocate (int num_glyphs);
1097
1098cairo_public void
1099cairo_glyph_free (cairo_glyph_t *glyphs);
1100
1101/**
1102 * cairo_text_cluster_t:
1103 * @num_bytes: the number of bytes of UTF-8 text covered by cluster
1104 * @num_glyphs: the number of glyphs covered by cluster
1105 *
1106 * The #cairo_text_cluster_t structure holds information about a single
1107 * <firstterm>text cluster</firstterm>. A text cluster is a minimal
1108 * mapping of some glyphs corresponding to some UTF-8 text.
1109 *
1110 * For a cluster to be valid, both @num_bytes and @num_glyphs should
1111 * be non-negative, and at least one should be non-zero.
1112 * Note that clusters with zero glyphs are not as well supported as
1113 * normal clusters. For example, PDF rendering applications typically
1114 * ignore those clusters when PDF text is being selected.
1115 *
1116 * See cairo_show_text_glyphs() for how clusters are used in advanced
1117 * text operations.
1118 *
1119 * Since: 1.8
1120 **/
1121typedef struct {
1122 int num_bytes;
1123 int num_glyphs;
1124} cairo_text_cluster_t;
1125
1126cairo_public cairo_text_cluster_t *
1127cairo_text_cluster_allocate (int num_clusters);
1128
1129cairo_public void
1130cairo_text_cluster_free (cairo_text_cluster_t *clusters);
1131
1132/**
1133 * cairo_text_cluster_flags_t:
1134 * @CAIRO_TEXT_CLUSTER_FLAG_BACKWARD: The clusters in the cluster array
1135 * map to glyphs in the glyph array from end to start. (Since 1.8)
1136 *
1137 * Specifies properties of a text cluster mapping.
1138 *
1139 * Since: 1.8
1140 **/
1141typedef enum _cairo_text_cluster_flags {
1142 CAIRO_TEXT_CLUSTER_FLAG_BACKWARD = 0x00000001
1143} cairo_text_cluster_flags_t;
1144
1145/**
1146 * cairo_text_extents_t:
1147 * @x_bearing: the horizontal distance from the origin to the
1148 * leftmost part of the glyphs as drawn. Positive if the
1149 * glyphs lie entirely to the right of the origin.
1150 * @y_bearing: the vertical distance from the origin to the
1151 * topmost part of the glyphs as drawn. Positive only if the
1152 * glyphs lie completely below the origin; will usually be
1153 * negative.
1154 * @width: width of the glyphs as drawn
1155 * @height: height of the glyphs as drawn
1156 * @x_advance:distance to advance in the X direction
1157 * after drawing these glyphs
1158 * @y_advance: distance to advance in the Y direction
1159 * after drawing these glyphs. Will typically be zero except
1160 * for vertical text layout as found in East-Asian languages.
1161 *
1162 * The #cairo_text_extents_t structure stores the extents of a single
1163 * glyph or a string of glyphs in user-space coordinates. Because text
1164 * extents are in user-space coordinates, they are mostly, but not
1165 * entirely, independent of the current transformation matrix. If you call
1166 * <literal>cairo_scale(cr, 2.0, 2.0)</literal>, text will
1167 * be drawn twice as big, but the reported text extents will not be
1168 * doubled. They will change slightly due to hinting (so you can't
1169 * assume that metrics are independent of the transformation matrix),
1170 * but otherwise will remain unchanged.
1171 *
1172 * Since: 1.0
1173 **/
1174typedef struct {
1175 double x_bearing;
1176 double y_bearing;
1177 double width;
1178 double height;
1179 double x_advance;
1180 double y_advance;
1181} cairo_text_extents_t;
1182
1183/**
1184 * cairo_font_extents_t:
1185 * @ascent: the distance that the font extends above the baseline.
1186 * Note that this is not always exactly equal to the maximum
1187 * of the extents of all the glyphs in the font, but rather
1188 * is picked to express the font designer's intent as to
1189 * how the font should align with elements above it.
1190 * @descent: the distance that the font extends below the baseline.
1191 * This value is positive for typical fonts that include
1192 * portions below the baseline. Note that this is not always
1193 * exactly equal to the maximum of the extents of all the
1194 * glyphs in the font, but rather is picked to express the
1195 * font designer's intent as to how the font should
1196 * align with elements below it.
1197 * @height: the recommended vertical distance between baselines when
1198 * setting consecutive lines of text with the font. This
1199 * is greater than @ascent+@descent by a
1200 * quantity known as the <firstterm>line spacing</firstterm>
1201 * or <firstterm>external leading</firstterm>. When space
1202 * is at a premium, most fonts can be set with only
1203 * a distance of @ascent+@descent between lines.
1204 * @max_x_advance: the maximum distance in the X direction that
1205 * the origin is advanced for any glyph in the font.
1206 * @max_y_advance: the maximum distance in the Y direction that
1207 * the origin is advanced for any glyph in the font.
1208 * This will be zero for normal fonts used for horizontal
1209 * writing. (The scripts of East Asia are sometimes written
1210 * vertically.)
1211 *
1212 * The #cairo_font_extents_t structure stores metric information for
1213 * a font. Values are given in the current user-space coordinate
1214 * system.
1215 *
1216 * Because font metrics are in user-space coordinates, they are
1217 * mostly, but not entirely, independent of the current transformation
1218 * matrix. If you call <literal>cairo_scale(cr, 2.0, 2.0)</literal>,
1219 * text will be drawn twice as big, but the reported text extents will
1220 * not be doubled. They will change slightly due to hinting (so you
1221 * can't assume that metrics are independent of the transformation
1222 * matrix), but otherwise will remain unchanged.
1223 *
1224 * Since: 1.0
1225 **/
1226typedef struct {
1227 double ascent;
1228 double descent;
1229 double height;
1230 double max_x_advance;
1231 double max_y_advance;
1232} cairo_font_extents_t;
1233
1234/**
1235 * cairo_font_slant_t:
1236 * @CAIRO_FONT_SLANT_NORMAL: Upright font style, since 1.0
1237 * @CAIRO_FONT_SLANT_ITALIC: Italic font style, since 1.0
1238 * @CAIRO_FONT_SLANT_OBLIQUE: Oblique font style, since 1.0
1239 *
1240 * Specifies variants of a font face based on their slant.
1241 *
1242 * Since: 1.0
1243 **/
1244typedef enum _cairo_font_slant {
1245 CAIRO_FONT_SLANT_NORMAL,
1246 CAIRO_FONT_SLANT_ITALIC,
1247 CAIRO_FONT_SLANT_OBLIQUE
1248} cairo_font_slant_t;
1249
1250/**
1251 * cairo_font_weight_t:
1252 * @CAIRO_FONT_WEIGHT_NORMAL: Normal font weight, since 1.0
1253 * @CAIRO_FONT_WEIGHT_BOLD: Bold font weight, since 1.0
1254 *
1255 * Specifies variants of a font face based on their weight.
1256 *
1257 * Since: 1.0
1258 **/
1259typedef enum _cairo_font_weight {
1260 CAIRO_FONT_WEIGHT_NORMAL,
1261 CAIRO_FONT_WEIGHT_BOLD
1262} cairo_font_weight_t;
1263
1264/**
1265 * cairo_subpixel_order_t:
1266 * @CAIRO_SUBPIXEL_ORDER_DEFAULT: Use the default subpixel order for
1267 * for the target device, since 1.0
1268 * @CAIRO_SUBPIXEL_ORDER_RGB: Subpixel elements are arranged horizontally
1269 * with red at the left, since 1.0
1270 * @CAIRO_SUBPIXEL_ORDER_BGR: Subpixel elements are arranged horizontally
1271 * with blue at the left, since 1.0
1272 * @CAIRO_SUBPIXEL_ORDER_VRGB: Subpixel elements are arranged vertically
1273 * with red at the top, since 1.0
1274 * @CAIRO_SUBPIXEL_ORDER_VBGR: Subpixel elements are arranged vertically
1275 * with blue at the top, since 1.0
1276 *
1277 * The subpixel order specifies the order of color elements within
1278 * each pixel on the display device when rendering with an
1279 * antialiasing mode of %CAIRO_ANTIALIAS_SUBPIXEL.
1280 *
1281 * Since: 1.0
1282 **/
1283typedef enum _cairo_subpixel_order {
1284 CAIRO_SUBPIXEL_ORDER_DEFAULT,
1285 CAIRO_SUBPIXEL_ORDER_RGB,
1286 CAIRO_SUBPIXEL_ORDER_BGR,
1287 CAIRO_SUBPIXEL_ORDER_VRGB,
1288 CAIRO_SUBPIXEL_ORDER_VBGR
1289} cairo_subpixel_order_t;
1290
1291/**
1292 * cairo_hint_style_t:
1293 * @CAIRO_HINT_STYLE_DEFAULT: Use the default hint style for
1294 * font backend and target device, since 1.0
1295 * @CAIRO_HINT_STYLE_NONE: Do not hint outlines, since 1.0
1296 * @CAIRO_HINT_STYLE_SLIGHT: Hint outlines slightly to improve
1297 * contrast while retaining good fidelity to the original
1298 * shapes, since 1.0
1299 * @CAIRO_HINT_STYLE_MEDIUM: Hint outlines with medium strength
1300 * giving a compromise between fidelity to the original shapes
1301 * and contrast, since 1.0
1302 * @CAIRO_HINT_STYLE_FULL: Hint outlines to maximize contrast, since 1.0
1303 *
1304 * Specifies the type of hinting to do on font outlines. Hinting
1305 * is the process of fitting outlines to the pixel grid in order
1306 * to improve the appearance of the result. Since hinting outlines
1307 * involves distorting them, it also reduces the faithfulness
1308 * to the original outline shapes. Not all of the outline hinting
1309 * styles are supported by all font backends.
1310 *
1311 * New entries may be added in future versions.
1312 *
1313 * Since: 1.0
1314 **/
1315typedef enum _cairo_hint_style {
1316 CAIRO_HINT_STYLE_DEFAULT,
1317 CAIRO_HINT_STYLE_NONE,
1318 CAIRO_HINT_STYLE_SLIGHT,
1319 CAIRO_HINT_STYLE_MEDIUM,
1320 CAIRO_HINT_STYLE_FULL
1321} cairo_hint_style_t;
1322
1323/**
1324 * cairo_hint_metrics_t:
1325 * @CAIRO_HINT_METRICS_DEFAULT: Hint metrics in the default
1326 * manner for the font backend and target device, since 1.0
1327 * @CAIRO_HINT_METRICS_OFF: Do not hint font metrics, since 1.0
1328 * @CAIRO_HINT_METRICS_ON: Hint font metrics, since 1.0
1329 *
1330 * Specifies whether to hint font metrics; hinting font metrics
1331 * means quantizing them so that they are integer values in
1332 * device space. Doing this improves the consistency of
1333 * letter and line spacing, however it also means that text
1334 * will be laid out differently at different zoom factors.
1335 *
1336 * Since: 1.0
1337 **/
1338typedef enum _cairo_hint_metrics {
1339 CAIRO_HINT_METRICS_DEFAULT,
1340 CAIRO_HINT_METRICS_OFF,
1341 CAIRO_HINT_METRICS_ON
1342} cairo_hint_metrics_t;
1343
1344/**
1345 * cairo_font_options_t:
1346 *
1347 * An opaque structure holding all options that are used when
1348 * rendering fonts.
1349 *
1350 * Individual features of a #cairo_font_options_t can be set or
1351 * accessed using functions named
1352 * <function>cairo_font_options_set_<emphasis>feature_name</emphasis>()</function> and
1353 * <function>cairo_font_options_get_<emphasis>feature_name</emphasis>()</function>, like
1354 * cairo_font_options_set_antialias() and
1355 * cairo_font_options_get_antialias().
1356 *
1357 * New features may be added to a #cairo_font_options_t in the
1358 * future. For this reason, cairo_font_options_copy(),
1359 * cairo_font_options_equal(), cairo_font_options_merge(), and
1360 * cairo_font_options_hash() should be used to copy, check
1361 * for equality, merge, or compute a hash value of
1362 * #cairo_font_options_t objects.
1363 *
1364 * Since: 1.0
1365 **/
1366typedef struct _cairo_font_options cairo_font_options_t;
1367
1368cairo_public cairo_font_options_t *
1369cairo_font_options_create (void);
1370
1371cairo_public cairo_font_options_t *
1372cairo_font_options_copy (const cairo_font_options_t *original);
1373
1374cairo_public void
1375cairo_font_options_destroy (cairo_font_options_t *options);
1376
1377cairo_public cairo_status_t
1378cairo_font_options_status (cairo_font_options_t *options);
1379
1380cairo_public void
1381cairo_font_options_merge (cairo_font_options_t *options,
1382 const cairo_font_options_t *other);
1383cairo_public cairo_bool_t
1384cairo_font_options_equal (const cairo_font_options_t *options,
1385 const cairo_font_options_t *other);
1386
1387cairo_public unsigned long
1388cairo_font_options_hash (const cairo_font_options_t *options);
1389
1390cairo_public void
1391cairo_font_options_set_antialias (cairo_font_options_t *options,
1392 cairo_antialias_t antialias);
1393cairo_public cairo_antialias_t
1394cairo_font_options_get_antialias (const cairo_font_options_t *options);
1395
1396cairo_public void
1397cairo_font_options_set_subpixel_order (cairo_font_options_t *options,
1398 cairo_subpixel_order_t subpixel_order);
1399cairo_public cairo_subpixel_order_t
1400cairo_font_options_get_subpixel_order (const cairo_font_options_t *options);
1401
1402cairo_public void
1403cairo_font_options_set_hint_style (cairo_font_options_t *options,
1404 cairo_hint_style_t hint_style);
1405cairo_public cairo_hint_style_t
1406cairo_font_options_get_hint_style (const cairo_font_options_t *options);
1407
1408cairo_public void
1409cairo_font_options_set_hint_metrics (cairo_font_options_t *options,
1410 cairo_hint_metrics_t hint_metrics);
1411cairo_public cairo_hint_metrics_t
1412cairo_font_options_get_hint_metrics (const cairo_font_options_t *options);
1413
1414/* This interface is for dealing with text as text, not caring about the
1415 font object inside the the cairo_t. */
1416
1417cairo_public void
1418cairo_select_font_face (cairo_t *cr,
1419 const char *family,
1420 cairo_font_slant_t slant,
1421 cairo_font_weight_t weight);
1422
1423cairo_public void
1424cairo_set_font_size (cairo_t *cr, double size);
1425
1426cairo_public void
1427cairo_set_font_matrix (cairo_t *cr,
1428 const cairo_matrix_t *matrix);
1429
1430cairo_public void
1431cairo_get_font_matrix (cairo_t *cr,
1432 cairo_matrix_t *matrix);
1433
1434cairo_public void
1435cairo_set_font_options (cairo_t *cr,
1436 const cairo_font_options_t *options);
1437
1438cairo_public void
1439cairo_get_font_options (cairo_t *cr,
1440 cairo_font_options_t *options);
1441
1442cairo_public void
1443cairo_set_font_face (cairo_t *cr, cairo_font_face_t *font_face);
1444
1445cairo_public cairo_font_face_t *
1446cairo_get_font_face (cairo_t *cr);
1447
1448cairo_public void
1449cairo_set_scaled_font (cairo_t *cr,
1450 const cairo_scaled_font_t *scaled_font);
1451
1452cairo_public cairo_scaled_font_t *
1453cairo_get_scaled_font (cairo_t *cr);
1454
1455cairo_public void
1456cairo_show_text (cairo_t *cr, const char *utf8);
1457
1458cairo_public void
1459cairo_show_glyphs (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs);
1460
1461cairo_public void
1462cairo_show_text_glyphs (cairo_t *cr,
1463 const char *utf8,
1464 int utf8_len,
1465 const cairo_glyph_t *glyphs,
1466 int num_glyphs,
1467 const cairo_text_cluster_t *clusters,
1468 int num_clusters,
1469 cairo_text_cluster_flags_t cluster_flags);
1470
1471cairo_public void
1472cairo_text_path (cairo_t *cr, const char *utf8);
1473
1474cairo_public void
1475cairo_glyph_path (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs);
1476
1477cairo_public void
1478cairo_text_extents (cairo_t *cr,
1479 const char *utf8,
1480 cairo_text_extents_t *extents);
1481
1482cairo_public void
1483cairo_glyph_extents (cairo_t *cr,
1484 const cairo_glyph_t *glyphs,
1485 int num_glyphs,
1486 cairo_text_extents_t *extents);
1487
1488cairo_public void
1489cairo_font_extents (cairo_t *cr,
1490 cairo_font_extents_t *extents);
1491
1492/* Generic identifier for a font style */
1493
1494cairo_public cairo_font_face_t *
1495cairo_font_face_reference (cairo_font_face_t *font_face);
1496
1497cairo_public void
1498cairo_font_face_destroy (cairo_font_face_t *font_face);
1499
1500cairo_public unsigned int
1501cairo_font_face_get_reference_count (cairo_font_face_t *font_face);
1502
1503cairo_public cairo_status_t
1504cairo_font_face_status (cairo_font_face_t *font_face);
1505
1506
1507/**
1508 * cairo_font_type_t:
1509 * @CAIRO_FONT_TYPE_TOY: The font was created using cairo's toy font api (Since: 1.2)
1510 * @CAIRO_FONT_TYPE_FT: The font is of type FreeType (Since: 1.2)
1511 * @CAIRO_FONT_TYPE_WIN32: The font is of type Win32 (Since: 1.2)
1512 * @CAIRO_FONT_TYPE_QUARTZ: The font is of type Quartz (Since: 1.6, in 1.2 and
1513 * 1.4 it was named CAIRO_FONT_TYPE_ATSUI)
1514 * @CAIRO_FONT_TYPE_USER: The font was create using cairo's user font api (Since: 1.8)
1515 *
1516 * #cairo_font_type_t is used to describe the type of a given font
1517 * face or scaled font. The font types are also known as "font
1518 * backends" within cairo.
1519 *
1520 * The type of a font face is determined by the function used to
1521 * create it, which will generally be of the form
1522 * <function>cairo_<emphasis>type</emphasis>_font_face_create(<!-- -->)</function>.
1523 * The font face type can be queried with cairo_font_face_get_type()
1524 *
1525 * The various #cairo_font_face_t functions can be used with a font face
1526 * of any type.
1527 *
1528 * The type of a scaled font is determined by the type of the font
1529 * face passed to cairo_scaled_font_create(). The scaled font type can
1530 * be queried with cairo_scaled_font_get_type()
1531 *
1532 * The various #cairo_scaled_font_t functions can be used with scaled
1533 * fonts of any type, but some font backends also provide
1534 * type-specific functions that must only be called with a scaled font
1535 * of the appropriate type. These functions have names that begin with
1536 * <function>cairo_<emphasis>type</emphasis>_scaled_font(<!-- -->)</function>
1537 * such as cairo_ft_scaled_font_lock_face().
1538 *
1539 * The behavior of calling a type-specific function with a scaled font
1540 * of the wrong type is undefined.
1541 *
1542 * New entries may be added in future versions.
1543 *
1544 * Since: 1.2
1545 **/
1546typedef enum _cairo_font_type {
1547 CAIRO_FONT_TYPE_TOY,
1548 CAIRO_FONT_TYPE_FT,
1549 CAIRO_FONT_TYPE_WIN32,
1550 CAIRO_FONT_TYPE_QUARTZ,
1551 CAIRO_FONT_TYPE_USER
1552} cairo_font_type_t;
1553
1554cairo_public cairo_font_type_t
1555cairo_font_face_get_type (cairo_font_face_t *font_face);
1556
1557cairo_public void *
1558cairo_font_face_get_user_data (cairo_font_face_t *font_face,
1559 const cairo_user_data_key_t *key);
1560
1561cairo_public cairo_status_t
1562cairo_font_face_set_user_data (cairo_font_face_t *font_face,
1563 const cairo_user_data_key_t *key,
1564 void *user_data,
1565 cairo_destroy_func_t destroy);
1566
1567/* Portable interface to general font features. */
1568
1569cairo_public cairo_scaled_font_t *
1570cairo_scaled_font_create (cairo_font_face_t *font_face,
1571 const cairo_matrix_t *font_matrix,
1572 const cairo_matrix_t *ctm,
1573 const cairo_font_options_t *options);
1574
1575cairo_public cairo_scaled_font_t *
1576cairo_scaled_font_reference (cairo_scaled_font_t *scaled_font);
1577
1578cairo_public void
1579cairo_scaled_font_destroy (cairo_scaled_font_t *scaled_font);
1580
1581cairo_public unsigned int
1582cairo_scaled_font_get_reference_count (cairo_scaled_font_t *scaled_font);
1583
1584cairo_public cairo_status_t
1585cairo_scaled_font_status (cairo_scaled_font_t *scaled_font);
1586
1587cairo_public cairo_font_type_t
1588cairo_scaled_font_get_type (cairo_scaled_font_t *scaled_font);
1589
1590cairo_public void *
1591cairo_scaled_font_get_user_data (cairo_scaled_font_t *scaled_font,
1592 const cairo_user_data_key_t *key);
1593
1594cairo_public cairo_status_t
1595cairo_scaled_font_set_user_data (cairo_scaled_font_t *scaled_font,
1596 const cairo_user_data_key_t *key,
1597 void *user_data,
1598 cairo_destroy_func_t destroy);
1599
1600cairo_public void
1601cairo_scaled_font_extents (cairo_scaled_font_t *scaled_font,
1602 cairo_font_extents_t *extents);
1603
1604cairo_public void
1605cairo_scaled_font_text_extents (cairo_scaled_font_t *scaled_font,
1606 const char *utf8,
1607 cairo_text_extents_t *extents);
1608
1609cairo_public void
1610cairo_scaled_font_glyph_extents (cairo_scaled_font_t *scaled_font,
1611 const cairo_glyph_t *glyphs,
1612 int num_glyphs,
1613 cairo_text_extents_t *extents);
1614
1615cairo_public cairo_status_t
1616cairo_scaled_font_text_to_glyphs (cairo_scaled_font_t *scaled_font,
1617 double x,
1618 double y,
1619 const char *utf8,
1620 int utf8_len,
1621 cairo_glyph_t **glyphs,
1622 int *num_glyphs,
1623 cairo_text_cluster_t **clusters,
1624 int *num_clusters,
1625 cairo_text_cluster_flags_t *cluster_flags);
1626
1627cairo_public cairo_font_face_t *
1628cairo_scaled_font_get_font_face (cairo_scaled_font_t *scaled_font);
1629
1630cairo_public void
1631cairo_scaled_font_get_font_matrix (cairo_scaled_font_t *scaled_font,
1632 cairo_matrix_t *font_matrix);
1633
1634cairo_public void
1635cairo_scaled_font_get_ctm (cairo_scaled_font_t *scaled_font,
1636 cairo_matrix_t *ctm);
1637
1638cairo_public void
1639cairo_scaled_font_get_scale_matrix (cairo_scaled_font_t *scaled_font,
1640 cairo_matrix_t *scale_matrix);
1641
1642cairo_public void
1643cairo_scaled_font_get_font_options (cairo_scaled_font_t *scaled_font,
1644 cairo_font_options_t *options);
1645
1646
1647/* Toy fonts */
1648
1649cairo_public cairo_font_face_t *
1650cairo_toy_font_face_create (const char *family,
1651 cairo_font_slant_t slant,
1652 cairo_font_weight_t weight);
1653
1654cairo_public const char *
1655cairo_toy_font_face_get_family (cairo_font_face_t *font_face);
1656
1657cairo_public cairo_font_slant_t
1658cairo_toy_font_face_get_slant (cairo_font_face_t *font_face);
1659
1660cairo_public cairo_font_weight_t
1661cairo_toy_font_face_get_weight (cairo_font_face_t *font_face);
1662
1663
1664/* User fonts */
1665
1666cairo_public cairo_font_face_t *
1667cairo_user_font_face_create (void);
1668
1669/* User-font method signatures */
1670
1671/**
1672 * cairo_user_scaled_font_init_func_t:
1673 * @scaled_font: the scaled-font being created
1674 * @cr: a cairo context, in font space
1675 * @extents: font extents to fill in, in font space
1676 *
1677 * #cairo_user_scaled_font_init_func_t is the type of function which is
1678 * called when a scaled-font needs to be created for a user font-face.
1679 *
1680 * The cairo context @cr is not used by the caller, but is prepared in font
1681 * space, similar to what the cairo contexts passed to the render_glyph
1682 * method will look like. The callback can use this context for extents
1683 * computation for example. After the callback is called, @cr is checked
1684 * for any error status.
1685 *
1686 * The @extents argument is where the user font sets the font extents for
1687 * @scaled_font. It is in font space, which means that for most cases its
1688 * ascent and descent members should add to 1.0. @extents is preset to
1689 * hold a value of 1.0 for ascent, height, and max_x_advance, and 0.0 for
1690 * descent and max_y_advance members.
1691 *
1692 * The callback is optional. If not set, default font extents as described
1693 * in the previous paragraph will be used.
1694 *
1695 * Note that @scaled_font is not fully initialized at this
1696 * point and trying to use it for text operations in the callback will result
1697 * in deadlock.
1698 *
1699 * Returns: %CAIRO_STATUS_SUCCESS upon success, or an error status on error.
1700 *
1701 * Since: 1.8
1702 **/
1703typedef cairo_status_t (*cairo_user_scaled_font_init_func_t) (cairo_scaled_font_t *scaled_font,
1704 cairo_t *cr,
1705 cairo_font_extents_t *extents);
1706
1707/**
1708 * cairo_user_scaled_font_render_glyph_func_t:
1709 * @scaled_font: user scaled-font
1710 * @glyph: glyph code to render
1711 * @cr: cairo context to draw to, in font space
1712 * @extents: glyph extents to fill in, in font space
1713 *
1714 * #cairo_user_scaled_font_render_glyph_func_t is the type of function which
1715 * is called when a user scaled-font needs to render a glyph.
1716 *
1717 * The callback is mandatory, and expected to draw the glyph with code @glyph to
1718 * the cairo context @cr. @cr is prepared such that the glyph drawing is done in
1719 * font space. That is, the matrix set on @cr is the scale matrix of @scaled_font,
1720 * The @extents argument is where the user font sets the font extents for
1721 * @scaled_font. However, if user prefers to draw in user space, they can
1722 * achieve that by changing the matrix on @cr. All cairo rendering operations
1723 * to @cr are permitted, however, the result is undefined if any source other
1724 * than the default source on @cr is used. That means, glyph bitmaps should
1725 * be rendered using cairo_mask() instead of cairo_paint().
1726 *
1727 * Other non-default settings on @cr include a font size of 1.0 (given that
1728 * it is set up to be in font space), and font options corresponding to
1729 * @scaled_font.
1730 *
1731 * The @extents argument is preset to have <literal>x_bearing</literal>,
1732 * <literal>width</literal>, and <literal>y_advance</literal> of zero,
1733 * <literal>y_bearing</literal> set to <literal>-font_extents.ascent</literal>,
1734 * <literal>height</literal> to <literal>font_extents.ascent+font_extents.descent</literal>,
1735 * and <literal>x_advance</literal> to <literal>font_extents.max_x_advance</literal>.
1736 * The only field user needs to set in majority of cases is
1737 * <literal>x_advance</literal>.
1738 * If the <literal>width</literal> field is zero upon the callback returning
1739 * (which is its preset value), the glyph extents are automatically computed
1740 * based on the drawings done to @cr. This is in most cases exactly what the
1741 * desired behavior is. However, if for any reason the callback sets the
1742 * extents, it must be ink extents, and include the extents of all drawing
1743 * done to @cr in the callback.
1744 *
1745 * Returns: %CAIRO_STATUS_SUCCESS upon success, or
1746 * %CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
1747 *
1748 * Since: 1.8
1749 **/
1750typedef cairo_status_t (*cairo_user_scaled_font_render_glyph_func_t) (cairo_scaled_font_t *scaled_font,
1751 unsigned long glyph,
1752 cairo_t *cr,
1753 cairo_text_extents_t *extents);
1754
1755/**
1756 * cairo_user_scaled_font_text_to_glyphs_func_t:
1757 * @scaled_font: the scaled-font being created
1758 * @utf8: a string of text encoded in UTF-8
1759 * @utf8_len: length of @utf8 in bytes
1760 * @glyphs: pointer to array of glyphs to fill, in font space
1761 * @num_glyphs: pointer to number of glyphs
1762 * @clusters: pointer to array of cluster mapping information to fill, or %NULL
1763 * @num_clusters: pointer to number of clusters
1764 * @cluster_flags: pointer to location to store cluster flags corresponding to the
1765 * output @clusters
1766 *
1767 * #cairo_user_scaled_font_text_to_glyphs_func_t is the type of function which
1768 * is called to convert input text to an array of glyphs. This is used by the
1769 * cairo_show_text() operation.
1770 *
1771 * Using this callback the user-font has full control on glyphs and their
1772 * positions. That means, it allows for features like ligatures and kerning,
1773 * as well as complex <firstterm>shaping</firstterm> required for scripts like
1774 * Arabic and Indic.
1775 *
1776 * The @num_glyphs argument is preset to the number of glyph entries available
1777 * in the @glyphs buffer. If the @glyphs buffer is %NULL, the value of
1778 * @num_glyphs will be zero. If the provided glyph array is too short for
1779 * the conversion (or for convenience), a new glyph array may be allocated
1780 * using cairo_glyph_allocate() and placed in @glyphs. Upon return,
1781 * @num_glyphs should contain the number of generated glyphs. If the value
1782 * @glyphs points at has changed after the call, the caller will free the
1783 * allocated glyph array using cairo_glyph_free(). The caller will also free
1784 * the original value of @glyphs, so the callback shouldn't do so.
1785 * The callback should populate the glyph indices and positions (in font space)
1786 * assuming that the text is to be shown at the origin.
1787 *
1788 * If @clusters is not %NULL, @num_clusters and @cluster_flags are also
1789 * non-%NULL, and cluster mapping should be computed. The semantics of how
1790 * cluster array allocation works is similar to the glyph array. That is,
1791 * if @clusters initially points to a non-%NULL value, that array may be used
1792 * as a cluster buffer, and @num_clusters points to the number of cluster
1793 * entries available there. If the provided cluster array is too short for
1794 * the conversion (or for convenience), a new cluster array may be allocated
1795 * using cairo_text_cluster_allocate() and placed in @clusters. In this case,
1796 * the original value of @clusters will still be freed by the caller. Upon
1797 * return, @num_clusters should contain the number of generated clusters.
1798 * If the value @clusters points at has changed after the call, the caller
1799 * will free the allocated cluster array using cairo_text_cluster_free().
1800 *
1801 * The callback is optional. If @num_glyphs is negative upon
1802 * the callback returning or if the return value
1803 * is %CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED, the unicode_to_glyph callback
1804 * is tried. See #cairo_user_scaled_font_unicode_to_glyph_func_t.
1805 *
1806 * Note: While cairo does not impose any limitation on glyph indices,
1807 * some applications may assume that a glyph index fits in a 16-bit
1808 * unsigned integer. As such, it is advised that user-fonts keep their
1809 * glyphs in the 0 to 65535 range. Furthermore, some applications may
1810 * assume that glyph 0 is a special glyph-not-found glyph. User-fonts
1811 * are advised to use glyph 0 for such purposes and do not use that
1812 * glyph value for other purposes.
1813 *
1814 * Returns: %CAIRO_STATUS_SUCCESS upon success,
1815 * %CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED if fallback options should be tried,
1816 * or %CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
1817 *
1818 * Since: 1.8
1819 **/
1820typedef cairo_status_t (*cairo_user_scaled_font_text_to_glyphs_func_t) (cairo_scaled_font_t *scaled_font,
1821 const char *utf8,
1822 int utf8_len,
1823 cairo_glyph_t **glyphs,
1824 int *num_glyphs,
1825 cairo_text_cluster_t **clusters,
1826 int *num_clusters,
1827 cairo_text_cluster_flags_t *cluster_flags);
1828
1829/**
1830 * cairo_user_scaled_font_unicode_to_glyph_func_t:
1831 * @scaled_font: the scaled-font being created
1832 * @unicode: input unicode character code-point
1833 * @glyph_index: output glyph index
1834 *
1835 * #cairo_user_scaled_font_unicode_to_glyph_func_t is the type of function which
1836 * is called to convert an input Unicode character to a single glyph.
1837 * This is used by the cairo_show_text() operation.
1838 *
1839 * This callback is used to provide the same functionality as the
1840 * text_to_glyphs callback does (see #cairo_user_scaled_font_text_to_glyphs_func_t)
1841 * but has much less control on the output,
1842 * in exchange for increased ease of use. The inherent assumption to using
1843 * this callback is that each character maps to one glyph, and that the
1844 * mapping is context independent. It also assumes that glyphs are positioned
1845 * according to their advance width. These mean no ligatures, kerning, or
1846 * complex scripts can be implemented using this callback.
1847 *
1848 * The callback is optional, and only used if text_to_glyphs callback is not
1849 * set or fails to return glyphs. If this callback is not set or if it returns
1850 * %CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED, an identity mapping from Unicode
1851 * code-points to glyph indices is assumed.
1852 *
1853 * Note: While cairo does not impose any limitation on glyph indices,
1854 * some applications may assume that a glyph index fits in a 16-bit
1855 * unsigned integer. As such, it is advised that user-fonts keep their
1856 * glyphs in the 0 to 65535 range. Furthermore, some applications may
1857 * assume that glyph 0 is a special glyph-not-found glyph. User-fonts
1858 * are advised to use glyph 0 for such purposes and do not use that
1859 * glyph value for other purposes.
1860 *
1861 * Returns: %CAIRO_STATUS_SUCCESS upon success,
1862 * %CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED if fallback options should be tried,
1863 * or %CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
1864 *
1865 * Since: 1.8
1866 **/
1867typedef cairo_status_t (*cairo_user_scaled_font_unicode_to_glyph_func_t) (cairo_scaled_font_t *scaled_font,
1868 unsigned long unicode,
1869 unsigned long *glyph_index);
1870
1871/* User-font method setters */
1872
1873cairo_public void
1874cairo_user_font_face_set_init_func (cairo_font_face_t *font_face,
1875 cairo_user_scaled_font_init_func_t init_func);
1876
1877cairo_public void
1878cairo_user_font_face_set_render_glyph_func (cairo_font_face_t *font_face,
1879 cairo_user_scaled_font_render_glyph_func_t render_glyph_func);
1880
1881cairo_public void
1882cairo_user_font_face_set_text_to_glyphs_func (cairo_font_face_t *font_face,
1883 cairo_user_scaled_font_text_to_glyphs_func_t text_to_glyphs_func);
1884
1885cairo_public void
1886cairo_user_font_face_set_unicode_to_glyph_func (cairo_font_face_t *font_face,
1887 cairo_user_scaled_font_unicode_to_glyph_func_t unicode_to_glyph_func);
1888
1889/* User-font method getters */
1890
1891cairo_public cairo_user_scaled_font_init_func_t
1892cairo_user_font_face_get_init_func (cairo_font_face_t *font_face);
1893
1894cairo_public cairo_user_scaled_font_render_glyph_func_t
1895cairo_user_font_face_get_render_glyph_func (cairo_font_face_t *font_face);
1896
1897cairo_public cairo_user_scaled_font_text_to_glyphs_func_t
1898cairo_user_font_face_get_text_to_glyphs_func (cairo_font_face_t *font_face);
1899
1900cairo_public cairo_user_scaled_font_unicode_to_glyph_func_t
1901cairo_user_font_face_get_unicode_to_glyph_func (cairo_font_face_t *font_face);
1902
1903
1904/* Query functions */
1905
1906cairo_public cairo_operator_t
1907cairo_get_operator (cairo_t *cr);
1908
1909cairo_public cairo_pattern_t *
1910cairo_get_source (cairo_t *cr);
1911
1912cairo_public double
1913cairo_get_tolerance (cairo_t *cr);
1914
1915cairo_public cairo_antialias_t
1916cairo_get_antialias (cairo_t *cr);
1917
1918cairo_public cairo_bool_t
1919cairo_has_current_point (cairo_t *cr);
1920
1921cairo_public void
1922cairo_get_current_point (cairo_t *cr, double *x, double *y);
1923
1924cairo_public cairo_fill_rule_t
1925cairo_get_fill_rule (cairo_t *cr);
1926
1927cairo_public double
1928cairo_get_line_width (cairo_t *cr);
1929
1930cairo_public cairo_line_cap_t
1931cairo_get_line_cap (cairo_t *cr);
1932
1933cairo_public cairo_line_join_t
1934cairo_get_line_join (cairo_t *cr);
1935
1936cairo_public double
1937cairo_get_miter_limit (cairo_t *cr);
1938
1939cairo_public int
1940cairo_get_dash_count (cairo_t *cr);
1941
1942cairo_public void
1943cairo_get_dash (cairo_t *cr, double *dashes, double *offset);
1944
1945cairo_public void
1946cairo_get_matrix (cairo_t *cr, cairo_matrix_t *matrix);
1947
1948cairo_public cairo_surface_t *
1949cairo_get_target (cairo_t *cr);
1950
1951cairo_public cairo_surface_t *
1952cairo_get_group_target (cairo_t *cr);
1953
1954/**
1955 * cairo_path_data_type_t:
1956 * @CAIRO_PATH_MOVE_TO: A move-to operation, since 1.0
1957 * @CAIRO_PATH_LINE_TO: A line-to operation, since 1.0
1958 * @CAIRO_PATH_CURVE_TO: A curve-to operation, since 1.0
1959 * @CAIRO_PATH_CLOSE_PATH: A close-path operation, since 1.0
1960 *
1961 * #cairo_path_data_t is used to describe the type of one portion
1962 * of a path when represented as a #cairo_path_t.
1963 * See #cairo_path_data_t for details.
1964 *
1965 * Since: 1.0
1966 **/
1967typedef enum _cairo_path_data_type {
1968 CAIRO_PATH_MOVE_TO,
1969 CAIRO_PATH_LINE_TO,
1970 CAIRO_PATH_CURVE_TO,
1971 CAIRO_PATH_CLOSE_PATH
1972} cairo_path_data_type_t;
1973
1974/**
1975 * cairo_path_data_t:
1976 *
1977 * #cairo_path_data_t is used to represent the path data inside a
1978 * #cairo_path_t.
1979 *
1980 * The data structure is designed to try to balance the demands of
1981 * efficiency and ease-of-use. A path is represented as an array of
1982 * #cairo_path_data_t, which is a union of headers and points.
1983 *
1984 * Each portion of the path is represented by one or more elements in
1985 * the array, (one header followed by 0 or more points). The length
1986 * value of the header is the number of array elements for the current
1987 * portion including the header, (ie. length == 1 + # of points), and
1988 * where the number of points for each element type is as follows:
1989 *
1990 * <programlisting>
1991 * %CAIRO_PATH_MOVE_TO: 1 point
1992 * %CAIRO_PATH_LINE_TO: 1 point
1993 * %CAIRO_PATH_CURVE_TO: 3 points
1994 * %CAIRO_PATH_CLOSE_PATH: 0 points
1995 * </programlisting>
1996 *
1997 * The semantics and ordering of the coordinate values are consistent
1998 * with cairo_move_to(), cairo_line_to(), cairo_curve_to(), and
1999 * cairo_close_path().
2000 *
2001 * Here is sample code for iterating through a #cairo_path_t:
2002 *
2003 * <informalexample><programlisting>
2004 * int i;
2005 * cairo_path_t *path;
2006 * cairo_path_data_t *data;
2007 * &nbsp;
2008 * path = cairo_copy_path (cr);
2009 * &nbsp;
2010 * for (i=0; i < path->num_data; i += path->data[i].header.length) {
2011 * data = &amp;path->data[i];
2012 * switch (data->header.type) {
2013 * case CAIRO_PATH_MOVE_TO:
2014 * do_move_to_things (data[1].point.x, data[1].point.y);
2015 * break;
2016 * case CAIRO_PATH_LINE_TO:
2017 * do_line_to_things (data[1].point.x, data[1].point.y);
2018 * break;
2019 * case CAIRO_PATH_CURVE_TO:
2020 * do_curve_to_things (data[1].point.x, data[1].point.y,
2021 * data[2].point.x, data[2].point.y,
2022 * data[3].point.x, data[3].point.y);
2023 * break;
2024 * case CAIRO_PATH_CLOSE_PATH:
2025 * do_close_path_things ();
2026 * break;
2027 * }
2028 * }
2029 * cairo_path_destroy (path);
2030 * </programlisting></informalexample>
2031 *
2032 * As of cairo 1.4, cairo does not mind if there are more elements in
2033 * a portion of the path than needed. Such elements can be used by
2034 * users of the cairo API to hold extra values in the path data
2035 * structure. For this reason, it is recommended that applications
2036 * always use <literal>data->header.length</literal> to
2037 * iterate over the path data, instead of hardcoding the number of
2038 * elements for each element type.
2039 *
2040 * Since: 1.0
2041 **/
2042typedef union _cairo_path_data_t cairo_path_data_t;
2043union _cairo_path_data_t {
2044 struct {
2045 cairo_path_data_type_t type;
2046 int length;
2047 } header;
2048 struct {
2049 double x, y;
2050 } point;
2051};
2052
2053/**
2054 * cairo_path_t:
2055 * @status: the current error status
2056 * @data: the elements in the path
2057 * @num_data: the number of elements in the data array
2058 *
2059 * A data structure for holding a path. This data structure serves as
2060 * the return value for cairo_copy_path() and
2061 * cairo_copy_path_flat() as well the input value for
2062 * cairo_append_path().
2063 *
2064 * See #cairo_path_data_t for hints on how to iterate over the
2065 * actual data within the path.
2066 *
2067 * The num_data member gives the number of elements in the data
2068 * array. This number is larger than the number of independent path
2069 * portions (defined in #cairo_path_data_type_t), since the data
2070 * includes both headers and coordinates for each portion.
2071 *
2072 * Since: 1.0
2073 **/
2074typedef struct cairo_path {
2075 cairo_status_t status;
2076 cairo_path_data_t *data;
2077 int num_data;
2078} cairo_path_t;
2079
2080cairo_public cairo_path_t *
2081cairo_copy_path (cairo_t *cr);
2082
2083cairo_public cairo_path_t *
2084cairo_copy_path_flat (cairo_t *cr);
2085
2086cairo_public void
2087cairo_append_path (cairo_t *cr,
2088 const cairo_path_t *path);
2089
2090cairo_public void
2091cairo_path_destroy (cairo_path_t *path);
2092
2093/* Error status queries */
2094
2095cairo_public cairo_status_t
2096cairo_status (cairo_t *cr);
2097
2098cairo_public const char *
2099cairo_status_to_string (cairo_status_t status);
2100
2101/* Backend device manipulation */
2102
2103cairo_public cairo_device_t *
2104cairo_device_reference (cairo_device_t *device);
2105
2106/**
2107 * cairo_device_type_t:
2108 * @CAIRO_DEVICE_TYPE_DRM: The device is of type Direct Render Manager, since 1.10
2109 * @CAIRO_DEVICE_TYPE_GL: The device is of type OpenGL, since 1.10
2110 * @CAIRO_DEVICE_TYPE_SCRIPT: The device is of type script, since 1.10
2111 * @CAIRO_DEVICE_TYPE_XCB: The device is of type xcb, since 1.10
2112 * @CAIRO_DEVICE_TYPE_XLIB: The device is of type xlib, since 1.10
2113 * @CAIRO_DEVICE_TYPE_XML: The device is of type XML, since 1.10
2114 * @CAIRO_DEVICE_TYPE_COGL: The device is of type cogl, since 1.12
2115 * @CAIRO_DEVICE_TYPE_WIN32: The device is of type win32, since 1.12
2116 * @CAIRO_DEVICE_TYPE_INVALID: The device is invalid, since 1.10
2117 *
2118 * #cairo_device_type_t is used to describe the type of a given
2119 * device. The devices types are also known as "backends" within cairo.
2120 *
2121 * The device type can be queried with cairo_device_get_type()
2122 *
2123 * The various #cairo_device_t functions can be used with devices of
2124 * any type, but some backends also provide type-specific functions
2125 * that must only be called with a device of the appropriate
2126 * type. These functions have names that begin with
2127 * <literal>cairo_<emphasis>type</emphasis>_device</literal> such as
2128 * cairo_xcb_device_debug_cap_xrender_version().
2129 *
2130 * The behavior of calling a type-specific function with a device of
2131 * the wrong type is undefined.
2132 *
2133 * New entries may be added in future versions.
2134 *
2135 * Since: 1.10
2136 **/
2137typedef enum _cairo_device_type {
2138 CAIRO_DEVICE_TYPE_DRM,
2139 CAIRO_DEVICE_TYPE_GL,
2140 CAIRO_DEVICE_TYPE_SCRIPT,
2141 CAIRO_DEVICE_TYPE_XCB,
2142 CAIRO_DEVICE_TYPE_XLIB,
2143 CAIRO_DEVICE_TYPE_XML,
2144 CAIRO_DEVICE_TYPE_COGL,
2145 CAIRO_DEVICE_TYPE_WIN32,
2146
2147 CAIRO_DEVICE_TYPE_INVALID = -1
2148} cairo_device_type_t;
2149
2150cairo_public cairo_device_type_t
2151cairo_device_get_type (cairo_device_t *device);
2152
2153cairo_public cairo_status_t
2154cairo_device_status (cairo_device_t *device);
2155
2156cairo_public cairo_status_t
2157cairo_device_acquire (cairo_device_t *device);
2158
2159cairo_public void
2160cairo_device_release (cairo_device_t *device);
2161
2162cairo_public void
2163cairo_device_flush (cairo_device_t *device);
2164
2165cairo_public void
2166cairo_device_finish (cairo_device_t *device);
2167
2168cairo_public void
2169cairo_device_destroy (cairo_device_t *device);
2170
2171cairo_public unsigned int
2172cairo_device_get_reference_count (cairo_device_t *device);
2173
2174cairo_public void *
2175cairo_device_get_user_data (cairo_device_t *device,
2176 const cairo_user_data_key_t *key);
2177
2178cairo_public cairo_status_t
2179cairo_device_set_user_data (cairo_device_t *device,
2180 const cairo_user_data_key_t *key,
2181 void *user_data,
2182 cairo_destroy_func_t destroy);
2183
2184
2185/* Surface manipulation */
2186
2187cairo_public cairo_surface_t *
2188cairo_surface_create_similar (cairo_surface_t *other,
2189 cairo_content_t content,
2190 int width,
2191 int height);
2192
2193cairo_public cairo_surface_t *
2194cairo_surface_create_similar_image (cairo_surface_t *other,
2195 cairo_format_t format,
2196 int width,
2197 int height);
2198
2199cairo_public cairo_surface_t *
2200cairo_surface_map_to_image (cairo_surface_t *surface,
2201 const cairo_rectangle_int_t *extents);
2202
2203cairo_public void
2204cairo_surface_unmap_image (cairo_surface_t *surface,
2205 cairo_surface_t *image);
2206
2207cairo_public cairo_surface_t *
2208cairo_surface_create_for_rectangle (cairo_surface_t *target,
2209 double x,
2210 double y,
2211 double width,
2212 double height);
2213
2214/**
2215 * cairo_surface_observer_mode_t:
2216 * @CAIRO_SURFACE_OBSERVER_NORMAL: no recording is done
2217 * @CAIRO_SURFACE_OBSERVER_RECORD_OPERATIONS: operations are recorded
2218 *
2219 * Whether operations should be recorded.
2220 *
2221 * Since: 1.12
2222 **/
2223typedef enum {
2224 CAIRO_SURFACE_OBSERVER_NORMAL = 0,
2225 CAIRO_SURFACE_OBSERVER_RECORD_OPERATIONS = 0x1
2226} cairo_surface_observer_mode_t;
2227
2228cairo_public cairo_surface_t *
2229cairo_surface_create_observer (cairo_surface_t *target,
2230 cairo_surface_observer_mode_t mode);
2231
2232typedef void (*cairo_surface_observer_callback_t) (cairo_surface_t *observer,
2233 cairo_surface_t *target,
2234 void *data);
2235
2236cairo_public cairo_status_t
2237cairo_surface_observer_add_paint_callback (cairo_surface_t *abstract_surface,
2238 cairo_surface_observer_callback_t func,
2239 void *data);
2240
2241cairo_public cairo_status_t
2242cairo_surface_observer_add_mask_callback (cairo_surface_t *abstract_surface,
2243 cairo_surface_observer_callback_t func,
2244 void *data);
2245
2246cairo_public cairo_status_t
2247cairo_surface_observer_add_fill_callback (cairo_surface_t *abstract_surface,
2248 cairo_surface_observer_callback_t func,
2249 void *data);
2250
2251cairo_public cairo_status_t
2252cairo_surface_observer_add_stroke_callback (cairo_surface_t *abstract_surface,
2253 cairo_surface_observer_callback_t func,
2254 void *data);
2255
2256cairo_public cairo_status_t
2257cairo_surface_observer_add_glyphs_callback (cairo_surface_t *abstract_surface,
2258 cairo_surface_observer_callback_t func,
2259 void *data);
2260
2261cairo_public cairo_status_t
2262cairo_surface_observer_add_flush_callback (cairo_surface_t *abstract_surface,
2263 cairo_surface_observer_callback_t func,
2264 void *data);
2265
2266cairo_public cairo_status_t
2267cairo_surface_observer_add_finish_callback (cairo_surface_t *abstract_surface,
2268 cairo_surface_observer_callback_t func,
2269 void *data);
2270
2271cairo_public cairo_status_t
2272cairo_surface_observer_print (cairo_surface_t *surface,
2273 cairo_write_func_t write_func,
2274 void *closure);
2275cairo_public double
2276cairo_surface_observer_elapsed (cairo_surface_t *surface);
2277
2278cairo_public cairo_status_t
2279cairo_device_observer_print (cairo_device_t *device,
2280 cairo_write_func_t write_func,
2281 void *closure);
2282
2283cairo_public double
2284cairo_device_observer_elapsed (cairo_device_t *device);
2285
2286cairo_public double
2287cairo_device_observer_paint_elapsed (cairo_device_t *device);
2288
2289cairo_public double
2290cairo_device_observer_mask_elapsed (cairo_device_t *device);
2291
2292cairo_public double
2293cairo_device_observer_fill_elapsed (cairo_device_t *device);
2294
2295cairo_public double
2296cairo_device_observer_stroke_elapsed (cairo_device_t *device);
2297
2298cairo_public double
2299cairo_device_observer_glyphs_elapsed (cairo_device_t *device);
2300
2301cairo_public cairo_surface_t *
2302cairo_surface_reference (cairo_surface_t *surface);
2303
2304cairo_public void
2305cairo_surface_finish (cairo_surface_t *surface);
2306
2307cairo_public void
2308cairo_surface_destroy (cairo_surface_t *surface);
2309
2310cairo_public cairo_device_t *
2311cairo_surface_get_device (cairo_surface_t *surface);
2312
2313cairo_public unsigned int
2314cairo_surface_get_reference_count (cairo_surface_t *surface);
2315
2316cairo_public cairo_status_t
2317cairo_surface_status (cairo_surface_t *surface);
2318
2319/**
2320 * cairo_surface_type_t:
2321 * @CAIRO_SURFACE_TYPE_IMAGE: The surface is of type image, since 1.2
2322 * @CAIRO_SURFACE_TYPE_PDF: The surface is of type pdf, since 1.2
2323 * @CAIRO_SURFACE_TYPE_PS: The surface is of type ps, since 1.2
2324 * @CAIRO_SURFACE_TYPE_XLIB: The surface is of type xlib, since 1.2
2325 * @CAIRO_SURFACE_TYPE_XCB: The surface is of type xcb, since 1.2
2326 * @CAIRO_SURFACE_TYPE_GLITZ: The surface is of type glitz, since 1.2
2327 * @CAIRO_SURFACE_TYPE_QUARTZ: The surface is of type quartz, since 1.2
2328 * @CAIRO_SURFACE_TYPE_WIN32: The surface is of type win32, since 1.2
2329 * @CAIRO_SURFACE_TYPE_BEOS: The surface is of type beos, since 1.2
2330 * @CAIRO_SURFACE_TYPE_DIRECTFB: The surface is of type directfb, since 1.2
2331 * @CAIRO_SURFACE_TYPE_SVG: The surface is of type svg, since 1.2
2332 * @CAIRO_SURFACE_TYPE_OS2: The surface is of type os2, since 1.4
2333 * @CAIRO_SURFACE_TYPE_WIN32_PRINTING: The surface is a win32 printing surface, since 1.6
2334 * @CAIRO_SURFACE_TYPE_QUARTZ_IMAGE: The surface is of type quartz_image, since 1.6
2335 * @CAIRO_SURFACE_TYPE_SCRIPT: The surface is of type script, since 1.10
2336 * @CAIRO_SURFACE_TYPE_QT: The surface is of type Qt, since 1.10
2337 * @CAIRO_SURFACE_TYPE_RECORDING: The surface is of type recording, since 1.10
2338 * @CAIRO_SURFACE_TYPE_VG: The surface is a OpenVG surface, since 1.10
2339 * @CAIRO_SURFACE_TYPE_GL: The surface is of type OpenGL, since 1.10
2340 * @CAIRO_SURFACE_TYPE_DRM: The surface is of type Direct Render Manager, since 1.10
2341 * @CAIRO_SURFACE_TYPE_TEE: The surface is of type 'tee' (a multiplexing surface), since 1.10
2342 * @CAIRO_SURFACE_TYPE_XML: The surface is of type XML (for debugging), since 1.10
2343 * @CAIRO_SURFACE_TYPE_SKIA: The surface is of type Skia, since 1.10
2344 * @CAIRO_SURFACE_TYPE_SUBSURFACE: The surface is a subsurface created with
2345 * cairo_surface_create_for_rectangle(), since 1.10
2346 * @CAIRO_SURFACE_TYPE_COGL: This surface is of type Cogl, since 1.12
2347 *
2348 * #cairo_surface_type_t is used to describe the type of a given
2349 * surface. The surface types are also known as "backends" or "surface
2350 * backends" within cairo.
2351 *
2352 * The type of a surface is determined by the function used to create
2353 * it, which will generally be of the form
2354 * <function>cairo_<emphasis>type</emphasis>_surface_create(<!-- -->)</function>,
2355 * (though see cairo_surface_create_similar() as well).
2356 *
2357 * The surface type can be queried with cairo_surface_get_type()
2358 *
2359 * The various #cairo_surface_t functions can be used with surfaces of
2360 * any type, but some backends also provide type-specific functions
2361 * that must only be called with a surface of the appropriate
2362 * type. These functions have names that begin with
2363 * <literal>cairo_<emphasis>type</emphasis>_surface</literal> such as cairo_image_surface_get_width().
2364 *
2365 * The behavior of calling a type-specific function with a surface of
2366 * the wrong type is undefined.
2367 *
2368 * New entries may be added in future versions.
2369 *
2370 * Since: 1.2
2371 **/
2372typedef enum _cairo_surface_type {
2373 CAIRO_SURFACE_TYPE_IMAGE,
2374 CAIRO_SURFACE_TYPE_PDF,
2375 CAIRO_SURFACE_TYPE_PS,
2376 CAIRO_SURFACE_TYPE_XLIB,
2377 CAIRO_SURFACE_TYPE_XCB,
2378 CAIRO_SURFACE_TYPE_GLITZ,
2379 CAIRO_SURFACE_TYPE_QUARTZ,
2380 CAIRO_SURFACE_TYPE_WIN32,
2381 CAIRO_SURFACE_TYPE_BEOS,
2382 CAIRO_SURFACE_TYPE_DIRECTFB,
2383 CAIRO_SURFACE_TYPE_SVG,
2384 CAIRO_SURFACE_TYPE_OS2,
2385 CAIRO_SURFACE_TYPE_WIN32_PRINTING,
2386 CAIRO_SURFACE_TYPE_QUARTZ_IMAGE,
2387 CAIRO_SURFACE_TYPE_SCRIPT,
2388 CAIRO_SURFACE_TYPE_QT,
2389 CAIRO_SURFACE_TYPE_RECORDING,
2390 CAIRO_SURFACE_TYPE_VG,
2391 CAIRO_SURFACE_TYPE_GL,
2392 CAIRO_SURFACE_TYPE_DRM,
2393 CAIRO_SURFACE_TYPE_TEE,
2394 CAIRO_SURFACE_TYPE_XML,
2395 CAIRO_SURFACE_TYPE_SKIA,
2396 CAIRO_SURFACE_TYPE_SUBSURFACE,
2397 CAIRO_SURFACE_TYPE_COGL
2398} cairo_surface_type_t;
2399
2400cairo_public cairo_surface_type_t
2401cairo_surface_get_type (cairo_surface_t *surface);
2402
2403cairo_public cairo_content_t
2404cairo_surface_get_content (cairo_surface_t *surface);
2405
2406#if CAIRO_HAS_PNG_FUNCTIONS
2407
2408cairo_public cairo_status_t
2409cairo_surface_write_to_png (cairo_surface_t *surface,
2410 const char *filename);
2411
2412cairo_public cairo_status_t
2413cairo_surface_write_to_png_stream (cairo_surface_t *surface,
2414 cairo_write_func_t write_func,
2415 void *closure);
2416
2417#endif
2418
2419cairo_public void *
2420cairo_surface_get_user_data (cairo_surface_t *surface,
2421 const cairo_user_data_key_t *key);
2422
2423cairo_public cairo_status_t
2424cairo_surface_set_user_data (cairo_surface_t *surface,
2425 const cairo_user_data_key_t *key,
2426 void *user_data,
2427 cairo_destroy_func_t destroy);
2428
2429#define CAIRO_MIME_TYPE_JPEG "image/jpeg"
2430#define CAIRO_MIME_TYPE_PNG "image/png"
2431#define CAIRO_MIME_TYPE_JP2 "image/jp2"
2432#define CAIRO_MIME_TYPE_URI "text/x-uri"
2433#define CAIRO_MIME_TYPE_UNIQUE_ID "application/x-cairo.uuid"
2434#define CAIRO_MIME_TYPE_JBIG2 "application/x-cairo.jbig2"
2435#define CAIRO_MIME_TYPE_JBIG2_GLOBAL "application/x-cairo.jbig2-global"
2436#define CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID "application/x-cairo.jbig2-global-id"
2437
2438cairo_public void
2439cairo_surface_get_mime_data (cairo_surface_t *surface,
2440 const char *mime_type,
2441 const unsigned char **data,
2442 unsigned long *length);
2443
2444cairo_public cairo_status_t
2445cairo_surface_set_mime_data (cairo_surface_t *surface,
2446 const char *mime_type,
2447 const unsigned char *data,
2448 unsigned long length,
2449 cairo_destroy_func_t destroy,
2450 void *closure);
2451
2452cairo_public cairo_bool_t
2453cairo_surface_supports_mime_type (cairo_surface_t *surface,
2454 const char *mime_type);
2455
2456cairo_public void
2457cairo_surface_get_font_options (cairo_surface_t *surface,
2458 cairo_font_options_t *options);
2459
2460cairo_public void
2461cairo_surface_flush (cairo_surface_t *surface);
2462
2463cairo_public void
2464cairo_surface_mark_dirty (cairo_surface_t *surface);
2465
2466cairo_public void
2467cairo_surface_mark_dirty_rectangle (cairo_surface_t *surface,
2468 int x,
2469 int y,
2470 int width,
2471 int height);
2472
2473cairo_public void
2474cairo_surface_set_device_scale (cairo_surface_t *surface,
2475 double x_scale,
2476 double y_scale);
2477
2478cairo_public void
2479cairo_surface_get_device_scale (cairo_surface_t *surface,
2480 double *x_scale,
2481 double *y_scale);
2482
2483cairo_public void
2484cairo_surface_set_device_offset (cairo_surface_t *surface,
2485 double x_offset,
2486 double y_offset);
2487
2488cairo_public void
2489cairo_surface_get_device_offset (cairo_surface_t *surface,
2490 double *x_offset,
2491 double *y_offset);
2492
2493cairo_public void
2494cairo_surface_set_fallback_resolution (cairo_surface_t *surface,
2495 double x_pixels_per_inch,
2496 double y_pixels_per_inch);
2497
2498cairo_public void
2499cairo_surface_get_fallback_resolution (cairo_surface_t *surface,
2500 double *x_pixels_per_inch,
2501 double *y_pixels_per_inch);
2502
2503cairo_public void
2504cairo_surface_copy_page (cairo_surface_t *surface);
2505
2506cairo_public void
2507cairo_surface_show_page (cairo_surface_t *surface);
2508
2509cairo_public cairo_bool_t
2510cairo_surface_has_show_text_glyphs (cairo_surface_t *surface);
2511
2512/* Image-surface functions */
2513
2514cairo_public cairo_surface_t *
2515cairo_image_surface_create (cairo_format_t format,
2516 int width,
2517 int height);
2518
2519cairo_public int
2520cairo_format_stride_for_width (cairo_format_t format,
2521 int width);
2522
2523cairo_public cairo_surface_t *
2524cairo_image_surface_create_for_data (unsigned char *data,
2525 cairo_format_t format,
2526 int width,
2527 int height,
2528 int stride);
2529
2530cairo_public unsigned char *
2531cairo_image_surface_get_data (cairo_surface_t *surface);
2532
2533cairo_public cairo_format_t
2534cairo_image_surface_get_format (cairo_surface_t *surface);
2535
2536cairo_public int
2537cairo_image_surface_get_width (cairo_surface_t *surface);
2538
2539cairo_public int
2540cairo_image_surface_get_height (cairo_surface_t *surface);
2541
2542cairo_public int
2543cairo_image_surface_get_stride (cairo_surface_t *surface);
2544
2545#if CAIRO_HAS_PNG_FUNCTIONS
2546
2547cairo_public cairo_surface_t *
2548cairo_image_surface_create_from_png (const char *filename);
2549
2550cairo_public cairo_surface_t *
2551cairo_image_surface_create_from_png_stream (cairo_read_func_t read_func,
2552 void *closure);
2553
2554#endif
2555
2556/* Recording-surface functions */
2557
2558cairo_public cairo_surface_t *
2559cairo_recording_surface_create (cairo_content_t content,
2560 const cairo_rectangle_t *extents);
2561
2562cairo_public void
2563cairo_recording_surface_ink_extents (cairo_surface_t *surface,
2564 double *x0,
2565 double *y0,
2566 double *width,
2567 double *height);
2568
2569cairo_public cairo_bool_t
2570cairo_recording_surface_get_extents (cairo_surface_t *surface,
2571 cairo_rectangle_t *extents);
2572
2573/* raster-source pattern (callback) functions */
2574
2575/**
2576 * cairo_raster_source_acquire_func_t:
2577 * @pattern: the pattern being rendered from
2578 * @callback_data: the user data supplied during creation
2579 * @target: the rendering target surface
2580 * @extents: rectangular region of interest in pixels in sample space
2581 *
2582 * #cairo_raster_source_acquire_func_t is the type of function which is
2583 * called when a pattern is being rendered from. It should create a surface
2584 * that provides the pixel data for the region of interest as defined by
2585 * extents, though the surface itself does not have to be limited to that
2586 * area. For convenience the surface should probably be of image type,
2587 * created with cairo_surface_create_similar_image() for the target (which
2588 * enables the number of copies to be reduced during transfer to the
2589 * device). Another option, might be to return a similar surface to the
2590 * target for explicit handling by the application of a set of cached sources
2591 * on the device. The region of sample data provided should be defined using
2592 * cairo_surface_set_device_offset() to specify the top-left corner of the
2593 * sample data (along with width and height of the surface).
2594 *
2595 * Returns: a #cairo_surface_t
2596 *
2597 * Since: 1.12
2598 **/
2599typedef cairo_surface_t *
2600(*cairo_raster_source_acquire_func_t) (cairo_pattern_t *pattern,
2601 void *callback_data,
2602 cairo_surface_t *target,
2603 const cairo_rectangle_int_t *extents);
2604
2605/**
2606 * cairo_raster_source_release_func_t:
2607 * @pattern: the pattern being rendered from
2608 * @callback_data: the user data supplied during creation
2609 * @surface: the surface created during acquire
2610 *
2611 * #cairo_raster_source_release_func_t is the type of function which is
2612 * called when the pixel data is no longer being access by the pattern
2613 * for the rendering operation. Typically this function will simply
2614 * destroy the surface created during acquire.
2615 *
2616 * Since: 1.12
2617 **/
2618typedef void
2619(*cairo_raster_source_release_func_t) (cairo_pattern_t *pattern,
2620 void *callback_data,
2621 cairo_surface_t *surface);
2622
2623/**
2624 * cairo_raster_source_snapshot_func_t:
2625 * @pattern: the pattern being rendered from
2626 * @callback_data: the user data supplied during creation
2627 *
2628 * #cairo_raster_source_snapshot_func_t is the type of function which is
2629 * called when the pixel data needs to be preserved for later use
2630 * during printing. This pattern will be accessed again later, and it
2631 * is expected to provide the pixel data that was current at the time
2632 * of snapshotting.
2633 *
2634 * Return value: CAIRO_STATUS_SUCCESS on success, or one of the
2635 * #cairo_status_t error codes for failure.
2636 *
2637 * Since: 1.12
2638 **/
2639typedef cairo_status_t
2640(*cairo_raster_source_snapshot_func_t) (cairo_pattern_t *pattern,
2641 void *callback_data);
2642
2643/**
2644 * cairo_raster_source_copy_func_t:
2645 * @pattern: the #cairo_pattern_t that was copied to
2646 * @callback_data: the user data supplied during creation
2647 * @other: the #cairo_pattern_t being used as the source for the copy
2648 *
2649 * #cairo_raster_source_copy_func_t is the type of function which is
2650 * called when the pattern gets copied as a normal part of rendering.
2651 *
2652 * Return value: CAIRO_STATUS_SUCCESS on success, or one of the
2653 * #cairo_status_t error codes for failure.
2654 *
2655 * Since: 1.12
2656 **/
2657typedef cairo_status_t
2658(*cairo_raster_source_copy_func_t) (cairo_pattern_t *pattern,
2659 void *callback_data,
2660 const cairo_pattern_t *other);
2661
2662/**
2663 * cairo_raster_source_finish_func_t:
2664 * @pattern: the pattern being rendered from
2665 * @callback_data: the user data supplied during creation
2666 *
2667 * #cairo_raster_source_finish_func_t is the type of function which is
2668 * called when the pattern (or a copy thereof) is no longer required.
2669 *
2670 * Since: 1.12
2671 **/
2672typedef void
2673(*cairo_raster_source_finish_func_t) (cairo_pattern_t *pattern,
2674 void *callback_data);
2675
2676cairo_public cairo_pattern_t *
2677cairo_pattern_create_raster_source (void *user_data,
2678 cairo_content_t content,
2679 int width, int height);
2680
2681cairo_public void
2682cairo_raster_source_pattern_set_callback_data (cairo_pattern_t *pattern,
2683 void *data);
2684
2685cairo_public void *
2686cairo_raster_source_pattern_get_callback_data (cairo_pattern_t *pattern);
2687
2688cairo_public void
2689cairo_raster_source_pattern_set_acquire (cairo_pattern_t *pattern,
2690 cairo_raster_source_acquire_func_t acquire,
2691 cairo_raster_source_release_func_t release);
2692
2693cairo_public void
2694cairo_raster_source_pattern_get_acquire (cairo_pattern_t *pattern,
2695 cairo_raster_source_acquire_func_t *acquire,
2696 cairo_raster_source_release_func_t *release);
2697cairo_public void
2698cairo_raster_source_pattern_set_snapshot (cairo_pattern_t *pattern,
2699 cairo_raster_source_snapshot_func_t snapshot);
2700
2701cairo_public cairo_raster_source_snapshot_func_t
2702cairo_raster_source_pattern_get_snapshot (cairo_pattern_t *pattern);
2703
2704cairo_public void
2705cairo_raster_source_pattern_set_copy (cairo_pattern_t *pattern,
2706 cairo_raster_source_copy_func_t copy);
2707
2708cairo_public cairo_raster_source_copy_func_t
2709cairo_raster_source_pattern_get_copy (cairo_pattern_t *pattern);
2710
2711cairo_public void
2712cairo_raster_source_pattern_set_finish (cairo_pattern_t *pattern,
2713 cairo_raster_source_finish_func_t finish);
2714
2715cairo_public cairo_raster_source_finish_func_t
2716cairo_raster_source_pattern_get_finish (cairo_pattern_t *pattern);
2717
2718/* Pattern creation functions */
2719
2720cairo_public cairo_pattern_t *
2721cairo_pattern_create_rgb (double red, double green, double blue);
2722
2723cairo_public cairo_pattern_t *
2724cairo_pattern_create_rgba (double red, double green, double blue,
2725 double alpha);
2726
2727cairo_public cairo_pattern_t *
2728cairo_pattern_create_for_surface (cairo_surface_t *surface);
2729
2730cairo_public cairo_pattern_t *
2731cairo_pattern_create_linear (double x0, double y0,
2732 double x1, double y1);
2733
2734cairo_public cairo_pattern_t *
2735cairo_pattern_create_radial (double cx0, double cy0, double radius0,
2736 double cx1, double cy1, double radius1);
2737
2738cairo_public cairo_pattern_t *
2739cairo_pattern_create_mesh (void);
2740
2741cairo_public cairo_pattern_t *
2742cairo_pattern_reference (cairo_pattern_t *pattern);
2743
2744cairo_public void
2745cairo_pattern_destroy (cairo_pattern_t *pattern);
2746
2747cairo_public unsigned int
2748cairo_pattern_get_reference_count (cairo_pattern_t *pattern);
2749
2750cairo_public cairo_status_t
2751cairo_pattern_status (cairo_pattern_t *pattern);
2752
2753cairo_public void *
2754cairo_pattern_get_user_data (cairo_pattern_t *pattern,
2755 const cairo_user_data_key_t *key);
2756
2757cairo_public cairo_status_t
2758cairo_pattern_set_user_data (cairo_pattern_t *pattern,
2759 const cairo_user_data_key_t *key,
2760 void *user_data,
2761 cairo_destroy_func_t destroy);
2762
2763/**
2764 * cairo_pattern_type_t:
2765 * @CAIRO_PATTERN_TYPE_SOLID: The pattern is a solid (uniform)
2766 * color. It may be opaque or translucent, since 1.2.
2767 * @CAIRO_PATTERN_TYPE_SURFACE: The pattern is a based on a surface (an image), since 1.2.
2768 * @CAIRO_PATTERN_TYPE_LINEAR: The pattern is a linear gradient, since 1.2.
2769 * @CAIRO_PATTERN_TYPE_RADIAL: The pattern is a radial gradient, since 1.2.
2770 * @CAIRO_PATTERN_TYPE_MESH: The pattern is a mesh, since 1.12.
2771 * @CAIRO_PATTERN_TYPE_RASTER_SOURCE: The pattern is a user pattern providing raster data, since 1.12.
2772 *
2773 * #cairo_pattern_type_t is used to describe the type of a given pattern.
2774 *
2775 * The type of a pattern is determined by the function used to create
2776 * it. The cairo_pattern_create_rgb() and cairo_pattern_create_rgba()
2777 * functions create SOLID patterns. The remaining
2778 * cairo_pattern_create<!-- --> functions map to pattern types in obvious
2779 * ways.
2780 *
2781 * The pattern type can be queried with cairo_pattern_get_type()
2782 *
2783 * Most #cairo_pattern_t functions can be called with a pattern of any
2784 * type, (though trying to change the extend or filter for a solid
2785 * pattern will have no effect). A notable exception is
2786 * cairo_pattern_add_color_stop_rgb() and
2787 * cairo_pattern_add_color_stop_rgba() which must only be called with
2788 * gradient patterns (either LINEAR or RADIAL). Otherwise the pattern
2789 * will be shutdown and put into an error state.
2790 *
2791 * New entries may be added in future versions.
2792 *
2793 * Since: 1.2
2794 **/
2795typedef enum _cairo_pattern_type {
2796 CAIRO_PATTERN_TYPE_SOLID,
2797 CAIRO_PATTERN_TYPE_SURFACE,
2798 CAIRO_PATTERN_TYPE_LINEAR,
2799 CAIRO_PATTERN_TYPE_RADIAL,
2800 CAIRO_PATTERN_TYPE_MESH,
2801 CAIRO_PATTERN_TYPE_RASTER_SOURCE
2802} cairo_pattern_type_t;
2803
2804cairo_public cairo_pattern_type_t
2805cairo_pattern_get_type (cairo_pattern_t *pattern);
2806
2807cairo_public void
2808cairo_pattern_add_color_stop_rgb (cairo_pattern_t *pattern,
2809 double offset,
2810 double red, double green, double blue);
2811
2812cairo_public void
2813cairo_pattern_add_color_stop_rgba (cairo_pattern_t *pattern,
2814 double offset,
2815 double red, double green, double blue,
2816 double alpha);
2817
2818cairo_public void
2819cairo_mesh_pattern_begin_patch (cairo_pattern_t *pattern);
2820
2821cairo_public void
2822cairo_mesh_pattern_end_patch (cairo_pattern_t *pattern);
2823
2824cairo_public void
2825cairo_mesh_pattern_curve_to (cairo_pattern_t *pattern,
2826 double x1, double y1,
2827 double x2, double y2,
2828 double x3, double y3);
2829
2830cairo_public void
2831cairo_mesh_pattern_line_to (cairo_pattern_t *pattern,
2832 double x, double y);
2833
2834cairo_public void
2835cairo_mesh_pattern_move_to (cairo_pattern_t *pattern,
2836 double x, double y);
2837
2838cairo_public void
2839cairo_mesh_pattern_set_control_point (cairo_pattern_t *pattern,
2840 unsigned int point_num,
2841 double x, double y);
2842
2843cairo_public void
2844cairo_mesh_pattern_set_corner_color_rgb (cairo_pattern_t *pattern,
2845 unsigned int corner_num,
2846 double red, double green, double blue);
2847
2848cairo_public void
2849cairo_mesh_pattern_set_corner_color_rgba (cairo_pattern_t *pattern,
2850 unsigned int corner_num,
2851 double red, double green, double blue,
2852 double alpha);
2853
2854cairo_public void
2855cairo_pattern_set_matrix (cairo_pattern_t *pattern,
2856 const cairo_matrix_t *matrix);
2857
2858cairo_public void
2859cairo_pattern_get_matrix (cairo_pattern_t *pattern,
2860 cairo_matrix_t *matrix);
2861
2862/**
2863 * cairo_extend_t:
2864 * @CAIRO_EXTEND_NONE: pixels outside of the source pattern
2865 * are fully transparent (Since 1.0)
2866 * @CAIRO_EXTEND_REPEAT: the pattern is tiled by repeating (Since 1.0)
2867 * @CAIRO_EXTEND_REFLECT: the pattern is tiled by reflecting
2868 * at the edges (Since 1.0; but only implemented for surface patterns since 1.6)
2869 * @CAIRO_EXTEND_PAD: pixels outside of the pattern copy
2870 * the closest pixel from the source (Since 1.2; but only
2871 * implemented for surface patterns since 1.6)
2872 *
2873 * #cairo_extend_t is used to describe how pattern color/alpha will be
2874 * determined for areas "outside" the pattern's natural area, (for
2875 * example, outside the surface bounds or outside the gradient
2876 * geometry).
2877 *
2878 * Mesh patterns are not affected by the extend mode.
2879 *
2880 * The default extend mode is %CAIRO_EXTEND_NONE for surface patterns
2881 * and %CAIRO_EXTEND_PAD for gradient patterns.
2882 *
2883 * New entries may be added in future versions.
2884 *
2885 * Since: 1.0
2886 **/
2887typedef enum _cairo_extend {
2888 CAIRO_EXTEND_NONE,
2889 CAIRO_EXTEND_REPEAT,
2890 CAIRO_EXTEND_REFLECT,
2891 CAIRO_EXTEND_PAD
2892} cairo_extend_t;
2893
2894cairo_public void
2895cairo_pattern_set_extend (cairo_pattern_t *pattern, cairo_extend_t extend);
2896
2897cairo_public cairo_extend_t
2898cairo_pattern_get_extend (cairo_pattern_t *pattern);
2899
2900/**
2901 * cairo_filter_t:
2902 * @CAIRO_FILTER_FAST: A high-performance filter, with quality similar
2903 * to %CAIRO_FILTER_NEAREST (Since 1.0)
2904 * @CAIRO_FILTER_GOOD: A reasonable-performance filter, with quality
2905 * similar to %CAIRO_FILTER_BILINEAR (Since 1.0)
2906 * @CAIRO_FILTER_BEST: The highest-quality available, performance may
2907 * not be suitable for interactive use. (Since 1.0)
2908 * @CAIRO_FILTER_NEAREST: Nearest-neighbor filtering (Since 1.0)
2909 * @CAIRO_FILTER_BILINEAR: Linear interpolation in two dimensions (Since 1.0)
2910 * @CAIRO_FILTER_GAUSSIAN: This filter value is currently
2911 * unimplemented, and should not be used in current code. (Since 1.0)
2912 *
2913 * #cairo_filter_t is used to indicate what filtering should be
2914 * applied when reading pixel values from patterns. See
2915 * cairo_pattern_set_filter() for indicating the desired filter to be
2916 * used with a particular pattern.
2917 *
2918 * Since: 1.0
2919 **/
2920typedef enum _cairo_filter {
2921 CAIRO_FILTER_FAST,
2922 CAIRO_FILTER_GOOD,
2923 CAIRO_FILTER_BEST,
2924 CAIRO_FILTER_NEAREST,
2925 CAIRO_FILTER_BILINEAR,
2926 CAIRO_FILTER_GAUSSIAN
2927} cairo_filter_t;
2928
2929cairo_public void
2930cairo_pattern_set_filter (cairo_pattern_t *pattern, cairo_filter_t filter);
2931
2932cairo_public cairo_filter_t
2933cairo_pattern_get_filter (cairo_pattern_t *pattern);
2934
2935cairo_public cairo_status_t
2936cairo_pattern_get_rgba (cairo_pattern_t *pattern,
2937 double *red, double *green,
2938 double *blue, double *alpha);
2939
2940cairo_public cairo_status_t
2941cairo_pattern_get_surface (cairo_pattern_t *pattern,
2942 cairo_surface_t **surface);
2943
2944
2945cairo_public cairo_status_t
2946cairo_pattern_get_color_stop_rgba (cairo_pattern_t *pattern,
2947 int index, double *offset,
2948 double *red, double *green,
2949 double *blue, double *alpha);
2950
2951cairo_public cairo_status_t
2952cairo_pattern_get_color_stop_count (cairo_pattern_t *pattern,
2953 int *count);
2954
2955cairo_public cairo_status_t
2956cairo_pattern_get_linear_points (cairo_pattern_t *pattern,
2957 double *x0, double *y0,
2958 double *x1, double *y1);
2959
2960cairo_public cairo_status_t
2961cairo_pattern_get_radial_circles (cairo_pattern_t *pattern,
2962 double *x0, double *y0, double *r0,
2963 double *x1, double *y1, double *r1);
2964
2965cairo_public cairo_status_t
2966cairo_mesh_pattern_get_patch_count (cairo_pattern_t *pattern,
2967 unsigned int *count);
2968
2969cairo_public cairo_path_t *
2970cairo_mesh_pattern_get_path (cairo_pattern_t *pattern,
2971 unsigned int patch_num);
2972
2973cairo_public cairo_status_t
2974cairo_mesh_pattern_get_corner_color_rgba (cairo_pattern_t *pattern,
2975 unsigned int patch_num,
2976 unsigned int corner_num,
2977 double *red, double *green,
2978 double *blue, double *alpha);
2979
2980cairo_public cairo_status_t
2981cairo_mesh_pattern_get_control_point (cairo_pattern_t *pattern,
2982 unsigned int patch_num,
2983 unsigned int point_num,
2984 double *x, double *y);
2985
2986/* Matrix functions */
2987
2988cairo_public void
2989cairo_matrix_init (cairo_matrix_t *matrix,
2990 double xx, double yx,
2991 double xy, double yy,
2992 double x0, double y0);
2993
2994cairo_public void
2995cairo_matrix_init_identity (cairo_matrix_t *matrix);
2996
2997cairo_public void
2998cairo_matrix_init_translate (cairo_matrix_t *matrix,
2999 double tx, double ty);
3000
3001cairo_public void
3002cairo_matrix_init_scale (cairo_matrix_t *matrix,
3003 double sx, double sy);
3004
3005cairo_public void
3006cairo_matrix_init_rotate (cairo_matrix_t *matrix,
3007 double radians);
3008
3009cairo_public void
3010cairo_matrix_translate (cairo_matrix_t *matrix, double tx, double ty);
3011
3012cairo_public void
3013cairo_matrix_scale (cairo_matrix_t *matrix, double sx, double sy);
3014
3015cairo_public void
3016cairo_matrix_rotate (cairo_matrix_t *matrix, double radians);
3017
3018cairo_public cairo_status_t
3019cairo_matrix_invert (cairo_matrix_t *matrix);
3020
3021cairo_public void
3022cairo_matrix_multiply (cairo_matrix_t *result,
3023 const cairo_matrix_t *a,
3024 const cairo_matrix_t *b);
3025
3026cairo_public void
3027cairo_matrix_transform_distance (const cairo_matrix_t *matrix,
3028 double *dx, double *dy);
3029
3030cairo_public void
3031cairo_matrix_transform_point (const cairo_matrix_t *matrix,
3032 double *x, double *y);
3033
3034/* Region functions */
3035
3036/**
3037 * cairo_region_t:
3038 *
3039 * A #cairo_region_t represents a set of integer-aligned rectangles.
3040 *
3041 * It allows set-theoretical operations like cairo_region_union() and
3042 * cairo_region_intersect() to be performed on them.
3043 *
3044 * Memory management of #cairo_region_t is done with
3045 * cairo_region_reference() and cairo_region_destroy().
3046 *
3047 * Since: 1.10
3048 **/
3049typedef struct _cairo_region cairo_region_t;
3050
3051/**
3052 * cairo_region_overlap_t:
3053 * @CAIRO_REGION_OVERLAP_IN: The contents are entirely inside the region. (Since 1.10)
3054 * @CAIRO_REGION_OVERLAP_OUT: The contents are entirely outside the region. (Since 1.10)
3055 * @CAIRO_REGION_OVERLAP_PART: The contents are partially inside and
3056 * partially outside the region. (Since 1.10)
3057 *
3058 * Used as the return value for cairo_region_contains_rectangle().
3059 *
3060 * Since: 1.10
3061 **/
3062typedef enum _cairo_region_overlap {
3063 CAIRO_REGION_OVERLAP_IN, /* completely inside region */
3064 CAIRO_REGION_OVERLAP_OUT, /* completely outside region */
3065 CAIRO_REGION_OVERLAP_PART /* partly inside region */
3066} cairo_region_overlap_t;
3067
3068cairo_public cairo_region_t *
3069cairo_region_create (void);
3070
3071cairo_public cairo_region_t *
3072cairo_region_create_rectangle (const cairo_rectangle_int_t *rectangle);
3073
3074cairo_public cairo_region_t *
3075cairo_region_create_rectangles (const cairo_rectangle_int_t *rects,
3076 int count);
3077
3078cairo_public cairo_region_t *
3079cairo_region_copy (const cairo_region_t *original);
3080
3081cairo_public cairo_region_t *
3082cairo_region_reference (cairo_region_t *region);
3083
3084cairo_public void
3085cairo_region_destroy (cairo_region_t *region);
3086
3087cairo_public cairo_bool_t
3088cairo_region_equal (const cairo_region_t *a, const cairo_region_t *b);
3089
3090cairo_public cairo_status_t
3091cairo_region_status (const cairo_region_t *region);
3092
3093cairo_public void
3094cairo_region_get_extents (const cairo_region_t *region,
3095 cairo_rectangle_int_t *extents);
3096
3097cairo_public int
3098cairo_region_num_rectangles (const cairo_region_t *region);
3099
3100cairo_public void
3101cairo_region_get_rectangle (const cairo_region_t *region,
3102 int nth,
3103 cairo_rectangle_int_t *rectangle);
3104
3105cairo_public cairo_bool_t
3106cairo_region_is_empty (const cairo_region_t *region);
3107
3108cairo_public cairo_region_overlap_t
3109cairo_region_contains_rectangle (const cairo_region_t *region,
3110 const cairo_rectangle_int_t *rectangle);
3111
3112cairo_public cairo_bool_t
3113cairo_region_contains_point (const cairo_region_t *region, int x, int y);
3114
3115cairo_public void
3116cairo_region_translate (cairo_region_t *region, int dx, int dy);
3117
3118cairo_public cairo_status_t
3119cairo_region_subtract (cairo_region_t *dst, const cairo_region_t *other);
3120
3121cairo_public cairo_status_t
3122cairo_region_subtract_rectangle (cairo_region_t *dst,
3123 const cairo_rectangle_int_t *rectangle);
3124
3125cairo_public cairo_status_t
3126cairo_region_intersect (cairo_region_t *dst, const cairo_region_t *other);
3127
3128cairo_public cairo_status_t
3129cairo_region_intersect_rectangle (cairo_region_t *dst,
3130 const cairo_rectangle_int_t *rectangle);
3131
3132cairo_public cairo_status_t
3133cairo_region_union (cairo_region_t *dst, const cairo_region_t *other);
3134
3135cairo_public cairo_status_t
3136cairo_region_union_rectangle (cairo_region_t *dst,
3137 const cairo_rectangle_int_t *rectangle);
3138
3139cairo_public cairo_status_t
3140cairo_region_xor (cairo_region_t *dst, const cairo_region_t *other);
3141
3142cairo_public cairo_status_t
3143cairo_region_xor_rectangle (cairo_region_t *dst,
3144 const cairo_rectangle_int_t *rectangle);
3145
3146/* Functions to be used while debugging (not intended for use in production code) */
3147cairo_public void
3148cairo_debug_reset_static_data (void);
3149
3150
3151CAIRO_END_DECLS
3152
3153#endif /* CAIRO_H */
3154