1 /* -*- Mode: c; c-basic-offset: 4; indent-tabs-mode: t; tab-width: 8; -*- */
2 /* cairo - a vector graphics library with display and print output
4 * Copyright © 2002 University of Southern California
5 * Copyright © 2005 Red Hat, Inc.
6 * Copyright © 2011 Intel Corporation
8 * This library is free software; you can redistribute it and/or
9 * modify it either under the terms of the GNU Lesser General Public
10 * License version 2.1 as published by the Free Software Foundation
11 * (the "LGPL") or, at your option, under the terms of the Mozilla
12 * Public License Version 1.1 (the "MPL"). If you do not alter this
13 * notice, a recipient may use your version of this file under either
14 * the MPL or the LGPL.
16 * You should have received a copy of the LGPL along with this library
17 * in the file COPYING-LGPL-2.1; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA
19 * You should have received a copy of the MPL along with this library
20 * in the file COPYING-MPL-1.1
22 * The contents of this file are subject to the Mozilla Public License
23 * Version 1.1 (the "License"); you may not use this file except in
24 * compliance with the License. You may obtain a copy of the License at
25 * http://www.mozilla.org/MPL/
27 * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
28 * OF ANY KIND, either express or implied. See the LGPL or the MPL for
29 * the specific language governing rights and limitations.
31 * The Original Code is the cairo graphics library.
33 * The Initial Developer of the Original Code is University of Southern
37 * Carl D. Worth <cworth@cworth.org>
38 * Chris Wilson <chris@chris-wilson.co.uk>
42 #include "cairo-private.h"
44 #include "cairo-backend-private.h"
45 #include "cairo-error-private.h"
46 #include "cairo-path-private.h"
47 #include "cairo-pattern-private.h"
48 #include "cairo-surface-private.h"
49 #include "cairo-surface-backend-private.h"
56 * @Short_Description: The cairo drawing context
57 * @See_Also: #cairo_surface_t
59 * #cairo_t is the main object used when drawing with cairo. To
60 * draw with cairo, you create a #cairo_t, set the target surface,
61 * and drawing options for the #cairo_t, create shapes with
62 * functions like cairo_move_to() and cairo_line_to(), and then
63 * draw shapes with cairo_stroke() or cairo_fill().
65 * #cairo_t<!-- -->'s can be pushed to a stack via cairo_save().
66 * They may then safely be changed, without losing the current state.
67 * Use cairo_restore() to restore to the saved state.
73 * @Short_Description: Rendering text and glyphs
74 * @See_Also: #cairo_font_face_t, #cairo_scaled_font_t, cairo_text_path(),
77 * The functions with <emphasis>text</emphasis> in their name form cairo's
78 * <firstterm>toy</firstterm> text API. The toy API takes UTF-8 encoded
79 * text and is limited in its functionality to rendering simple
80 * left-to-right text with no advanced features. That means for example
81 * that most complex scripts like Hebrew, Arabic, and Indic scripts are
82 * out of question. No kerning or correct positioning of diacritical marks
83 * either. The font selection is pretty limited too and doesn't handle the
84 * case that the selected font does not cover the characters in the text.
85 * This set of functions are really that, a toy text API, for testing and
86 * demonstration purposes. Any serious application should avoid them.
88 * The functions with <emphasis>glyphs</emphasis> in their name form cairo's
89 * <firstterm>low-level</firstterm> text API. The low-level API relies on
90 * the user to convert text to a set of glyph indexes and positions. This
91 * is a very hard problem and is best handled by external libraries, like
92 * the pangocairo that is part of the Pango text layout and rendering library.
93 * Pango is available from <ulink
94 * url="http://www.pango.org/">http://www.pango.org/</ulink>.
98 * SECTION:cairo-transforms
99 * @Title: Transformations
100 * @Short_Description: Manipulating the current transformation matrix
101 * @See_Also: #cairo_matrix_t
103 * The current transformation matrix, <firstterm>ctm</firstterm>, is a
104 * two-dimensional affine transformation that maps all coordinates and other
105 * drawing instruments from the <firstterm>user space</firstterm> into the
106 * surface's canonical coordinate system, also known as the <firstterm>device
110 #define DEFINE_NIL_CONTEXT(status) \
112 CAIRO_REFERENCE_COUNT_INVALID, /* ref_count */ \
113 status, /* status */ \
114 { 0, 0, 0, NULL }, /* user_data */ \
118 static const cairo_t _cairo_nil[] = {
119 DEFINE_NIL_CONTEXT (CAIRO_STATUS_NO_MEMORY),
120 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_RESTORE),
121 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_POP_GROUP),
122 DEFINE_NIL_CONTEXT (CAIRO_STATUS_NO_CURRENT_POINT),
123 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_MATRIX),
124 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_STATUS),
125 DEFINE_NIL_CONTEXT (CAIRO_STATUS_NULL_POINTER),
126 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_STRING),
127 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_PATH_DATA),
128 DEFINE_NIL_CONTEXT (CAIRO_STATUS_READ_ERROR),
129 DEFINE_NIL_CONTEXT (CAIRO_STATUS_WRITE_ERROR),
130 DEFINE_NIL_CONTEXT (CAIRO_STATUS_SURFACE_FINISHED),
131 DEFINE_NIL_CONTEXT (CAIRO_STATUS_SURFACE_TYPE_MISMATCH),
132 DEFINE_NIL_CONTEXT (CAIRO_STATUS_PATTERN_TYPE_MISMATCH),
133 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_CONTENT),
134 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_FORMAT),
135 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_VISUAL),
136 DEFINE_NIL_CONTEXT (CAIRO_STATUS_FILE_NOT_FOUND),
137 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_DASH),
138 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_DSC_COMMENT),
139 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_INDEX),
140 DEFINE_NIL_CONTEXT (CAIRO_STATUS_CLIP_NOT_REPRESENTABLE),
141 DEFINE_NIL_CONTEXT (CAIRO_STATUS_TEMP_FILE_ERROR),
142 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_STRIDE),
143 DEFINE_NIL_CONTEXT (CAIRO_STATUS_FONT_TYPE_MISMATCH),
144 DEFINE_NIL_CONTEXT (CAIRO_STATUS_USER_FONT_IMMUTABLE),
145 DEFINE_NIL_CONTEXT (CAIRO_STATUS_USER_FONT_ERROR),
146 DEFINE_NIL_CONTEXT (CAIRO_STATUS_NEGATIVE_COUNT),
147 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_CLUSTERS),
148 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_SLANT),
149 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_WEIGHT),
150 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_SIZE),
151 DEFINE_NIL_CONTEXT (CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED),
152 DEFINE_NIL_CONTEXT (CAIRO_STATUS_DEVICE_TYPE_MISMATCH),
153 DEFINE_NIL_CONTEXT (CAIRO_STATUS_DEVICE_ERROR),
154 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_MESH_CONSTRUCTION),
155 DEFINE_NIL_CONTEXT (CAIRO_STATUS_DEVICE_FINISHED)
157 COMPILE_TIME_ASSERT (ARRAY_LENGTH (_cairo_nil) == CAIRO_STATUS_LAST_STATUS - 1);
161 * @cr: a cairo context
162 * @status: a status value indicating an error
164 * Atomically sets cr->status to @status and calls _cairo_error;
165 * Does nothing if status is %CAIRO_STATUS_SUCCESS.
167 * All assignments of an error status to cr->status should happen
168 * through _cairo_set_error(). Note that due to the nature of the atomic
169 * operation, it is not safe to call this function on the nil objects.
171 * The purpose of this function is to allow the user to set a
172 * breakpoint in _cairo_error() to generate a stack trace for when the
173 * user causes cairo to detect an error.
176 _cairo_set_error (cairo_t *cr, cairo_status_t status)
178 /* Don't overwrite an existing error. This preserves the first
179 * error, which is the most significant. */
180 _cairo_status_set_error (&cr->status, _cairo_error (status));
184 _cairo_create_in_error (cairo_status_t status)
188 assert (status != CAIRO_STATUS_SUCCESS);
190 cr = (cairo_t *) &_cairo_nil[status - CAIRO_STATUS_NO_MEMORY];
191 assert (status == cr->status);
198 * @target: target surface for the context
200 * Creates a new #cairo_t with all graphics state parameters set to
201 * default values and with @target as a target surface. The target
202 * surface should be constructed with a backend-specific function such
203 * as cairo_image_surface_create() (or any other
204 * <function>cairo_<emphasis>backend</emphasis>_surface_create(<!-- -->)</function>
207 * This function references @target, so you can immediately
208 * call cairo_surface_destroy() on it if you don't need to
209 * maintain a separate reference to it.
211 * Return value: a newly allocated #cairo_t with a reference
212 * count of 1. The initial reference count should be released
213 * with cairo_destroy() when you are done using the #cairo_t.
214 * This function never returns %NULL. If memory cannot be
215 * allocated, a special #cairo_t object will be returned on
216 * which cairo_status() returns %CAIRO_STATUS_NO_MEMORY. If
217 * you attempt to target a surface which does not support
218 * writing (such as #cairo_mime_surface_t) then a
219 * %CAIRO_STATUS_WRITE_ERROR will be raised. You can use this
220 * object normally, but no drawing will be done.
225 cairo_create (cairo_surface_t *target)
227 if (unlikely (target == NULL))
228 return _cairo_create_in_error (_cairo_error (CAIRO_STATUS_NULL_POINTER));
229 if (unlikely (target->status))
230 return _cairo_create_in_error (target->status);
232 if (target->backend->create_context == NULL)
233 return _cairo_create_in_error (_cairo_error (CAIRO_STATUS_WRITE_ERROR));
235 return target->backend->create_context (target);
238 slim_hidden_def (cairo_create);
241 _cairo_init (cairo_t *cr,
242 const cairo_backend_t *backend)
244 CAIRO_REFERENCE_COUNT_INIT (&cr->ref_count, 1);
245 cr->status = CAIRO_STATUS_SUCCESS;
246 _cairo_user_data_array_init (&cr->user_data);
248 cr->backend = backend;
255 * Increases the reference count on @cr by one. This prevents
256 * @cr from being destroyed until a matching call to cairo_destroy()
259 * The number of references to a #cairo_t can be get using
260 * cairo_get_reference_count().
262 * Return value: the referenced #cairo_t.
267 cairo_reference (cairo_t *cr)
269 if (cr == NULL || CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
272 assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&cr->ref_count));
274 _cairo_reference_count_inc (&cr->ref_count);
280 _cairo_fini (cairo_t *cr)
282 _cairo_user_data_array_fini (&cr->user_data);
289 * Decreases the reference count on @cr by one. If the result
290 * is zero, then @cr and all associated resources are freed.
291 * See cairo_reference().
296 cairo_destroy (cairo_t *cr)
298 if (cr == NULL || CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
301 assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&cr->ref_count));
303 if (! _cairo_reference_count_dec_and_test (&cr->ref_count))
306 cr->backend->destroy (cr);
308 slim_hidden_def (cairo_destroy);
311 * cairo_get_user_data:
313 * @key: the address of the #cairo_user_data_key_t the user data was
316 * Return user data previously attached to @cr using the specified
317 * key. If no user data has been attached with the given key this
318 * function returns %NULL.
320 * Return value: the user data previously attached or %NULL.
325 cairo_get_user_data (cairo_t *cr,
326 const cairo_user_data_key_t *key)
328 return _cairo_user_data_array_get_data (&cr->user_data, key);
332 * cairo_set_user_data:
334 * @key: the address of a #cairo_user_data_key_t to attach the user data to
335 * @user_data: the user data to attach to the #cairo_t
336 * @destroy: a #cairo_destroy_func_t which will be called when the
337 * #cairo_t is destroyed or when new user data is attached using the
340 * Attach user data to @cr. To remove user data from a surface,
341 * call this function with the key that was used to set it and %NULL
344 * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a
345 * slot could not be allocated for the user data.
350 cairo_set_user_data (cairo_t *cr,
351 const cairo_user_data_key_t *key,
353 cairo_destroy_func_t destroy)
355 if (CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
358 return _cairo_user_data_array_set_data (&cr->user_data,
359 key, user_data, destroy);
363 * cairo_get_reference_count:
366 * Returns the current reference count of @cr.
368 * Return value: the current reference count of @cr. If the
369 * object is a nil object, 0 will be returned.
374 cairo_get_reference_count (cairo_t *cr)
376 if (cr == NULL || CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
379 return CAIRO_REFERENCE_COUNT_GET_VALUE (&cr->ref_count);
386 * Makes a copy of the current state of @cr and saves it
387 * on an internal stack of saved states for @cr. When
388 * cairo_restore() is called, @cr will be restored to
389 * the saved state. Multiple calls to cairo_save() and
390 * cairo_restore() can be nested; each call to cairo_restore()
391 * restores the state from the matching paired cairo_save().
393 * It isn't necessary to clear all saved states before
394 * a #cairo_t is freed. If the reference count of a #cairo_t
395 * drops to zero in response to a call to cairo_destroy(),
396 * any saved states will be freed along with the #cairo_t.
401 cairo_save (cairo_t *cr)
403 cairo_status_t status;
405 if (unlikely (cr->status))
408 status = cr->backend->save (cr);
409 if (unlikely (status))
410 _cairo_set_error (cr, status);
412 slim_hidden_def(cairo_save);
418 * Restores @cr to the state saved by a preceding call to
419 * cairo_save() and removes that state from the stack of
425 cairo_restore (cairo_t *cr)
427 cairo_status_t status;
429 if (unlikely (cr->status))
432 status = cr->backend->restore (cr);
433 if (unlikely (status))
434 _cairo_set_error (cr, status);
436 slim_hidden_def(cairo_restore);
440 * @cr: a cairo context
442 * Temporarily redirects drawing to an intermediate surface known as a
443 * group. The redirection lasts until the group is completed by a call
444 * to cairo_pop_group() or cairo_pop_group_to_source(). These calls
445 * provide the result of any drawing to the group as a pattern,
446 * (either as an explicit object, or set as the source pattern).
448 * This group functionality can be convenient for performing
449 * intermediate compositing. One common use of a group is to render
450 * objects as opaque within the group, (so that they occlude each
451 * other), and then blend the result with translucence onto the
454 * Groups can be nested arbitrarily deep by making balanced calls to
455 * cairo_push_group()/cairo_pop_group(). Each call pushes/pops the new
456 * target group onto/from a stack.
458 * The cairo_push_group() function calls cairo_save() so that any
459 * changes to the graphics state will not be visible outside the
460 * group, (the pop_group functions call cairo_restore()).
462 * By default the intermediate group will have a content type of
463 * %CAIRO_CONTENT_COLOR_ALPHA. Other content types can be chosen for
464 * the group by using cairo_push_group_with_content() instead.
466 * As an example, here is how one might fill and stroke a path with
467 * translucence, but without any portion of the fill being visible
470 * <informalexample><programlisting>
471 * cairo_push_group (cr);
472 * cairo_set_source (cr, fill_pattern);
473 * cairo_fill_preserve (cr);
474 * cairo_set_source (cr, stroke_pattern);
476 * cairo_pop_group_to_source (cr);
477 * cairo_paint_with_alpha (cr, alpha);
478 * </programlisting></informalexample>
483 cairo_push_group (cairo_t *cr)
485 cairo_push_group_with_content (cr, CAIRO_CONTENT_COLOR_ALPHA);
489 * cairo_push_group_with_content:
490 * @cr: a cairo context
491 * @content: a #cairo_content_t indicating the type of group that
494 * Temporarily redirects drawing to an intermediate surface known as a
495 * group. The redirection lasts until the group is completed by a call
496 * to cairo_pop_group() or cairo_pop_group_to_source(). These calls
497 * provide the result of any drawing to the group as a pattern,
498 * (either as an explicit object, or set as the source pattern).
500 * The group will have a content type of @content. The ability to
501 * control this content type is the only distinction between this
502 * function and cairo_push_group() which you should see for a more
503 * detailed description of group rendering.
508 cairo_push_group_with_content (cairo_t *cr, cairo_content_t content)
510 cairo_status_t status;
512 if (unlikely (cr->status))
515 status = cr->backend->push_group (cr, content);
516 if (unlikely (status))
517 _cairo_set_error (cr, status);
519 slim_hidden_def(cairo_push_group_with_content);
523 * @cr: a cairo context
525 * Terminates the redirection begun by a call to cairo_push_group() or
526 * cairo_push_group_with_content() and returns a new pattern
527 * containing the results of all drawing operations performed to the
530 * The cairo_pop_group() function calls cairo_restore(), (balancing a
531 * call to cairo_save() by the push_group function), so that any
532 * changes to the graphics state will not be visible outside the
535 * Return value: a newly created (surface) pattern containing the
536 * results of all drawing operations performed to the group. The
537 * caller owns the returned object and should call
538 * cairo_pattern_destroy() when finished with it.
543 cairo_pop_group (cairo_t *cr)
545 cairo_pattern_t *group_pattern;
547 if (unlikely (cr->status))
548 return _cairo_pattern_create_in_error (cr->status);
550 group_pattern = cr->backend->pop_group (cr);
551 if (unlikely (group_pattern->status))
552 _cairo_set_error (cr, group_pattern->status);
554 return group_pattern;
556 slim_hidden_def(cairo_pop_group);
559 * cairo_pop_group_to_source:
560 * @cr: a cairo context
562 * Terminates the redirection begun by a call to cairo_push_group() or
563 * cairo_push_group_with_content() and installs the resulting pattern
564 * as the source pattern in the given cairo context.
566 * The behavior of this function is equivalent to the sequence of
569 * <informalexample><programlisting>
570 * cairo_pattern_t *group = cairo_pop_group (cr);
571 * cairo_set_source (cr, group);
572 * cairo_pattern_destroy (group);
573 * </programlisting></informalexample>
575 * but is more convenient as their is no need for a variable to store
576 * the short-lived pointer to the pattern.
578 * The cairo_pop_group() function calls cairo_restore(), (balancing a
579 * call to cairo_save() by the push_group function), so that any
580 * changes to the graphics state will not be visible outside the
586 cairo_pop_group_to_source (cairo_t *cr)
588 cairo_pattern_t *group_pattern;
590 group_pattern = cairo_pop_group (cr);
591 cairo_set_source (cr, group_pattern);
592 cairo_pattern_destroy (group_pattern);
596 * cairo_set_operator:
598 * @op: a compositing operator, specified as a #cairo_operator_t
600 * Sets the compositing operator to be used for all drawing
601 * operations. See #cairo_operator_t for details on the semantics of
602 * each available compositing operator.
604 * The default operator is %CAIRO_OPERATOR_OVER.
609 cairo_set_operator (cairo_t *cr, cairo_operator_t op)
611 cairo_status_t status;
613 if (unlikely (cr->status))
616 status = cr->backend->set_operator (cr, op);
617 if (unlikely (status))
618 _cairo_set_error (cr, status);
620 slim_hidden_def (cairo_set_operator);
627 * @opacity: the level of opacity to use when compositing
629 * Sets the compositing opacity to be used for all drawing
630 * operations. The effect is to fade out the operations
631 * using the alpha value.
633 * The default opacity is 1.
638 cairo_set_opacity (cairo_t *cr, double opacity)
640 cairo_status_t status;
642 if (unlikely (cr->status))
645 status = cr->backend->set_opacity (cr, opacity);
646 if (unlikely (status))
647 _cairo_set_error (cr, status);
652 * cairo_set_source_rgb:
653 * @cr: a cairo context
654 * @red: red component of color
655 * @green: green component of color
656 * @blue: blue component of color
658 * Sets the source pattern within @cr to an opaque color. This opaque
659 * color will then be used for any subsequent drawing operation until
660 * a new source pattern is set.
662 * The color components are floating point numbers in the range 0 to
663 * 1. If the values passed in are outside that range, they will be
666 * The default source pattern is opaque black, (that is, it is
667 * equivalent to cairo_set_source_rgb(cr, 0.0, 0.0, 0.0)).
672 cairo_set_source_rgb (cairo_t *cr, double red, double green, double blue)
674 cairo_status_t status;
676 if (unlikely (cr->status))
679 status = cr->backend->set_source_rgba (cr, red, green, blue, 1.);
680 if (unlikely (status))
681 _cairo_set_error (cr, status);
683 slim_hidden_def (cairo_set_source_rgb);
686 * cairo_set_source_rgba:
687 * @cr: a cairo context
688 * @red: red component of color
689 * @green: green component of color
690 * @blue: blue component of color
691 * @alpha: alpha component of color
693 * Sets the source pattern within @cr to a translucent color. This
694 * color will then be used for any subsequent drawing operation until
695 * a new source pattern is set.
697 * The color and alpha components are floating point numbers in the
698 * range 0 to 1. If the values passed in are outside that range, they
701 * The default source pattern is opaque black, (that is, it is
702 * equivalent to cairo_set_source_rgba(cr, 0.0, 0.0, 0.0, 1.0)).
707 cairo_set_source_rgba (cairo_t *cr,
708 double red, double green, double blue,
711 cairo_status_t status;
713 if (unlikely (cr->status))
716 status = cr->backend->set_source_rgba (cr, red, green, blue, alpha);
717 if (unlikely (status))
718 _cairo_set_error (cr, status);
722 * cairo_set_source_surface:
723 * @cr: a cairo context
724 * @surface: a surface to be used to set the source pattern
725 * @x: User-space X coordinate for surface origin
726 * @y: User-space Y coordinate for surface origin
728 * This is a convenience function for creating a pattern from @surface
729 * and setting it as the source in @cr with cairo_set_source().
731 * The @x and @y parameters give the user-space coordinate at which
732 * the surface origin should appear. (The surface origin is its
733 * upper-left corner before any transformation has been applied.) The
734 * @x and @y parameters are negated and then set as translation values
735 * in the pattern matrix.
737 * Other than the initial translation pattern matrix, as described
738 * above, all other pattern attributes, (such as its extend mode), are
739 * set to the default values as in cairo_pattern_create_for_surface().
740 * The resulting pattern can be queried with cairo_get_source() so
741 * that these attributes can be modified if desired, (eg. to create a
742 * repeating pattern with cairo_pattern_set_extend()).
747 cairo_set_source_surface (cairo_t *cr,
748 cairo_surface_t *surface,
752 cairo_status_t status;
754 if (unlikely (cr->status))
757 if (unlikely (surface == NULL)) {
758 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
762 status = cr->backend->set_source_surface (cr, surface, x, y);
763 if (unlikely (status))
764 _cairo_set_error (cr, status);
766 slim_hidden_def (cairo_set_source_surface);
770 * @cr: a cairo context
771 * @source: a #cairo_pattern_t to be used as the source for
772 * subsequent drawing operations.
774 * Sets the source pattern within @cr to @source. This pattern
775 * will then be used for any subsequent drawing operation until a new
776 * source pattern is set.
778 * Note: The pattern's transformation matrix will be locked to the
779 * user space in effect at the time of cairo_set_source(). This means
780 * that further modifications of the current transformation matrix
781 * will not affect the source pattern. See cairo_pattern_set_matrix().
783 * The default source pattern is a solid pattern that is opaque black,
784 * (that is, it is equivalent to cairo_set_source_rgb(cr, 0.0, 0.0,
790 cairo_set_source (cairo_t *cr, cairo_pattern_t *source)
792 cairo_status_t status;
794 if (unlikely (cr->status))
797 if (unlikely (source == NULL)) {
798 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
802 if (unlikely (source->status)) {
803 _cairo_set_error (cr, source->status);
807 status = cr->backend->set_source (cr, source);
808 if (unlikely (status))
809 _cairo_set_error (cr, status);
811 slim_hidden_def (cairo_set_source);
815 * @cr: a cairo context
817 * Gets the current source pattern for @cr.
819 * Return value: the current source pattern. This object is owned by
820 * cairo. To keep a reference to it, you must call
821 * cairo_pattern_reference().
826 cairo_get_source (cairo_t *cr)
828 if (unlikely (cr->status))
829 return _cairo_pattern_create_in_error (cr->status);
831 return cr->backend->get_source (cr);
835 * cairo_set_tolerance:
837 * @tolerance: the tolerance, in device units (typically pixels)
839 * Sets the tolerance used when converting paths into trapezoids.
840 * Curved segments of the path will be subdivided until the maximum
841 * deviation between the original path and the polygonal approximation
842 * is less than @tolerance. The default value is 0.1. A larger
843 * value will give better performance, a smaller value, better
844 * appearance. (Reducing the value from the default value of 0.1
845 * is unlikely to improve appearance significantly.) The accuracy of paths
846 * within Cairo is limited by the precision of its internal arithmetic, and
847 * the prescribed @tolerance is restricted to the smallest
848 * representable internal value.
853 cairo_set_tolerance (cairo_t *cr, double tolerance)
855 cairo_status_t status;
857 if (unlikely (cr->status))
860 status = cr->backend->set_tolerance (cr, tolerance);
861 if (unlikely (status))
862 _cairo_set_error (cr, status);
864 slim_hidden_def (cairo_set_tolerance);
867 * cairo_set_antialias:
869 * @antialias: the new antialiasing mode
871 * Set the antialiasing mode of the rasterizer used for drawing shapes.
872 * This value is a hint, and a particular backend may or may not support
873 * a particular value. At the current time, no backend supports
874 * %CAIRO_ANTIALIAS_SUBPIXEL when drawing shapes.
876 * Note that this option does not affect text rendering, instead see
877 * cairo_font_options_set_antialias().
882 cairo_set_antialias (cairo_t *cr, cairo_antialias_t antialias)
884 cairo_status_t status;
886 if (unlikely (cr->status))
889 status = cr->backend->set_antialias (cr, antialias);
890 if (unlikely (status))
891 _cairo_set_error (cr, status);
895 * cairo_set_fill_rule:
897 * @fill_rule: a fill rule, specified as a #cairo_fill_rule_t
899 * Set the current fill rule within the cairo context. The fill rule
900 * is used to determine which regions are inside or outside a complex
901 * (potentially self-intersecting) path. The current fill rule affects
902 * both cairo_fill() and cairo_clip(). See #cairo_fill_rule_t for details
903 * on the semantics of each available fill rule.
905 * The default fill rule is %CAIRO_FILL_RULE_WINDING.
910 cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule)
912 cairo_status_t status;
914 if (unlikely (cr->status))
917 status = cr->backend->set_fill_rule (cr, fill_rule);
918 if (unlikely (status))
919 _cairo_set_error (cr, status);
923 * cairo_set_line_width:
925 * @width: a line width
927 * Sets the current line width within the cairo context. The line
928 * width value specifies the diameter of a pen that is circular in
929 * user space, (though device-space pen may be an ellipse in general
930 * due to scaling/shear/rotation of the CTM).
932 * Note: When the description above refers to user space and CTM it
933 * refers to the user space and CTM in effect at the time of the
934 * stroking operation, not the user space and CTM in effect at the
935 * time of the call to cairo_set_line_width(). The simplest usage
936 * makes both of these spaces identical. That is, if there is no
937 * change to the CTM between a call to cairo_set_line_width() and the
938 * stroking operation, then one can just pass user-space values to
939 * cairo_set_line_width() and ignore this note.
941 * As with the other stroke parameters, the current line width is
942 * examined by cairo_stroke(), cairo_stroke_extents(), and
943 * cairo_stroke_to_path(), but does not have any effect during path
946 * The default line width value is 2.0.
951 cairo_set_line_width (cairo_t *cr, double width)
953 cairo_status_t status;
955 if (unlikely (cr->status))
961 status = cr->backend->set_line_width (cr, width);
962 if (unlikely (status))
963 _cairo_set_error (cr, status);
965 slim_hidden_def (cairo_set_line_width);
968 * cairo_set_line_cap:
969 * @cr: a cairo context
970 * @line_cap: a line cap style
972 * Sets the current line cap style within the cairo context. See
973 * #cairo_line_cap_t for details about how the available line cap
976 * As with the other stroke parameters, the current line cap style is
977 * examined by cairo_stroke(), cairo_stroke_extents(), and
978 * cairo_stroke_to_path(), but does not have any effect during path
981 * The default line cap style is %CAIRO_LINE_CAP_BUTT.
986 cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap)
988 cairo_status_t status;
990 if (unlikely (cr->status))
993 status = cr->backend->set_line_cap (cr, line_cap);
994 if (unlikely (status))
995 _cairo_set_error (cr, status);
997 slim_hidden_def (cairo_set_line_cap);
1000 * cairo_set_line_join:
1001 * @cr: a cairo context
1002 * @line_join: a line join style
1004 * Sets the current line join style within the cairo context. See
1005 * #cairo_line_join_t for details about how the available line join
1008 * As with the other stroke parameters, the current line join style is
1009 * examined by cairo_stroke(), cairo_stroke_extents(), and
1010 * cairo_stroke_to_path(), but does not have any effect during path
1013 * The default line join style is %CAIRO_LINE_JOIN_MITER.
1018 cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join)
1020 cairo_status_t status;
1022 if (unlikely (cr->status))
1025 status = cr->backend->set_line_join (cr, line_join);
1026 if (unlikely (status))
1027 _cairo_set_error (cr, status);
1029 slim_hidden_def (cairo_set_line_join);
1033 * @cr: a cairo context
1034 * @dashes: an array specifying alternate lengths of on and off stroke portions
1035 * @num_dashes: the length of the dashes array
1036 * @offset: an offset into the dash pattern at which the stroke should start
1038 * Sets the dash pattern to be used by cairo_stroke(). A dash pattern
1039 * is specified by @dashes, an array of positive values. Each value
1040 * provides the length of alternate "on" and "off" portions of the
1041 * stroke. The @offset specifies an offset into the pattern at which
1042 * the stroke begins.
1044 * Each "on" segment will have caps applied as if the segment were a
1045 * separate sub-path. In particular, it is valid to use an "on" length
1046 * of 0.0 with %CAIRO_LINE_CAP_ROUND or %CAIRO_LINE_CAP_SQUARE in order
1047 * to distributed dots or squares along a path.
1049 * Note: The length values are in user-space units as evaluated at the
1050 * time of stroking. This is not necessarily the same as the user
1051 * space at the time of cairo_set_dash().
1053 * If @num_dashes is 0 dashing is disabled.
1055 * If @num_dashes is 1 a symmetric pattern is assumed with alternating
1056 * on and off portions of the size specified by the single value in
1059 * If any value in @dashes is negative, or if all values are 0, then
1060 * @cr will be put into an error state with a status of
1061 * %CAIRO_STATUS_INVALID_DASH.
1066 cairo_set_dash (cairo_t *cr,
1067 const double *dashes,
1071 cairo_status_t status;
1073 if (unlikely (cr->status))
1076 status = cr->backend->set_dash (cr, dashes, num_dashes, offset);
1077 if (unlikely (status))
1078 _cairo_set_error (cr, status);
1082 * cairo_get_dash_count:
1085 * This function returns the length of the dash array in @cr (0 if dashing
1086 * is not currently in effect).
1088 * See also cairo_set_dash() and cairo_get_dash().
1090 * Return value: the length of the dash array, or 0 if no dash array set.
1095 cairo_get_dash_count (cairo_t *cr)
1099 if (unlikely (cr->status))
1102 cr->backend->get_dash (cr, NULL, &num_dashes, NULL);
1110 * @dashes: return value for the dash array, or %NULL
1111 * @offset: return value for the current dash offset, or %NULL
1113 * Gets the current dash array. If not %NULL, @dashes should be big
1114 * enough to hold at least the number of values returned by
1115 * cairo_get_dash_count().
1120 cairo_get_dash (cairo_t *cr,
1124 if (unlikely (cr->status))
1127 cr->backend->get_dash (cr, dashes, NULL, offset);
1131 * cairo_set_miter_limit:
1132 * @cr: a cairo context
1133 * @limit: miter limit to set
1135 * Sets the current miter limit within the cairo context.
1137 * If the current line join style is set to %CAIRO_LINE_JOIN_MITER
1138 * (see cairo_set_line_join()), the miter limit is used to determine
1139 * whether the lines should be joined with a bevel instead of a miter.
1140 * Cairo divides the length of the miter by the line width.
1141 * If the result is greater than the miter limit, the style is
1142 * converted to a bevel.
1144 * As with the other stroke parameters, the current line miter limit is
1145 * examined by cairo_stroke(), cairo_stroke_extents(), and
1146 * cairo_stroke_to_path(), but does not have any effect during path
1149 * The default miter limit value is 10.0, which will convert joins
1150 * with interior angles less than 11 degrees to bevels instead of
1151 * miters. For reference, a miter limit of 2.0 makes the miter cutoff
1152 * at 60 degrees, and a miter limit of 1.414 makes the cutoff at 90
1155 * A miter limit for a desired angle can be computed as: miter limit =
1161 cairo_set_miter_limit (cairo_t *cr, double limit)
1163 cairo_status_t status;
1165 if (unlikely (cr->status))
1168 status = cr->backend->set_miter_limit (cr, limit);
1169 if (unlikely (status))
1170 _cairo_set_error (cr, status);
1175 * @cr: a cairo context
1176 * @tx: amount to translate in the X direction
1177 * @ty: amount to translate in the Y direction
1179 * Modifies the current transformation matrix (CTM) by translating the
1180 * user-space origin by (@tx, @ty). This offset is interpreted as a
1181 * user-space coordinate according to the CTM in place before the new
1182 * call to cairo_translate(). In other words, the translation of the
1183 * user-space origin takes place after any existing transformation.
1188 cairo_translate (cairo_t *cr, double tx, double ty)
1190 cairo_status_t status;
1192 if (unlikely (cr->status))
1195 status = cr->backend->translate (cr, tx, ty);
1196 if (unlikely (status))
1197 _cairo_set_error (cr, status);
1199 slim_hidden_def (cairo_translate);
1203 * @cr: a cairo context
1204 * @sx: scale factor for the X dimension
1205 * @sy: scale factor for the Y dimension
1207 * Modifies the current transformation matrix (CTM) by scaling the X
1208 * and Y user-space axes by @sx and @sy respectively. The scaling of
1209 * the axes takes place after any existing transformation of user
1215 cairo_scale (cairo_t *cr, double sx, double sy)
1217 cairo_status_t status;
1219 if (unlikely (cr->status))
1222 status = cr->backend->scale (cr, sx, sy);
1223 if (unlikely (status))
1224 _cairo_set_error (cr, status);
1226 slim_hidden_def (cairo_scale);
1230 * @cr: a cairo context
1231 * @angle: angle (in radians) by which the user-space axes will be
1234 * Modifies the current transformation matrix (CTM) by rotating the
1235 * user-space axes by @angle radians. The rotation of the axes takes
1236 * places after any existing transformation of user space. The
1237 * rotation direction for positive angles is from the positive X axis
1238 * toward the positive Y axis.
1243 cairo_rotate (cairo_t *cr, double angle)
1245 cairo_status_t status;
1247 if (unlikely (cr->status))
1250 status = cr->backend->rotate (cr, angle);
1251 if (unlikely (status))
1252 _cairo_set_error (cr, status);
1257 * @cr: a cairo context
1258 * @matrix: a transformation to be applied to the user-space axes
1260 * Modifies the current transformation matrix (CTM) by applying
1261 * @matrix as an additional transformation. The new transformation of
1262 * user space takes place after any existing transformation.
1267 cairo_transform (cairo_t *cr,
1268 const cairo_matrix_t *matrix)
1270 cairo_status_t status;
1272 if (unlikely (cr->status))
1275 status = cr->backend->transform (cr, matrix);
1276 if (unlikely (status))
1277 _cairo_set_error (cr, status);
1279 slim_hidden_def (cairo_transform);
1283 * @cr: a cairo context
1284 * @matrix: a transformation matrix from user space to device space
1286 * Modifies the current transformation matrix (CTM) by setting it
1292 cairo_set_matrix (cairo_t *cr,
1293 const cairo_matrix_t *matrix)
1295 cairo_status_t status;
1297 if (unlikely (cr->status))
1300 status = cr->backend->set_matrix (cr, matrix);
1301 if (unlikely (status))
1302 _cairo_set_error (cr, status);
1304 slim_hidden_def (cairo_set_matrix);
1307 * cairo_identity_matrix:
1308 * @cr: a cairo context
1310 * Resets the current transformation matrix (CTM) by setting it equal
1311 * to the identity matrix. That is, the user-space and device-space
1312 * axes will be aligned and one user-space unit will transform to one
1313 * device-space unit.
1318 cairo_identity_matrix (cairo_t *cr)
1320 cairo_status_t status;
1322 if (unlikely (cr->status))
1325 status = cr->backend->set_identity_matrix (cr);
1326 if (unlikely (status))
1327 _cairo_set_error (cr, status);
1331 * cairo_user_to_device:
1332 * @cr: a cairo context
1333 * @x: X value of coordinate (in/out parameter)
1334 * @y: Y value of coordinate (in/out parameter)
1336 * Transform a coordinate from user space to device space by
1337 * multiplying the given point by the current transformation matrix
1343 cairo_user_to_device (cairo_t *cr, double *x, double *y)
1345 if (unlikely (cr->status))
1348 cr->backend->user_to_device (cr, x, y);
1350 slim_hidden_def (cairo_user_to_device);
1353 * cairo_user_to_device_distance:
1354 * @cr: a cairo context
1355 * @dx: X component of a distance vector (in/out parameter)
1356 * @dy: Y component of a distance vector (in/out parameter)
1358 * Transform a distance vector from user space to device space. This
1359 * function is similar to cairo_user_to_device() except that the
1360 * translation components of the CTM will be ignored when transforming
1366 cairo_user_to_device_distance (cairo_t *cr, double *dx, double *dy)
1368 if (unlikely (cr->status))
1371 cr->backend->user_to_device_distance (cr, dx, dy);
1373 slim_hidden_def (cairo_user_to_device_distance);
1376 * cairo_device_to_user:
1378 * @x: X value of coordinate (in/out parameter)
1379 * @y: Y value of coordinate (in/out parameter)
1381 * Transform a coordinate from device space to user space by
1382 * multiplying the given point by the inverse of the current
1383 * transformation matrix (CTM).
1388 cairo_device_to_user (cairo_t *cr, double *x, double *y)
1390 if (unlikely (cr->status))
1393 cr->backend->device_to_user (cr, x, y);
1395 slim_hidden_def (cairo_device_to_user);
1398 * cairo_device_to_user_distance:
1399 * @cr: a cairo context
1400 * @dx: X component of a distance vector (in/out parameter)
1401 * @dy: Y component of a distance vector (in/out parameter)
1403 * Transform a distance vector from device space to user space. This
1404 * function is similar to cairo_device_to_user() except that the
1405 * translation components of the inverse CTM will be ignored when
1406 * transforming (@dx,@dy).
1411 cairo_device_to_user_distance (cairo_t *cr, double *dx, double *dy)
1413 if (unlikely (cr->status))
1416 cr->backend->device_to_user_distance (cr, dx, dy);
1421 * @cr: a cairo context
1423 * Clears the current path. After this call there will be no path and
1429 cairo_new_path (cairo_t *cr)
1431 cairo_status_t status;
1433 if (unlikely (cr->status))
1436 status = cr->backend->new_path (cr);
1437 if (unlikely (status))
1438 _cairo_set_error (cr, status);
1440 slim_hidden_def(cairo_new_path);
1443 * cairo_new_sub_path:
1444 * @cr: a cairo context
1446 * Begin a new sub-path. Note that the existing path is not
1447 * affected. After this call there will be no current point.
1449 * In many cases, this call is not needed since new sub-paths are
1450 * frequently started with cairo_move_to().
1452 * A call to cairo_new_sub_path() is particularly useful when
1453 * beginning a new sub-path with one of the cairo_arc() calls. This
1454 * makes things easier as it is no longer necessary to manually
1455 * compute the arc's initial coordinates for a call to
1461 cairo_new_sub_path (cairo_t *cr)
1463 cairo_status_t status;
1465 if (unlikely (cr->status))
1468 status = cr->backend->new_sub_path (cr);
1469 if (unlikely (status))
1470 _cairo_set_error (cr, status);
1475 * @cr: a cairo context
1476 * @x: the X coordinate of the new position
1477 * @y: the Y coordinate of the new position
1479 * Begin a new sub-path. After this call the current point will be (@x,
1485 cairo_move_to (cairo_t *cr, double x, double y)
1487 cairo_status_t status;
1489 if (unlikely (cr->status))
1492 status = cr->backend->move_to (cr, x, y);
1493 if (unlikely (status))
1494 _cairo_set_error (cr, status);
1496 slim_hidden_def(cairo_move_to);
1501 * @cr: a cairo context
1502 * @x: the X coordinate of the end of the new line
1503 * @y: the Y coordinate of the end of the new line
1505 * Adds a line to the path from the current point to position (@x, @y)
1506 * in user-space coordinates. After this call the current point
1509 * If there is no current point before the call to cairo_line_to()
1510 * this function will behave as cairo_move_to(@cr, @x, @y).
1515 cairo_line_to (cairo_t *cr, double x, double y)
1517 cairo_status_t status;
1519 if (unlikely (cr->status))
1522 status = cr->backend->line_to (cr, x, y);
1523 if (unlikely (status))
1524 _cairo_set_error (cr, status);
1526 slim_hidden_def (cairo_line_to);
1530 * @cr: a cairo context
1531 * @x1: the X coordinate of the first control point
1532 * @y1: the Y coordinate of the first control point
1533 * @x2: the X coordinate of the second control point
1534 * @y2: the Y coordinate of the second control point
1535 * @x3: the X coordinate of the end of the curve
1536 * @y3: the Y coordinate of the end of the curve
1538 * Adds a cubic Bézier spline to the path from the current point to
1539 * position (@x3, @y3) in user-space coordinates, using (@x1, @y1) and
1540 * (@x2, @y2) as the control points. After this call the current point
1541 * will be (@x3, @y3).
1543 * If there is no current point before the call to cairo_curve_to()
1544 * this function will behave as if preceded by a call to
1545 * cairo_move_to(@cr, @x1, @y1).
1550 cairo_curve_to (cairo_t *cr,
1551 double x1, double y1,
1552 double x2, double y2,
1553 double x3, double y3)
1555 cairo_status_t status;
1557 if (unlikely (cr->status))
1560 status = cr->backend->curve_to (cr,
1564 if (unlikely (status))
1565 _cairo_set_error (cr, status);
1567 slim_hidden_def (cairo_curve_to);
1571 * @cr: a cairo context
1572 * @xc: X position of the center of the arc
1573 * @yc: Y position of the center of the arc
1574 * @radius: the radius of the arc
1575 * @angle1: the start angle, in radians
1576 * @angle2: the end angle, in radians
1578 * Adds a circular arc of the given @radius to the current path. The
1579 * arc is centered at (@xc, @yc), begins at @angle1 and proceeds in
1580 * the direction of increasing angles to end at @angle2. If @angle2 is
1581 * less than @angle1 it will be progressively increased by
1582 * <literal>2*M_PI</literal> until it is greater than @angle1.
1584 * If there is a current point, an initial line segment will be added
1585 * to the path to connect the current point to the beginning of the
1586 * arc. If this initial line is undesired, it can be avoided by
1587 * calling cairo_new_sub_path() before calling cairo_arc().
1589 * Angles are measured in radians. An angle of 0.0 is in the direction
1590 * of the positive X axis (in user space). An angle of
1591 * <literal>M_PI/2.0</literal> radians (90 degrees) is in the
1592 * direction of the positive Y axis (in user space). Angles increase
1593 * in the direction from the positive X axis toward the positive Y
1594 * axis. So with the default transformation matrix, angles increase in
1595 * a clockwise direction.
1597 * (To convert from degrees to radians, use <literal>degrees * (M_PI /
1600 * This function gives the arc in the direction of increasing angles;
1601 * see cairo_arc_negative() to get the arc in the direction of
1602 * decreasing angles.
1604 * The arc is circular in user space. To achieve an elliptical arc,
1605 * you can scale the current transformation matrix by different
1606 * amounts in the X and Y directions. For example, to draw an ellipse
1607 * in the box given by @x, @y, @width, @height:
1609 * <informalexample><programlisting>
1611 * cairo_translate (cr, x + width / 2., y + height / 2.);
1612 * cairo_scale (cr, width / 2., height / 2.);
1613 * cairo_arc (cr, 0., 0., 1., 0., 2 * M_PI);
1614 * cairo_restore (cr);
1615 * </programlisting></informalexample>
1620 cairo_arc (cairo_t *cr,
1621 double xc, double yc,
1623 double angle1, double angle2)
1625 cairo_status_t status;
1627 if (unlikely (cr->status))
1630 if (angle2 < angle1) {
1631 /* increase angle2 by multiples of full circle until it
1632 * satisfies angle2 >= angle1 */
1633 angle2 = fmod (angle2 - angle1, 2 * M_PI);
1639 status = cr->backend->arc (cr, xc, yc, radius, angle1, angle2, TRUE);
1640 if (unlikely (status))
1641 _cairo_set_error (cr, status);
1645 * cairo_arc_negative:
1646 * @cr: a cairo context
1647 * @xc: X position of the center of the arc
1648 * @yc: Y position of the center of the arc
1649 * @radius: the radius of the arc
1650 * @angle1: the start angle, in radians
1651 * @angle2: the end angle, in radians
1653 * Adds a circular arc of the given @radius to the current path. The
1654 * arc is centered at (@xc, @yc), begins at @angle1 and proceeds in
1655 * the direction of decreasing angles to end at @angle2. If @angle2 is
1656 * greater than @angle1 it will be progressively decreased by
1657 * <literal>2*M_PI</literal> until it is less than @angle1.
1659 * See cairo_arc() for more details. This function differs only in the
1660 * direction of the arc between the two angles.
1665 cairo_arc_negative (cairo_t *cr,
1666 double xc, double yc,
1668 double angle1, double angle2)
1670 cairo_status_t status;
1672 if (unlikely (cr->status))
1675 if (angle2 > angle1) {
1676 /* decrease angle2 by multiples of full circle until it
1677 * satisfies angle2 <= angle1 */
1678 angle2 = fmod (angle2 - angle1, 2 * M_PI);
1684 status = cr->backend->arc (cr, xc, yc, radius, angle1, angle2, FALSE);
1685 if (unlikely (status))
1686 _cairo_set_error (cr, status);
1691 cairo_arc_to (cairo_t *cr,
1692 double x1, double y1,
1693 double x2, double y2,
1696 cairo_status_t status;
1698 if (unlikely (cr->status))
1701 status = cr->backend->arc_to (cr, x1, y1, x2, y2, radius);
1702 if (unlikely (status))
1703 _cairo_set_error (cr, status);
1707 cairo_rel_arc_to (cairo_t *cr,
1708 double dx1, double dy1,
1709 double dx2, double dy2,
1712 cairo_status_t status;
1714 if (unlikely (cr->status))
1717 status = cr->backend->rel_arc_to (cr, dx1, dy1, dx2, dy2, radius);
1718 if (unlikely (status))
1719 _cairo_set_error (cr, status);
1724 * cairo_rel_move_to:
1725 * @cr: a cairo context
1729 * Begin a new sub-path. After this call the current point will offset
1732 * Given a current point of (x, y), cairo_rel_move_to(@cr, @dx, @dy)
1733 * is logically equivalent to cairo_move_to(@cr, x + @dx, y + @dy).
1735 * It is an error to call this function with no current point. Doing
1736 * so will cause @cr to shutdown with a status of
1737 * %CAIRO_STATUS_NO_CURRENT_POINT.
1742 cairo_rel_move_to (cairo_t *cr, double dx, double dy)
1744 cairo_status_t status;
1746 if (unlikely (cr->status))
1749 status = cr->backend->rel_move_to (cr, dx, dy);
1750 if (unlikely (status))
1751 _cairo_set_error (cr, status);
1755 * cairo_rel_line_to:
1756 * @cr: a cairo context
1757 * @dx: the X offset to the end of the new line
1758 * @dy: the Y offset to the end of the new line
1760 * Relative-coordinate version of cairo_line_to(). Adds a line to the
1761 * path from the current point to a point that is offset from the
1762 * current point by (@dx, @dy) in user space. After this call the
1763 * current point will be offset by (@dx, @dy).
1765 * Given a current point of (x, y), cairo_rel_line_to(@cr, @dx, @dy)
1766 * is logically equivalent to cairo_line_to(@cr, x + @dx, y + @dy).
1768 * It is an error to call this function with no current point. Doing
1769 * so will cause @cr to shutdown with a status of
1770 * %CAIRO_STATUS_NO_CURRENT_POINT.
1775 cairo_rel_line_to (cairo_t *cr, double dx, double dy)
1777 cairo_status_t status;
1779 if (unlikely (cr->status))
1782 status = cr->backend->rel_line_to (cr, dx, dy);
1783 if (unlikely (status))
1784 _cairo_set_error (cr, status);
1786 slim_hidden_def(cairo_rel_line_to);
1789 * cairo_rel_curve_to:
1790 * @cr: a cairo context
1791 * @dx1: the X offset to the first control point
1792 * @dy1: the Y offset to the first control point
1793 * @dx2: the X offset to the second control point
1794 * @dy2: the Y offset to the second control point
1795 * @dx3: the X offset to the end of the curve
1796 * @dy3: the Y offset to the end of the curve
1798 * Relative-coordinate version of cairo_curve_to(). All offsets are
1799 * relative to the current point. Adds a cubic Bézier spline to the
1800 * path from the current point to a point offset from the current
1801 * point by (@dx3, @dy3), using points offset by (@dx1, @dy1) and
1802 * (@dx2, @dy2) as the control points. After this call the current
1803 * point will be offset by (@dx3, @dy3).
1805 * Given a current point of (x, y), cairo_rel_curve_to(@cr, @dx1,
1806 * @dy1, @dx2, @dy2, @dx3, @dy3) is logically equivalent to
1807 * cairo_curve_to(@cr, x+@dx1, y+@dy1, x+@dx2, y+@dy2, x+@dx3, y+@dy3).
1809 * It is an error to call this function with no current point. Doing
1810 * so will cause @cr to shutdown with a status of
1811 * %CAIRO_STATUS_NO_CURRENT_POINT.
1816 cairo_rel_curve_to (cairo_t *cr,
1817 double dx1, double dy1,
1818 double dx2, double dy2,
1819 double dx3, double dy3)
1821 cairo_status_t status;
1823 if (unlikely (cr->status))
1826 status = cr->backend->rel_curve_to (cr,
1830 if (unlikely (status))
1831 _cairo_set_error (cr, status);
1836 * @cr: a cairo context
1837 * @x: the X coordinate of the top left corner of the rectangle
1838 * @y: the Y coordinate to the top left corner of the rectangle
1839 * @width: the width of the rectangle
1840 * @height: the height of the rectangle
1842 * Adds a closed sub-path rectangle of the given size to the current
1843 * path at position (@x, @y) in user-space coordinates.
1845 * This function is logically equivalent to:
1846 * <informalexample><programlisting>
1847 * cairo_move_to (cr, x, y);
1848 * cairo_rel_line_to (cr, width, 0);
1849 * cairo_rel_line_to (cr, 0, height);
1850 * cairo_rel_line_to (cr, -width, 0);
1851 * cairo_close_path (cr);
1852 * </programlisting></informalexample>
1857 cairo_rectangle (cairo_t *cr,
1859 double width, double height)
1861 cairo_status_t status;
1863 if (unlikely (cr->status))
1866 status = cr->backend->rectangle (cr, x, y, width, height);
1867 if (unlikely (status))
1868 _cairo_set_error (cr, status);
1874 cairo_stroke_to_path (cairo_t *cr)
1876 cairo_status_t status;
1878 if (unlikely (cr->status))
1881 /* The code in _cairo_recording_surface_get_path has a poorman's stroke_to_path */
1883 status = _cairo_gstate_stroke_path (cr->gstate);
1884 if (unlikely (status))
1885 _cairo_set_error (cr, status);
1891 * @cr: a cairo context
1893 * Adds a line segment to the path from the current point to the
1894 * beginning of the current sub-path, (the most recent point passed to
1895 * cairo_move_to()), and closes this sub-path. After this call the
1896 * current point will be at the joined endpoint of the sub-path.
1898 * The behavior of cairo_close_path() is distinct from simply calling
1899 * cairo_line_to() with the equivalent coordinate in the case of
1900 * stroking. When a closed sub-path is stroked, there are no caps on
1901 * the ends of the sub-path. Instead, there is a line join connecting
1902 * the final and initial segments of the sub-path.
1904 * If there is no current point before the call to cairo_close_path(),
1905 * this function will have no effect.
1907 * Note: As of cairo version 1.2.4 any call to cairo_close_path() will
1908 * place an explicit MOVE_TO element into the path immediately after
1909 * the CLOSE_PATH element, (which can be seen in cairo_copy_path() for
1910 * example). This can simplify path processing in some cases as it may
1911 * not be necessary to save the "last move_to point" during processing
1912 * as the MOVE_TO immediately after the CLOSE_PATH will provide that
1918 cairo_close_path (cairo_t *cr)
1920 cairo_status_t status;
1922 if (unlikely (cr->status))
1925 status = cr->backend->close_path (cr);
1926 if (unlikely (status))
1927 _cairo_set_error (cr, status);
1929 slim_hidden_def(cairo_close_path);
1932 * cairo_path_extents:
1933 * @cr: a cairo context
1934 * @x1: left of the resulting extents
1935 * @y1: top of the resulting extents
1936 * @x2: right of the resulting extents
1937 * @y2: bottom of the resulting extents
1939 * Computes a bounding box in user-space coordinates covering the
1940 * points on the current path. If the current path is empty, returns
1941 * an empty rectangle ((0,0), (0,0)). Stroke parameters, fill rule,
1942 * surface dimensions and clipping are not taken into account.
1944 * Contrast with cairo_fill_extents() and cairo_stroke_extents() which
1945 * return the extents of only the area that would be "inked" by
1946 * the corresponding drawing operations.
1948 * The result of cairo_path_extents() is defined as equivalent to the
1949 * limit of cairo_stroke_extents() with %CAIRO_LINE_CAP_ROUND as the
1950 * line width approaches 0.0, (but never reaching the empty-rectangle
1951 * returned by cairo_stroke_extents() for a line width of 0.0).
1953 * Specifically, this means that zero-area sub-paths such as
1954 * cairo_move_to();cairo_line_to() segments, (even degenerate cases
1955 * where the coordinates to both calls are identical), will be
1956 * considered as contributing to the extents. However, a lone
1957 * cairo_move_to() will not contribute to the results of
1958 * cairo_path_extents().
1963 cairo_path_extents (cairo_t *cr,
1964 double *x1, double *y1, double *x2, double *y2)
1966 if (unlikely (cr->status)) {
1979 cr->backend->path_extents (cr, x1, y1, x2, y2);
1984 * @cr: a cairo context
1986 * A drawing operator that paints the current source everywhere within
1987 * the current clip region.
1992 cairo_paint (cairo_t *cr)
1994 cairo_status_t status;
1996 if (unlikely (cr->status))
1999 status = cr->backend->paint (cr);
2000 if (unlikely (status))
2001 _cairo_set_error (cr, status);
2003 slim_hidden_def (cairo_paint);
2006 * cairo_paint_with_alpha:
2007 * @cr: a cairo context
2008 * @alpha: alpha value, between 0 (transparent) and 1 (opaque)
2010 * A drawing operator that paints the current source everywhere within
2011 * the current clip region using a mask of constant alpha value
2012 * @alpha. The effect is similar to cairo_paint(), but the drawing
2013 * is faded out using the alpha value.
2018 cairo_paint_with_alpha (cairo_t *cr,
2021 cairo_status_t status;
2023 if (unlikely (cr->status))
2026 status = cr->backend->paint_with_alpha (cr, alpha);
2027 if (unlikely (status))
2028 _cairo_set_error (cr, status);
2033 * @cr: a cairo context
2034 * @pattern: a #cairo_pattern_t
2036 * A drawing operator that paints the current source
2037 * using the alpha channel of @pattern as a mask. (Opaque
2038 * areas of @pattern are painted with the source, transparent
2039 * areas are not painted.)
2044 cairo_mask (cairo_t *cr,
2045 cairo_pattern_t *pattern)
2047 cairo_status_t status;
2049 if (unlikely (cr->status))
2052 if (unlikely (pattern == NULL)) {
2053 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
2057 if (unlikely (pattern->status)) {
2058 _cairo_set_error (cr, pattern->status);
2062 status = cr->backend->mask (cr, pattern);
2063 if (unlikely (status))
2064 _cairo_set_error (cr, status);
2066 slim_hidden_def (cairo_mask);
2069 * cairo_mask_surface:
2070 * @cr: a cairo context
2071 * @surface: a #cairo_surface_t
2072 * @surface_x: X coordinate at which to place the origin of @surface
2073 * @surface_y: Y coordinate at which to place the origin of @surface
2075 * A drawing operator that paints the current source
2076 * using the alpha channel of @surface as a mask. (Opaque
2077 * areas of @surface are painted with the source, transparent
2078 * areas are not painted.)
2083 cairo_mask_surface (cairo_t *cr,
2084 cairo_surface_t *surface,
2088 cairo_pattern_t *pattern;
2089 cairo_matrix_t matrix;
2091 if (unlikely (cr->status))
2094 pattern = cairo_pattern_create_for_surface (surface);
2096 cairo_matrix_init_translate (&matrix, - surface_x, - surface_y);
2097 cairo_pattern_set_matrix (pattern, &matrix);
2099 cairo_mask (cr, pattern);
2101 cairo_pattern_destroy (pattern);
2106 * @cr: a cairo context
2108 * A drawing operator that strokes the current path according to the
2109 * current line width, line join, line cap, and dash settings. After
2110 * cairo_stroke(), the current path will be cleared from the cairo
2111 * context. See cairo_set_line_width(), cairo_set_line_join(),
2112 * cairo_set_line_cap(), cairo_set_dash(), and
2113 * cairo_stroke_preserve().
2115 * Note: Degenerate segments and sub-paths are treated specially and
2116 * provide a useful result. These can result in two different
2119 * 1. Zero-length "on" segments set in cairo_set_dash(). If the cap
2120 * style is %CAIRO_LINE_CAP_ROUND or %CAIRO_LINE_CAP_SQUARE then these
2121 * segments will be drawn as circular dots or squares respectively. In
2122 * the case of %CAIRO_LINE_CAP_SQUARE, the orientation of the squares
2123 * is determined by the direction of the underlying path.
2125 * 2. A sub-path created by cairo_move_to() followed by either a
2126 * cairo_close_path() or one or more calls to cairo_line_to() to the
2127 * same coordinate as the cairo_move_to(). If the cap style is
2128 * %CAIRO_LINE_CAP_ROUND then these sub-paths will be drawn as circular
2129 * dots. Note that in the case of %CAIRO_LINE_CAP_SQUARE a degenerate
2130 * sub-path will not be drawn at all, (since the correct orientation
2131 * is indeterminate).
2133 * In no case will a cap style of %CAIRO_LINE_CAP_BUTT cause anything
2134 * to be drawn in the case of either degenerate segments or sub-paths.
2139 cairo_stroke (cairo_t *cr)
2141 cairo_status_t status;
2143 if (unlikely (cr->status))
2146 status = cr->backend->stroke (cr);
2147 if (unlikely (status))
2148 _cairo_set_error (cr, status);
2150 slim_hidden_def(cairo_stroke);
2153 * cairo_stroke_preserve:
2154 * @cr: a cairo context
2156 * A drawing operator that strokes the current path according to the
2157 * current line width, line join, line cap, and dash settings. Unlike
2158 * cairo_stroke(), cairo_stroke_preserve() preserves the path within the
2161 * See cairo_set_line_width(), cairo_set_line_join(),
2162 * cairo_set_line_cap(), cairo_set_dash(), and
2163 * cairo_stroke_preserve().
2168 cairo_stroke_preserve (cairo_t *cr)
2170 cairo_status_t status;
2172 if (unlikely (cr->status))
2175 status = cr->backend->stroke_preserve (cr);
2176 if (unlikely (status))
2177 _cairo_set_error (cr, status);
2179 slim_hidden_def(cairo_stroke_preserve);
2183 * @cr: a cairo context
2185 * A drawing operator that fills the current path according to the
2186 * current fill rule, (each sub-path is implicitly closed before being
2187 * filled). After cairo_fill(), the current path will be cleared from
2188 * the cairo context. See cairo_set_fill_rule() and
2189 * cairo_fill_preserve().
2194 cairo_fill (cairo_t *cr)
2196 cairo_status_t status;
2198 if (unlikely (cr->status))
2201 status = cr->backend->fill (cr);
2202 if (unlikely (status))
2203 _cairo_set_error (cr, status);
2207 * cairo_fill_preserve:
2208 * @cr: a cairo context
2210 * A drawing operator that fills the current path according to the
2211 * current fill rule, (each sub-path is implicitly closed before being
2212 * filled). Unlike cairo_fill(), cairo_fill_preserve() preserves the
2213 * path within the cairo context.
2215 * See cairo_set_fill_rule() and cairo_fill().
2220 cairo_fill_preserve (cairo_t *cr)
2222 cairo_status_t status;
2224 if (unlikely (cr->status))
2227 status = cr->backend->fill_preserve (cr);
2228 if (unlikely (status))
2229 _cairo_set_error (cr, status);
2231 slim_hidden_def(cairo_fill_preserve);
2235 * @cr: a cairo context
2237 * Emits the current page for backends that support multiple pages, but
2238 * doesn't clear it, so, the contents of the current page will be retained
2239 * for the next page too. Use cairo_show_page() if you want to get an
2240 * empty page after the emission.
2242 * This is a convenience function that simply calls
2243 * cairo_surface_copy_page() on @cr's target.
2248 cairo_copy_page (cairo_t *cr)
2250 cairo_status_t status;
2252 if (unlikely (cr->status))
2255 status = cr->backend->copy_page (cr);
2256 if (unlikely (status))
2257 _cairo_set_error (cr, status);
2262 * @cr: a cairo context
2264 * Emits and clears the current page for backends that support multiple
2265 * pages. Use cairo_copy_page() if you don't want to clear the page.
2267 * This is a convenience function that simply calls
2268 * cairo_surface_show_page() on @cr's target.
2273 cairo_show_page (cairo_t *cr)
2275 cairo_status_t status;
2277 if (unlikely (cr->status))
2280 status = cr->backend->show_page (cr);
2281 if (unlikely (status))
2282 _cairo_set_error (cr, status);
2287 * @cr: a cairo context
2288 * @x: X coordinate of the point to test
2289 * @y: Y coordinate of the point to test
2291 * Tests whether the given point is inside the area that would be
2292 * affected by a cairo_stroke() operation given the current path and
2293 * stroking parameters. Surface dimensions and clipping are not taken
2296 * See cairo_stroke(), cairo_set_line_width(), cairo_set_line_join(),
2297 * cairo_set_line_cap(), cairo_set_dash(), and
2298 * cairo_stroke_preserve().
2300 * Return value: A non-zero value if the point is inside, or zero if
2306 cairo_in_stroke (cairo_t *cr, double x, double y)
2308 cairo_status_t status;
2309 cairo_bool_t inside = FALSE;
2311 if (unlikely (cr->status))
2314 status = cr->backend->in_stroke (cr, x, y, &inside);
2315 if (unlikely (status))
2316 _cairo_set_error (cr, status);
2323 * @cr: a cairo context
2324 * @x: X coordinate of the point to test
2325 * @y: Y coordinate of the point to test
2327 * Tests whether the given point is inside the area that would be
2328 * affected by a cairo_fill() operation given the current path and
2329 * filling parameters. Surface dimensions and clipping are not taken
2332 * See cairo_fill(), cairo_set_fill_rule() and cairo_fill_preserve().
2334 * Return value: A non-zero value if the point is inside, or zero if
2340 cairo_in_fill (cairo_t *cr, double x, double y)
2342 cairo_status_t status;
2343 cairo_bool_t inside = FALSE;
2345 if (unlikely (cr->status))
2348 status = cr->backend->in_fill (cr, x, y, &inside);
2349 if (unlikely (status))
2350 _cairo_set_error (cr, status);
2356 * cairo_stroke_extents:
2357 * @cr: a cairo context
2358 * @x1: left of the resulting extents
2359 * @y1: top of the resulting extents
2360 * @x2: right of the resulting extents
2361 * @y2: bottom of the resulting extents
2363 * Computes a bounding box in user coordinates covering the area that
2364 * would be affected, (the "inked" area), by a cairo_stroke()
2365 * operation given the current path and stroke parameters.
2366 * If the current path is empty, returns an empty rectangle ((0,0), (0,0)).
2367 * Surface dimensions and clipping are not taken into account.
2369 * Note that if the line width is set to exactly zero, then
2370 * cairo_stroke_extents() will return an empty rectangle. Contrast with
2371 * cairo_path_extents() which can be used to compute the non-empty
2372 * bounds as the line width approaches zero.
2374 * Note that cairo_stroke_extents() must necessarily do more work to
2375 * compute the precise inked areas in light of the stroke parameters,
2376 * so cairo_path_extents() may be more desirable for sake of
2377 * performance if non-inked path extents are desired.
2379 * See cairo_stroke(), cairo_set_line_width(), cairo_set_line_join(),
2380 * cairo_set_line_cap(), cairo_set_dash(), and
2381 * cairo_stroke_preserve().
2386 cairo_stroke_extents (cairo_t *cr,
2387 double *x1, double *y1, double *x2, double *y2)
2389 cairo_status_t status;
2391 if (unlikely (cr->status)) {
2404 status = cr->backend->stroke_extents (cr, x1, y1, x2, y2);
2405 if (unlikely (status))
2406 _cairo_set_error (cr, status);
2410 * cairo_fill_extents:
2411 * @cr: a cairo context
2412 * @x1: left of the resulting extents
2413 * @y1: top of the resulting extents
2414 * @x2: right of the resulting extents
2415 * @y2: bottom of the resulting extents
2417 * Computes a bounding box in user coordinates covering the area that
2418 * would be affected, (the "inked" area), by a cairo_fill() operation
2419 * given the current path and fill parameters. If the current path is
2420 * empty, returns an empty rectangle ((0,0), (0,0)). Surface
2421 * dimensions and clipping are not taken into account.
2423 * Contrast with cairo_path_extents(), which is similar, but returns
2424 * non-zero extents for some paths with no inked area, (such as a
2425 * simple line segment).
2427 * Note that cairo_fill_extents() must necessarily do more work to
2428 * compute the precise inked areas in light of the fill rule, so
2429 * cairo_path_extents() may be more desirable for sake of performance
2430 * if the non-inked path extents are desired.
2432 * See cairo_fill(), cairo_set_fill_rule() and cairo_fill_preserve().
2437 cairo_fill_extents (cairo_t *cr,
2438 double *x1, double *y1, double *x2, double *y2)
2440 cairo_status_t status;
2442 if (unlikely (cr->status)) {
2455 status = cr->backend->fill_extents (cr, x1, y1, x2, y2);
2456 if (unlikely (status))
2457 _cairo_set_error (cr, status);
2462 * @cr: a cairo context
2464 * Establishes a new clip region by intersecting the current clip
2465 * region with the current path as it would be filled by cairo_fill()
2466 * and according to the current fill rule (see cairo_set_fill_rule()).
2468 * After cairo_clip(), the current path will be cleared from the cairo
2471 * The current clip region affects all drawing operations by
2472 * effectively masking out any changes to the surface that are outside
2473 * the current clip region.
2475 * Calling cairo_clip() can only make the clip region smaller, never
2476 * larger. But the current clip is part of the graphics state, so a
2477 * temporary restriction of the clip region can be achieved by
2478 * calling cairo_clip() within a cairo_save()/cairo_restore()
2479 * pair. The only other means of increasing the size of the clip
2480 * region is cairo_reset_clip().
2485 cairo_clip (cairo_t *cr)
2487 cairo_status_t status;
2489 if (unlikely (cr->status))
2492 status = cr->backend->clip (cr);
2493 if (unlikely (status))
2494 _cairo_set_error (cr, status);
2498 * cairo_clip_preserve:
2499 * @cr: a cairo context
2501 * Establishes a new clip region by intersecting the current clip
2502 * region with the current path as it would be filled by cairo_fill()
2503 * and according to the current fill rule (see cairo_set_fill_rule()).
2505 * Unlike cairo_clip(), cairo_clip_preserve() preserves the path within
2506 * the cairo context.
2508 * The current clip region affects all drawing operations by
2509 * effectively masking out any changes to the surface that are outside
2510 * the current clip region.
2512 * Calling cairo_clip_preserve() can only make the clip region smaller, never
2513 * larger. But the current clip is part of the graphics state, so a
2514 * temporary restriction of the clip region can be achieved by
2515 * calling cairo_clip_preserve() within a cairo_save()/cairo_restore()
2516 * pair. The only other means of increasing the size of the clip
2517 * region is cairo_reset_clip().
2522 cairo_clip_preserve (cairo_t *cr)
2524 cairo_status_t status;
2526 if (unlikely (cr->status))
2529 status = cr->backend->clip_preserve (cr);
2530 if (unlikely (status))
2531 _cairo_set_error (cr, status);
2533 slim_hidden_def(cairo_clip_preserve);
2537 * @cr: a cairo context
2539 * Reset the current clip region to its original, unrestricted
2540 * state. That is, set the clip region to an infinitely large shape
2541 * containing the target surface. Equivalently, if infinity is too
2542 * hard to grasp, one can imagine the clip region being reset to the
2543 * exact bounds of the target surface.
2545 * Note that code meant to be reusable should not call
2546 * cairo_reset_clip() as it will cause results unexpected by
2547 * higher-level code which calls cairo_clip(). Consider using
2548 * cairo_save() and cairo_restore() around cairo_clip() as a more
2549 * robust means of temporarily restricting the clip region.
2554 cairo_reset_clip (cairo_t *cr)
2556 cairo_status_t status;
2558 if (unlikely (cr->status))
2561 status = cr->backend->reset_clip (cr);
2562 if (unlikely (status))
2563 _cairo_set_error (cr, status);
2567 * cairo_clip_extents:
2568 * @cr: a cairo context
2569 * @x1: left of the resulting extents
2570 * @y1: top of the resulting extents
2571 * @x2: right of the resulting extents
2572 * @y2: bottom of the resulting extents
2574 * Computes a bounding box in user coordinates covering the area inside the
2580 cairo_clip_extents (cairo_t *cr,
2581 double *x1, double *y1,
2582 double *x2, double *y2)
2584 cairo_status_t status;
2595 if (unlikely (cr->status))
2598 status = cr->backend->clip_extents (cr, x1, y1, x2, y2);
2599 if (unlikely (status))
2600 _cairo_set_error (cr, status);
2605 * @cr: a cairo context
2606 * @x: X coordinate of the point to test
2607 * @y: Y coordinate of the point to test
2609 * Tests whether the given point is inside the area that would be
2610 * visible through the current clip, i.e. the area that would be filled by
2611 * a cairo_paint() operation.
2613 * See cairo_clip(), and cairo_clip_preserve().
2615 * Return value: A non-zero value if the point is inside, or zero if
2621 cairo_in_clip (cairo_t *cr, double x, double y)
2623 cairo_status_t status;
2624 cairo_bool_t inside = FALSE;
2626 if (unlikely (cr->status))
2629 status = cr->backend->in_clip (cr, x, y, &inside);
2630 if (unlikely (status))
2631 _cairo_set_error (cr, status);
2637 * cairo_copy_clip_rectangle_list:
2638 * @cr: a cairo context
2640 * Gets the current clip region as a list of rectangles in user coordinates.
2641 * Never returns %NULL.
2643 * The status in the list may be %CAIRO_STATUS_CLIP_NOT_REPRESENTABLE to
2644 * indicate that the clip region cannot be represented as a list of
2645 * user-space rectangles. The status may have other values to indicate
2648 * Returns: the current clip region as a list of rectangles in user coordinates,
2649 * which should be destroyed using cairo_rectangle_list_destroy().
2653 cairo_rectangle_list_t *
2654 cairo_copy_clip_rectangle_list (cairo_t *cr)
2656 if (unlikely (cr->status))
2657 return _cairo_rectangle_list_create_in_error (cr->status);
2659 return cr->backend->clip_copy_rectangle_list (cr);
2663 * cairo_select_font_face:
2665 * @family: a font family name, encoded in UTF-8
2666 * @slant: the slant for the font
2667 * @weight: the weight for the font
2669 * Note: The cairo_select_font_face() function call is part of what
2670 * the cairo designers call the "toy" text API. It is convenient for
2671 * short demos and simple programs, but it is not expected to be
2672 * adequate for serious text-using applications.
2674 * Selects a family and style of font from a simplified description as
2675 * a family name, slant and weight. Cairo provides no operation to
2676 * list available family names on the system (this is a "toy",
2677 * remember), but the standard CSS2 generic family names, ("serif",
2678 * "sans-serif", "cursive", "fantasy", "monospace"), are likely to
2681 * If @family starts with the string "@cairo:", or if no native font
2682 * backends are compiled in, cairo will use an internal font family.
2683 * The internal font family recognizes many modifiers in the @family
2684 * string, most notably, it recognizes the string "monospace". That is,
2685 * the family name "@cairo:monospace" will use the monospace version of
2686 * the internal font family.
2688 * For "real" font selection, see the font-backend-specific
2689 * font_face_create functions for the font backend you are using. (For
2690 * example, if you are using the freetype-based cairo-ft font backend,
2691 * see cairo_ft_font_face_create_for_ft_face() or
2692 * cairo_ft_font_face_create_for_pattern().) The resulting font face
2693 * could then be used with cairo_scaled_font_create() and
2694 * cairo_set_scaled_font().
2696 * Similarly, when using the "real" font support, you can call
2697 * directly into the underlying font system, (such as fontconfig or
2698 * freetype), for operations such as listing available fonts, etc.
2700 * It is expected that most applications will need to use a more
2701 * comprehensive font handling and text layout library, (for example,
2702 * pango), in conjunction with cairo.
2704 * If text is drawn without a call to cairo_select_font_face(), (nor
2705 * cairo_set_font_face() nor cairo_set_scaled_font()), the default
2706 * family is platform-specific, but is essentially "sans-serif".
2707 * Default slant is %CAIRO_FONT_SLANT_NORMAL, and default weight is
2708 * %CAIRO_FONT_WEIGHT_NORMAL.
2710 * This function is equivalent to a call to cairo_toy_font_face_create()
2711 * followed by cairo_set_font_face().
2716 cairo_select_font_face (cairo_t *cr,
2718 cairo_font_slant_t slant,
2719 cairo_font_weight_t weight)
2721 cairo_font_face_t *font_face;
2722 cairo_status_t status;
2724 if (unlikely (cr->status))
2727 font_face = cairo_toy_font_face_create (family, slant, weight);
2728 if (unlikely (font_face->status)) {
2729 _cairo_set_error (cr, font_face->status);
2733 status = cr->backend->set_font_face (cr, font_face);
2734 cairo_font_face_destroy (font_face);
2736 if (unlikely (status))
2737 _cairo_set_error (cr, status);
2741 * cairo_font_extents:
2743 * @extents: a #cairo_font_extents_t object into which the results
2746 * Gets the font extents for the currently selected font.
2751 cairo_font_extents (cairo_t *cr,
2752 cairo_font_extents_t *extents)
2754 cairo_status_t status;
2756 extents->ascent = 0.0;
2757 extents->descent = 0.0;
2758 extents->height = 0.0;
2759 extents->max_x_advance = 0.0;
2760 extents->max_y_advance = 0.0;
2762 if (unlikely (cr->status))
2765 status = cr->backend->font_extents (cr, extents);
2766 if (unlikely (status))
2767 _cairo_set_error (cr, status);
2771 * cairo_set_font_face:
2773 * @font_face: a #cairo_font_face_t, or %NULL to restore to the default font
2775 * Replaces the current #cairo_font_face_t object in the #cairo_t with
2776 * @font_face. The replaced font face in the #cairo_t will be
2777 * destroyed if there are no other references to it.
2782 cairo_set_font_face (cairo_t *cr,
2783 cairo_font_face_t *font_face)
2785 cairo_status_t status;
2787 if (unlikely (cr->status))
2790 status = cr->backend->set_font_face (cr, font_face);
2791 if (unlikely (status))
2792 _cairo_set_error (cr, status);
2796 * cairo_get_font_face:
2799 * Gets the current font face for a #cairo_t.
2801 * Return value: the current font face. This object is owned by
2802 * cairo. To keep a reference to it, you must call
2803 * cairo_font_face_reference().
2805 * This function never returns %NULL. If memory cannot be allocated, a
2806 * special "nil" #cairo_font_face_t object will be returned on which
2807 * cairo_font_face_status() returns %CAIRO_STATUS_NO_MEMORY. Using
2808 * this nil object will cause its error state to propagate to other
2809 * objects it is passed to, (for example, calling
2810 * cairo_set_font_face() with a nil font will trigger an error that
2811 * will shutdown the #cairo_t object).
2816 cairo_get_font_face (cairo_t *cr)
2818 if (unlikely (cr->status))
2819 return (cairo_font_face_t*) &_cairo_font_face_nil;
2821 return cr->backend->get_font_face (cr);
2825 * cairo_set_font_size:
2827 * @size: the new font size, in user space units
2829 * Sets the current font matrix to a scale by a factor of @size, replacing
2830 * any font matrix previously set with cairo_set_font_size() or
2831 * cairo_set_font_matrix(). This results in a font size of @size user space
2832 * units. (More precisely, this matrix will result in the font's
2833 * em-square being a @size by @size square in user space.)
2835 * If text is drawn without a call to cairo_set_font_size(), (nor
2836 * cairo_set_font_matrix() nor cairo_set_scaled_font()), the default
2837 * font size is 10.0.
2842 cairo_set_font_size (cairo_t *cr, double size)
2844 cairo_status_t status;
2846 if (unlikely (cr->status))
2849 status = cr->backend->set_font_size (cr, size);
2850 if (unlikely (status))
2851 _cairo_set_error (cr, status);
2853 slim_hidden_def (cairo_set_font_size);
2856 * cairo_set_font_matrix:
2858 * @matrix: a #cairo_matrix_t describing a transform to be applied to
2861 * Sets the current font matrix to @matrix. The font matrix gives a
2862 * transformation from the design space of the font (in this space,
2863 * the em-square is 1 unit by 1 unit) to user space. Normally, a
2864 * simple scale is used (see cairo_set_font_size()), but a more
2865 * complex font matrix can be used to shear the font
2866 * or stretch it unequally along the two axes
2871 cairo_set_font_matrix (cairo_t *cr,
2872 const cairo_matrix_t *matrix)
2874 cairo_status_t status;
2876 if (unlikely (cr->status))
2879 status = cr->backend->set_font_matrix (cr, matrix);
2880 if (unlikely (status))
2881 _cairo_set_error (cr, status);
2883 slim_hidden_def (cairo_set_font_matrix);
2886 * cairo_get_font_matrix:
2888 * @matrix: return value for the matrix
2890 * Stores the current font matrix into @matrix. See
2891 * cairo_set_font_matrix().
2896 cairo_get_font_matrix (cairo_t *cr, cairo_matrix_t *matrix)
2898 if (unlikely (cr->status)) {
2899 cairo_matrix_init_identity (matrix);
2903 cr->backend->get_font_matrix (cr, matrix);
2907 * cairo_set_font_options:
2909 * @options: font options to use
2911 * Sets a set of custom font rendering options for the #cairo_t.
2912 * Rendering options are derived by merging these options with the
2913 * options derived from underlying surface; if the value in @options
2914 * has a default value (like %CAIRO_ANTIALIAS_DEFAULT), then the value
2915 * from the surface is used.
2920 cairo_set_font_options (cairo_t *cr,
2921 const cairo_font_options_t *options)
2923 cairo_status_t status;
2925 if (unlikely (cr->status))
2928 status = cairo_font_options_status ((cairo_font_options_t *) options);
2929 if (unlikely (status)) {
2930 _cairo_set_error (cr, status);
2934 status = cr->backend->set_font_options (cr, options);
2935 if (unlikely (status))
2936 _cairo_set_error (cr, status);
2938 slim_hidden_def (cairo_set_font_options);
2941 * cairo_get_font_options:
2943 * @options: a #cairo_font_options_t object into which to store
2944 * the retrieved options. All existing values are overwritten
2946 * Retrieves font rendering options set via #cairo_set_font_options.
2947 * Note that the returned options do not include any options derived
2948 * from the underlying surface; they are literally the options
2949 * passed to cairo_set_font_options().
2954 cairo_get_font_options (cairo_t *cr,
2955 cairo_font_options_t *options)
2957 /* check that we aren't trying to overwrite the nil object */
2958 if (cairo_font_options_status (options))
2961 if (unlikely (cr->status)) {
2962 _cairo_font_options_init_default (options);
2966 cr->backend->get_font_options (cr, options);
2970 * cairo_set_scaled_font:
2972 * @scaled_font: a #cairo_scaled_font_t
2974 * Replaces the current font face, font matrix, and font options in
2975 * the #cairo_t with those of the #cairo_scaled_font_t. Except for
2976 * some translation, the current CTM of the #cairo_t should be the
2977 * same as that of the #cairo_scaled_font_t, which can be accessed
2978 * using cairo_scaled_font_get_ctm().
2983 cairo_set_scaled_font (cairo_t *cr,
2984 const cairo_scaled_font_t *scaled_font)
2986 cairo_status_t status;
2988 if (unlikely (cr->status))
2991 if ((scaled_font == NULL)) {
2992 _cairo_set_error (cr, _cairo_error (CAIRO_STATUS_NULL_POINTER));
2996 status = scaled_font->status;
2997 if (unlikely (status)) {
2998 _cairo_set_error (cr, status);
3002 status = cr->backend->set_scaled_font (cr, (cairo_scaled_font_t *) scaled_font);
3003 if (unlikely (status))
3004 _cairo_set_error (cr, status);
3008 * cairo_get_scaled_font:
3011 * Gets the current scaled font for a #cairo_t.
3013 * Return value: the current scaled font. This object is owned by
3014 * cairo. To keep a reference to it, you must call
3015 * cairo_scaled_font_reference().
3017 * This function never returns %NULL. If memory cannot be allocated, a
3018 * special "nil" #cairo_scaled_font_t object will be returned on which
3019 * cairo_scaled_font_status() returns %CAIRO_STATUS_NO_MEMORY. Using
3020 * this nil object will cause its error state to propagate to other
3021 * objects it is passed to, (for example, calling
3022 * cairo_set_scaled_font() with a nil font will trigger an error that
3023 * will shutdown the #cairo_t object).
3027 cairo_scaled_font_t *
3028 cairo_get_scaled_font (cairo_t *cr)
3030 if (unlikely (cr->status))
3031 return _cairo_scaled_font_create_in_error (cr->status);
3033 return cr->backend->get_scaled_font (cr);
3035 slim_hidden_def (cairo_get_scaled_font);
3038 * cairo_text_extents:
3040 * @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
3041 * @extents: a #cairo_text_extents_t object into which the results
3044 * Gets the extents for a string of text. The extents describe a
3045 * user-space rectangle that encloses the "inked" portion of the text,
3046 * (as it would be drawn by cairo_show_text()). Additionally, the
3047 * x_advance and y_advance values indicate the amount by which the
3048 * current point would be advanced by cairo_show_text().
3050 * Note that whitespace characters do not directly contribute to the
3051 * size of the rectangle (extents.width and extents.height). They do
3052 * contribute indirectly by changing the position of non-whitespace
3053 * characters. In particular, trailing whitespace characters are
3054 * likely to not affect the size of the rectangle, though they will
3055 * affect the x_advance and y_advance values.
3060 cairo_text_extents (cairo_t *cr,
3062 cairo_text_extents_t *extents)
3064 cairo_status_t status;
3065 cairo_scaled_font_t *scaled_font;
3066 cairo_glyph_t *glyphs = NULL;
3070 extents->x_bearing = 0.0;
3071 extents->y_bearing = 0.0;
3072 extents->width = 0.0;
3073 extents->height = 0.0;
3074 extents->x_advance = 0.0;
3075 extents->y_advance = 0.0;
3077 if (unlikely (cr->status))
3083 scaled_font = cairo_get_scaled_font (cr);
3084 if (unlikely (scaled_font->status)) {
3085 _cairo_set_error (cr, scaled_font->status);
3089 cairo_get_current_point (cr, &x, &y);
3090 status = cairo_scaled_font_text_to_glyphs (scaled_font,
3093 &glyphs, &num_glyphs,
3096 if (likely (status == CAIRO_STATUS_SUCCESS)) {
3097 status = cr->backend->glyph_extents (cr,
3101 cairo_glyph_free (glyphs);
3103 if (unlikely (status))
3104 _cairo_set_error (cr, status);
3108 * cairo_glyph_extents:
3110 * @glyphs: an array of #cairo_glyph_t objects
3111 * @num_glyphs: the number of elements in @glyphs
3112 * @extents: a #cairo_text_extents_t object into which the results
3115 * Gets the extents for an array of glyphs. The extents describe a
3116 * user-space rectangle that encloses the "inked" portion of the
3117 * glyphs, (as they would be drawn by cairo_show_glyphs()).
3118 * Additionally, the x_advance and y_advance values indicate the
3119 * amount by which the current point would be advanced by
3120 * cairo_show_glyphs().
3122 * Note that whitespace glyphs do not contribute to the size of the
3123 * rectangle (extents.width and extents.height).
3128 cairo_glyph_extents (cairo_t *cr,
3129 const cairo_glyph_t *glyphs,
3131 cairo_text_extents_t *extents)
3133 cairo_status_t status;
3135 extents->x_bearing = 0.0;
3136 extents->y_bearing = 0.0;
3137 extents->width = 0.0;
3138 extents->height = 0.0;
3139 extents->x_advance = 0.0;
3140 extents->y_advance = 0.0;
3142 if (unlikely (cr->status))
3145 if (num_glyphs == 0)
3148 if (unlikely (num_glyphs < 0)) {
3149 _cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
3153 if (unlikely (glyphs == NULL)) {
3154 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3158 status = cr->backend->glyph_extents (cr, glyphs, num_glyphs, extents);
3159 if (unlikely (status))
3160 _cairo_set_error (cr, status);
3165 * @cr: a cairo context
3166 * @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
3168 * A drawing operator that generates the shape from a string of UTF-8
3169 * characters, rendered according to the current font_face, font_size
3170 * (font_matrix), and font_options.
3172 * This function first computes a set of glyphs for the string of
3173 * text. The first glyph is placed so that its origin is at the
3174 * current point. The origin of each subsequent glyph is offset from
3175 * that of the previous glyph by the advance values of the previous
3178 * After this call the current point is moved to the origin of where
3179 * the next glyph would be placed in this same progression. That is,
3180 * the current point will be at the origin of the final glyph offset
3181 * by its advance values. This allows for easy display of a single
3182 * logical string with multiple calls to cairo_show_text().
3184 * Note: The cairo_show_text() function call is part of what the cairo
3185 * designers call the "toy" text API. It is convenient for short demos
3186 * and simple programs, but it is not expected to be adequate for
3187 * serious text-using applications. See cairo_show_glyphs() for the
3188 * "real" text display API in cairo.
3193 cairo_show_text (cairo_t *cr, const char *utf8)
3195 cairo_text_extents_t extents;
3196 cairo_status_t status;
3197 cairo_glyph_t *glyphs, *last_glyph;
3198 cairo_text_cluster_t *clusters;
3199 int utf8_len, num_glyphs, num_clusters;
3200 cairo_text_cluster_flags_t cluster_flags;
3202 cairo_bool_t has_show_text_glyphs;
3203 cairo_glyph_t stack_glyphs[CAIRO_STACK_ARRAY_LENGTH (cairo_glyph_t)];
3204 cairo_text_cluster_t stack_clusters[CAIRO_STACK_ARRAY_LENGTH (cairo_text_cluster_t)];
3205 cairo_scaled_font_t *scaled_font;
3206 cairo_glyph_text_info_t info, *i;
3208 if (unlikely (cr->status))
3214 scaled_font = cairo_get_scaled_font (cr);
3215 if (unlikely (scaled_font->status)) {
3216 _cairo_set_error (cr, scaled_font->status);
3220 utf8_len = strlen (utf8);
3222 has_show_text_glyphs =
3223 cairo_surface_has_show_text_glyphs (cairo_get_target (cr));
3225 glyphs = stack_glyphs;
3226 num_glyphs = ARRAY_LENGTH (stack_glyphs);
3228 if (has_show_text_glyphs) {
3229 clusters = stack_clusters;
3230 num_clusters = ARRAY_LENGTH (stack_clusters);
3236 cairo_get_current_point (cr, &x, &y);
3237 status = cairo_scaled_font_text_to_glyphs (scaled_font,
3240 &glyphs, &num_glyphs,
3241 has_show_text_glyphs ? &clusters : NULL, &num_clusters,
3243 if (unlikely (status))
3246 if (num_glyphs == 0)
3250 if (has_show_text_glyphs) {
3252 info.utf8_len = utf8_len;
3253 info.clusters = clusters;
3254 info.num_clusters = num_clusters;
3255 info.cluster_flags = cluster_flags;
3259 status = cr->backend->glyphs (cr, glyphs, num_glyphs, i);
3260 if (unlikely (status))
3263 last_glyph = &glyphs[num_glyphs - 1];
3264 status = cr->backend->glyph_extents (cr, last_glyph, 1, &extents);
3265 if (unlikely (status))
3268 x = last_glyph->x + extents.x_advance;
3269 y = last_glyph->y + extents.y_advance;
3270 cr->backend->move_to (cr, x, y);
3273 if (glyphs != stack_glyphs)
3274 cairo_glyph_free (glyphs);
3275 if (clusters != stack_clusters)
3276 cairo_text_cluster_free (clusters);
3278 if (unlikely (status))
3279 _cairo_set_error (cr, status);
3283 * cairo_show_glyphs:
3284 * @cr: a cairo context
3285 * @glyphs: array of glyphs to show
3286 * @num_glyphs: number of glyphs to show
3288 * A drawing operator that generates the shape from an array of glyphs,
3289 * rendered according to the current font face, font size
3290 * (font matrix), and font options.
3295 cairo_show_glyphs (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs)
3297 cairo_status_t status;
3299 if (unlikely (cr->status))
3302 if (num_glyphs == 0)
3305 if (num_glyphs < 0) {
3306 _cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
3310 if (glyphs == NULL) {
3311 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3315 status = cr->backend->glyphs (cr, glyphs, num_glyphs, NULL);
3316 if (unlikely (status))
3317 _cairo_set_error (cr, status);
3321 * cairo_show_text_glyphs:
3322 * @cr: a cairo context
3323 * @utf8: a string of text encoded in UTF-8
3324 * @utf8_len: length of @utf8 in bytes, or -1 if it is NUL-terminated
3325 * @glyphs: array of glyphs to show
3326 * @num_glyphs: number of glyphs to show
3327 * @clusters: array of cluster mapping information
3328 * @num_clusters: number of clusters in the mapping
3329 * @cluster_flags: cluster mapping flags
3331 * This operation has rendering effects similar to cairo_show_glyphs()
3332 * but, if the target surface supports it, uses the provided text and
3333 * cluster mapping to embed the text for the glyphs shown in the output.
3334 * If the target does not support the extended attributes, this function
3335 * acts like the basic cairo_show_glyphs() as if it had been passed
3336 * @glyphs and @num_glyphs.
3338 * The mapping between @utf8 and @glyphs is provided by an array of
3339 * <firstterm>clusters</firstterm>. Each cluster covers a number of
3340 * text bytes and glyphs, and neighboring clusters cover neighboring
3341 * areas of @utf8 and @glyphs. The clusters should collectively cover @utf8
3342 * and @glyphs in entirety.
3344 * The first cluster always covers bytes from the beginning of @utf8.
3345 * If @cluster_flags do not have the %CAIRO_TEXT_CLUSTER_FLAG_BACKWARD
3346 * set, the first cluster also covers the beginning
3347 * of @glyphs, otherwise it covers the end of the @glyphs array and
3348 * following clusters move backward.
3350 * See #cairo_text_cluster_t for constraints on valid clusters.
3355 cairo_show_text_glyphs (cairo_t *cr,
3358 const cairo_glyph_t *glyphs,
3360 const cairo_text_cluster_t *clusters,
3362 cairo_text_cluster_flags_t cluster_flags)
3364 cairo_status_t status;
3366 if (unlikely (cr->status))
3369 /* A slew of sanity checks */
3371 /* Special case for NULL and -1 */
3372 if (utf8 == NULL && utf8_len == -1)
3375 /* No NULLs for non-zeros */
3376 if ((num_glyphs && glyphs == NULL) ||
3377 (utf8_len && utf8 == NULL) ||
3378 (num_clusters && clusters == NULL)) {
3379 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3383 /* A -1 for utf8_len means NUL-terminated */
3385 utf8_len = strlen (utf8);
3387 /* Apart from that, no negatives */
3388 if (num_glyphs < 0 || utf8_len < 0 || num_clusters < 0) {
3389 _cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
3393 if (num_glyphs == 0 && utf8_len == 0)
3397 /* Make sure clusters cover the entire glyphs and utf8 arrays,
3398 * and that cluster boundaries are UTF-8 boundaries. */
3399 status = _cairo_validate_text_clusters (utf8, utf8_len,
3401 clusters, num_clusters, cluster_flags);
3402 if (status == CAIRO_STATUS_INVALID_CLUSTERS) {
3403 /* Either got invalid UTF-8 text, or cluster mapping is bad.
3404 * Differentiate those. */
3406 cairo_status_t status2;
3408 status2 = _cairo_utf8_to_ucs4 (utf8, utf8_len, NULL, NULL);
3412 cairo_glyph_text_info_t info;
3415 info.utf8_len = utf8_len;
3416 info.clusters = clusters;
3417 info.num_clusters = num_clusters;
3418 info.cluster_flags = cluster_flags;
3420 status = cr->backend->glyphs (cr, glyphs, num_glyphs, &info);
3423 status = cr->backend->glyphs (cr, glyphs, num_glyphs, NULL);
3425 if (unlikely (status))
3426 _cairo_set_error (cr, status);
3431 * @cr: a cairo context
3432 * @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
3434 * Adds closed paths for text to the current path. The generated
3435 * path if filled, achieves an effect similar to that of
3436 * cairo_show_text().
3438 * Text conversion and positioning is done similar to cairo_show_text().
3440 * Like cairo_show_text(), After this call the current point is
3441 * moved to the origin of where the next glyph would be placed in
3442 * this same progression. That is, the current point will be at
3443 * the origin of the final glyph offset by its advance values.
3444 * This allows for chaining multiple calls to to cairo_text_path()
3445 * without having to set current point in between.
3447 * Note: The cairo_text_path() function call is part of what the cairo
3448 * designers call the "toy" text API. It is convenient for short demos
3449 * and simple programs, but it is not expected to be adequate for
3450 * serious text-using applications. See cairo_glyph_path() for the
3451 * "real" text path API in cairo.
3456 cairo_text_path (cairo_t *cr, const char *utf8)
3458 cairo_status_t status;
3459 cairo_text_extents_t extents;
3460 cairo_glyph_t stack_glyphs[CAIRO_STACK_ARRAY_LENGTH (cairo_glyph_t)];
3461 cairo_glyph_t *glyphs, *last_glyph;
3462 cairo_scaled_font_t *scaled_font;
3466 if (unlikely (cr->status))
3473 glyphs = stack_glyphs;
3474 num_glyphs = ARRAY_LENGTH (stack_glyphs);
3476 scaled_font = cairo_get_scaled_font (cr);
3477 if (unlikely (scaled_font->status)) {
3478 _cairo_set_error (cr, scaled_font->status);
3482 cairo_get_current_point (cr, &x, &y);
3483 status = cairo_scaled_font_text_to_glyphs (scaled_font,
3486 &glyphs, &num_glyphs,
3489 if (num_glyphs == 0)
3492 status = cr->backend->glyph_path (cr, glyphs, num_glyphs);
3494 if (unlikely (status))
3497 last_glyph = &glyphs[num_glyphs - 1];
3498 status = cr->backend->glyph_extents (cr, last_glyph, 1, &extents);
3500 if (unlikely (status))
3503 x = last_glyph->x + extents.x_advance;
3504 y = last_glyph->y + extents.y_advance;
3505 cr->backend->move_to (cr, x, y);
3508 if (glyphs != stack_glyphs)
3509 cairo_glyph_free (glyphs);
3511 if (unlikely (status))
3512 _cairo_set_error (cr, status);
3517 * @cr: a cairo context
3518 * @glyphs: array of glyphs to show
3519 * @num_glyphs: number of glyphs to show
3521 * Adds closed paths for the glyphs to the current path. The generated
3522 * path if filled, achieves an effect similar to that of
3523 * cairo_show_glyphs().
3528 cairo_glyph_path (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs)
3530 cairo_status_t status;
3532 if (unlikely (cr->status))
3535 if (num_glyphs == 0)
3538 if (unlikely (num_glyphs < 0)) {
3539 _cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
3543 if (unlikely (glyphs == NULL)) {
3544 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3548 status = cr->backend->glyph_path (cr, glyphs, num_glyphs);
3549 if (unlikely (status))
3550 _cairo_set_error (cr, status);
3554 * cairo_get_operator:
3555 * @cr: a cairo context
3557 * Gets the current compositing operator for a cairo context.
3559 * Return value: the current compositing operator.
3564 cairo_get_operator (cairo_t *cr)
3566 if (unlikely (cr->status))
3567 return CAIRO_GSTATE_OPERATOR_DEFAULT;
3569 return cr->backend->get_operator (cr);
3574 * cairo_get_opacity:
3575 * @cr: a cairo context
3577 * Gets the current compositing opacity for a cairo context.
3579 * Return value: the current compositing opacity.
3584 cairo_get_opacity (cairo_t *cr)
3586 if (unlikely (cr->status))
3589 return cr->backend->get_opacity (cr);
3594 * cairo_get_tolerance:
3595 * @cr: a cairo context
3597 * Gets the current tolerance value, as set by cairo_set_tolerance().
3599 * Return value: the current tolerance value.
3604 cairo_get_tolerance (cairo_t *cr)
3606 if (unlikely (cr->status))
3607 return CAIRO_GSTATE_TOLERANCE_DEFAULT;
3609 return cr->backend->get_tolerance (cr);
3611 slim_hidden_def (cairo_get_tolerance);
3614 * cairo_get_antialias:
3615 * @cr: a cairo context
3617 * Gets the current shape antialiasing mode, as set by
3618 * cairo_set_antialias().
3620 * Return value: the current shape antialiasing mode.
3625 cairo_get_antialias (cairo_t *cr)
3627 if (unlikely (cr->status))
3628 return CAIRO_ANTIALIAS_DEFAULT;
3630 return cr->backend->get_antialias (cr);
3634 * cairo_has_current_point:
3635 * @cr: a cairo context
3637 * Returns whether a current point is defined on the current path.
3638 * See cairo_get_current_point() for details on the current point.
3640 * Return value: whether a current point is defined.
3645 cairo_has_current_point (cairo_t *cr)
3647 if (unlikely (cr->status))
3650 return cr->backend->has_current_point (cr);
3654 * cairo_get_current_point:
3655 * @cr: a cairo context
3656 * @x: return value for X coordinate of the current point
3657 * @y: return value for Y coordinate of the current point
3659 * Gets the current point of the current path, which is
3660 * conceptually the final point reached by the path so far.
3662 * The current point is returned in the user-space coordinate
3663 * system. If there is no defined current point or if @cr is in an
3664 * error status, @x and @y will both be set to 0.0. It is possible to
3665 * check this in advance with cairo_has_current_point().
3667 * Most path construction functions alter the current point. See the
3668 * following for details on how they affect the current point:
3669 * cairo_new_path(), cairo_new_sub_path(),
3670 * cairo_append_path(), cairo_close_path(),
3671 * cairo_move_to(), cairo_line_to(), cairo_curve_to(),
3672 * cairo_rel_move_to(), cairo_rel_line_to(), cairo_rel_curve_to(),
3673 * cairo_arc(), cairo_arc_negative(), cairo_rectangle(),
3674 * cairo_text_path(), cairo_glyph_path(), cairo_stroke_to_path().
3676 * Some functions use and alter the current point but do not
3677 * otherwise change current path:
3678 * cairo_show_text().
3680 * Some functions unset the current path and as a result, current point:
3681 * cairo_fill(), cairo_stroke().
3686 cairo_get_current_point (cairo_t *cr, double *x_ret, double *y_ret)
3691 if (cr->status == CAIRO_STATUS_SUCCESS &&
3692 cr->backend->has_current_point (cr))
3694 cr->backend->get_current_point (cr, &x, &y);
3702 slim_hidden_def(cairo_get_current_point);
3705 * cairo_get_fill_rule:
3706 * @cr: a cairo context
3708 * Gets the current fill rule, as set by cairo_set_fill_rule().
3710 * Return value: the current fill rule.
3715 cairo_get_fill_rule (cairo_t *cr)
3717 if (unlikely (cr->status))
3718 return CAIRO_GSTATE_FILL_RULE_DEFAULT;
3720 return cr->backend->get_fill_rule (cr);
3724 * cairo_get_line_width:
3725 * @cr: a cairo context
3727 * This function returns the current line width value exactly as set by
3728 * cairo_set_line_width(). Note that the value is unchanged even if
3729 * the CTM has changed between the calls to cairo_set_line_width() and
3730 * cairo_get_line_width().
3732 * Return value: the current line width.
3737 cairo_get_line_width (cairo_t *cr)
3739 if (unlikely (cr->status))
3740 return CAIRO_GSTATE_LINE_WIDTH_DEFAULT;
3742 return cr->backend->get_line_width (cr);
3744 slim_hidden_def (cairo_get_line_width);
3747 * cairo_get_line_cap:
3748 * @cr: a cairo context
3750 * Gets the current line cap style, as set by cairo_set_line_cap().
3752 * Return value: the current line cap style.
3757 cairo_get_line_cap (cairo_t *cr)
3759 if (unlikely (cr->status))
3760 return CAIRO_GSTATE_LINE_CAP_DEFAULT;
3762 return cr->backend->get_line_cap (cr);
3766 * cairo_get_line_join:
3767 * @cr: a cairo context
3769 * Gets the current line join style, as set by cairo_set_line_join().
3771 * Return value: the current line join style.
3776 cairo_get_line_join (cairo_t *cr)
3778 if (unlikely (cr->status))
3779 return CAIRO_GSTATE_LINE_JOIN_DEFAULT;
3781 return cr->backend->get_line_join (cr);
3785 * cairo_get_miter_limit:
3786 * @cr: a cairo context
3788 * Gets the current miter limit, as set by cairo_set_miter_limit().
3790 * Return value: the current miter limit.
3795 cairo_get_miter_limit (cairo_t *cr)
3797 if (unlikely (cr->status))
3798 return CAIRO_GSTATE_MITER_LIMIT_DEFAULT;
3800 return cr->backend->get_miter_limit (cr);
3805 * @cr: a cairo context
3806 * @matrix: return value for the matrix
3808 * Stores the current transformation matrix (CTM) into @matrix.
3813 cairo_get_matrix (cairo_t *cr, cairo_matrix_t *matrix)
3815 if (unlikely (cr->status)) {
3816 cairo_matrix_init_identity (matrix);
3820 cr->backend->get_matrix (cr, matrix);
3822 slim_hidden_def (cairo_get_matrix);
3826 * @cr: a cairo context
3828 * Gets the target surface for the cairo context as passed to
3831 * This function will always return a valid pointer, but the result
3832 * can be a "nil" surface if @cr is already in an error state,
3833 * (ie. cairo_status() <literal>!=</literal> %CAIRO_STATUS_SUCCESS).
3834 * A nil surface is indicated by cairo_surface_status()
3835 * <literal>!=</literal> %CAIRO_STATUS_SUCCESS.
3837 * Return value: the target surface. This object is owned by cairo. To
3838 * keep a reference to it, you must call cairo_surface_reference().
3843 cairo_get_target (cairo_t *cr)
3845 if (unlikely (cr->status))
3846 return _cairo_surface_create_in_error (cr->status);
3848 return cr->backend->get_original_target (cr);
3850 slim_hidden_def (cairo_get_target);
3853 * cairo_get_group_target:
3854 * @cr: a cairo context
3856 * Gets the current destination surface for the context. This is either
3857 * the original target surface as passed to cairo_create() or the target
3858 * surface for the current group as started by the most recent call to
3859 * cairo_push_group() or cairo_push_group_with_content().
3861 * This function will always return a valid pointer, but the result
3862 * can be a "nil" surface if @cr is already in an error state,
3863 * (ie. cairo_status() <literal>!=</literal> %CAIRO_STATUS_SUCCESS).
3864 * A nil surface is indicated by cairo_surface_status()
3865 * <literal>!=</literal> %CAIRO_STATUS_SUCCESS.
3867 * Return value: the target surface. This object is owned by cairo. To
3868 * keep a reference to it, you must call cairo_surface_reference().
3873 cairo_get_group_target (cairo_t *cr)
3875 if (unlikely (cr->status))
3876 return _cairo_surface_create_in_error (cr->status);
3878 return cr->backend->get_current_target (cr);
3883 * @cr: a cairo context
3885 * Creates a copy of the current path and returns it to the user as a
3886 * #cairo_path_t. See #cairo_path_data_t for hints on how to iterate
3887 * over the returned data structure.
3889 * This function will always return a valid pointer, but the result
3890 * will have no data (<literal>data==%NULL</literal> and
3891 * <literal>num_data==0</literal>), if either of the following
3895 * <listitem>If there is insufficient memory to copy the path. In this
3896 * case <literal>path->status</literal> will be set to
3897 * %CAIRO_STATUS_NO_MEMORY.</listitem>
3898 * <listitem>If @cr is already in an error state. In this case
3899 * <literal>path->status</literal> will contain the same status that
3900 * would be returned by cairo_status().</listitem>
3903 * Return value: the copy of the current path. The caller owns the
3904 * returned object and should call cairo_path_destroy() when finished
3910 cairo_copy_path (cairo_t *cr)
3912 if (unlikely (cr->status))
3913 return _cairo_path_create_in_error (cr->status);
3915 return cr->backend->copy_path (cr);
3919 * cairo_copy_path_flat:
3920 * @cr: a cairo context
3922 * Gets a flattened copy of the current path and returns it to the
3923 * user as a #cairo_path_t. See #cairo_path_data_t for hints on
3924 * how to iterate over the returned data structure.
3926 * This function is like cairo_copy_path() except that any curves
3927 * in the path will be approximated with piecewise-linear
3928 * approximations, (accurate to within the current tolerance
3929 * value). That is, the result is guaranteed to not have any elements
3930 * of type %CAIRO_PATH_CURVE_TO which will instead be replaced by a
3931 * series of %CAIRO_PATH_LINE_TO elements.
3933 * This function will always return a valid pointer, but the result
3934 * will have no data (<literal>data==%NULL</literal> and
3935 * <literal>num_data==0</literal>), if either of the following
3939 * <listitem>If there is insufficient memory to copy the path. In this
3940 * case <literal>path->status</literal> will be set to
3941 * %CAIRO_STATUS_NO_MEMORY.</listitem>
3942 * <listitem>If @cr is already in an error state. In this case
3943 * <literal>path->status</literal> will contain the same status that
3944 * would be returned by cairo_status().</listitem>
3947 * Return value: the copy of the current path. The caller owns the
3948 * returned object and should call cairo_path_destroy() when finished
3954 cairo_copy_path_flat (cairo_t *cr)
3956 if (unlikely (cr->status))
3957 return _cairo_path_create_in_error (cr->status);
3959 return cr->backend->copy_path_flat (cr);
3963 * cairo_append_path:
3964 * @cr: a cairo context
3965 * @path: path to be appended
3967 * Append the @path onto the current path. The @path may be either the
3968 * return value from one of cairo_copy_path() or
3969 * cairo_copy_path_flat() or it may be constructed manually. See
3970 * #cairo_path_t for details on how the path data structure should be
3971 * initialized, and note that <literal>path->status</literal> must be
3972 * initialized to %CAIRO_STATUS_SUCCESS.
3977 cairo_append_path (cairo_t *cr,
3978 const cairo_path_t *path)
3980 cairo_status_t status;
3982 if (unlikely (cr->status))
3985 if (unlikely (path == NULL)) {
3986 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3990 if (unlikely (path->status)) {
3991 if (path->status > CAIRO_STATUS_SUCCESS &&
3992 path->status <= CAIRO_STATUS_LAST_STATUS)
3993 _cairo_set_error (cr, path->status);
3995 _cairo_set_error (cr, CAIRO_STATUS_INVALID_STATUS);
3999 if (path->num_data == 0)
4002 if (unlikely (path->data == NULL)) {
4003 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
4007 status = cr->backend->append_path (cr, path);
4008 if (unlikely (status))
4009 _cairo_set_error (cr, status);
4014 * @cr: a cairo context
4016 * Checks whether an error has previously occurred for this context.
4018 * Returns: the current status of this context, see #cairo_status_t
4023 cairo_status (cairo_t *cr)
4027 slim_hidden_def (cairo_status);