1 /* cairo - a vector graphics library with display and print output
3 * Copyright © 2002 University of Southern California
4 * Copyright © 2005 Red Hat, Inc.
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.
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
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/
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.
29 * The Original Code is the cairo graphics library.
31 * The Initial Developer of the Original Code is University of Southern
35 * Carl D. Worth <cworth@cworth.org>
41 #include "cairo-version.h"
42 #include "cairo-features.h"
43 #include "cairo-deprecated.h"
46 # define CAIRO_BEGIN_DECLS extern "C" {
47 # define CAIRO_END_DECLS }
49 # define CAIRO_BEGIN_DECLS
50 # define CAIRO_END_DECLS
54 # if defined (_MSC_VER) && ! defined (CAIRO_WIN32_STATIC_BUILD)
55 # define cairo_public __declspec(dllimport)
63 #define CAIRO_VERSION_ENCODE(major, minor, micro) ( \
68 #define CAIRO_VERSION CAIRO_VERSION_ENCODE( \
69 CAIRO_VERSION_MAJOR, \
70 CAIRO_VERSION_MINOR, \
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)
79 #define CAIRO_VERSION_STRING CAIRO_VERSION_STRINGIZE( \
80 CAIRO_VERSION_MAJOR, \
81 CAIRO_VERSION_MINOR, \
88 cairo_public const char*
89 cairo_version_string (void);
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.
99 * <informalexample><programlisting>
100 * if (cairo_in_stroke (cr, x, y)) {
101 * /<!-- -->* do something *<!-- -->/
103 * </programlisting></informalexample>
107 typedef int cairo_bool_t;
112 * A #cairo_t contains the current state of the rendering device,
113 * including coordinates of yet to be drawn shapes.
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
119 * Memory management of #cairo_t is done with
120 * cairo_reference() and cairo_destroy().
124 typedef struct _cairo cairo_t;
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().
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().
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().
148 * Memory management of #cairo_surface_t is done with
149 * cairo_surface_reference() and cairo_surface_destroy().
153 typedef struct _cairo_surface cairo_surface_t;
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
164 * The type of a device can be queried with cairo_device_get_type().
166 * Memory management of #cairo_device_t is done with
167 * cairo_device_reference() and cairo_device_destroy().
171 typedef struct _cairo_device cairo_device_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
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:
186 * x_new = xx * x + xy * y + x0;
187 * y_new = yx * x + yy * y + y0;
192 typedef struct _cairo_matrix {
193 double xx; double yx;
194 double xy; double yy;
195 double x0; double y0;
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
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().
213 * The type of a pattern can be queried with cairo_pattern_get_type().
215 * Memory management of #cairo_pattern_t is done with
216 * cairo_pattern_reference() and cairo_pattern_destroy().
220 typedef struct _cairo_pattern cairo_pattern_t;
223 * cairo_destroy_func_t:
224 * @data: The data element being destroyed.
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.
232 typedef void (*cairo_destroy_func_t) (void *data);
235 * cairo_user_data_key_t:
236 * @unused: not used; ignore.
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.
246 typedef struct _cairo_user_data_key {
248 } cairo_user_data_key_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()
292 * @CAIRO_STATUS_DEVICE_FINISHED: target device has been finished (Since 1.12)
293 * @CAIRO_STATUS_JBIG2_GLOBAL_MISSING: %CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID has been used on at least one image
294 * but no image provided %CAIRO_MIME_TYPE_JBIG2_GLOBAL (Since 1.14)
295 * @CAIRO_STATUS_LAST_STATUS: this is a special value indicating the number of
296 * status values defined in this enumeration. When using this value, note
297 * that the version of cairo at run-time may have additional status values
298 * defined than the value of this symbol at compile-time. (Since 1.10)
300 * #cairo_status_t is used to indicate errors that can occur when
301 * using Cairo. In some cases it is returned directly by functions.
302 * but when using #cairo_t, the last error, if any, is stored in
303 * the context and can be retrieved with cairo_status().
305 * New entries may be added in future versions. Use cairo_status_to_string()
306 * to get a human-readable representation of an error message.
310 typedef enum _cairo_status {
311 CAIRO_STATUS_SUCCESS = 0,
313 CAIRO_STATUS_NO_MEMORY,
314 CAIRO_STATUS_INVALID_RESTORE,
315 CAIRO_STATUS_INVALID_POP_GROUP,
316 CAIRO_STATUS_NO_CURRENT_POINT,
317 CAIRO_STATUS_INVALID_MATRIX,
318 CAIRO_STATUS_INVALID_STATUS,
319 CAIRO_STATUS_NULL_POINTER,
320 CAIRO_STATUS_INVALID_STRING,
321 CAIRO_STATUS_INVALID_PATH_DATA,
322 CAIRO_STATUS_READ_ERROR,
323 CAIRO_STATUS_WRITE_ERROR,
324 CAIRO_STATUS_SURFACE_FINISHED,
325 CAIRO_STATUS_SURFACE_TYPE_MISMATCH,
326 CAIRO_STATUS_PATTERN_TYPE_MISMATCH,
327 CAIRO_STATUS_INVALID_CONTENT,
328 CAIRO_STATUS_INVALID_FORMAT,
329 CAIRO_STATUS_INVALID_VISUAL,
330 CAIRO_STATUS_FILE_NOT_FOUND,
331 CAIRO_STATUS_INVALID_DASH,
332 CAIRO_STATUS_INVALID_DSC_COMMENT,
333 CAIRO_STATUS_INVALID_INDEX,
334 CAIRO_STATUS_CLIP_NOT_REPRESENTABLE,
335 CAIRO_STATUS_TEMP_FILE_ERROR,
336 CAIRO_STATUS_INVALID_STRIDE,
337 CAIRO_STATUS_FONT_TYPE_MISMATCH,
338 CAIRO_STATUS_USER_FONT_IMMUTABLE,
339 CAIRO_STATUS_USER_FONT_ERROR,
340 CAIRO_STATUS_NEGATIVE_COUNT,
341 CAIRO_STATUS_INVALID_CLUSTERS,
342 CAIRO_STATUS_INVALID_SLANT,
343 CAIRO_STATUS_INVALID_WEIGHT,
344 CAIRO_STATUS_INVALID_SIZE,
345 CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED,
346 CAIRO_STATUS_DEVICE_TYPE_MISMATCH,
347 CAIRO_STATUS_DEVICE_ERROR,
348 CAIRO_STATUS_INVALID_MESH_CONSTRUCTION,
349 CAIRO_STATUS_DEVICE_FINISHED,
350 CAIRO_STATUS_JBIG2_GLOBAL_MISSING,
352 CAIRO_STATUS_LAST_STATUS
357 * @CAIRO_CONTENT_COLOR: The surface will hold color content only. (Since 1.0)
358 * @CAIRO_CONTENT_ALPHA: The surface will hold alpha content only. (Since 1.0)
359 * @CAIRO_CONTENT_COLOR_ALPHA: The surface will hold color and alpha content. (Since 1.0)
361 * #cairo_content_t is used to describe the content that a surface will
362 * contain, whether color information, alpha information (translucence
363 * vs. opacity), or both.
365 * Note: The large values here are designed to keep #cairo_content_t
366 * values distinct from #cairo_format_t values so that the
367 * implementation can detect the error if users confuse the two types.
371 typedef enum _cairo_content {
372 CAIRO_CONTENT_COLOR = 0x1000,
373 CAIRO_CONTENT_ALPHA = 0x2000,
374 CAIRO_CONTENT_COLOR_ALPHA = 0x3000
379 * @CAIRO_FORMAT_INVALID: no such format exists or is supported.
380 * @CAIRO_FORMAT_ARGB32: each pixel is a 32-bit quantity, with
381 * alpha in the upper 8 bits, then red, then green, then blue.
382 * The 32-bit quantities are stored native-endian. Pre-multiplied
383 * alpha is used. (That is, 50% transparent red is 0x80800000,
384 * not 0x80ff0000.) (Since 1.0)
385 * @CAIRO_FORMAT_RGB24: each pixel is a 32-bit quantity, with
386 * the upper 8 bits unused. Red, Green, and Blue are stored
387 * in the remaining 24 bits in that order. (Since 1.0)
388 * @CAIRO_FORMAT_A8: each pixel is a 8-bit quantity holding
389 * an alpha value. (Since 1.0)
390 * @CAIRO_FORMAT_A1: each pixel is a 1-bit quantity holding
391 * an alpha value. Pixels are packed together into 32-bit
392 * quantities. The ordering of the bits matches the
393 * endianess of the platform. On a big-endian machine, the
394 * first pixel is in the uppermost bit, on a little-endian
395 * machine the first pixel is in the least-significant bit. (Since 1.0)
396 * @CAIRO_FORMAT_RGB16_565: each pixel is a 16-bit quantity
397 * with red in the upper 5 bits, then green in the middle
398 * 6 bits, and blue in the lower 5 bits. (Since 1.2)
399 * @CAIRO_FORMAT_RGB30: like RGB24 but with 10bpc. (Since 1.12)
401 * #cairo_format_t is used to identify the memory format of
404 * New entries may be added in future versions.
408 typedef enum _cairo_format {
409 CAIRO_FORMAT_INVALID = -1,
410 CAIRO_FORMAT_ARGB32 = 0,
411 CAIRO_FORMAT_RGB24 = 1,
414 CAIRO_FORMAT_RGB16_565 = 4,
415 CAIRO_FORMAT_RGB30 = 5
420 * cairo_write_func_t:
421 * @closure: the output closure
422 * @data: the buffer containing the data to write
423 * @length: the amount of data to write
425 * #cairo_write_func_t is the type of function which is called when a
426 * backend needs to write data to an output stream. It is passed the
427 * closure which was specified by the user at the time the write
428 * function was registered, the data to write and the length of the
429 * data in bytes. The write function should return
430 * %CAIRO_STATUS_SUCCESS if all the data was successfully written,
431 * %CAIRO_STATUS_WRITE_ERROR otherwise.
433 * Returns: the status code of the write operation
437 typedef cairo_status_t (*cairo_write_func_t) (void *closure,
438 const unsigned char *data,
439 unsigned int length);
443 * @closure: the input closure
444 * @data: the buffer into which to read the data
445 * @length: the amount of data to read
447 * #cairo_read_func_t is the type of function which is called when a
448 * backend needs to read data from an input stream. It is passed the
449 * closure which was specified by the user at the time the read
450 * function was registered, the buffer to read the data into and the
451 * length of the data in bytes. The read function should return
452 * %CAIRO_STATUS_SUCCESS if all the data was successfully read,
453 * %CAIRO_STATUS_READ_ERROR otherwise.
455 * Returns: the status code of the read operation
459 typedef cairo_status_t (*cairo_read_func_t) (void *closure,
461 unsigned int length);
464 * cairo_rectangle_int_t:
465 * @x: X coordinate of the left side of the rectangle
466 * @y: Y coordinate of the the top side of the rectangle
467 * @width: width of the rectangle
468 * @height: height of the rectangle
470 * A data structure for holding a rectangle with integer coordinates.
475 typedef struct _cairo_rectangle_int {
478 } cairo_rectangle_int_t;
481 /* Functions for manipulating state objects */
482 cairo_public cairo_t *
483 cairo_create (cairo_surface_t *target);
485 cairo_public cairo_t *
486 cairo_reference (cairo_t *cr);
489 cairo_destroy (cairo_t *cr);
491 cairo_public unsigned int
492 cairo_get_reference_count (cairo_t *cr);
495 cairo_get_user_data (cairo_t *cr,
496 const cairo_user_data_key_t *key);
498 cairo_public cairo_status_t
499 cairo_set_user_data (cairo_t *cr,
500 const cairo_user_data_key_t *key,
502 cairo_destroy_func_t destroy);
505 cairo_save (cairo_t *cr);
508 cairo_restore (cairo_t *cr);
511 cairo_push_group (cairo_t *cr);
514 cairo_push_group_with_content (cairo_t *cr, cairo_content_t content);
516 cairo_public cairo_pattern_t *
517 cairo_pop_group (cairo_t *cr);
520 cairo_pop_group_to_source (cairo_t *cr);
526 * @CAIRO_OPERATOR_CLEAR: clear destination layer (bounded) (Since 1.0)
527 * @CAIRO_OPERATOR_SOURCE: replace destination layer (bounded) (Since 1.0)
528 * @CAIRO_OPERATOR_OVER: draw source layer on top of destination layer
529 * (bounded) (Since 1.0)
530 * @CAIRO_OPERATOR_IN: draw source where there was destination content
531 * (unbounded) (Since 1.0)
532 * @CAIRO_OPERATOR_OUT: draw source where there was no destination
533 * content (unbounded) (Since 1.0)
534 * @CAIRO_OPERATOR_ATOP: draw source on top of destination content and
535 * only there (Since 1.0)
536 * @CAIRO_OPERATOR_DEST: ignore the source (Since 1.0)
537 * @CAIRO_OPERATOR_DEST_OVER: draw destination on top of source (Since 1.0)
538 * @CAIRO_OPERATOR_DEST_IN: leave destination only where there was
539 * source content (unbounded) (Since 1.0)
540 * @CAIRO_OPERATOR_DEST_OUT: leave destination only where there was no
541 * source content (Since 1.0)
542 * @CAIRO_OPERATOR_DEST_ATOP: leave destination on top of source content
543 * and only there (unbounded) (Since 1.0)
544 * @CAIRO_OPERATOR_XOR: source and destination are shown where there is only
545 * one of them (Since 1.0)
546 * @CAIRO_OPERATOR_ADD: source and destination layers are accumulated (Since 1.0)
547 * @CAIRO_OPERATOR_SATURATE: like over, but assuming source and dest are
548 * disjoint geometries (Since 1.0)
549 * @CAIRO_OPERATOR_MULTIPLY: source and destination layers are multiplied.
550 * This causes the result to be at least as dark as the darker inputs. (Since 1.10)
551 * @CAIRO_OPERATOR_SCREEN: source and destination are complemented and
552 * multiplied. This causes the result to be at least as light as the lighter
553 * inputs. (Since 1.10)
554 * @CAIRO_OPERATOR_OVERLAY: multiplies or screens, depending on the
555 * lightness of the destination color. (Since 1.10)
556 * @CAIRO_OPERATOR_DARKEN: replaces the destination with the source if it
557 * is darker, otherwise keeps the source. (Since 1.10)
558 * @CAIRO_OPERATOR_LIGHTEN: replaces the destination with the source if it
559 * is lighter, otherwise keeps the source. (Since 1.10)
560 * @CAIRO_OPERATOR_COLOR_DODGE: brightens the destination color to reflect
561 * the source color. (Since 1.10)
562 * @CAIRO_OPERATOR_COLOR_BURN: darkens the destination color to reflect
563 * the source color. (Since 1.10)
564 * @CAIRO_OPERATOR_HARD_LIGHT: Multiplies or screens, dependent on source
565 * color. (Since 1.10)
566 * @CAIRO_OPERATOR_SOFT_LIGHT: Darkens or lightens, dependent on source
567 * color. (Since 1.10)
568 * @CAIRO_OPERATOR_DIFFERENCE: Takes the difference of the source and
569 * destination color. (Since 1.10)
570 * @CAIRO_OPERATOR_EXCLUSION: Produces an effect similar to difference, but
571 * with lower contrast. (Since 1.10)
572 * @CAIRO_OPERATOR_HSL_HUE: Creates a color with the hue of the source
573 * and the saturation and luminosity of the target. (Since 1.10)
574 * @CAIRO_OPERATOR_HSL_SATURATION: Creates a color with the saturation
575 * of the source and the hue and luminosity of the target. Painting with
576 * this mode onto a gray area produces no change. (Since 1.10)
577 * @CAIRO_OPERATOR_HSL_COLOR: Creates a color with the hue and saturation
578 * of the source and the luminosity of the target. This preserves the gray
579 * levels of the target and is useful for coloring monochrome images or
580 * tinting color images. (Since 1.10)
581 * @CAIRO_OPERATOR_HSL_LUMINOSITY: Creates a color with the luminosity of
582 * the source and the hue and saturation of the target. This produces an
583 * inverse effect to @CAIRO_OPERATOR_HSL_COLOR. (Since 1.10)
585 * #cairo_operator_t is used to set the compositing operator for all cairo
586 * drawing operations.
588 * The default operator is %CAIRO_OPERATOR_OVER.
590 * The operators marked as <firstterm>unbounded</firstterm> modify their
591 * destination even outside of the mask layer (that is, their effect is not
592 * bound by the mask layer). However, their effect can still be limited by
595 * To keep things simple, the operator descriptions here
596 * document the behavior for when both source and destination are either fully
597 * transparent or fully opaque. The actual implementation works for
598 * translucent layers too.
599 * For a more detailed explanation of the effects of each operator, including
600 * the mathematical definitions, see
601 * <ulink url="http://cairographics.org/operators/">http://cairographics.org/operators/</ulink>.
605 typedef enum _cairo_operator {
606 CAIRO_OPERATOR_CLEAR,
608 CAIRO_OPERATOR_SOURCE,
615 CAIRO_OPERATOR_DEST_OVER,
616 CAIRO_OPERATOR_DEST_IN,
617 CAIRO_OPERATOR_DEST_OUT,
618 CAIRO_OPERATOR_DEST_ATOP,
622 CAIRO_OPERATOR_SATURATE,
624 CAIRO_OPERATOR_MULTIPLY,
625 CAIRO_OPERATOR_SCREEN,
626 CAIRO_OPERATOR_OVERLAY,
627 CAIRO_OPERATOR_DARKEN,
628 CAIRO_OPERATOR_LIGHTEN,
629 CAIRO_OPERATOR_COLOR_DODGE,
630 CAIRO_OPERATOR_COLOR_BURN,
631 CAIRO_OPERATOR_HARD_LIGHT,
632 CAIRO_OPERATOR_SOFT_LIGHT,
633 CAIRO_OPERATOR_DIFFERENCE,
634 CAIRO_OPERATOR_EXCLUSION,
635 CAIRO_OPERATOR_HSL_HUE,
636 CAIRO_OPERATOR_HSL_SATURATION,
637 CAIRO_OPERATOR_HSL_COLOR,
638 CAIRO_OPERATOR_HSL_LUMINOSITY
642 cairo_set_operator (cairo_t *cr, cairo_operator_t op);
645 cairo_set_source (cairo_t *cr, cairo_pattern_t *source);
648 cairo_set_source_rgb (cairo_t *cr, double red, double green, double blue);
651 cairo_set_source_rgba (cairo_t *cr,
652 double red, double green, double blue,
656 cairo_set_source_surface (cairo_t *cr,
657 cairo_surface_t *surface,
662 cairo_set_tolerance (cairo_t *cr, double tolerance);
666 * @CAIRO_ANTIALIAS_DEFAULT: Use the default antialiasing for
667 * the subsystem and target device, since 1.0
668 * @CAIRO_ANTIALIAS_NONE: Use a bilevel alpha mask, since 1.0
669 * @CAIRO_ANTIALIAS_GRAY: Perform single-color antialiasing (using
670 * shades of gray for black text on a white background, for example), since 1.0
671 * @CAIRO_ANTIALIAS_SUBPIXEL: Perform antialiasing by taking
672 * advantage of the order of subpixel elements on devices
673 * such as LCD panels, since 1.0
674 * @CAIRO_ANTIALIAS_FAST: Hint that the backend should perform some
675 * antialiasing but prefer speed over quality, since 1.12
676 * @CAIRO_ANTIALIAS_GOOD: The backend should balance quality against
677 * performance, since 1.12
678 * @CAIRO_ANTIALIAS_BEST: Hint that the backend should render at the highest
679 * quality, sacrificing speed if necessary, since 1.12
681 * Specifies the type of antialiasing to do when rendering text or shapes.
683 * As it is not necessarily clear from the above what advantages a particular
684 * antialias method provides, since 1.12, there is also a set of hints:
685 * @CAIRO_ANTIALIAS_FAST: Allow the backend to degrade raster quality for speed
686 * @CAIRO_ANTIALIAS_GOOD: A balance between speed and quality
687 * @CAIRO_ANTIALIAS_BEST: A high-fidelity, but potentially slow, raster mode
689 * These make no guarantee on how the backend will perform its rasterisation
690 * (if it even rasterises!), nor that they have any differing effect other
691 * than to enable some form of antialiasing. In the case of glyph rendering,
692 * @CAIRO_ANTIALIAS_FAST and @CAIRO_ANTIALIAS_GOOD will be mapped to
693 * @CAIRO_ANTIALIAS_GRAY, with @CAIRO_ANTALIAS_BEST being equivalent to
694 * @CAIRO_ANTIALIAS_SUBPIXEL.
696 * The interpretation of @CAIRO_ANTIALIAS_DEFAULT is left entirely up to
697 * the backend, typically this will be similar to @CAIRO_ANTIALIAS_GOOD.
701 typedef enum _cairo_antialias {
702 CAIRO_ANTIALIAS_DEFAULT,
705 CAIRO_ANTIALIAS_NONE,
706 CAIRO_ANTIALIAS_GRAY,
707 CAIRO_ANTIALIAS_SUBPIXEL,
710 CAIRO_ANTIALIAS_FAST,
711 CAIRO_ANTIALIAS_GOOD,
716 cairo_set_antialias (cairo_t *cr, cairo_antialias_t antialias);
720 * @CAIRO_FILL_RULE_WINDING: If the path crosses the ray from
721 * left-to-right, counts +1. If the path crosses the ray
722 * from right to left, counts -1. (Left and right are determined
723 * from the perspective of looking along the ray from the starting
724 * point.) If the total count is non-zero, the point will be filled. (Since 1.0)
725 * @CAIRO_FILL_RULE_EVEN_ODD: Counts the total number of
726 * intersections, without regard to the orientation of the contour. If
727 * the total number of intersections is odd, the point will be
728 * filled. (Since 1.0)
730 * #cairo_fill_rule_t is used to select how paths are filled. For both
731 * fill rules, whether or not a point is included in the fill is
732 * determined by taking a ray from that point to infinity and looking
733 * at intersections with the path. The ray can be in any direction,
734 * as long as it doesn't pass through the end point of a segment
735 * or have a tricky intersection such as intersecting tangent to the path.
736 * (Note that filling is not actually implemented in this way. This
737 * is just a description of the rule that is applied.)
739 * The default fill rule is %CAIRO_FILL_RULE_WINDING.
741 * New entries may be added in future versions.
745 typedef enum _cairo_fill_rule {
746 CAIRO_FILL_RULE_WINDING,
747 CAIRO_FILL_RULE_EVEN_ODD
751 cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule);
754 cairo_set_line_width (cairo_t *cr, double width);
758 * @CAIRO_LINE_CAP_BUTT: start(stop) the line exactly at the start(end) point (Since 1.0)
759 * @CAIRO_LINE_CAP_ROUND: use a round ending, the center of the circle is the end point (Since 1.0)
760 * @CAIRO_LINE_CAP_SQUARE: use squared ending, the center of the square is the end point (Since 1.0)
762 * Specifies how to render the endpoints of the path when stroking.
764 * The default line cap style is %CAIRO_LINE_CAP_BUTT.
768 typedef enum _cairo_line_cap {
770 CAIRO_LINE_CAP_ROUND,
771 CAIRO_LINE_CAP_SQUARE
775 cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap);
779 * @CAIRO_LINE_JOIN_MITER: use a sharp (angled) corner, see
780 * cairo_set_miter_limit() (Since 1.0)
781 * @CAIRO_LINE_JOIN_ROUND: use a rounded join, the center of the circle is the
782 * joint point (Since 1.0)
783 * @CAIRO_LINE_JOIN_BEVEL: use a cut-off join, the join is cut off at half
784 * the line width from the joint point (Since 1.0)
786 * Specifies how to render the junction of two lines when stroking.
788 * The default line join style is %CAIRO_LINE_JOIN_MITER.
792 typedef enum _cairo_line_join {
793 CAIRO_LINE_JOIN_MITER,
794 CAIRO_LINE_JOIN_ROUND,
795 CAIRO_LINE_JOIN_BEVEL
799 cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join);
802 cairo_set_dash (cairo_t *cr,
803 const double *dashes,
808 cairo_set_miter_limit (cairo_t *cr, double limit);
811 cairo_translate (cairo_t *cr, double tx, double ty);
814 cairo_scale (cairo_t *cr, double sx, double sy);
817 cairo_rotate (cairo_t *cr, double angle);
820 cairo_transform (cairo_t *cr,
821 const cairo_matrix_t *matrix);
824 cairo_set_matrix (cairo_t *cr,
825 const cairo_matrix_t *matrix);
828 cairo_identity_matrix (cairo_t *cr);
831 cairo_user_to_device (cairo_t *cr, double *x, double *y);
834 cairo_user_to_device_distance (cairo_t *cr, double *dx, double *dy);
837 cairo_device_to_user (cairo_t *cr, double *x, double *y);
840 cairo_device_to_user_distance (cairo_t *cr, double *dx, double *dy);
842 /* Path creation functions */
844 cairo_new_path (cairo_t *cr);
847 cairo_move_to (cairo_t *cr, double x, double y);
850 cairo_new_sub_path (cairo_t *cr);
853 cairo_line_to (cairo_t *cr, double x, double y);
856 cairo_curve_to (cairo_t *cr,
857 double x1, double y1,
858 double x2, double y2,
859 double x3, double y3);
862 cairo_arc (cairo_t *cr,
863 double xc, double yc,
865 double angle1, double angle2);
868 cairo_arc_negative (cairo_t *cr,
869 double xc, double yc,
871 double angle1, double angle2);
875 cairo_arc_to (cairo_t *cr,
876 double x1, double y1,
877 double x2, double y2,
882 cairo_rel_move_to (cairo_t *cr, double dx, double dy);
885 cairo_rel_line_to (cairo_t *cr, double dx, double dy);
888 cairo_rel_curve_to (cairo_t *cr,
889 double dx1, double dy1,
890 double dx2, double dy2,
891 double dx3, double dy3);
894 cairo_rectangle (cairo_t *cr,
896 double width, double height);
899 cairo_rounded_rectangle (cairo_t *cr,
901 double width, double height,
902 double r_top_left, double r_top_right,
903 double r_bottom_left, double r_bottom_right);
907 cairo_stroke_to_path (cairo_t *cr);
911 cairo_close_path (cairo_t *cr);
914 cairo_path_extents (cairo_t *cr,
915 double *x1, double *y1,
916 double *x2, double *y2);
918 /* Painting functions */
920 cairo_paint (cairo_t *cr);
923 cairo_paint_with_alpha (cairo_t *cr,
927 cairo_mask (cairo_t *cr,
928 cairo_pattern_t *pattern);
931 cairo_mask_surface (cairo_t *cr,
932 cairo_surface_t *surface,
937 cairo_stroke (cairo_t *cr);
940 cairo_stroke_preserve (cairo_t *cr);
943 cairo_fill (cairo_t *cr);
946 cairo_fill_preserve (cairo_t *cr);
949 cairo_copy_page (cairo_t *cr);
952 cairo_show_page (cairo_t *cr);
954 /* Insideness testing */
955 cairo_public cairo_bool_t
956 cairo_in_stroke (cairo_t *cr, double x, double y);
958 cairo_public cairo_bool_t
959 cairo_in_fill (cairo_t *cr, double x, double y);
961 cairo_public cairo_bool_t
962 cairo_in_clip (cairo_t *cr, double x, double y);
964 /* Rectangular extents */
966 cairo_stroke_extents (cairo_t *cr,
967 double *x1, double *y1,
968 double *x2, double *y2);
971 cairo_fill_extents (cairo_t *cr,
972 double *x1, double *y1,
973 double *x2, double *y2);
977 cairo_reset_clip (cairo_t *cr);
980 cairo_clip (cairo_t *cr);
983 cairo_clip_preserve (cairo_t *cr);
986 cairo_clip_extents (cairo_t *cr,
987 double *x1, double *y1,
988 double *x2, double *y2);
992 * @x: X coordinate of the left side of the rectangle
993 * @y: Y coordinate of the the top side of the rectangle
994 * @width: width of the rectangle
995 * @height: height of the rectangle
997 * A data structure for holding a rectangle.
1001 typedef struct _cairo_rectangle {
1002 double x, y, width, height;
1003 } cairo_rectangle_t;
1006 * cairo_rectangle_list_t:
1007 * @status: Error status of the rectangle list
1008 * @rectangles: Array containing the rectangles
1009 * @num_rectangles: Number of rectangles in this list
1011 * A data structure for holding a dynamically allocated
1012 * array of rectangles.
1016 typedef struct _cairo_rectangle_list {
1017 cairo_status_t status;
1018 cairo_rectangle_t *rectangles;
1020 } cairo_rectangle_list_t;
1022 cairo_public cairo_rectangle_list_t *
1023 cairo_copy_clip_rectangle_list (cairo_t *cr);
1026 cairo_rectangle_list_destroy (cairo_rectangle_list_t *rectangle_list);
1028 /* Font/Text functions */
1031 * cairo_scaled_font_t:
1033 * A #cairo_scaled_font_t is a font scaled to a particular size and device
1034 * resolution. A #cairo_scaled_font_t is most useful for low-level font
1035 * usage where a library or application wants to cache a reference
1036 * to a scaled font to speed up the computation of metrics.
1038 * There are various types of scaled fonts, depending on the
1039 * <firstterm>font backend</firstterm> they use. The type of a
1040 * scaled font can be queried using cairo_scaled_font_get_type().
1042 * Memory management of #cairo_scaled_font_t is done with
1043 * cairo_scaled_font_reference() and cairo_scaled_font_destroy().
1047 typedef struct _cairo_scaled_font cairo_scaled_font_t;
1050 * cairo_font_face_t:
1052 * A #cairo_font_face_t specifies all aspects of a font other
1053 * than the size or font matrix (a font matrix is used to distort
1054 * a font by sheering it or scaling it unequally in the two
1055 * directions) . A font face can be set on a #cairo_t by using
1056 * cairo_set_font_face(); the size and font matrix are set with
1057 * cairo_set_font_size() and cairo_set_font_matrix().
1059 * There are various types of font faces, depending on the
1060 * <firstterm>font backend</firstterm> they use. The type of a
1061 * font face can be queried using cairo_font_face_get_type().
1063 * Memory management of #cairo_font_face_t is done with
1064 * cairo_font_face_reference() and cairo_font_face_destroy().
1068 typedef struct _cairo_font_face cairo_font_face_t;
1072 * @index: glyph index in the font. The exact interpretation of the
1073 * glyph index depends on the font technology being used.
1074 * @x: the offset in the X direction between the origin used for
1075 * drawing or measuring the string and the origin of this glyph.
1076 * @y: the offset in the Y direction between the origin used for
1077 * drawing or measuring the string and the origin of this glyph.
1079 * The #cairo_glyph_t structure holds information about a single glyph
1080 * when drawing or measuring text. A font is (in simple terms) a
1081 * collection of shapes used to draw text. A glyph is one of these
1082 * shapes. There can be multiple glyphs for a single character
1083 * (alternates to be used in different contexts, for example), or a
1084 * glyph can be a <firstterm>ligature</firstterm> of multiple
1085 * characters. Cairo doesn't expose any way of converting input text
1086 * into glyphs, so in order to use the Cairo interfaces that take
1087 * arrays of glyphs, you must directly access the appropriate
1088 * underlying font system.
1090 * Note that the offsets given by @x and @y are not cumulative. When
1091 * drawing or measuring text, each glyph is individually positioned
1092 * with respect to the overall origin
1097 unsigned long index;
1102 cairo_public cairo_glyph_t *
1103 cairo_glyph_allocate (int num_glyphs);
1106 cairo_glyph_free (cairo_glyph_t *glyphs);
1109 * cairo_text_cluster_t:
1110 * @num_bytes: the number of bytes of UTF-8 text covered by cluster
1111 * @num_glyphs: the number of glyphs covered by cluster
1113 * The #cairo_text_cluster_t structure holds information about a single
1114 * <firstterm>text cluster</firstterm>. A text cluster is a minimal
1115 * mapping of some glyphs corresponding to some UTF-8 text.
1117 * For a cluster to be valid, both @num_bytes and @num_glyphs should
1118 * be non-negative, and at least one should be non-zero.
1119 * Note that clusters with zero glyphs are not as well supported as
1120 * normal clusters. For example, PDF rendering applications typically
1121 * ignore those clusters when PDF text is being selected.
1123 * See cairo_show_text_glyphs() for how clusters are used in advanced
1131 } cairo_text_cluster_t;
1133 cairo_public cairo_text_cluster_t *
1134 cairo_text_cluster_allocate (int num_clusters);
1137 cairo_text_cluster_free (cairo_text_cluster_t *clusters);
1140 * cairo_text_cluster_flags_t:
1141 * @CAIRO_TEXT_CLUSTER_FLAG_BACKWARD: The clusters in the cluster array
1142 * map to glyphs in the glyph array from end to start. (Since 1.8)
1144 * Specifies properties of a text cluster mapping.
1148 typedef enum _cairo_text_cluster_flags {
1149 CAIRO_TEXT_CLUSTER_FLAG_BACKWARD = 0x00000001
1150 } cairo_text_cluster_flags_t;
1153 * cairo_text_extents_t:
1154 * @x_bearing: the horizontal distance from the origin to the
1155 * leftmost part of the glyphs as drawn. Positive if the
1156 * glyphs lie entirely to the right of the origin.
1157 * @y_bearing: the vertical distance from the origin to the
1158 * topmost part of the glyphs as drawn. Positive only if the
1159 * glyphs lie completely below the origin; will usually be
1161 * @width: width of the glyphs as drawn
1162 * @height: height of the glyphs as drawn
1163 * @x_advance:distance to advance in the X direction
1164 * after drawing these glyphs
1165 * @y_advance: distance to advance in the Y direction
1166 * after drawing these glyphs. Will typically be zero except
1167 * for vertical text layout as found in East-Asian languages.
1169 * The #cairo_text_extents_t structure stores the extents of a single
1170 * glyph or a string of glyphs in user-space coordinates. Because text
1171 * extents are in user-space coordinates, they are mostly, but not
1172 * entirely, independent of the current transformation matrix. If you call
1173 * <literal>cairo_scale(cr, 2.0, 2.0)</literal>, text will
1174 * be drawn twice as big, but the reported text extents will not be
1175 * doubled. They will change slightly due to hinting (so you can't
1176 * assume that metrics are independent of the transformation matrix),
1177 * but otherwise will remain unchanged.
1188 } cairo_text_extents_t;
1191 * cairo_font_extents_t:
1192 * @ascent: the distance that the font extends above the baseline.
1193 * Note that this is not always exactly equal to the maximum
1194 * of the extents of all the glyphs in the font, but rather
1195 * is picked to express the font designer's intent as to
1196 * how the font should align with elements above it.
1197 * @descent: the distance that the font extends below the baseline.
1198 * This value is positive for typical fonts that include
1199 * portions below the baseline. Note that this is not always
1200 * exactly equal to the maximum of the extents of all the
1201 * glyphs in the font, but rather is picked to express the
1202 * font designer's intent as to how the font should
1203 * align with elements below it.
1204 * @height: the recommended vertical distance between baselines when
1205 * setting consecutive lines of text with the font. This
1206 * is greater than @ascent+@descent by a
1207 * quantity known as the <firstterm>line spacing</firstterm>
1208 * or <firstterm>external leading</firstterm>. When space
1209 * is at a premium, most fonts can be set with only
1210 * a distance of @ascent+@descent between lines.
1211 * @max_x_advance: the maximum distance in the X direction that
1212 * the origin is advanced for any glyph in the font.
1213 * @max_y_advance: the maximum distance in the Y direction that
1214 * the origin is advanced for any glyph in the font.
1215 * This will be zero for normal fonts used for horizontal
1216 * writing. (The scripts of East Asia are sometimes written
1219 * The #cairo_font_extents_t structure stores metric information for
1220 * a font. Values are given in the current user-space coordinate
1223 * Because font metrics are in user-space coordinates, they are
1224 * mostly, but not entirely, independent of the current transformation
1225 * matrix. If you call <literal>cairo_scale(cr, 2.0, 2.0)</literal>,
1226 * text will be drawn twice as big, but the reported text extents will
1227 * not be doubled. They will change slightly due to hinting (so you
1228 * can't assume that metrics are independent of the transformation
1229 * matrix), but otherwise will remain unchanged.
1237 double max_x_advance;
1238 double max_y_advance;
1239 } cairo_font_extents_t;
1242 * cairo_font_slant_t:
1243 * @CAIRO_FONT_SLANT_NORMAL: Upright font style, since 1.0
1244 * @CAIRO_FONT_SLANT_ITALIC: Italic font style, since 1.0
1245 * @CAIRO_FONT_SLANT_OBLIQUE: Oblique font style, since 1.0
1247 * Specifies variants of a font face based on their slant.
1251 typedef enum _cairo_font_slant {
1252 CAIRO_FONT_SLANT_NORMAL,
1253 CAIRO_FONT_SLANT_ITALIC,
1254 CAIRO_FONT_SLANT_OBLIQUE
1255 } cairo_font_slant_t;
1258 * cairo_font_weight_t:
1259 * @CAIRO_FONT_WEIGHT_NORMAL: Normal font weight, since 1.0
1260 * @CAIRO_FONT_WEIGHT_BOLD: Bold font weight, since 1.0
1262 * Specifies variants of a font face based on their weight.
1266 typedef enum _cairo_font_weight {
1267 CAIRO_FONT_WEIGHT_NORMAL,
1268 CAIRO_FONT_WEIGHT_BOLD
1269 } cairo_font_weight_t;
1272 * cairo_subpixel_order_t:
1273 * @CAIRO_SUBPIXEL_ORDER_DEFAULT: Use the default subpixel order for
1274 * for the target device, since 1.0
1275 * @CAIRO_SUBPIXEL_ORDER_RGB: Subpixel elements are arranged horizontally
1276 * with red at the left, since 1.0
1277 * @CAIRO_SUBPIXEL_ORDER_BGR: Subpixel elements are arranged horizontally
1278 * with blue at the left, since 1.0
1279 * @CAIRO_SUBPIXEL_ORDER_VRGB: Subpixel elements are arranged vertically
1280 * with red at the top, since 1.0
1281 * @CAIRO_SUBPIXEL_ORDER_VBGR: Subpixel elements are arranged vertically
1282 * with blue at the top, since 1.0
1284 * The subpixel order specifies the order of color elements within
1285 * each pixel on the display device when rendering with an
1286 * antialiasing mode of %CAIRO_ANTIALIAS_SUBPIXEL.
1290 typedef enum _cairo_subpixel_order {
1291 CAIRO_SUBPIXEL_ORDER_DEFAULT,
1292 CAIRO_SUBPIXEL_ORDER_RGB,
1293 CAIRO_SUBPIXEL_ORDER_BGR,
1294 CAIRO_SUBPIXEL_ORDER_VRGB,
1295 CAIRO_SUBPIXEL_ORDER_VBGR
1296 } cairo_subpixel_order_t;
1299 * cairo_hint_style_t:
1300 * @CAIRO_HINT_STYLE_DEFAULT: Use the default hint style for
1301 * font backend and target device, since 1.0
1302 * @CAIRO_HINT_STYLE_NONE: Do not hint outlines, since 1.0
1303 * @CAIRO_HINT_STYLE_SLIGHT: Hint outlines slightly to improve
1304 * contrast while retaining good fidelity to the original
1306 * @CAIRO_HINT_STYLE_MEDIUM: Hint outlines with medium strength
1307 * giving a compromise between fidelity to the original shapes
1308 * and contrast, since 1.0
1309 * @CAIRO_HINT_STYLE_FULL: Hint outlines to maximize contrast, since 1.0
1311 * Specifies the type of hinting to do on font outlines. Hinting
1312 * is the process of fitting outlines to the pixel grid in order
1313 * to improve the appearance of the result. Since hinting outlines
1314 * involves distorting them, it also reduces the faithfulness
1315 * to the original outline shapes. Not all of the outline hinting
1316 * styles are supported by all font backends.
1318 * New entries may be added in future versions.
1322 typedef enum _cairo_hint_style {
1323 CAIRO_HINT_STYLE_DEFAULT,
1324 CAIRO_HINT_STYLE_NONE,
1325 CAIRO_HINT_STYLE_SLIGHT,
1326 CAIRO_HINT_STYLE_MEDIUM,
1327 CAIRO_HINT_STYLE_FULL
1328 } cairo_hint_style_t;
1331 * cairo_hint_metrics_t:
1332 * @CAIRO_HINT_METRICS_DEFAULT: Hint metrics in the default
1333 * manner for the font backend and target device, since 1.0
1334 * @CAIRO_HINT_METRICS_OFF: Do not hint font metrics, since 1.0
1335 * @CAIRO_HINT_METRICS_ON: Hint font metrics, since 1.0
1337 * Specifies whether to hint font metrics; hinting font metrics
1338 * means quantizing them so that they are integer values in
1339 * device space. Doing this improves the consistency of
1340 * letter and line spacing, however it also means that text
1341 * will be laid out differently at different zoom factors.
1345 typedef enum _cairo_hint_metrics {
1346 CAIRO_HINT_METRICS_DEFAULT,
1347 CAIRO_HINT_METRICS_OFF,
1348 CAIRO_HINT_METRICS_ON
1349 } cairo_hint_metrics_t;
1352 * cairo_font_color_t:
1353 * @CAIRO_FONT_COLOR_DEFAULT: default color, if the font has color,
1354 * use font's color, otherwise, use user specified, since 1.12.14
1355 * @CAIRO_FONT_COLOR_USER: always uses user's color, since 1.0
1357 * When rendering text, specifies whether to use user's color set
1358 * by cairo_set_source_XXXX() or use glyph's builtin color
1362 typedef enum _cairo_font_color {
1363 CAIRO_FONT_COLOR_DEFAULT,
1364 CAIRO_FONT_COLOR_USER
1365 } cairo_font_color_t;
1368 * cairo_font_options_t:
1370 * An opaque structure holding all options that are used when
1373 * Individual features of a #cairo_font_options_t can be set or
1374 * accessed using functions named
1375 * <function>cairo_font_options_set_<emphasis>feature_name</emphasis>()</function> and
1376 * <function>cairo_font_options_get_<emphasis>feature_name</emphasis>()</function>, like
1377 * cairo_font_options_set_antialias() and
1378 * cairo_font_options_get_antialias().
1380 * New features may be added to a #cairo_font_options_t in the
1381 * future. For this reason, cairo_font_options_copy(),
1382 * cairo_font_options_equal(), cairo_font_options_merge(), and
1383 * cairo_font_options_hash() should be used to copy, check
1384 * for equality, merge, or compute a hash value of
1385 * #cairo_font_options_t objects.
1389 typedef struct _cairo_font_options cairo_font_options_t;
1391 cairo_public cairo_font_options_t *
1392 cairo_font_options_create (void);
1394 cairo_public cairo_font_options_t *
1395 cairo_font_options_copy (const cairo_font_options_t *original);
1398 cairo_font_options_destroy (cairo_font_options_t *options);
1400 cairo_public cairo_status_t
1401 cairo_font_options_status (cairo_font_options_t *options);
1404 cairo_font_options_merge (cairo_font_options_t *options,
1405 const cairo_font_options_t *other);
1406 cairo_public cairo_bool_t
1407 cairo_font_options_equal (const cairo_font_options_t *options,
1408 const cairo_font_options_t *other);
1410 cairo_public unsigned long
1411 cairo_font_options_hash (const cairo_font_options_t *options);
1414 cairo_font_options_set_antialias (cairo_font_options_t *options,
1415 cairo_antialias_t antialias);
1416 cairo_public cairo_antialias_t
1417 cairo_font_options_get_antialias (const cairo_font_options_t *options);
1420 cairo_font_options_set_subpixel_order (cairo_font_options_t *options,
1421 cairo_subpixel_order_t subpixel_order);
1422 cairo_public cairo_subpixel_order_t
1423 cairo_font_options_get_subpixel_order (const cairo_font_options_t *options);
1426 cairo_font_options_set_hint_style (cairo_font_options_t *options,
1427 cairo_hint_style_t hint_style);
1428 cairo_public cairo_hint_style_t
1429 cairo_font_options_get_hint_style (const cairo_font_options_t *options);
1432 cairo_font_options_set_hint_metrics (cairo_font_options_t *options,
1433 cairo_hint_metrics_t hint_metrics);
1434 cairo_public cairo_hint_metrics_t
1435 cairo_font_options_get_hint_metrics (const cairo_font_options_t *options);
1438 cairo_font_options_set_font_color (cairo_font_options_t *options,
1439 cairo_font_color_t font_color);
1440 cairo_public cairo_font_color_t
1441 cairo_font_options_get_font_color (const cairo_font_options_t *options);
1443 /* This interface is for dealing with text as text, not caring about the
1444 font object inside the the cairo_t. */
1447 cairo_select_font_face (cairo_t *cr,
1449 cairo_font_slant_t slant,
1450 cairo_font_weight_t weight);
1453 cairo_set_font_size (cairo_t *cr, double size);
1456 cairo_set_font_matrix (cairo_t *cr,
1457 const cairo_matrix_t *matrix);
1460 cairo_get_font_matrix (cairo_t *cr,
1461 cairo_matrix_t *matrix);
1464 cairo_set_font_options (cairo_t *cr,
1465 const cairo_font_options_t *options);
1468 cairo_get_font_options (cairo_t *cr,
1469 cairo_font_options_t *options);
1472 cairo_set_font_face (cairo_t *cr, cairo_font_face_t *font_face);
1474 cairo_public cairo_font_face_t *
1475 cairo_get_font_face (cairo_t *cr);
1478 cairo_set_scaled_font (cairo_t *cr,
1479 const cairo_scaled_font_t *scaled_font);
1481 cairo_public cairo_scaled_font_t *
1482 cairo_get_scaled_font (cairo_t *cr);
1485 cairo_show_text (cairo_t *cr, const char *utf8);
1488 cairo_show_glyphs (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs);
1491 cairo_show_text_glyphs (cairo_t *cr,
1494 const cairo_glyph_t *glyphs,
1496 const cairo_text_cluster_t *clusters,
1498 cairo_text_cluster_flags_t cluster_flags);
1501 cairo_text_path (cairo_t *cr, const char *utf8);
1504 cairo_glyph_path (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs);
1507 cairo_text_extents (cairo_t *cr,
1509 cairo_text_extents_t *extents);
1512 cairo_glyph_extents (cairo_t *cr,
1513 const cairo_glyph_t *glyphs,
1515 cairo_text_extents_t *extents);
1518 cairo_font_extents (cairo_t *cr,
1519 cairo_font_extents_t *extents);
1521 /* Generic identifier for a font style */
1523 cairo_public cairo_font_face_t *
1524 cairo_font_face_reference (cairo_font_face_t *font_face);
1527 cairo_font_face_destroy (cairo_font_face_t *font_face);
1529 cairo_public unsigned int
1530 cairo_font_face_get_reference_count (cairo_font_face_t *font_face);
1532 cairo_public cairo_status_t
1533 cairo_font_face_status (cairo_font_face_t *font_face);
1537 * cairo_font_type_t:
1538 * @CAIRO_FONT_TYPE_TOY: The font was created using cairo's toy font api (Since: 1.2)
1539 * @CAIRO_FONT_TYPE_FT: The font is of type FreeType (Since: 1.2)
1540 * @CAIRO_FONT_TYPE_WIN32: The font is of type Win32 (Since: 1.2)
1541 * @CAIRO_FONT_TYPE_QUARTZ: The font is of type Quartz (Since: 1.6, in 1.2 and
1542 * 1.4 it was named CAIRO_FONT_TYPE_ATSUI)
1543 * @CAIRO_FONT_TYPE_USER: The font was create using cairo's user font api (Since: 1.8)
1545 * #cairo_font_type_t is used to describe the type of a given font
1546 * face or scaled font. The font types are also known as "font
1547 * backends" within cairo.
1549 * The type of a font face is determined by the function used to
1550 * create it, which will generally be of the form
1551 * <function>cairo_<emphasis>type</emphasis>_font_face_create(<!-- -->)</function>.
1552 * The font face type can be queried with cairo_font_face_get_type()
1554 * The various #cairo_font_face_t functions can be used with a font face
1557 * The type of a scaled font is determined by the type of the font
1558 * face passed to cairo_scaled_font_create(). The scaled font type can
1559 * be queried with cairo_scaled_font_get_type()
1561 * The various #cairo_scaled_font_t functions can be used with scaled
1562 * fonts of any type, but some font backends also provide
1563 * type-specific functions that must only be called with a scaled font
1564 * of the appropriate type. These functions have names that begin with
1565 * <function>cairo_<emphasis>type</emphasis>_scaled_font(<!-- -->)</function>
1566 * such as cairo_ft_scaled_font_lock_face().
1568 * The behavior of calling a type-specific function with a scaled font
1569 * of the wrong type is undefined.
1571 * New entries may be added in future versions.
1575 typedef enum _cairo_font_type {
1576 CAIRO_FONT_TYPE_TOY,
1578 CAIRO_FONT_TYPE_WIN32,
1579 CAIRO_FONT_TYPE_QUARTZ,
1580 CAIRO_FONT_TYPE_USER
1581 } cairo_font_type_t;
1583 cairo_public cairo_font_type_t
1584 cairo_font_face_get_type (cairo_font_face_t *font_face);
1587 cairo_font_face_get_user_data (cairo_font_face_t *font_face,
1588 const cairo_user_data_key_t *key);
1590 cairo_public cairo_status_t
1591 cairo_font_face_set_user_data (cairo_font_face_t *font_face,
1592 const cairo_user_data_key_t *key,
1594 cairo_destroy_func_t destroy);
1596 /* Portable interface to general font features. */
1598 cairo_public cairo_scaled_font_t *
1599 cairo_scaled_font_create (cairo_font_face_t *font_face,
1600 const cairo_matrix_t *font_matrix,
1601 const cairo_matrix_t *ctm,
1602 const cairo_font_options_t *options);
1604 cairo_public cairo_scaled_font_t *
1605 cairo_scaled_font_reference (cairo_scaled_font_t *scaled_font);
1608 cairo_scaled_font_destroy (cairo_scaled_font_t *scaled_font);
1610 cairo_public unsigned int
1611 cairo_scaled_font_get_reference_count (cairo_scaled_font_t *scaled_font);
1613 cairo_public cairo_status_t
1614 cairo_scaled_font_status (cairo_scaled_font_t *scaled_font);
1616 cairo_public cairo_font_type_t
1617 cairo_scaled_font_get_type (cairo_scaled_font_t *scaled_font);
1620 cairo_scaled_font_get_user_data (cairo_scaled_font_t *scaled_font,
1621 const cairo_user_data_key_t *key);
1623 cairo_public cairo_status_t
1624 cairo_scaled_font_set_user_data (cairo_scaled_font_t *scaled_font,
1625 const cairo_user_data_key_t *key,
1627 cairo_destroy_func_t destroy);
1630 cairo_scaled_font_extents (cairo_scaled_font_t *scaled_font,
1631 cairo_font_extents_t *extents);
1634 cairo_scaled_font_text_extents (cairo_scaled_font_t *scaled_font,
1636 cairo_text_extents_t *extents);
1639 cairo_scaled_font_glyph_extents (cairo_scaled_font_t *scaled_font,
1640 const cairo_glyph_t *glyphs,
1642 cairo_text_extents_t *extents);
1644 cairo_public cairo_status_t
1645 cairo_scaled_font_text_to_glyphs (cairo_scaled_font_t *scaled_font,
1650 cairo_glyph_t **glyphs,
1652 cairo_text_cluster_t **clusters,
1654 cairo_text_cluster_flags_t *cluster_flags);
1656 cairo_public cairo_font_face_t *
1657 cairo_scaled_font_get_font_face (cairo_scaled_font_t *scaled_font);
1660 cairo_scaled_font_get_font_matrix (cairo_scaled_font_t *scaled_font,
1661 cairo_matrix_t *font_matrix);
1664 cairo_scaled_font_get_ctm (cairo_scaled_font_t *scaled_font,
1665 cairo_matrix_t *ctm);
1668 cairo_scaled_font_get_scale_matrix (cairo_scaled_font_t *scaled_font,
1669 cairo_matrix_t *scale_matrix);
1672 cairo_scaled_font_get_font_options (cairo_scaled_font_t *scaled_font,
1673 cairo_font_options_t *options);
1678 cairo_public cairo_font_face_t *
1679 cairo_toy_font_face_create (const char *family,
1680 cairo_font_slant_t slant,
1681 cairo_font_weight_t weight);
1683 cairo_public const char *
1684 cairo_toy_font_face_get_family (cairo_font_face_t *font_face);
1686 cairo_public cairo_font_slant_t
1687 cairo_toy_font_face_get_slant (cairo_font_face_t *font_face);
1689 cairo_public cairo_font_weight_t
1690 cairo_toy_font_face_get_weight (cairo_font_face_t *font_face);
1695 cairo_public cairo_font_face_t *
1696 cairo_user_font_face_create (void);
1698 /* User-font method signatures */
1701 * cairo_user_scaled_font_init_func_t:
1702 * @scaled_font: the scaled-font being created
1703 * @cr: a cairo context, in font space
1704 * @extents: font extents to fill in, in font space
1706 * #cairo_user_scaled_font_init_func_t is the type of function which is
1707 * called when a scaled-font needs to be created for a user font-face.
1709 * The cairo context @cr is not used by the caller, but is prepared in font
1710 * space, similar to what the cairo contexts passed to the render_glyph
1711 * method will look like. The callback can use this context for extents
1712 * computation for example. After the callback is called, @cr is checked
1713 * for any error status.
1715 * The @extents argument is where the user font sets the font extents for
1716 * @scaled_font. It is in font space, which means that for most cases its
1717 * ascent and descent members should add to 1.0. @extents is preset to
1718 * hold a value of 1.0 for ascent, height, and max_x_advance, and 0.0 for
1719 * descent and max_y_advance members.
1721 * The callback is optional. If not set, default font extents as described
1722 * in the previous paragraph will be used.
1724 * Note that @scaled_font is not fully initialized at this
1725 * point and trying to use it for text operations in the callback will result
1728 * Returns: %CAIRO_STATUS_SUCCESS upon success, or an error status on error.
1732 typedef cairo_status_t (*cairo_user_scaled_font_init_func_t) (cairo_scaled_font_t *scaled_font,
1734 cairo_font_extents_t *extents);
1737 * cairo_user_scaled_font_render_glyph_func_t:
1738 * @scaled_font: user scaled-font
1739 * @glyph: glyph code to render
1740 * @cr: cairo context to draw to, in font space
1741 * @extents: glyph extents to fill in, in font space
1743 * #cairo_user_scaled_font_render_glyph_func_t is the type of function which
1744 * is called when a user scaled-font needs to render a glyph.
1746 * The callback is mandatory, and expected to draw the glyph with code @glyph to
1747 * the cairo context @cr. @cr is prepared such that the glyph drawing is done in
1748 * font space. That is, the matrix set on @cr is the scale matrix of @scaled_font,
1749 * The @extents argument is where the user font sets the font extents for
1750 * @scaled_font. However, if user prefers to draw in user space, they can
1751 * achieve that by changing the matrix on @cr. All cairo rendering operations
1752 * to @cr are permitted, however, the result is undefined if any source other
1753 * than the default source on @cr is used. That means, glyph bitmaps should
1754 * be rendered using cairo_mask() instead of cairo_paint().
1756 * Other non-default settings on @cr include a font size of 1.0 (given that
1757 * it is set up to be in font space), and font options corresponding to
1760 * The @extents argument is preset to have <literal>x_bearing</literal>,
1761 * <literal>width</literal>, and <literal>y_advance</literal> of zero,
1762 * <literal>y_bearing</literal> set to <literal>-font_extents.ascent</literal>,
1763 * <literal>height</literal> to <literal>font_extents.ascent+font_extents.descent</literal>,
1764 * and <literal>x_advance</literal> to <literal>font_extents.max_x_advance</literal>.
1765 * The only field user needs to set in majority of cases is
1766 * <literal>x_advance</literal>.
1767 * If the <literal>width</literal> field is zero upon the callback returning
1768 * (which is its preset value), the glyph extents are automatically computed
1769 * based on the drawings done to @cr. This is in most cases exactly what the
1770 * desired behavior is. However, if for any reason the callback sets the
1771 * extents, it must be ink extents, and include the extents of all drawing
1772 * done to @cr in the callback.
1774 * Returns: %CAIRO_STATUS_SUCCESS upon success, or
1775 * %CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
1779 typedef cairo_status_t (*cairo_user_scaled_font_render_glyph_func_t) (cairo_scaled_font_t *scaled_font,
1780 unsigned long glyph,
1782 cairo_text_extents_t *extents);
1785 * cairo_user_scaled_font_text_to_glyphs_func_t:
1786 * @scaled_font: the scaled-font being created
1787 * @utf8: a string of text encoded in UTF-8
1788 * @utf8_len: length of @utf8 in bytes
1789 * @glyphs: pointer to array of glyphs to fill, in font space
1790 * @num_glyphs: pointer to number of glyphs
1791 * @clusters: pointer to array of cluster mapping information to fill, or %NULL
1792 * @num_clusters: pointer to number of clusters
1793 * @cluster_flags: pointer to location to store cluster flags corresponding to the
1796 * #cairo_user_scaled_font_text_to_glyphs_func_t is the type of function which
1797 * is called to convert input text to an array of glyphs. This is used by the
1798 * cairo_show_text() operation.
1800 * Using this callback the user-font has full control on glyphs and their
1801 * positions. That means, it allows for features like ligatures and kerning,
1802 * as well as complex <firstterm>shaping</firstterm> required for scripts like
1805 * The @num_glyphs argument is preset to the number of glyph entries available
1806 * in the @glyphs buffer. If the @glyphs buffer is %NULL, the value of
1807 * @num_glyphs will be zero. If the provided glyph array is too short for
1808 * the conversion (or for convenience), a new glyph array may be allocated
1809 * using cairo_glyph_allocate() and placed in @glyphs. Upon return,
1810 * @num_glyphs should contain the number of generated glyphs. If the value
1811 * @glyphs points at has changed after the call, the caller will free the
1812 * allocated glyph array using cairo_glyph_free(). The caller will also free
1813 * the original value of @glyphs, so the callback shouldn't do so.
1814 * The callback should populate the glyph indices and positions (in font space)
1815 * assuming that the text is to be shown at the origin.
1817 * If @clusters is not %NULL, @num_clusters and @cluster_flags are also
1818 * non-%NULL, and cluster mapping should be computed. The semantics of how
1819 * cluster array allocation works is similar to the glyph array. That is,
1820 * if @clusters initially points to a non-%NULL value, that array may be used
1821 * as a cluster buffer, and @num_clusters points to the number of cluster
1822 * entries available there. If the provided cluster array is too short for
1823 * the conversion (or for convenience), a new cluster array may be allocated
1824 * using cairo_text_cluster_allocate() and placed in @clusters. In this case,
1825 * the original value of @clusters will still be freed by the caller. Upon
1826 * return, @num_clusters should contain the number of generated clusters.
1827 * If the value @clusters points at has changed after the call, the caller
1828 * will free the allocated cluster array using cairo_text_cluster_free().
1830 * The callback is optional. If @num_glyphs is negative upon
1831 * the callback returning or if the return value
1832 * is %CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED, the unicode_to_glyph callback
1833 * is tried. See #cairo_user_scaled_font_unicode_to_glyph_func_t.
1835 * Note: While cairo does not impose any limitation on glyph indices,
1836 * some applications may assume that a glyph index fits in a 16-bit
1837 * unsigned integer. As such, it is advised that user-fonts keep their
1838 * glyphs in the 0 to 65535 range. Furthermore, some applications may
1839 * assume that glyph 0 is a special glyph-not-found glyph. User-fonts
1840 * are advised to use glyph 0 for such purposes and do not use that
1841 * glyph value for other purposes.
1843 * Returns: %CAIRO_STATUS_SUCCESS upon success,
1844 * %CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED if fallback options should be tried,
1845 * or %CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
1849 typedef cairo_status_t (*cairo_user_scaled_font_text_to_glyphs_func_t) (cairo_scaled_font_t *scaled_font,
1852 cairo_glyph_t **glyphs,
1854 cairo_text_cluster_t **clusters,
1856 cairo_text_cluster_flags_t *cluster_flags);
1859 * cairo_user_scaled_font_unicode_to_glyph_func_t:
1860 * @scaled_font: the scaled-font being created
1861 * @unicode: input unicode character code-point
1862 * @glyph_index: output glyph index
1864 * #cairo_user_scaled_font_unicode_to_glyph_func_t is the type of function which
1865 * is called to convert an input Unicode character to a single glyph.
1866 * This is used by the cairo_show_text() operation.
1868 * This callback is used to provide the same functionality as the
1869 * text_to_glyphs callback does (see #cairo_user_scaled_font_text_to_glyphs_func_t)
1870 * but has much less control on the output,
1871 * in exchange for increased ease of use. The inherent assumption to using
1872 * this callback is that each character maps to one glyph, and that the
1873 * mapping is context independent. It also assumes that glyphs are positioned
1874 * according to their advance width. These mean no ligatures, kerning, or
1875 * complex scripts can be implemented using this callback.
1877 * The callback is optional, and only used if text_to_glyphs callback is not
1878 * set or fails to return glyphs. If this callback is not set or if it returns
1879 * %CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED, an identity mapping from Unicode
1880 * code-points to glyph indices is assumed.
1882 * Note: While cairo does not impose any limitation on glyph indices,
1883 * some applications may assume that a glyph index fits in a 16-bit
1884 * unsigned integer. As such, it is advised that user-fonts keep their
1885 * glyphs in the 0 to 65535 range. Furthermore, some applications may
1886 * assume that glyph 0 is a special glyph-not-found glyph. User-fonts
1887 * are advised to use glyph 0 for such purposes and do not use that
1888 * glyph value for other purposes.
1890 * Returns: %CAIRO_STATUS_SUCCESS upon success,
1891 * %CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED if fallback options should be tried,
1892 * or %CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
1896 typedef cairo_status_t (*cairo_user_scaled_font_unicode_to_glyph_func_t) (cairo_scaled_font_t *scaled_font,
1897 unsigned long unicode,
1898 unsigned long *glyph_index);
1900 /* User-font method setters */
1903 cairo_user_font_face_set_init_func (cairo_font_face_t *font_face,
1904 cairo_user_scaled_font_init_func_t init_func);
1907 cairo_user_font_face_set_render_glyph_func (cairo_font_face_t *font_face,
1908 cairo_user_scaled_font_render_glyph_func_t render_glyph_func);
1911 cairo_user_font_face_set_text_to_glyphs_func (cairo_font_face_t *font_face,
1912 cairo_user_scaled_font_text_to_glyphs_func_t text_to_glyphs_func);
1915 cairo_user_font_face_set_unicode_to_glyph_func (cairo_font_face_t *font_face,
1916 cairo_user_scaled_font_unicode_to_glyph_func_t unicode_to_glyph_func);
1918 /* User-font method getters */
1920 cairo_public cairo_user_scaled_font_init_func_t
1921 cairo_user_font_face_get_init_func (cairo_font_face_t *font_face);
1923 cairo_public cairo_user_scaled_font_render_glyph_func_t
1924 cairo_user_font_face_get_render_glyph_func (cairo_font_face_t *font_face);
1926 cairo_public cairo_user_scaled_font_text_to_glyphs_func_t
1927 cairo_user_font_face_get_text_to_glyphs_func (cairo_font_face_t *font_face);
1929 cairo_public cairo_user_scaled_font_unicode_to_glyph_func_t
1930 cairo_user_font_face_get_unicode_to_glyph_func (cairo_font_face_t *font_face);
1933 /* Query functions */
1935 cairo_public cairo_operator_t
1936 cairo_get_operator (cairo_t *cr);
1938 cairo_public cairo_pattern_t *
1939 cairo_get_source (cairo_t *cr);
1942 cairo_get_tolerance (cairo_t *cr);
1944 cairo_public cairo_antialias_t
1945 cairo_get_antialias (cairo_t *cr);
1947 cairo_public cairo_bool_t
1948 cairo_has_current_point (cairo_t *cr);
1951 cairo_get_current_point (cairo_t *cr, double *x, double *y);
1953 cairo_public cairo_fill_rule_t
1954 cairo_get_fill_rule (cairo_t *cr);
1957 cairo_get_line_width (cairo_t *cr);
1959 cairo_public cairo_line_cap_t
1960 cairo_get_line_cap (cairo_t *cr);
1962 cairo_public cairo_line_join_t
1963 cairo_get_line_join (cairo_t *cr);
1966 cairo_get_miter_limit (cairo_t *cr);
1969 cairo_get_dash_count (cairo_t *cr);
1972 cairo_get_dash (cairo_t *cr, double *dashes, double *offset);
1975 cairo_get_matrix (cairo_t *cr, cairo_matrix_t *matrix);
1977 cairo_public cairo_surface_t *
1978 cairo_get_target (cairo_t *cr);
1980 cairo_public cairo_surface_t *
1981 cairo_get_group_target (cairo_t *cr);
1984 * cairo_path_data_type_t:
1985 * @CAIRO_PATH_MOVE_TO: A move-to operation, since 1.0
1986 * @CAIRO_PATH_LINE_TO: A line-to operation, since 1.0
1987 * @CAIRO_PATH_CURVE_TO: A curve-to operation, since 1.0
1988 * @CAIRO_PATH_CLOSE_PATH: A close-path operation, since 1.0
1990 * #cairo_path_data_t is used to describe the type of one portion
1991 * of a path when represented as a #cairo_path_t.
1992 * See #cairo_path_data_t for details.
1996 typedef enum _cairo_path_data_type {
1999 CAIRO_PATH_CURVE_TO,
2000 CAIRO_PATH_CLOSE_PATH
2001 } cairo_path_data_type_t;
2004 * cairo_path_data_t:
2006 * #cairo_path_data_t is used to represent the path data inside a
2009 * The data structure is designed to try to balance the demands of
2010 * efficiency and ease-of-use. A path is represented as an array of
2011 * #cairo_path_data_t, which is a union of headers and points.
2013 * Each portion of the path is represented by one or more elements in
2014 * the array, (one header followed by 0 or more points). The length
2015 * value of the header is the number of array elements for the current
2016 * portion including the header, (ie. length == 1 + # of points), and
2017 * where the number of points for each element type is as follows:
2020 * %CAIRO_PATH_MOVE_TO: 1 point
2021 * %CAIRO_PATH_LINE_TO: 1 point
2022 * %CAIRO_PATH_CURVE_TO: 3 points
2023 * %CAIRO_PATH_CLOSE_PATH: 0 points
2026 * The semantics and ordering of the coordinate values are consistent
2027 * with cairo_move_to(), cairo_line_to(), cairo_curve_to(), and
2028 * cairo_close_path().
2030 * Here is sample code for iterating through a #cairo_path_t:
2032 * <informalexample><programlisting>
2034 * cairo_path_t *path;
2035 * cairo_path_data_t *data;
2037 * path = cairo_copy_path (cr);
2039 * for (i=0; i < path->num_data; i += path->data[i].header.length) {
2040 * data = &path->data[i];
2041 * switch (data->header.type) {
2042 * case CAIRO_PATH_MOVE_TO:
2043 * do_move_to_things (data[1].point.x, data[1].point.y);
2045 * case CAIRO_PATH_LINE_TO:
2046 * do_line_to_things (data[1].point.x, data[1].point.y);
2048 * case CAIRO_PATH_CURVE_TO:
2049 * do_curve_to_things (data[1].point.x, data[1].point.y,
2050 * data[2].point.x, data[2].point.y,
2051 * data[3].point.x, data[3].point.y);
2053 * case CAIRO_PATH_CLOSE_PATH:
2054 * do_close_path_things ();
2058 * cairo_path_destroy (path);
2059 * </programlisting></informalexample>
2061 * As of cairo 1.4, cairo does not mind if there are more elements in
2062 * a portion of the path than needed. Such elements can be used by
2063 * users of the cairo API to hold extra values in the path data
2064 * structure. For this reason, it is recommended that applications
2065 * always use <literal>data->header.length</literal> to
2066 * iterate over the path data, instead of hardcoding the number of
2067 * elements for each element type.
2071 typedef union _cairo_path_data_t cairo_path_data_t;
2072 union _cairo_path_data_t {
2074 cairo_path_data_type_t type;
2084 * @status: the current error status
2085 * @data: the elements in the path
2086 * @num_data: the number of elements in the data array
2088 * A data structure for holding a path. This data structure serves as
2089 * the return value for cairo_copy_path() and
2090 * cairo_copy_path_flat() as well the input value for
2091 * cairo_append_path().
2093 * See #cairo_path_data_t for hints on how to iterate over the
2094 * actual data within the path.
2096 * The num_data member gives the number of elements in the data
2097 * array. This number is larger than the number of independent path
2098 * portions (defined in #cairo_path_data_type_t), since the data
2099 * includes both headers and coordinates for each portion.
2103 typedef struct cairo_path {
2104 cairo_status_t status;
2105 cairo_path_data_t *data;
2107 unsigned int is_convex : 1;
2110 cairo_public cairo_path_t *
2111 cairo_copy_path (cairo_t *cr);
2113 cairo_public cairo_path_t *
2114 cairo_copy_path_flat (cairo_t *cr);
2117 cairo_append_path (cairo_t *cr,
2118 const cairo_path_t *path);
2121 cairo_path_destroy (cairo_path_t *path);
2123 /* Error status queries */
2125 cairo_public cairo_status_t
2126 cairo_status (cairo_t *cr);
2128 cairo_public const char *
2129 cairo_status_to_string (cairo_status_t status);
2131 /* Backend device manipulation */
2133 cairo_public cairo_device_t *
2134 cairo_device_reference (cairo_device_t *device);
2137 * cairo_device_type_t:
2138 * @CAIRO_DEVICE_TYPE_DRM: The device is of type Direct Render Manager, since 1.10
2139 * @CAIRO_DEVICE_TYPE_GL: The device is of type OpenGL, since 1.10
2140 * @CAIRO_DEVICE_TYPE_SCRIPT: The device is of type script, since 1.10
2141 * @CAIRO_DEVICE_TYPE_XCB: The device is of type xcb, since 1.10
2142 * @CAIRO_DEVICE_TYPE_XLIB: The device is of type xlib, since 1.10
2143 * @CAIRO_DEVICE_TYPE_XML: The device is of type XML, since 1.10
2144 * @CAIRO_DEVICE_TYPE_COGL: The device is of type cogl, since 1.12
2145 * @CAIRO_DEVICE_TYPE_WIN32: The device is of type win32, since 1.12
2146 * @CAIRO_DEVICE_TYPE_INVALID: The device is invalid, since 1.10
2148 * #cairo_device_type_t is used to describe the type of a given
2149 * device. The devices types are also known as "backends" within cairo.
2151 * The device type can be queried with cairo_device_get_type()
2153 * The various #cairo_device_t functions can be used with devices of
2154 * any type, but some backends also provide type-specific functions
2155 * that must only be called with a device of the appropriate
2156 * type. These functions have names that begin with
2157 * <literal>cairo_<emphasis>type</emphasis>_device</literal> such as
2158 * cairo_xcb_device_debug_cap_xrender_version().
2160 * The behavior of calling a type-specific function with a device of
2161 * the wrong type is undefined.
2163 * New entries may be added in future versions.
2167 typedef enum _cairo_device_type {
2168 CAIRO_DEVICE_TYPE_DRM,
2169 CAIRO_DEVICE_TYPE_GL,
2170 CAIRO_DEVICE_TYPE_SCRIPT,
2171 CAIRO_DEVICE_TYPE_XCB,
2172 CAIRO_DEVICE_TYPE_XLIB,
2173 CAIRO_DEVICE_TYPE_XML,
2174 CAIRO_DEVICE_TYPE_COGL,
2175 CAIRO_DEVICE_TYPE_WIN32,
2177 CAIRO_DEVICE_TYPE_INVALID = -1
2178 } cairo_device_type_t;
2180 cairo_public cairo_device_type_t
2181 cairo_device_get_type (cairo_device_t *device);
2183 cairo_public cairo_status_t
2184 cairo_device_status (cairo_device_t *device);
2186 cairo_public cairo_status_t
2187 cairo_device_acquire (cairo_device_t *device);
2190 cairo_device_release (cairo_device_t *device);
2193 cairo_device_flush (cairo_device_t *device);
2196 cairo_device_finish (cairo_device_t *device);
2199 cairo_device_destroy (cairo_device_t *device);
2201 cairo_public unsigned int
2202 cairo_device_get_reference_count (cairo_device_t *device);
2205 cairo_device_get_user_data (cairo_device_t *device,
2206 const cairo_user_data_key_t *key);
2208 cairo_public cairo_status_t
2209 cairo_device_set_user_data (cairo_device_t *device,
2210 const cairo_user_data_key_t *key,
2212 cairo_destroy_func_t destroy);
2215 /* Surface manipulation */
2217 cairo_public cairo_surface_t *
2218 cairo_surface_create_similar (cairo_surface_t *other,
2219 cairo_content_t content,
2223 cairo_public cairo_surface_t *
2224 cairo_surface_create_similar_image (cairo_surface_t *other,
2225 cairo_format_t format,
2229 cairo_public cairo_surface_t *
2230 cairo_surface_map_to_image (cairo_surface_t *surface,
2231 const cairo_rectangle_int_t *extents);
2234 cairo_surface_unmap_image (cairo_surface_t *surface,
2235 cairo_surface_t *image);
2237 cairo_public cairo_surface_t *
2238 cairo_surface_create_for_rectangle (cairo_surface_t *target,
2245 * cairo_surface_observer_mode_t:
2246 * @CAIRO_SURFACE_OBSERVER_NORMAL: no recording is done
2247 * @CAIRO_SURFACE_OBSERVER_RECORD_OPERATIONS: operations are recorded
2249 * Whether operations should be recorded.
2254 CAIRO_SURFACE_OBSERVER_NORMAL = 0,
2255 CAIRO_SURFACE_OBSERVER_RECORD_OPERATIONS = 0x1
2256 } cairo_surface_observer_mode_t;
2258 cairo_public cairo_surface_t *
2259 cairo_surface_create_observer (cairo_surface_t *target,
2260 cairo_surface_observer_mode_t mode);
2262 typedef void (*cairo_surface_observer_callback_t) (cairo_surface_t *observer,
2263 cairo_surface_t *target,
2266 cairo_public cairo_status_t
2267 cairo_surface_observer_add_paint_callback (cairo_surface_t *abstract_surface,
2268 cairo_surface_observer_callback_t func,
2271 cairo_public cairo_status_t
2272 cairo_surface_observer_add_mask_callback (cairo_surface_t *abstract_surface,
2273 cairo_surface_observer_callback_t func,
2276 cairo_public cairo_status_t
2277 cairo_surface_observer_add_fill_callback (cairo_surface_t *abstract_surface,
2278 cairo_surface_observer_callback_t func,
2281 cairo_public cairo_status_t
2282 cairo_surface_observer_add_stroke_callback (cairo_surface_t *abstract_surface,
2283 cairo_surface_observer_callback_t func,
2286 cairo_public cairo_status_t
2287 cairo_surface_observer_add_glyphs_callback (cairo_surface_t *abstract_surface,
2288 cairo_surface_observer_callback_t func,
2291 cairo_public cairo_status_t
2292 cairo_surface_observer_add_flush_callback (cairo_surface_t *abstract_surface,
2293 cairo_surface_observer_callback_t func,
2296 cairo_public cairo_status_t
2297 cairo_surface_observer_add_finish_callback (cairo_surface_t *abstract_surface,
2298 cairo_surface_observer_callback_t func,
2301 cairo_public cairo_status_t
2302 cairo_surface_observer_print (cairo_surface_t *surface,
2303 cairo_write_func_t write_func,
2306 cairo_surface_observer_elapsed (cairo_surface_t *surface);
2308 cairo_public cairo_status_t
2309 cairo_device_observer_print (cairo_device_t *device,
2310 cairo_write_func_t write_func,
2314 cairo_device_observer_elapsed (cairo_device_t *device);
2317 cairo_device_observer_paint_elapsed (cairo_device_t *device);
2320 cairo_device_observer_mask_elapsed (cairo_device_t *device);
2323 cairo_device_observer_fill_elapsed (cairo_device_t *device);
2326 cairo_device_observer_stroke_elapsed (cairo_device_t *device);
2329 cairo_device_observer_glyphs_elapsed (cairo_device_t *device);
2331 cairo_public cairo_surface_t *
2332 cairo_surface_reference (cairo_surface_t *surface);
2335 cairo_surface_finish (cairo_surface_t *surface);
2338 cairo_surface_destroy (cairo_surface_t *surface);
2340 cairo_public cairo_device_t *
2341 cairo_surface_get_device (cairo_surface_t *surface);
2343 cairo_public unsigned int
2344 cairo_surface_get_reference_count (cairo_surface_t *surface);
2346 cairo_public cairo_status_t
2347 cairo_surface_status (cairo_surface_t *surface);
2350 * cairo_surface_type_t:
2351 * @CAIRO_SURFACE_TYPE_IMAGE: The surface is of type image, since 1.2
2352 * @CAIRO_SURFACE_TYPE_PDF: The surface is of type pdf, since 1.2
2353 * @CAIRO_SURFACE_TYPE_PS: The surface is of type ps, since 1.2
2354 * @CAIRO_SURFACE_TYPE_XLIB: The surface is of type xlib, since 1.2
2355 * @CAIRO_SURFACE_TYPE_XCB: The surface is of type xcb, since 1.2
2356 * @CAIRO_SURFACE_TYPE_GLITZ: The surface is of type glitz, since 1.2
2357 * @CAIRO_SURFACE_TYPE_QUARTZ: The surface is of type quartz, since 1.2
2358 * @CAIRO_SURFACE_TYPE_WIN32: The surface is of type win32, since 1.2
2359 * @CAIRO_SURFACE_TYPE_BEOS: The surface is of type beos, since 1.2
2360 * @CAIRO_SURFACE_TYPE_DIRECTFB: The surface is of type directfb, since 1.2
2361 * @CAIRO_SURFACE_TYPE_SVG: The surface is of type svg, since 1.2
2362 * @CAIRO_SURFACE_TYPE_OS2: The surface is of type os2, since 1.4
2363 * @CAIRO_SURFACE_TYPE_WIN32_PRINTING: The surface is a win32 printing surface, since 1.6
2364 * @CAIRO_SURFACE_TYPE_QUARTZ_IMAGE: The surface is of type quartz_image, since 1.6
2365 * @CAIRO_SURFACE_TYPE_SCRIPT: The surface is of type script, since 1.10
2366 * @CAIRO_SURFACE_TYPE_QT: The surface is of type Qt, since 1.10
2367 * @CAIRO_SURFACE_TYPE_RECORDING: The surface is of type recording, since 1.10
2368 * @CAIRO_SURFACE_TYPE_VG: The surface is a OpenVG surface, since 1.10
2369 * @CAIRO_SURFACE_TYPE_GL: The surface is of type OpenGL, since 1.10
2370 * @CAIRO_SURFACE_TYPE_DRM: The surface is of type Direct Render Manager, since 1.10
2371 * @CAIRO_SURFACE_TYPE_TEE: The surface is of type 'tee' (a multiplexing surface), since 1.10
2372 * @CAIRO_SURFACE_TYPE_XML: The surface is of type XML (for debugging), since 1.10
2373 * @CAIRO_SURFACE_TYPE_SKIA: The surface is of type Skia, since 1.10
2374 * @CAIRO_SURFACE_TYPE_SUBSURFACE: The surface is a subsurface created with
2375 * cairo_surface_create_for_rectangle(), since 1.10
2376 * @CAIRO_SURFACE_TYPE_COGL: This surface is of type Cogl, since 1.12
2378 * #cairo_surface_type_t is used to describe the type of a given
2379 * surface. The surface types are also known as "backends" or "surface
2380 * backends" within cairo.
2382 * The type of a surface is determined by the function used to create
2383 * it, which will generally be of the form
2384 * <function>cairo_<emphasis>type</emphasis>_surface_create(<!-- -->)</function>,
2385 * (though see cairo_surface_create_similar() as well).
2387 * The surface type can be queried with cairo_surface_get_type()
2389 * The various #cairo_surface_t functions can be used with surfaces of
2390 * any type, but some backends also provide type-specific functions
2391 * that must only be called with a surface of the appropriate
2392 * type. These functions have names that begin with
2393 * <literal>cairo_<emphasis>type</emphasis>_surface</literal> such as cairo_image_surface_get_width().
2395 * The behavior of calling a type-specific function with a surface of
2396 * the wrong type is undefined.
2398 * New entries may be added in future versions.
2402 typedef enum _cairo_surface_type {
2403 CAIRO_SURFACE_TYPE_IMAGE,
2404 CAIRO_SURFACE_TYPE_PDF,
2405 CAIRO_SURFACE_TYPE_PS,
2406 CAIRO_SURFACE_TYPE_XLIB,
2407 CAIRO_SURFACE_TYPE_XCB,
2408 CAIRO_SURFACE_TYPE_GLITZ,
2409 CAIRO_SURFACE_TYPE_QUARTZ,
2410 CAIRO_SURFACE_TYPE_WIN32,
2411 CAIRO_SURFACE_TYPE_BEOS,
2412 CAIRO_SURFACE_TYPE_DIRECTFB,
2413 CAIRO_SURFACE_TYPE_SVG,
2414 CAIRO_SURFACE_TYPE_OS2,
2415 CAIRO_SURFACE_TYPE_WIN32_PRINTING,
2416 CAIRO_SURFACE_TYPE_QUARTZ_IMAGE,
2417 CAIRO_SURFACE_TYPE_SCRIPT,
2418 CAIRO_SURFACE_TYPE_QT,
2419 CAIRO_SURFACE_TYPE_RECORDING,
2420 CAIRO_SURFACE_TYPE_VG,
2421 CAIRO_SURFACE_TYPE_GL,
2422 CAIRO_SURFACE_TYPE_DRM,
2423 CAIRO_SURFACE_TYPE_TEE,
2424 CAIRO_SURFACE_TYPE_XML,
2425 CAIRO_SURFACE_TYPE_SKIA,
2426 CAIRO_SURFACE_TYPE_SUBSURFACE,
2427 CAIRO_SURFACE_TYPE_COGL
2428 } cairo_surface_type_t;
2430 cairo_public cairo_surface_type_t
2431 cairo_surface_get_type (cairo_surface_t *surface);
2433 cairo_public cairo_content_t
2434 cairo_surface_get_content (cairo_surface_t *surface);
2436 #if CAIRO_HAS_PNG_FUNCTIONS
2438 cairo_public cairo_status_t
2439 cairo_surface_write_to_png (cairo_surface_t *surface,
2440 const char *filename);
2442 cairo_public cairo_status_t
2443 cairo_surface_write_to_png_stream (cairo_surface_t *surface,
2444 cairo_write_func_t write_func,
2450 cairo_surface_get_user_data (cairo_surface_t *surface,
2451 const cairo_user_data_key_t *key);
2453 cairo_public cairo_status_t
2454 cairo_surface_set_user_data (cairo_surface_t *surface,
2455 const cairo_user_data_key_t *key,
2457 cairo_destroy_func_t destroy);
2459 #define CAIRO_MIME_TYPE_JPEG "image/jpeg"
2460 #define CAIRO_MIME_TYPE_PNG "image/png"
2461 #define CAIRO_MIME_TYPE_JP2 "image/jp2"
2462 #define CAIRO_MIME_TYPE_URI "text/x-uri"
2463 #define CAIRO_MIME_TYPE_UNIQUE_ID "application/x-cairo.uuid"
2464 #define CAIRO_MIME_TYPE_JBIG2 "application/x-cairo.jbig2"
2465 #define CAIRO_MIME_TYPE_JBIG2_GLOBAL "application/x-cairo.jbig2-global"
2466 #define CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID "application/x-cairo.jbig2-global-id"
2469 cairo_surface_get_mime_data (cairo_surface_t *surface,
2470 const char *mime_type,
2471 const unsigned char **data,
2472 unsigned long *length);
2474 cairo_public cairo_status_t
2475 cairo_surface_set_mime_data (cairo_surface_t *surface,
2476 const char *mime_type,
2477 const unsigned char *data,
2478 unsigned long length,
2479 cairo_destroy_func_t destroy,
2482 cairo_public cairo_bool_t
2483 cairo_surface_supports_mime_type (cairo_surface_t *surface,
2484 const char *mime_type);
2487 cairo_surface_get_font_options (cairo_surface_t *surface,
2488 cairo_font_options_t *options);
2491 cairo_surface_flush (cairo_surface_t *surface);
2494 cairo_surface_mark_dirty (cairo_surface_t *surface);
2497 cairo_surface_mark_dirty_rectangle (cairo_surface_t *surface,
2504 cairo_surface_set_device_scale (cairo_surface_t *surface,
2509 cairo_surface_get_device_scale (cairo_surface_t *surface,
2514 cairo_surface_set_device_offset (cairo_surface_t *surface,
2519 cairo_surface_get_device_offset (cairo_surface_t *surface,
2524 cairo_surface_set_fallback_resolution (cairo_surface_t *surface,
2525 double x_pixels_per_inch,
2526 double y_pixels_per_inch);
2529 cairo_surface_get_fallback_resolution (cairo_surface_t *surface,
2530 double *x_pixels_per_inch,
2531 double *y_pixels_per_inch);
2534 cairo_surface_copy_page (cairo_surface_t *surface);
2537 cairo_surface_show_page (cairo_surface_t *surface);
2539 cairo_public cairo_bool_t
2540 cairo_surface_has_show_text_glyphs (cairo_surface_t *surface);
2542 /* Image-surface functions */
2544 cairo_public cairo_surface_t *
2545 cairo_image_surface_create (cairo_format_t format,
2550 cairo_format_stride_for_width (cairo_format_t format,
2553 cairo_public cairo_surface_t *
2554 cairo_image_surface_create_for_data (unsigned char *data,
2555 cairo_format_t format,
2560 cairo_public unsigned char *
2561 cairo_image_surface_get_data (cairo_surface_t *surface);
2563 cairo_public cairo_format_t
2564 cairo_image_surface_get_format (cairo_surface_t *surface);
2567 cairo_image_surface_get_width (cairo_surface_t *surface);
2570 cairo_image_surface_get_height (cairo_surface_t *surface);
2573 cairo_image_surface_get_stride (cairo_surface_t *surface);
2575 #if CAIRO_HAS_PNG_FUNCTIONS
2577 cairo_public cairo_surface_t *
2578 cairo_image_surface_create_from_png (const char *filename);
2580 cairo_public cairo_surface_t *
2581 cairo_image_surface_create_from_png_stream (cairo_read_func_t read_func,
2586 /* Recording-surface functions */
2588 cairo_public cairo_surface_t *
2589 cairo_recording_surface_create (cairo_content_t content,
2590 const cairo_rectangle_t *extents);
2593 cairo_recording_surface_ink_extents (cairo_surface_t *surface,
2599 cairo_public cairo_bool_t
2600 cairo_recording_surface_get_extents (cairo_surface_t *surface,
2601 cairo_rectangle_t *extents);
2603 /* raster-source pattern (callback) functions */
2606 * cairo_raster_source_acquire_func_t:
2607 * @pattern: the pattern being rendered from
2608 * @callback_data: the user data supplied during creation
2609 * @target: the rendering target surface
2610 * @extents: rectangular region of interest in pixels in sample space
2612 * #cairo_raster_source_acquire_func_t is the type of function which is
2613 * called when a pattern is being rendered from. It should create a surface
2614 * that provides the pixel data for the region of interest as defined by
2615 * extents, though the surface itself does not have to be limited to that
2616 * area. For convenience the surface should probably be of image type,
2617 * created with cairo_surface_create_similar_image() for the target (which
2618 * enables the number of copies to be reduced during transfer to the
2619 * device). Another option, might be to return a similar surface to the
2620 * target for explicit handling by the application of a set of cached sources
2621 * on the device. The region of sample data provided should be defined using
2622 * cairo_surface_set_device_offset() to specify the top-left corner of the
2623 * sample data (along with width and height of the surface).
2625 * Returns: a #cairo_surface_t
2629 typedef cairo_surface_t *
2630 (*cairo_raster_source_acquire_func_t) (cairo_pattern_t *pattern,
2631 void *callback_data,
2632 cairo_surface_t *target,
2633 const cairo_rectangle_int_t *extents);
2636 * cairo_raster_source_release_func_t:
2637 * @pattern: the pattern being rendered from
2638 * @callback_data: the user data supplied during creation
2639 * @surface: the surface created during acquire
2641 * #cairo_raster_source_release_func_t is the type of function which is
2642 * called when the pixel data is no longer being access by the pattern
2643 * for the rendering operation. Typically this function will simply
2644 * destroy the surface created during acquire.
2649 (*cairo_raster_source_release_func_t) (cairo_pattern_t *pattern,
2650 void *callback_data,
2651 cairo_surface_t *surface);
2654 * cairo_raster_source_snapshot_func_t:
2655 * @pattern: the pattern being rendered from
2656 * @callback_data: the user data supplied during creation
2658 * #cairo_raster_source_snapshot_func_t is the type of function which is
2659 * called when the pixel data needs to be preserved for later use
2660 * during printing. This pattern will be accessed again later, and it
2661 * is expected to provide the pixel data that was current at the time
2664 * Return value: CAIRO_STATUS_SUCCESS on success, or one of the
2665 * #cairo_status_t error codes for failure.
2669 typedef cairo_status_t
2670 (*cairo_raster_source_snapshot_func_t) (cairo_pattern_t *pattern,
2671 void *callback_data);
2674 * cairo_raster_source_copy_func_t:
2675 * @pattern: the #cairo_pattern_t that was copied to
2676 * @callback_data: the user data supplied during creation
2677 * @other: the #cairo_pattern_t being used as the source for the copy
2679 * #cairo_raster_source_copy_func_t is the type of function which is
2680 * called when the pattern gets copied as a normal part of rendering.
2682 * Return value: CAIRO_STATUS_SUCCESS on success, or one of the
2683 * #cairo_status_t error codes for failure.
2687 typedef cairo_status_t
2688 (*cairo_raster_source_copy_func_t) (cairo_pattern_t *pattern,
2689 void *callback_data,
2690 const cairo_pattern_t *other);
2693 * cairo_raster_source_finish_func_t:
2694 * @pattern: the pattern being rendered from
2695 * @callback_data: the user data supplied during creation
2697 * #cairo_raster_source_finish_func_t is the type of function which is
2698 * called when the pattern (or a copy thereof) is no longer required.
2703 (*cairo_raster_source_finish_func_t) (cairo_pattern_t *pattern,
2704 void *callback_data);
2706 cairo_public cairo_pattern_t *
2707 cairo_pattern_create_raster_source (void *user_data,
2708 cairo_content_t content,
2709 int width, int height);
2712 cairo_raster_source_pattern_set_callback_data (cairo_pattern_t *pattern,
2716 cairo_raster_source_pattern_get_callback_data (cairo_pattern_t *pattern);
2719 cairo_raster_source_pattern_set_acquire (cairo_pattern_t *pattern,
2720 cairo_raster_source_acquire_func_t acquire,
2721 cairo_raster_source_release_func_t release);
2724 cairo_raster_source_pattern_get_acquire (cairo_pattern_t *pattern,
2725 cairo_raster_source_acquire_func_t *acquire,
2726 cairo_raster_source_release_func_t *release);
2728 cairo_raster_source_pattern_set_snapshot (cairo_pattern_t *pattern,
2729 cairo_raster_source_snapshot_func_t snapshot);
2731 cairo_public cairo_raster_source_snapshot_func_t
2732 cairo_raster_source_pattern_get_snapshot (cairo_pattern_t *pattern);
2735 cairo_raster_source_pattern_set_copy (cairo_pattern_t *pattern,
2736 cairo_raster_source_copy_func_t copy);
2738 cairo_public cairo_raster_source_copy_func_t
2739 cairo_raster_source_pattern_get_copy (cairo_pattern_t *pattern);
2742 cairo_raster_source_pattern_set_finish (cairo_pattern_t *pattern,
2743 cairo_raster_source_finish_func_t finish);
2745 cairo_public cairo_raster_source_finish_func_t
2746 cairo_raster_source_pattern_get_finish (cairo_pattern_t *pattern);
2748 /* Pattern creation functions */
2750 cairo_public cairo_pattern_t *
2751 cairo_pattern_create_rgb (double red, double green, double blue);
2753 cairo_public cairo_pattern_t *
2754 cairo_pattern_create_rgba (double red, double green, double blue,
2757 cairo_public cairo_pattern_t *
2758 cairo_pattern_create_for_surface (cairo_surface_t *surface);
2760 cairo_public cairo_pattern_t *
2761 cairo_pattern_create_linear (double x0, double y0,
2762 double x1, double y1);
2764 cairo_public cairo_pattern_t *
2765 cairo_pattern_create_radial (double cx0, double cy0, double radius0,
2766 double cx1, double cy1, double radius1);
2768 cairo_public cairo_pattern_t *
2769 cairo_pattern_create_mesh (void);
2771 cairo_public cairo_pattern_t *
2772 cairo_pattern_reference (cairo_pattern_t *pattern);
2775 cairo_pattern_destroy (cairo_pattern_t *pattern);
2777 cairo_public unsigned int
2778 cairo_pattern_get_reference_count (cairo_pattern_t *pattern);
2780 cairo_public cairo_status_t
2781 cairo_pattern_status (cairo_pattern_t *pattern);
2784 cairo_pattern_get_user_data (cairo_pattern_t *pattern,
2785 const cairo_user_data_key_t *key);
2787 cairo_public cairo_status_t
2788 cairo_pattern_set_user_data (cairo_pattern_t *pattern,
2789 const cairo_user_data_key_t *key,
2791 cairo_destroy_func_t destroy);
2794 * cairo_pattern_type_t:
2795 * @CAIRO_PATTERN_TYPE_SOLID: The pattern is a solid (uniform)
2796 * color. It may be opaque or translucent, since 1.2.
2797 * @CAIRO_PATTERN_TYPE_SURFACE: The pattern is a based on a surface (an image), since 1.2.
2798 * @CAIRO_PATTERN_TYPE_LINEAR: The pattern is a linear gradient, since 1.2.
2799 * @CAIRO_PATTERN_TYPE_RADIAL: The pattern is a radial gradient, since 1.2.
2800 * @CAIRO_PATTERN_TYPE_MESH: The pattern is a mesh, since 1.12.
2801 * @CAIRO_PATTERN_TYPE_RASTER_SOURCE: The pattern is a user pattern providing raster data, since 1.12.
2803 * #cairo_pattern_type_t is used to describe the type of a given pattern.
2805 * The type of a pattern is determined by the function used to create
2806 * it. The cairo_pattern_create_rgb() and cairo_pattern_create_rgba()
2807 * functions create SOLID patterns. The remaining
2808 * cairo_pattern_create<!-- --> functions map to pattern types in obvious
2811 * The pattern type can be queried with cairo_pattern_get_type()
2813 * Most #cairo_pattern_t functions can be called with a pattern of any
2814 * type, (though trying to change the extend or filter for a solid
2815 * pattern will have no effect). A notable exception is
2816 * cairo_pattern_add_color_stop_rgb() and
2817 * cairo_pattern_add_color_stop_rgba() which must only be called with
2818 * gradient patterns (either LINEAR or RADIAL). Otherwise the pattern
2819 * will be shutdown and put into an error state.
2821 * New entries may be added in future versions.
2825 typedef enum _cairo_pattern_type {
2826 CAIRO_PATTERN_TYPE_SOLID,
2827 CAIRO_PATTERN_TYPE_SURFACE,
2828 CAIRO_PATTERN_TYPE_LINEAR,
2829 CAIRO_PATTERN_TYPE_RADIAL,
2830 CAIRO_PATTERN_TYPE_MESH,
2831 CAIRO_PATTERN_TYPE_RASTER_SOURCE
2832 } cairo_pattern_type_t;
2834 cairo_public cairo_pattern_type_t
2835 cairo_pattern_get_type (cairo_pattern_t *pattern);
2838 cairo_pattern_add_color_stop_rgb (cairo_pattern_t *pattern,
2840 double red, double green, double blue);
2843 cairo_pattern_add_color_stop_rgba (cairo_pattern_t *pattern,
2845 double red, double green, double blue,
2849 cairo_mesh_pattern_begin_patch (cairo_pattern_t *pattern);
2852 cairo_mesh_pattern_end_patch (cairo_pattern_t *pattern);
2855 cairo_mesh_pattern_curve_to (cairo_pattern_t *pattern,
2856 double x1, double y1,
2857 double x2, double y2,
2858 double x3, double y3);
2861 cairo_mesh_pattern_line_to (cairo_pattern_t *pattern,
2862 double x, double y);
2865 cairo_mesh_pattern_move_to (cairo_pattern_t *pattern,
2866 double x, double y);
2869 cairo_mesh_pattern_set_control_point (cairo_pattern_t *pattern,
2870 unsigned int point_num,
2871 double x, double y);
2874 cairo_mesh_pattern_set_corner_color_rgb (cairo_pattern_t *pattern,
2875 unsigned int corner_num,
2876 double red, double green, double blue);
2879 cairo_mesh_pattern_set_corner_color_rgba (cairo_pattern_t *pattern,
2880 unsigned int corner_num,
2881 double red, double green, double blue,
2885 cairo_pattern_set_matrix (cairo_pattern_t *pattern,
2886 const cairo_matrix_t *matrix);
2889 cairo_pattern_get_matrix (cairo_pattern_t *pattern,
2890 cairo_matrix_t *matrix);
2894 * @CAIRO_EXTEND_NONE: pixels outside of the source pattern
2895 * are fully transparent (Since 1.0)
2896 * @CAIRO_EXTEND_REPEAT: the pattern is tiled by repeating (Since 1.0)
2897 * @CAIRO_EXTEND_REFLECT: the pattern is tiled by reflecting
2898 * at the edges (Since 1.0; but only implemented for surface patterns since 1.6)
2899 * @CAIRO_EXTEND_PAD: pixels outside of the pattern copy
2900 * the closest pixel from the source (Since 1.2; but only
2901 * implemented for surface patterns since 1.6)
2903 * #cairo_extend_t is used to describe how pattern color/alpha will be
2904 * determined for areas "outside" the pattern's natural area, (for
2905 * example, outside the surface bounds or outside the gradient
2908 * Mesh patterns are not affected by the extend mode.
2910 * The default extend mode is %CAIRO_EXTEND_NONE for surface patterns
2911 * and %CAIRO_EXTEND_PAD for gradient patterns.
2913 * New entries may be added in future versions.
2917 typedef enum _cairo_extend {
2919 CAIRO_EXTEND_REPEAT,
2920 CAIRO_EXTEND_REFLECT,
2925 cairo_pattern_set_extend (cairo_pattern_t *pattern, cairo_extend_t extend);
2927 cairo_public cairo_extend_t
2928 cairo_pattern_get_extend (cairo_pattern_t *pattern);
2932 * @CAIRO_FILTER_FAST: A high-performance filter, with quality similar
2933 * to %CAIRO_FILTER_NEAREST (Since 1.0)
2934 * @CAIRO_FILTER_GOOD: A reasonable-performance filter, with quality
2935 * similar to %CAIRO_FILTER_BILINEAR (Since 1.0)
2936 * @CAIRO_FILTER_BEST: The highest-quality available, performance may
2937 * not be suitable for interactive use. (Since 1.0)
2938 * @CAIRO_FILTER_NEAREST: Nearest-neighbor filtering (Since 1.0)
2939 * @CAIRO_FILTER_BILINEAR: Linear interpolation in two dimensions (Since 1.0)
2940 * @CAIRO_FILTER_GAUSSIAN: This filter value is currently
2941 * unimplemented, and should not be used in current code. (Since 1.0)
2943 * #cairo_filter_t is used to indicate what filtering should be
2944 * applied when reading pixel values from patterns. See
2945 * cairo_pattern_set_filter() for indicating the desired filter to be
2946 * used with a particular pattern.
2950 typedef enum _cairo_filter {
2954 CAIRO_FILTER_NEAREST,
2955 CAIRO_FILTER_BILINEAR,
2956 CAIRO_FILTER_GAUSSIAN
2960 cairo_pattern_set_filter (cairo_pattern_t *pattern, cairo_filter_t filter);
2962 cairo_public cairo_filter_t
2963 cairo_pattern_get_filter (cairo_pattern_t *pattern);
2965 cairo_public cairo_status_t
2966 cairo_pattern_set_sigma (cairo_pattern_t *pattern,
2967 const double x_sigma,
2968 const double y_sigma);
2970 cairo_public cairo_status_t
2971 cairo_pattern_get_sigma (cairo_pattern_t *pattern,
2976 typedef enum _cairo_shadow_type {
2977 CAIRO_SHADOW_NONE = 0,
2980 } cairo_shadow_type_t;
2983 cairo_set_shadow (cairo_t *cr, cairo_shadow_type_t shadow);
2986 cairo_set_shadow_offset (cairo_t *cr, double x_offset, double y_offset);
2989 cairo_set_shadow_rgb (cairo_t *cr, double red, double green, double blue);
2992 cairo_set_shadow_rgba (cairo_t *cr, double red, double green,
2993 double blue, double alpha);
2996 cairo_set_shadow_blur (cairo_t *cr, double x_blur, double y_blur);
2999 cairo_set_draw_shadow_only (cairo_t *cr, cairo_bool_t draw_shadow_only);
3002 cairo_shadow_enable_cache (cairo_t *cr, cairo_bool_t enable);
3005 cairo_set_path_is_inset_shadow_with_spread (cairo_t *cr,
3006 cairo_bool_t is_spread_path);
3008 cairo_public cairo_status_t
3009 cairo_pattern_get_rgba (cairo_pattern_t *pattern,
3010 double *red, double *green,
3011 double *blue, double *alpha);
3013 cairo_public cairo_status_t
3014 cairo_pattern_get_surface (cairo_pattern_t *pattern,
3015 cairo_surface_t **surface);
3018 cairo_public cairo_status_t
3019 cairo_pattern_get_color_stop_rgba (cairo_pattern_t *pattern,
3020 int index, double *offset,
3021 double *red, double *green,
3022 double *blue, double *alpha);
3024 cairo_public cairo_status_t
3025 cairo_pattern_get_color_stop_count (cairo_pattern_t *pattern,
3028 cairo_public cairo_status_t
3029 cairo_pattern_get_linear_points (cairo_pattern_t *pattern,
3030 double *x0, double *y0,
3031 double *x1, double *y1);
3033 cairo_public cairo_status_t
3034 cairo_pattern_get_radial_circles (cairo_pattern_t *pattern,
3035 double *x0, double *y0, double *r0,
3036 double *x1, double *y1, double *r1);
3038 cairo_public cairo_status_t
3039 cairo_mesh_pattern_get_patch_count (cairo_pattern_t *pattern,
3040 unsigned int *count);
3042 cairo_public cairo_path_t *
3043 cairo_mesh_pattern_get_path (cairo_pattern_t *pattern,
3044 unsigned int patch_num);
3046 cairo_public cairo_status_t
3047 cairo_mesh_pattern_get_corner_color_rgba (cairo_pattern_t *pattern,
3048 unsigned int patch_num,
3049 unsigned int corner_num,
3050 double *red, double *green,
3051 double *blue, double *alpha);
3053 cairo_public cairo_status_t
3054 cairo_mesh_pattern_get_control_point (cairo_pattern_t *pattern,
3055 unsigned int patch_num,
3056 unsigned int point_num,
3057 double *x, double *y);
3059 /* Matrix functions */
3062 cairo_matrix_init (cairo_matrix_t *matrix,
3063 double xx, double yx,
3064 double xy, double yy,
3065 double x0, double y0);
3068 cairo_matrix_init_identity (cairo_matrix_t *matrix);
3071 cairo_matrix_init_translate (cairo_matrix_t *matrix,
3072 double tx, double ty);
3075 cairo_matrix_init_scale (cairo_matrix_t *matrix,
3076 double sx, double sy);
3079 cairo_matrix_init_rotate (cairo_matrix_t *matrix,
3083 cairo_matrix_translate (cairo_matrix_t *matrix, double tx, double ty);
3086 cairo_matrix_scale (cairo_matrix_t *matrix, double sx, double sy);
3089 cairo_matrix_rotate (cairo_matrix_t *matrix, double radians);
3091 cairo_public cairo_status_t
3092 cairo_matrix_invert (cairo_matrix_t *matrix);
3095 cairo_matrix_multiply (cairo_matrix_t *result,
3096 const cairo_matrix_t *a,
3097 const cairo_matrix_t *b);
3100 cairo_matrix_transform_distance (const cairo_matrix_t *matrix,
3101 double *dx, double *dy);
3104 cairo_matrix_transform_point (const cairo_matrix_t *matrix,
3105 double *x, double *y);
3107 /* Region functions */
3112 * A #cairo_region_t represents a set of integer-aligned rectangles.
3114 * It allows set-theoretical operations like cairo_region_union() and
3115 * cairo_region_intersect() to be performed on them.
3117 * Memory management of #cairo_region_t is done with
3118 * cairo_region_reference() and cairo_region_destroy().
3122 typedef struct _cairo_region cairo_region_t;
3125 * cairo_region_overlap_t:
3126 * @CAIRO_REGION_OVERLAP_IN: The contents are entirely inside the region. (Since 1.10)
3127 * @CAIRO_REGION_OVERLAP_OUT: The contents are entirely outside the region. (Since 1.10)
3128 * @CAIRO_REGION_OVERLAP_PART: The contents are partially inside and
3129 * partially outside the region. (Since 1.10)
3131 * Used as the return value for cairo_region_contains_rectangle().
3135 typedef enum _cairo_region_overlap {
3136 CAIRO_REGION_OVERLAP_IN, /* completely inside region */
3137 CAIRO_REGION_OVERLAP_OUT, /* completely outside region */
3138 CAIRO_REGION_OVERLAP_PART /* partly inside region */
3139 } cairo_region_overlap_t;
3141 cairo_public cairo_region_t *
3142 cairo_region_create (void);
3144 cairo_public cairo_region_t *
3145 cairo_region_create_rectangle (const cairo_rectangle_int_t *rectangle);
3147 cairo_public cairo_region_t *
3148 cairo_region_create_rectangles (const cairo_rectangle_int_t *rects,
3151 cairo_public cairo_region_t *
3152 cairo_region_copy (const cairo_region_t *original);
3154 cairo_public cairo_region_t *
3155 cairo_region_reference (cairo_region_t *region);
3158 cairo_region_destroy (cairo_region_t *region);
3160 cairo_public cairo_bool_t
3161 cairo_region_equal (const cairo_region_t *a, const cairo_region_t *b);
3163 cairo_public cairo_status_t
3164 cairo_region_status (const cairo_region_t *region);
3167 cairo_region_get_extents (const cairo_region_t *region,
3168 cairo_rectangle_int_t *extents);
3171 cairo_region_num_rectangles (const cairo_region_t *region);
3174 cairo_region_get_rectangle (const cairo_region_t *region,
3176 cairo_rectangle_int_t *rectangle);
3178 cairo_public cairo_bool_t
3179 cairo_region_is_empty (const cairo_region_t *region);
3181 cairo_public cairo_region_overlap_t
3182 cairo_region_contains_rectangle (const cairo_region_t *region,
3183 const cairo_rectangle_int_t *rectangle);
3185 cairo_public cairo_bool_t
3186 cairo_region_contains_point (const cairo_region_t *region, int x, int y);
3189 cairo_region_translate (cairo_region_t *region, int dx, int dy);
3191 cairo_public cairo_status_t
3192 cairo_region_subtract (cairo_region_t *dst, const cairo_region_t *other);
3194 cairo_public cairo_status_t
3195 cairo_region_subtract_rectangle (cairo_region_t *dst,
3196 const cairo_rectangle_int_t *rectangle);
3198 cairo_public cairo_status_t
3199 cairo_region_intersect (cairo_region_t *dst, const cairo_region_t *other);
3201 cairo_public cairo_status_t
3202 cairo_region_intersect_rectangle (cairo_region_t *dst,
3203 const cairo_rectangle_int_t *rectangle);
3205 cairo_public cairo_status_t
3206 cairo_region_union (cairo_region_t *dst, const cairo_region_t *other);
3208 cairo_public cairo_status_t
3209 cairo_region_union_rectangle (cairo_region_t *dst,
3210 const cairo_rectangle_int_t *rectangle);
3212 cairo_public cairo_status_t
3213 cairo_region_xor (cairo_region_t *dst, const cairo_region_t *other);
3215 cairo_public cairo_status_t
3216 cairo_region_xor_rectangle (cairo_region_t *dst,
3217 const cairo_rectangle_int_t *rectangle);
3219 /* Functions to be used while debugging (not intended for use in production code) */
3221 cairo_debug_reset_static_data (void);
3226 #endif /* CAIRO_H */