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