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 loosing 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.
223 cairo_create (cairo_surface_t *target)
225 if (unlikely (target == NULL))
226 return _cairo_create_in_error (_cairo_error (CAIRO_STATUS_NULL_POINTER));
227 if (unlikely (target->status))
228 return _cairo_create_in_error (target->status);
230 if (target->backend->create_context == NULL)
231 return _cairo_create_in_error (_cairo_error (CAIRO_STATUS_WRITE_ERROR));
233 return target->backend->create_context (target);
236 slim_hidden_def (cairo_create);
239 _cairo_init (cairo_t *cr,
240 const cairo_backend_t *backend)
242 CAIRO_REFERENCE_COUNT_INIT (&cr->ref_count, 1);
243 cr->status = CAIRO_STATUS_SUCCESS;
244 _cairo_user_data_array_init (&cr->user_data);
246 cr->backend = backend;
253 * Increases the reference count on @cr by one. This prevents
254 * @cr from being destroyed until a matching call to cairo_destroy()
257 * The number of references to a #cairo_t can be get using
258 * cairo_get_reference_count().
260 * Return value: the referenced #cairo_t.
263 cairo_reference (cairo_t *cr)
265 if (cr == NULL || CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
268 assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&cr->ref_count));
270 _cairo_reference_count_inc (&cr->ref_count);
276 _cairo_fini (cairo_t *cr)
278 _cairo_user_data_array_fini (&cr->user_data);
285 * Decreases the reference count on @cr by one. If the result
286 * is zero, then @cr and all associated resources are freed.
287 * See cairo_reference().
290 cairo_destroy (cairo_t *cr)
292 if (cr == NULL || CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
295 assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&cr->ref_count));
297 if (! _cairo_reference_count_dec_and_test (&cr->ref_count))
300 cr->backend->destroy (cr);
302 slim_hidden_def (cairo_destroy);
305 * cairo_get_user_data:
307 * @key: the address of the #cairo_user_data_key_t the user data was
310 * Return user data previously attached to @cr using the specified
311 * key. If no user data has been attached with the given key this
312 * function returns %NULL.
314 * Return value: the user data previously attached or %NULL.
319 cairo_get_user_data (cairo_t *cr,
320 const cairo_user_data_key_t *key)
322 return _cairo_user_data_array_get_data (&cr->user_data, key);
326 * cairo_set_user_data:
328 * @key: the address of a #cairo_user_data_key_t to attach the user data to
329 * @user_data: the user data to attach to the #cairo_t
330 * @destroy: a #cairo_destroy_func_t which will be called when the
331 * #cairo_t is destroyed or when new user data is attached using the
334 * Attach user data to @cr. To remove user data from a surface,
335 * call this function with the key that was used to set it and %NULL
338 * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a
339 * slot could not be allocated for the user data.
344 cairo_set_user_data (cairo_t *cr,
345 const cairo_user_data_key_t *key,
347 cairo_destroy_func_t destroy)
349 if (CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
352 return _cairo_user_data_array_set_data (&cr->user_data,
353 key, user_data, destroy);
357 * cairo_get_reference_count:
360 * Returns the current reference count of @cr.
362 * Return value: the current reference count of @cr. If the
363 * object is a nil object, 0 will be returned.
368 cairo_get_reference_count (cairo_t *cr)
370 if (cr == NULL || CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
373 return CAIRO_REFERENCE_COUNT_GET_VALUE (&cr->ref_count);
380 * Makes a copy of the current state of @cr and saves it
381 * on an internal stack of saved states for @cr. When
382 * cairo_restore() is called, @cr will be restored to
383 * the saved state. Multiple calls to cairo_save() and
384 * cairo_restore() can be nested; each call to cairo_restore()
385 * restores the state from the matching paired cairo_save().
387 * It isn't necessary to clear all saved states before
388 * a #cairo_t is freed. If the reference count of a #cairo_t
389 * drops to zero in response to a call to cairo_destroy(),
390 * any saved states will be freed along with the #cairo_t.
393 cairo_save (cairo_t *cr)
395 cairo_status_t status;
397 if (unlikely (cr->status))
400 status = cr->backend->save (cr);
401 if (unlikely (status))
402 _cairo_set_error (cr, status);
404 slim_hidden_def(cairo_save);
410 * Restores @cr to the state saved by a preceding call to
411 * cairo_save() and removes that state from the stack of
415 cairo_restore (cairo_t *cr)
417 cairo_status_t status;
419 if (unlikely (cr->status))
422 status = cr->backend->restore (cr);
423 if (unlikely (status))
424 _cairo_set_error (cr, status);
426 slim_hidden_def(cairo_restore);
430 * @cr: a cairo context
432 * Temporarily redirects drawing to an intermediate surface known as a
433 * group. The redirection lasts until the group is completed by a call
434 * to cairo_pop_group() or cairo_pop_group_to_source(). These calls
435 * provide the result of any drawing to the group as a pattern,
436 * (either as an explicit object, or set as the source pattern).
438 * This group functionality can be convenient for performing
439 * intermediate compositing. One common use of a group is to render
440 * objects as opaque within the group, (so that they occlude each
441 * other), and then blend the result with translucence onto the
444 * Groups can be nested arbitrarily deep by making balanced calls to
445 * cairo_push_group()/cairo_pop_group(). Each call pushes/pops the new
446 * target group onto/from a stack.
448 * The cairo_push_group() function calls cairo_save() so that any
449 * changes to the graphics state will not be visible outside the
450 * group, (the pop_group functions call cairo_restore()).
452 * By default the intermediate group will have a content type of
453 * %CAIRO_CONTENT_COLOR_ALPHA. Other content types can be chosen for
454 * the group by using cairo_push_group_with_content() instead.
456 * As an example, here is how one might fill and stroke a path with
457 * translucence, but without any portion of the fill being visible
460 * <informalexample><programlisting>
461 * cairo_push_group (cr);
462 * cairo_set_source (cr, fill_pattern);
463 * cairo_fill_preserve (cr);
464 * cairo_set_source (cr, stroke_pattern);
466 * cairo_pop_group_to_source (cr);
467 * cairo_paint_with_alpha (cr, alpha);
468 * </programlisting></informalexample>
473 cairo_push_group (cairo_t *cr)
475 cairo_push_group_with_content (cr, CAIRO_CONTENT_COLOR_ALPHA);
479 * cairo_push_group_with_content:
480 * @cr: a cairo context
481 * @content: a #cairo_content_t indicating the type of group that
484 * Temporarily redirects drawing to an intermediate surface known as a
485 * group. The redirection lasts until the group is completed by a call
486 * to cairo_pop_group() or cairo_pop_group_to_source(). These calls
487 * provide the result of any drawing to the group as a pattern,
488 * (either as an explicit object, or set as the source pattern).
490 * The group will have a content type of @content. The ability to
491 * control this content type is the only distinction between this
492 * function and cairo_push_group() which you should see for a more
493 * detailed description of group rendering.
498 cairo_push_group_with_content (cairo_t *cr, cairo_content_t content)
500 cairo_status_t status;
502 if (unlikely (cr->status))
505 status = cr->backend->push_group (cr, content);
506 if (unlikely (status))
507 _cairo_set_error (cr, status);
509 slim_hidden_def(cairo_push_group_with_content);
513 * @cr: a cairo context
515 * Terminates the redirection begun by a call to cairo_push_group() or
516 * cairo_push_group_with_content() and returns a new pattern
517 * containing the results of all drawing operations performed to the
520 * The cairo_pop_group() function calls cairo_restore(), (balancing a
521 * call to cairo_save() by the push_group function), so that any
522 * changes to the graphics state will not be visible outside the
525 * Return value: a newly created (surface) pattern containing the
526 * results of all drawing operations performed to the group. The
527 * caller owns the returned object and should call
528 * cairo_pattern_destroy() when finished with it.
533 cairo_pop_group (cairo_t *cr)
535 cairo_pattern_t *group_pattern;
537 if (unlikely (cr->status))
538 return _cairo_pattern_create_in_error (cr->status);
540 group_pattern = cr->backend->pop_group (cr);
541 if (unlikely (group_pattern->status))
542 _cairo_set_error (cr, group_pattern->status);
544 return group_pattern;
546 slim_hidden_def(cairo_pop_group);
549 * cairo_pop_group_to_source:
550 * @cr: a cairo context
552 * Terminates the redirection begun by a call to cairo_push_group() or
553 * cairo_push_group_with_content() and installs the resulting pattern
554 * as the source pattern in the given cairo context.
556 * The behavior of this function is equivalent to the sequence of
559 * <informalexample><programlisting>
560 * cairo_pattern_t *group = cairo_pop_group (cr);
561 * cairo_set_source (cr, group);
562 * cairo_pattern_destroy (group);
563 * </programlisting></informalexample>
565 * but is more convenient as their is no need for a variable to store
566 * the short-lived pointer to the pattern.
568 * The cairo_pop_group() function calls cairo_restore(), (balancing a
569 * call to cairo_save() by the push_group function), so that any
570 * changes to the graphics state will not be visible outside the
576 cairo_pop_group_to_source (cairo_t *cr)
578 cairo_pattern_t *group_pattern;
580 group_pattern = cairo_pop_group (cr);
581 cairo_set_source (cr, group_pattern);
582 cairo_pattern_destroy (group_pattern);
586 * cairo_set_operator:
588 * @op: a compositing operator, specified as a #cairo_operator_t
590 * Sets the compositing operator to be used for all drawing
591 * operations. See #cairo_operator_t for details on the semantics of
592 * each available compositing operator.
594 * The default operator is %CAIRO_OPERATOR_OVER.
597 cairo_set_operator (cairo_t *cr, cairo_operator_t op)
599 cairo_status_t status;
601 if (unlikely (cr->status))
604 status = cr->backend->set_operator (cr, op);
605 if (unlikely (status))
606 _cairo_set_error (cr, status);
608 slim_hidden_def (cairo_set_operator);
615 * @opacity: the level of opacity to use when compositing
617 * Sets the compositing opacity to be used for all drawing
618 * operations. The effect is to fade out the operations
619 * using the alpha value.
621 * The default opacity is 1.
624 cairo_set_opacity (cairo_t *cr, double opacity)
626 cairo_status_t status;
628 if (unlikely (cr->status))
631 status = cr->backend->set_opacity (cr, opacity);
632 if (unlikely (status))
633 _cairo_set_error (cr, status);
638 * cairo_set_source_rgb
639 * @cr: a cairo context
640 * @red: red component of color
641 * @green: green component of color
642 * @blue: blue component of color
644 * Sets the source pattern within @cr to an opaque color. This opaque
645 * color will then be used for any subsequent drawing operation until
646 * a new source pattern is set.
648 * The color components are floating point numbers in the range 0 to
649 * 1. If the values passed in are outside that range, they will be
652 * The default source pattern is opaque black, (that is, it is
653 * equivalent to cairo_set_source_rgb(cr, 0.0, 0.0, 0.0)).
656 cairo_set_source_rgb (cairo_t *cr, double red, double green, double blue)
658 cairo_status_t status;
660 if (unlikely (cr->status))
663 status = cr->backend->set_source_rgba (cr, red, green, blue, 1.);
664 if (unlikely (status))
665 _cairo_set_error (cr, status);
667 slim_hidden_def (cairo_set_source_rgb);
670 * cairo_set_source_rgba:
671 * @cr: a cairo context
672 * @red: red component of color
673 * @green: green component of color
674 * @blue: blue component of color
675 * @alpha: alpha component of color
677 * Sets the source pattern within @cr to a translucent color. This
678 * color will then be used for any subsequent drawing operation until
679 * a new source pattern is set.
681 * The color and alpha components are floating point numbers in the
682 * range 0 to 1. If the values passed in are outside that range, they
685 * The default source pattern is opaque black, (that is, it is
686 * equivalent to cairo_set_source_rgba(cr, 0.0, 0.0, 0.0, 1.0)).
689 cairo_set_source_rgba (cairo_t *cr,
690 double red, double green, double blue,
693 cairo_status_t status;
695 if (unlikely (cr->status))
698 status = cr->backend->set_source_rgba (cr, red, green, blue, alpha);
699 if (unlikely (status))
700 _cairo_set_error (cr, status);
704 * cairo_set_source_surface:
705 * @cr: a cairo context
706 * @surface: a surface to be used to set the source pattern
707 * @x: User-space X coordinate for surface origin
708 * @y: User-space Y coordinate for surface origin
710 * This is a convenience function for creating a pattern from @surface
711 * and setting it as the source in @cr with cairo_set_source().
713 * The @x and @y parameters give the user-space coordinate at which
714 * the surface origin should appear. (The surface origin is its
715 * upper-left corner before any transformation has been applied.) The
716 * @x and @y parameters are negated and then set as translation values
717 * in the pattern matrix.
719 * Other than the initial translation pattern matrix, as described
720 * above, all other pattern attributes, (such as its extend mode), are
721 * set to the default values as in cairo_pattern_create_for_surface().
722 * The resulting pattern can be queried with cairo_get_source() so
723 * that these attributes can be modified if desired, (eg. to create a
724 * repeating pattern with cairo_pattern_set_extend()).
727 cairo_set_source_surface (cairo_t *cr,
728 cairo_surface_t *surface,
732 cairo_status_t status;
734 if (unlikely (cr->status))
737 if (unlikely (surface == NULL)) {
738 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
742 status = cr->backend->set_source_surface (cr, surface, x, y);
743 if (unlikely (status))
744 _cairo_set_error (cr, status);
746 slim_hidden_def (cairo_set_source_surface);
750 * @cr: a cairo context
751 * @source: a #cairo_pattern_t to be used as the source for
752 * subsequent drawing operations.
754 * Sets the source pattern within @cr to @source. This pattern
755 * will then be used for any subsequent drawing operation until a new
756 * source pattern is set.
758 * Note: The pattern's transformation matrix will be locked to the
759 * user space in effect at the time of cairo_set_source(). This means
760 * that further modifications of the current transformation matrix
761 * will not affect the source pattern. See cairo_pattern_set_matrix().
763 * The default source pattern is a solid pattern that is opaque black,
764 * (that is, it is equivalent to cairo_set_source_rgb(cr, 0.0, 0.0,
768 cairo_set_source (cairo_t *cr, cairo_pattern_t *source)
770 cairo_status_t status;
772 if (unlikely (cr->status))
775 if (unlikely (source == NULL)) {
776 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
780 if (unlikely (source->status)) {
781 _cairo_set_error (cr, source->status);
785 status = cr->backend->set_source (cr, source);
786 if (unlikely (status))
787 _cairo_set_error (cr, status);
789 slim_hidden_def (cairo_set_source);
793 * @cr: a cairo context
795 * Gets the current source pattern for @cr.
797 * Return value: the current source pattern. This object is owned by
798 * cairo. To keep a reference to it, you must call
799 * cairo_pattern_reference().
802 cairo_get_source (cairo_t *cr)
804 if (unlikely (cr->status))
805 return _cairo_pattern_create_in_error (cr->status);
807 return cr->backend->get_source (cr);
811 * cairo_set_tolerance:
813 * @tolerance: the tolerance, in device units (typically pixels)
815 * Sets the tolerance used when converting paths into trapezoids.
816 * Curved segments of the path will be subdivided until the maximum
817 * deviation between the original path and the polygonal approximation
818 * is less than @tolerance. The default value is 0.1. A larger
819 * value will give better performance, a smaller value, better
820 * appearance. (Reducing the value from the default value of 0.1
821 * is unlikely to improve appearance significantly.) The accuracy of paths
822 * within Cairo is limited by the precision of its internal arithmetic, and
823 * the prescribed @tolerance is restricted to the smallest
824 * representable internal value.
827 cairo_set_tolerance (cairo_t *cr, double tolerance)
829 cairo_status_t status;
831 if (unlikely (cr->status))
834 status = cr->backend->set_tolerance (cr, tolerance);
835 if (unlikely (status))
836 _cairo_set_error (cr, status);
838 slim_hidden_def (cairo_set_tolerance);
841 * cairo_set_antialias:
843 * @antialias: the new antialiasing mode
845 * Set the antialiasing mode of the rasterizer used for drawing shapes.
846 * This value is a hint, and a particular backend may or may not support
847 * a particular value. At the current time, no backend supports
848 * %CAIRO_ANTIALIAS_SUBPIXEL when drawing shapes.
850 * Note that this option does not affect text rendering, instead see
851 * cairo_font_options_set_antialias().
854 cairo_set_antialias (cairo_t *cr, cairo_antialias_t antialias)
856 cairo_status_t status;
858 if (unlikely (cr->status))
861 status = cr->backend->set_antialias (cr, antialias);
862 if (unlikely (status))
863 _cairo_set_error (cr, status);
867 * cairo_set_fill_rule:
869 * @fill_rule: a fill rule, specified as a #cairo_fill_rule_t
871 * Set the current fill rule within the cairo context. The fill rule
872 * is used to determine which regions are inside or outside a complex
873 * (potentially self-intersecting) path. The current fill rule affects
874 * both cairo_fill() and cairo_clip(). See #cairo_fill_rule_t for details
875 * on the semantics of each available fill rule.
877 * The default fill rule is %CAIRO_FILL_RULE_WINDING.
880 cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule)
882 cairo_status_t status;
884 if (unlikely (cr->status))
887 status = cr->backend->set_fill_rule (cr, fill_rule);
888 if (unlikely (status))
889 _cairo_set_error (cr, status);
893 * cairo_set_line_width:
895 * @width: a line width
897 * Sets the current line width within the cairo context. The line
898 * width value specifies the diameter of a pen that is circular in
899 * user space, (though device-space pen may be an ellipse in general
900 * due to scaling/shear/rotation of the CTM).
902 * Note: When the description above refers to user space and CTM it
903 * refers to the user space and CTM in effect at the time of the
904 * stroking operation, not the user space and CTM in effect at the
905 * time of the call to cairo_set_line_width(). The simplest usage
906 * makes both of these spaces identical. That is, if there is no
907 * change to the CTM between a call to cairo_set_line_width() and the
908 * stroking operation, then one can just pass user-space values to
909 * cairo_set_line_width() and ignore this note.
911 * As with the other stroke parameters, the current line width is
912 * examined by cairo_stroke(), cairo_stroke_extents(), and
913 * cairo_stroke_to_path(), but does not have any effect during path
916 * The default line width value is 2.0.
919 cairo_set_line_width (cairo_t *cr, double width)
921 cairo_status_t status;
923 if (unlikely (cr->status))
929 status = cr->backend->set_line_width (cr, width);
930 if (unlikely (status))
931 _cairo_set_error (cr, status);
933 slim_hidden_def (cairo_set_line_width);
936 * cairo_set_line_cap:
937 * @cr: a cairo context
938 * @line_cap: a line cap style
940 * Sets the current line cap style within the cairo context. See
941 * #cairo_line_cap_t for details about how the available line cap
944 * As with the other stroke parameters, the current line cap style is
945 * examined by cairo_stroke(), cairo_stroke_extents(), and
946 * cairo_stroke_to_path(), but does not have any effect during path
949 * The default line cap style is %CAIRO_LINE_CAP_BUTT.
952 cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap)
954 cairo_status_t status;
956 if (unlikely (cr->status))
959 status = cr->backend->set_line_cap (cr, line_cap);
960 if (unlikely (status))
961 _cairo_set_error (cr, status);
963 slim_hidden_def (cairo_set_line_cap);
966 * cairo_set_line_join:
967 * @cr: a cairo context
968 * @line_join: a line join style
970 * Sets the current line join style within the cairo context. See
971 * #cairo_line_join_t for details about how the available line join
974 * As with the other stroke parameters, the current line join style is
975 * examined by cairo_stroke(), cairo_stroke_extents(), and
976 * cairo_stroke_to_path(), but does not have any effect during path
979 * The default line join style is %CAIRO_LINE_JOIN_MITER.
982 cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join)
984 cairo_status_t status;
986 if (unlikely (cr->status))
989 status = cr->backend->set_line_join (cr, line_join);
990 if (unlikely (status))
991 _cairo_set_error (cr, status);
993 slim_hidden_def (cairo_set_line_join);
997 * @cr: a cairo context
998 * @dashes: an array specifying alternate lengths of on and off stroke portions
999 * @num_dashes: the length of the dashes array
1000 * @offset: an offset into the dash pattern at which the stroke should start
1002 * Sets the dash pattern to be used by cairo_stroke(). A dash pattern
1003 * is specified by @dashes, an array of positive values. Each value
1004 * provides the length of alternate "on" and "off" portions of the
1005 * stroke. The @offset specifies an offset into the pattern at which
1006 * the stroke begins.
1008 * Each "on" segment will have caps applied as if the segment were a
1009 * separate sub-path. In particular, it is valid to use an "on" length
1010 * of 0.0 with %CAIRO_LINE_CAP_ROUND or %CAIRO_LINE_CAP_SQUARE in order
1011 * to distributed dots or squares along a path.
1013 * Note: The length values are in user-space units as evaluated at the
1014 * time of stroking. This is not necessarily the same as the user
1015 * space at the time of cairo_set_dash().
1017 * If @num_dashes is 0 dashing is disabled.
1019 * If @num_dashes is 1 a symmetric pattern is assumed with alternating
1020 * on and off portions of the size specified by the single value in
1023 * If any value in @dashes is negative, or if all values are 0, then
1024 * @cr will be put into an error state with a status of
1025 * %CAIRO_STATUS_INVALID_DASH.
1028 cairo_set_dash (cairo_t *cr,
1029 const double *dashes,
1033 cairo_status_t status;
1035 if (unlikely (cr->status))
1038 status = cr->backend->set_dash (cr, dashes, num_dashes, offset);
1039 if (unlikely (status))
1040 _cairo_set_error (cr, status);
1044 * cairo_get_dash_count:
1047 * This function returns the length of the dash array in @cr (0 if dashing
1048 * is not currently in effect).
1050 * See also cairo_set_dash() and cairo_get_dash().
1052 * Return value: the length of the dash array, or 0 if no dash array set.
1057 cairo_get_dash_count (cairo_t *cr)
1061 if (unlikely (cr->status))
1064 cr->backend->get_dash (cr, NULL, &num_dashes, NULL);
1072 * @dashes: return value for the dash array, or %NULL
1073 * @offset: return value for the current dash offset, or %NULL
1075 * Gets the current dash array. If not %NULL, @dashes should be big
1076 * enough to hold at least the number of values returned by
1077 * cairo_get_dash_count().
1082 cairo_get_dash (cairo_t *cr,
1086 if (unlikely (cr->status))
1089 cr->backend->get_dash (cr, dashes, NULL, offset);
1093 * cairo_set_miter_limit:
1094 * @cr: a cairo context
1095 * @limit: miter limit to set
1097 * Sets the current miter limit within the cairo context.
1099 * If the current line join style is set to %CAIRO_LINE_JOIN_MITER
1100 * (see cairo_set_line_join()), the miter limit is used to determine
1101 * whether the lines should be joined with a bevel instead of a miter.
1102 * Cairo divides the length of the miter by the line width.
1103 * If the result is greater than the miter limit, the style is
1104 * converted to a bevel.
1106 * As with the other stroke parameters, the current line miter limit is
1107 * examined by cairo_stroke(), cairo_stroke_extents(), and
1108 * cairo_stroke_to_path(), but does not have any effect during path
1111 * The default miter limit value is 10.0, which will convert joins
1112 * with interior angles less than 11 degrees to bevels instead of
1113 * miters. For reference, a miter limit of 2.0 makes the miter cutoff
1114 * at 60 degrees, and a miter limit of 1.414 makes the cutoff at 90
1117 * A miter limit for a desired angle can be computed as: miter limit =
1121 cairo_set_miter_limit (cairo_t *cr, double limit)
1123 cairo_status_t status;
1125 if (unlikely (cr->status))
1128 status = cr->backend->set_miter_limit (cr, limit);
1129 if (unlikely (status))
1130 _cairo_set_error (cr, status);
1135 * @cr: a cairo context
1136 * @tx: amount to translate in the X direction
1137 * @ty: amount to translate in the Y direction
1139 * Modifies the current transformation matrix (CTM) by translating the
1140 * user-space origin by (@tx, @ty). This offset is interpreted as a
1141 * user-space coordinate according to the CTM in place before the new
1142 * call to cairo_translate(). In other words, the translation of the
1143 * user-space origin takes place after any existing transformation.
1146 cairo_translate (cairo_t *cr, double tx, double ty)
1148 cairo_status_t status;
1150 if (unlikely (cr->status))
1153 status = cr->backend->translate (cr, tx, ty);
1154 if (unlikely (status))
1155 _cairo_set_error (cr, status);
1157 slim_hidden_def (cairo_translate);
1161 * @cr: a cairo context
1162 * @sx: scale factor for the X dimension
1163 * @sy: scale factor for the Y dimension
1165 * Modifies the current transformation matrix (CTM) by scaling the X
1166 * and Y user-space axes by @sx and @sy respectively. The scaling of
1167 * the axes takes place after any existing transformation of user
1171 cairo_scale (cairo_t *cr, double sx, double sy)
1173 cairo_status_t status;
1175 if (unlikely (cr->status))
1178 status = cr->backend->scale (cr, sx, sy);
1179 if (unlikely (status))
1180 _cairo_set_error (cr, status);
1182 slim_hidden_def (cairo_scale);
1186 * @cr: a cairo context
1187 * @angle: angle (in radians) by which the user-space axes will be
1190 * Modifies the current transformation matrix (CTM) by rotating the
1191 * user-space axes by @angle radians. The rotation of the axes takes
1192 * places after any existing transformation of user space. The
1193 * rotation direction for positive angles is from the positive X axis
1194 * toward the positive Y axis.
1197 cairo_rotate (cairo_t *cr, double angle)
1199 cairo_status_t status;
1201 if (unlikely (cr->status))
1204 status = cr->backend->rotate (cr, angle);
1205 if (unlikely (status))
1206 _cairo_set_error (cr, status);
1211 * @cr: a cairo context
1212 * @matrix: a transformation to be applied to the user-space axes
1214 * Modifies the current transformation matrix (CTM) by applying
1215 * @matrix as an additional transformation. The new transformation of
1216 * user space takes place after any existing transformation.
1219 cairo_transform (cairo_t *cr,
1220 const cairo_matrix_t *matrix)
1222 cairo_status_t status;
1224 if (unlikely (cr->status))
1227 status = cr->backend->transform (cr, matrix);
1228 if (unlikely (status))
1229 _cairo_set_error (cr, status);
1231 slim_hidden_def (cairo_transform);
1235 * @cr: a cairo context
1236 * @matrix: a transformation matrix from user space to device space
1238 * Modifies the current transformation matrix (CTM) by setting it
1242 cairo_set_matrix (cairo_t *cr,
1243 const cairo_matrix_t *matrix)
1245 cairo_status_t status;
1247 if (unlikely (cr->status))
1250 status = cr->backend->set_matrix (cr, matrix);
1251 if (unlikely (status))
1252 _cairo_set_error (cr, status);
1254 slim_hidden_def (cairo_set_matrix);
1257 * cairo_identity_matrix:
1258 * @cr: a cairo context
1260 * Resets the current transformation matrix (CTM) by setting it equal
1261 * to the identity matrix. That is, the user-space and device-space
1262 * axes will be aligned and one user-space unit will transform to one
1263 * device-space unit.
1266 cairo_identity_matrix (cairo_t *cr)
1268 cairo_status_t status;
1270 if (unlikely (cr->status))
1273 status = cr->backend->set_identity_matrix (cr);
1274 if (unlikely (status))
1275 _cairo_set_error (cr, status);
1279 * cairo_user_to_device:
1280 * @cr: a cairo context
1281 * @x: X value of coordinate (in/out parameter)
1282 * @y: Y value of coordinate (in/out parameter)
1284 * Transform a coordinate from user space to device space by
1285 * multiplying the given point by the current transformation matrix
1289 cairo_user_to_device (cairo_t *cr, double *x, double *y)
1291 if (unlikely (cr->status))
1294 cr->backend->user_to_device (cr, x, y);
1296 slim_hidden_def (cairo_user_to_device);
1299 * cairo_user_to_device_distance:
1300 * @cr: a cairo context
1301 * @dx: X component of a distance vector (in/out parameter)
1302 * @dy: Y component of a distance vector (in/out parameter)
1304 * Transform a distance vector from user space to device space. This
1305 * function is similar to cairo_user_to_device() except that the
1306 * translation components of the CTM will be ignored when transforming
1310 cairo_user_to_device_distance (cairo_t *cr, double *dx, double *dy)
1312 if (unlikely (cr->status))
1315 cr->backend->user_to_device_distance (cr, dx, dy);
1317 slim_hidden_def (cairo_user_to_device_distance);
1320 * cairo_device_to_user:
1322 * @x: X value of coordinate (in/out parameter)
1323 * @y: Y value of coordinate (in/out parameter)
1325 * Transform a coordinate from device space to user space by
1326 * multiplying the given point by the inverse of the current
1327 * transformation matrix (CTM).
1330 cairo_device_to_user (cairo_t *cr, double *x, double *y)
1332 if (unlikely (cr->status))
1335 cr->backend->device_to_user (cr, x, y);
1337 slim_hidden_def (cairo_device_to_user);
1340 * cairo_device_to_user_distance:
1341 * @cr: a cairo context
1342 * @dx: X component of a distance vector (in/out parameter)
1343 * @dy: Y component of a distance vector (in/out parameter)
1345 * Transform a distance vector from device space to user space. This
1346 * function is similar to cairo_device_to_user() except that the
1347 * translation components of the inverse CTM will be ignored when
1348 * transforming (@dx,@dy).
1351 cairo_device_to_user_distance (cairo_t *cr, double *dx, double *dy)
1353 if (unlikely (cr->status))
1356 cr->backend->device_to_user_distance (cr, dx, dy);
1361 * @cr: a cairo context
1363 * Clears the current path. After this call there will be no path and
1367 cairo_new_path (cairo_t *cr)
1369 cairo_status_t status;
1371 if (unlikely (cr->status))
1374 status = cr->backend->new_path (cr);
1375 if (unlikely (status))
1376 _cairo_set_error (cr, status);
1378 slim_hidden_def(cairo_new_path);
1381 * cairo_new_sub_path:
1382 * @cr: a cairo context
1384 * Begin a new sub-path. Note that the existing path is not
1385 * affected. After this call there will be no current point.
1387 * In many cases, this call is not needed since new sub-paths are
1388 * frequently started with cairo_move_to().
1390 * A call to cairo_new_sub_path() is particularly useful when
1391 * beginning a new sub-path with one of the cairo_arc() calls. This
1392 * makes things easier as it is no longer necessary to manually
1393 * compute the arc's initial coordinates for a call to
1399 cairo_new_sub_path (cairo_t *cr)
1401 cairo_status_t status;
1403 if (unlikely (cr->status))
1406 status = cr->backend->new_sub_path (cr);
1407 if (unlikely (status))
1408 _cairo_set_error (cr, status);
1413 * @cr: a cairo context
1414 * @x: the X coordinate of the new position
1415 * @y: the Y coordinate of the new position
1417 * Begin a new sub-path. After this call the current point will be (@x,
1421 cairo_move_to (cairo_t *cr, double x, double y)
1423 cairo_status_t status;
1425 if (unlikely (cr->status))
1428 status = cr->backend->move_to (cr, x, y);
1429 if (unlikely (status))
1430 _cairo_set_error (cr, status);
1432 slim_hidden_def(cairo_move_to);
1437 * @cr: a cairo context
1438 * @x: the X coordinate of the end of the new line
1439 * @y: the Y coordinate of the end of the new line
1441 * Adds a line to the path from the current point to position (@x, @y)
1442 * in user-space coordinates. After this call the current point
1445 * If there is no current point before the call to cairo_line_to()
1446 * this function will behave as cairo_move_to(@cr, @x, @y).
1449 cairo_line_to (cairo_t *cr, double x, double y)
1451 cairo_status_t status;
1453 if (unlikely (cr->status))
1456 status = cr->backend->line_to (cr, x, y);
1457 if (unlikely (status))
1458 _cairo_set_error (cr, status);
1460 slim_hidden_def (cairo_line_to);
1464 * @cr: a cairo context
1465 * @x1: the X coordinate of the first control point
1466 * @y1: the Y coordinate of the first control point
1467 * @x2: the X coordinate of the second control point
1468 * @y2: the Y coordinate of the second control point
1469 * @x3: the X coordinate of the end of the curve
1470 * @y3: the Y coordinate of the end of the curve
1472 * Adds a cubic Bézier spline to the path from the current point to
1473 * position (@x3, @y3) in user-space coordinates, using (@x1, @y1) and
1474 * (@x2, @y2) as the control points. After this call the current point
1475 * will be (@x3, @y3).
1477 * If there is no current point before the call to cairo_curve_to()
1478 * this function will behave as if preceded by a call to
1479 * cairo_move_to(@cr, @x1, @y1).
1482 cairo_curve_to (cairo_t *cr,
1483 double x1, double y1,
1484 double x2, double y2,
1485 double x3, double y3)
1487 cairo_status_t status;
1489 if (unlikely (cr->status))
1492 status = cr->backend->curve_to (cr,
1496 if (unlikely (status))
1497 _cairo_set_error (cr, status);
1499 slim_hidden_def (cairo_curve_to);
1503 * @cr: a cairo context
1504 * @xc: X position of the center of the arc
1505 * @yc: Y position of the center of the arc
1506 * @radius: the radius of the arc
1507 * @angle1: the start angle, in radians
1508 * @angle2: the end angle, in radians
1510 * Adds a circular arc of the given @radius to the current path. The
1511 * arc is centered at (@xc, @yc), begins at @angle1 and proceeds in
1512 * the direction of increasing angles to end at @angle2. If @angle2 is
1513 * less than @angle1 it will be progressively increased by
1514 * <literal>2*M_PI</literal> until it is greater than @angle1.
1516 * If there is a current point, an initial line segment will be added
1517 * to the path to connect the current point to the beginning of the
1518 * arc. If this initial line is undesired, it can be avoided by
1519 * calling cairo_new_sub_path() before calling cairo_arc().
1521 * Angles are measured in radians. An angle of 0.0 is in the direction
1522 * of the positive X axis (in user space). An angle of
1523 * <literal>M_PI/2.0</literal> radians (90 degrees) is in the
1524 * direction of the positive Y axis (in user space). Angles increase
1525 * in the direction from the positive X axis toward the positive Y
1526 * axis. So with the default transformation matrix, angles increase in
1527 * a clockwise direction.
1529 * (To convert from degrees to radians, use <literal>degrees * (M_PI /
1532 * This function gives the arc in the direction of increasing angles;
1533 * see cairo_arc_negative() to get the arc in the direction of
1534 * decreasing angles.
1536 * The arc is circular in user space. To achieve an elliptical arc,
1537 * you can scale the current transformation matrix by different
1538 * amounts in the X and Y directions. For example, to draw an ellipse
1539 * in the box given by @x, @y, @width, @height:
1541 * <informalexample><programlisting>
1543 * cairo_translate (cr, x + width / 2., y + height / 2.);
1544 * cairo_scale (cr, width / 2., height / 2.);
1545 * cairo_arc (cr, 0., 0., 1., 0., 2 * M_PI);
1546 * cairo_restore (cr);
1547 * </programlisting></informalexample>
1550 cairo_arc (cairo_t *cr,
1551 double xc, double yc,
1553 double angle1, double angle2)
1555 cairo_status_t status;
1557 if (unlikely (cr->status))
1560 if (angle2 < angle1) {
1561 /* increase angle2 by multiples of full circle until it
1562 * satisfies angle2 >= angle1 */
1563 angle2 = fmod (angle2 - angle1, 2 * M_PI);
1569 status = cr->backend->arc (cr, xc, yc, radius, angle1, angle2, TRUE);
1570 if (unlikely (status))
1571 _cairo_set_error (cr, status);
1575 * cairo_arc_negative:
1576 * @cr: a cairo context
1577 * @xc: X position of the center of the arc
1578 * @yc: Y position of the center of the arc
1579 * @radius: the radius of the arc
1580 * @angle1: the start angle, in radians
1581 * @angle2: the end angle, in radians
1583 * Adds a circular arc of the given @radius to the current path. The
1584 * arc is centered at (@xc, @yc), begins at @angle1 and proceeds in
1585 * the direction of decreasing angles to end at @angle2. If @angle2 is
1586 * greater than @angle1 it will be progressively decreased by
1587 * <literal>2*M_PI</literal> until it is less than @angle1.
1589 * See cairo_arc() for more details. This function differs only in the
1590 * direction of the arc between the two angles.
1593 cairo_arc_negative (cairo_t *cr,
1594 double xc, double yc,
1596 double angle1, double angle2)
1598 cairo_status_t status;
1600 if (unlikely (cr->status))
1603 if (angle2 > angle1) {
1604 /* decrease angle2 by multiples of full circle until it
1605 * satisfies angle2 <= angle1 */
1606 angle2 = fmod (angle2 - angle1, 2 * M_PI);
1612 status = cr->backend->arc (cr, xc, yc, radius, angle1, angle2, FALSE);
1613 if (unlikely (status))
1614 _cairo_set_error (cr, status);
1619 cairo_arc_to (cairo_t *cr,
1620 double x1, double y1,
1621 double x2, double y2,
1624 cairo_status_t status;
1626 if (unlikely (cr->status))
1629 status = cr->backend->arc_to (cr, x1, y1, x2, y2, radius);
1630 if (unlikely (status))
1631 _cairo_set_error (cr, status);
1635 cairo_rel_arc_to (cairo_t *cr,
1636 double dx1, double dy1,
1637 double dx2, double dy2,
1640 cairo_status_t status;
1642 if (unlikely (cr->status))
1645 status = cr->backend->rel_arc_to (cr, dx1, dy1, dx2, dy2, radius);
1646 if (unlikely (status))
1647 _cairo_set_error (cr, status);
1652 * cairo_rel_move_to:
1653 * @cr: a cairo context
1657 * Begin a new sub-path. After this call the current point will offset
1660 * Given a current point of (x, y), cairo_rel_move_to(@cr, @dx, @dy)
1661 * is logically equivalent to cairo_move_to(@cr, x + @dx, y + @dy).
1663 * It is an error to call this function with no current point. Doing
1664 * so will cause @cr to shutdown with a status of
1665 * %CAIRO_STATUS_NO_CURRENT_POINT.
1668 cairo_rel_move_to (cairo_t *cr, double dx, double dy)
1670 cairo_status_t status;
1672 if (unlikely (cr->status))
1675 status = cr->backend->rel_move_to (cr, dx, dy);
1676 if (unlikely (status))
1677 _cairo_set_error (cr, status);
1681 * cairo_rel_line_to:
1682 * @cr: a cairo context
1683 * @dx: the X offset to the end of the new line
1684 * @dy: the Y offset to the end of the new line
1686 * Relative-coordinate version of cairo_line_to(). Adds a line to the
1687 * path from the current point to a point that is offset from the
1688 * current point by (@dx, @dy) in user space. After this call the
1689 * current point will be offset by (@dx, @dy).
1691 * Given a current point of (x, y), cairo_rel_line_to(@cr, @dx, @dy)
1692 * is logically equivalent to cairo_line_to(@cr, x + @dx, y + @dy).
1694 * It is an error to call this function with no current point. Doing
1695 * so will cause @cr to shutdown with a status of
1696 * %CAIRO_STATUS_NO_CURRENT_POINT.
1699 cairo_rel_line_to (cairo_t *cr, double dx, double dy)
1701 cairo_status_t status;
1703 if (unlikely (cr->status))
1706 status = cr->backend->rel_line_to (cr, dx, dy);
1707 if (unlikely (status))
1708 _cairo_set_error (cr, status);
1710 slim_hidden_def(cairo_rel_line_to);
1713 * cairo_rel_curve_to:
1714 * @cr: a cairo context
1715 * @dx1: the X offset to the first control point
1716 * @dy1: the Y offset to the first control point
1717 * @dx2: the X offset to the second control point
1718 * @dy2: the Y offset to the second control point
1719 * @dx3: the X offset to the end of the curve
1720 * @dy3: the Y offset to the end of the curve
1722 * Relative-coordinate version of cairo_curve_to(). All offsets are
1723 * relative to the current point. Adds a cubic Bézier spline to the
1724 * path from the current point to a point offset from the current
1725 * point by (@dx3, @dy3), using points offset by (@dx1, @dy1) and
1726 * (@dx2, @dy2) as the control points. After this call the current
1727 * point will be offset by (@dx3, @dy3).
1729 * Given a current point of (x, y), cairo_rel_curve_to(@cr, @dx1,
1730 * @dy1, @dx2, @dy2, @dx3, @dy3) is logically equivalent to
1731 * cairo_curve_to(@cr, x+@dx1, y+@dy1, x+@dx2, y+@dy2, x+@dx3, y+@dy3).
1733 * It is an error to call this function with no current point. Doing
1734 * so will cause @cr to shutdown with a status of
1735 * %CAIRO_STATUS_NO_CURRENT_POINT.
1738 cairo_rel_curve_to (cairo_t *cr,
1739 double dx1, double dy1,
1740 double dx2, double dy2,
1741 double dx3, double dy3)
1743 cairo_status_t status;
1745 if (unlikely (cr->status))
1748 status = cr->backend->rel_curve_to (cr,
1752 if (unlikely (status))
1753 _cairo_set_error (cr, status);
1758 * @cr: a cairo context
1759 * @x: the X coordinate of the top left corner of the rectangle
1760 * @y: the Y coordinate to the top left corner of the rectangle
1761 * @width: the width of the rectangle
1762 * @height: the height of the rectangle
1764 * Adds a closed sub-path rectangle of the given size to the current
1765 * path at position (@x, @y) in user-space coordinates.
1767 * This function is logically equivalent to:
1768 * <informalexample><programlisting>
1769 * cairo_move_to (cr, x, y);
1770 * cairo_rel_line_to (cr, width, 0);
1771 * cairo_rel_line_to (cr, 0, height);
1772 * cairo_rel_line_to (cr, -width, 0);
1773 * cairo_close_path (cr);
1774 * </programlisting></informalexample>
1777 cairo_rectangle (cairo_t *cr,
1779 double width, double height)
1781 cairo_status_t status;
1783 if (unlikely (cr->status))
1786 status = cr->backend->rectangle (cr, x, y, width, height);
1787 if (unlikely (status))
1788 _cairo_set_error (cr, status);
1794 cairo_stroke_to_path (cairo_t *cr)
1796 cairo_status_t status;
1798 if (unlikely (cr->status))
1801 /* The code in _cairo_recording_surface_get_path has a poorman's stroke_to_path */
1803 status = _cairo_gstate_stroke_path (cr->gstate);
1804 if (unlikely (status))
1805 _cairo_set_error (cr, status);
1811 * @cr: a cairo context
1813 * Adds a line segment to the path from the current point to the
1814 * beginning of the current sub-path, (the most recent point passed to
1815 * cairo_move_to()), and closes this sub-path. After this call the
1816 * current point will be at the joined endpoint of the sub-path.
1818 * The behavior of cairo_close_path() is distinct from simply calling
1819 * cairo_line_to() with the equivalent coordinate in the case of
1820 * stroking. When a closed sub-path is stroked, there are no caps on
1821 * the ends of the sub-path. Instead, there is a line join connecting
1822 * the final and initial segments of the sub-path.
1824 * If there is no current point before the call to cairo_close_path(),
1825 * this function will have no effect.
1827 * Note: As of cairo version 1.2.4 any call to cairo_close_path() will
1828 * place an explicit MOVE_TO element into the path immediately after
1829 * the CLOSE_PATH element, (which can be seen in cairo_copy_path() for
1830 * example). This can simplify path processing in some cases as it may
1831 * not be necessary to save the "last move_to point" during processing
1832 * as the MOVE_TO immediately after the CLOSE_PATH will provide that
1836 cairo_close_path (cairo_t *cr)
1838 cairo_status_t status;
1840 if (unlikely (cr->status))
1843 status = cr->backend->close_path (cr);
1844 if (unlikely (status))
1845 _cairo_set_error (cr, status);
1847 slim_hidden_def(cairo_close_path);
1850 * cairo_path_extents:
1851 * @cr: a cairo context
1852 * @x1: left of the resulting extents
1853 * @y1: top of the resulting extents
1854 * @x2: right of the resulting extents
1855 * @y2: bottom of the resulting extents
1857 * Computes a bounding box in user-space coordinates covering the
1858 * points on the current path. If the current path is empty, returns
1859 * an empty rectangle ((0,0), (0,0)). Stroke parameters, fill rule,
1860 * surface dimensions and clipping are not taken into account.
1862 * Contrast with cairo_fill_extents() and cairo_stroke_extents() which
1863 * return the extents of only the area that would be "inked" by
1864 * the corresponding drawing operations.
1866 * The result of cairo_path_extents() is defined as equivalent to the
1867 * limit of cairo_stroke_extents() with %CAIRO_LINE_CAP_ROUND as the
1868 * line width approaches 0.0, (but never reaching the empty-rectangle
1869 * returned by cairo_stroke_extents() for a line width of 0.0).
1871 * Specifically, this means that zero-area sub-paths such as
1872 * cairo_move_to();cairo_line_to() segments, (even degenerate cases
1873 * where the coordinates to both calls are identical), will be
1874 * considered as contributing to the extents. However, a lone
1875 * cairo_move_to() will not contribute to the results of
1876 * cairo_path_extents().
1881 cairo_path_extents (cairo_t *cr,
1882 double *x1, double *y1, double *x2, double *y2)
1884 if (unlikely (cr->status)) {
1897 cr->backend->path_extents (cr, x1, y1, x2, y2);
1902 * @cr: a cairo context
1904 * A drawing operator that paints the current source everywhere within
1905 * the current clip region.
1908 cairo_paint (cairo_t *cr)
1910 cairo_status_t status;
1912 if (unlikely (cr->status))
1915 status = cr->backend->paint (cr);
1916 if (unlikely (status))
1917 _cairo_set_error (cr, status);
1919 slim_hidden_def (cairo_paint);
1922 * cairo_paint_with_alpha:
1923 * @cr: a cairo context
1924 * @alpha: alpha value, between 0 (transparent) and 1 (opaque)
1926 * A drawing operator that paints the current source everywhere within
1927 * the current clip region using a mask of constant alpha value
1928 * @alpha. The effect is similar to cairo_paint(), but the drawing
1929 * is faded out using the alpha value.
1932 cairo_paint_with_alpha (cairo_t *cr,
1935 cairo_status_t status;
1937 if (unlikely (cr->status))
1940 status = cr->backend->paint_with_alpha (cr, alpha);
1941 if (unlikely (status))
1942 _cairo_set_error (cr, status);
1947 * @cr: a cairo context
1948 * @pattern: a #cairo_pattern_t
1950 * A drawing operator that paints the current source
1951 * using the alpha channel of @pattern as a mask. (Opaque
1952 * areas of @pattern are painted with the source, transparent
1953 * areas are not painted.)
1956 cairo_mask (cairo_t *cr,
1957 cairo_pattern_t *pattern)
1959 cairo_status_t status;
1961 if (unlikely (cr->status))
1964 if (unlikely (pattern == NULL)) {
1965 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
1969 if (unlikely (pattern->status)) {
1970 _cairo_set_error (cr, pattern->status);
1974 status = cr->backend->mask (cr, pattern);
1975 if (unlikely (status))
1976 _cairo_set_error (cr, status);
1978 slim_hidden_def (cairo_mask);
1981 * cairo_mask_surface:
1982 * @cr: a cairo context
1983 * @surface: a #cairo_surface_t
1984 * @surface_x: X coordinate at which to place the origin of @surface
1985 * @surface_y: Y coordinate at which to place the origin of @surface
1987 * A drawing operator that paints the current source
1988 * using the alpha channel of @surface as a mask. (Opaque
1989 * areas of @surface are painted with the source, transparent
1990 * areas are not painted.)
1993 cairo_mask_surface (cairo_t *cr,
1994 cairo_surface_t *surface,
1998 cairo_pattern_t *pattern;
1999 cairo_matrix_t matrix;
2001 if (unlikely (cr->status))
2004 pattern = cairo_pattern_create_for_surface (surface);
2006 cairo_matrix_init_translate (&matrix, - surface_x, - surface_y);
2007 cairo_pattern_set_matrix (pattern, &matrix);
2009 cairo_mask (cr, pattern);
2011 cairo_pattern_destroy (pattern);
2016 * @cr: a cairo context
2018 * A drawing operator that strokes the current path according to the
2019 * current line width, line join, line cap, and dash settings. After
2020 * cairo_stroke(), the current path will be cleared from the cairo
2021 * context. See cairo_set_line_width(), cairo_set_line_join(),
2022 * cairo_set_line_cap(), cairo_set_dash(), and
2023 * cairo_stroke_preserve().
2025 * Note: Degenerate segments and sub-paths are treated specially and
2026 * provide a useful result. These can result in two different
2029 * 1. Zero-length "on" segments set in cairo_set_dash(). If the cap
2030 * style is %CAIRO_LINE_CAP_ROUND or %CAIRO_LINE_CAP_SQUARE then these
2031 * segments will be drawn as circular dots or squares respectively. In
2032 * the case of %CAIRO_LINE_CAP_SQUARE, the orientation of the squares
2033 * is determined by the direction of the underlying path.
2035 * 2. A sub-path created by cairo_move_to() followed by either a
2036 * cairo_close_path() or one or more calls to cairo_line_to() to the
2037 * same coordinate as the cairo_move_to(). If the cap style is
2038 * %CAIRO_LINE_CAP_ROUND then these sub-paths will be drawn as circular
2039 * dots. Note that in the case of %CAIRO_LINE_CAP_SQUARE a degenerate
2040 * sub-path will not be drawn at all, (since the correct orientation
2041 * is indeterminate).
2043 * In no case will a cap style of %CAIRO_LINE_CAP_BUTT cause anything
2044 * to be drawn in the case of either degenerate segments or sub-paths.
2047 cairo_stroke (cairo_t *cr)
2049 cairo_status_t status;
2051 if (unlikely (cr->status))
2054 status = cr->backend->stroke (cr);
2055 if (unlikely (status))
2056 _cairo_set_error (cr, status);
2058 slim_hidden_def(cairo_stroke);
2061 * cairo_stroke_preserve:
2062 * @cr: a cairo context
2064 * A drawing operator that strokes the current path according to the
2065 * current line width, line join, line cap, and dash settings. Unlike
2066 * cairo_stroke(), cairo_stroke_preserve() preserves the path within the
2069 * See cairo_set_line_width(), cairo_set_line_join(),
2070 * cairo_set_line_cap(), cairo_set_dash(), and
2071 * cairo_stroke_preserve().
2074 cairo_stroke_preserve (cairo_t *cr)
2076 cairo_status_t status;
2078 if (unlikely (cr->status))
2081 status = cr->backend->stroke_preserve (cr);
2082 if (unlikely (status))
2083 _cairo_set_error (cr, status);
2085 slim_hidden_def(cairo_stroke_preserve);
2089 * @cr: a cairo context
2091 * A drawing operator that fills the current path according to the
2092 * current fill rule, (each sub-path is implicitly closed before being
2093 * filled). After cairo_fill(), the current path will be cleared from
2094 * the cairo context. See cairo_set_fill_rule() and
2095 * cairo_fill_preserve().
2098 cairo_fill (cairo_t *cr)
2100 cairo_status_t status;
2102 if (unlikely (cr->status))
2105 status = cr->backend->fill (cr);
2106 if (unlikely (status))
2107 _cairo_set_error (cr, status);
2111 * cairo_fill_preserve:
2112 * @cr: a cairo context
2114 * A drawing operator that fills the current path according to the
2115 * current fill rule, (each sub-path is implicitly closed before being
2116 * filled). Unlike cairo_fill(), cairo_fill_preserve() preserves the
2117 * path within the cairo context.
2119 * See cairo_set_fill_rule() and cairo_fill().
2122 cairo_fill_preserve (cairo_t *cr)
2124 cairo_status_t status;
2126 if (unlikely (cr->status))
2129 status = cr->backend->fill_preserve (cr);
2130 if (unlikely (status))
2131 _cairo_set_error (cr, status);
2133 slim_hidden_def(cairo_fill_preserve);
2137 * @cr: a cairo context
2139 * Emits the current page for backends that support multiple pages, but
2140 * doesn't clear it, so, the contents of the current page will be retained
2141 * for the next page too. Use cairo_show_page() if you want to get an
2142 * empty page after the emission.
2144 * This is a convenience function that simply calls
2145 * cairo_surface_copy_page() on @cr's target.
2148 cairo_copy_page (cairo_t *cr)
2150 cairo_status_t status;
2152 if (unlikely (cr->status))
2155 status = cr->backend->copy_page (cr);
2156 if (unlikely (status))
2157 _cairo_set_error (cr, status);
2162 * @cr: a cairo context
2164 * Emits and clears the current page for backends that support multiple
2165 * pages. Use cairo_copy_page() if you don't want to clear the page.
2167 * This is a convenience function that simply calls
2168 * cairo_surface_show_page() on @cr's target.
2171 cairo_show_page (cairo_t *cr)
2173 cairo_status_t status;
2175 if (unlikely (cr->status))
2178 status = cr->backend->show_page (cr);
2179 if (unlikely (status))
2180 _cairo_set_error (cr, status);
2185 * @cr: a cairo context
2186 * @x: X coordinate of the point to test
2187 * @y: Y coordinate of the point to test
2189 * Tests whether the given point is inside the area that would be
2190 * affected by a cairo_stroke() operation given the current path and
2191 * stroking parameters. Surface dimensions and clipping are not taken
2194 * See cairo_stroke(), cairo_set_line_width(), cairo_set_line_join(),
2195 * cairo_set_line_cap(), cairo_set_dash(), and
2196 * cairo_stroke_preserve().
2198 * Return value: A non-zero value if the point is inside, or zero if
2202 cairo_in_stroke (cairo_t *cr, double x, double y)
2204 cairo_status_t status;
2205 cairo_bool_t inside = FALSE;
2207 if (unlikely (cr->status))
2210 status = cr->backend->in_stroke (cr, x, y, &inside);
2211 if (unlikely (status))
2212 _cairo_set_error (cr, status);
2219 * @cr: a cairo context
2220 * @x: X coordinate of the point to test
2221 * @y: Y coordinate of the point to test
2223 * Tests whether the given point is inside the area that would be
2224 * affected by a cairo_fill() operation given the current path and
2225 * filling parameters. Surface dimensions and clipping are not taken
2228 * See cairo_fill(), cairo_set_fill_rule() and cairo_fill_preserve().
2230 * Return value: A non-zero value if the point is inside, or zero if
2234 cairo_in_fill (cairo_t *cr, double x, double y)
2236 cairo_status_t status;
2237 cairo_bool_t inside = FALSE;
2239 if (unlikely (cr->status))
2242 status = cr->backend->in_fill (cr, x, y, &inside);
2243 if (unlikely (status))
2244 _cairo_set_error (cr, status);
2250 * cairo_stroke_extents:
2251 * @cr: a cairo context
2252 * @x1: left of the resulting extents
2253 * @y1: top of the resulting extents
2254 * @x2: right of the resulting extents
2255 * @y2: bottom of the resulting extents
2257 * Computes a bounding box in user coordinates covering the area that
2258 * would be affected, (the "inked" area), by a cairo_stroke()
2259 * operation given the current path and stroke parameters.
2260 * If the current path is empty, returns an empty rectangle ((0,0), (0,0)).
2261 * Surface dimensions and clipping are not taken into account.
2263 * Note that if the line width is set to exactly zero, then
2264 * cairo_stroke_extents() will return an empty rectangle. Contrast with
2265 * cairo_path_extents() which can be used to compute the non-empty
2266 * bounds as the line width approaches zero.
2268 * Note that cairo_stroke_extents() must necessarily do more work to
2269 * compute the precise inked areas in light of the stroke parameters,
2270 * so cairo_path_extents() may be more desirable for sake of
2271 * performance if non-inked path extents are desired.
2273 * See cairo_stroke(), cairo_set_line_width(), cairo_set_line_join(),
2274 * cairo_set_line_cap(), cairo_set_dash(), and
2275 * cairo_stroke_preserve().
2278 cairo_stroke_extents (cairo_t *cr,
2279 double *x1, double *y1, double *x2, double *y2)
2281 cairo_status_t status;
2283 if (unlikely (cr->status)) {
2296 status = cr->backend->stroke_extents (cr, x1, y1, x2, y2);
2297 if (unlikely (status))
2298 _cairo_set_error (cr, status);
2302 * cairo_fill_extents:
2303 * @cr: a cairo context
2304 * @x1: left of the resulting extents
2305 * @y1: top of the resulting extents
2306 * @x2: right of the resulting extents
2307 * @y2: bottom of the resulting extents
2309 * Computes a bounding box in user coordinates covering the area that
2310 * would be affected, (the "inked" area), by a cairo_fill() operation
2311 * given the current path and fill parameters. If the current path is
2312 * empty, returns an empty rectangle ((0,0), (0,0)). Surface
2313 * dimensions and clipping are not taken into account.
2315 * Contrast with cairo_path_extents(), which is similar, but returns
2316 * non-zero extents for some paths with no inked area, (such as a
2317 * simple line segment).
2319 * Note that cairo_fill_extents() must necessarily do more work to
2320 * compute the precise inked areas in light of the fill rule, so
2321 * cairo_path_extents() may be more desirable for sake of performance
2322 * if the non-inked path extents are desired.
2324 * See cairo_fill(), cairo_set_fill_rule() and cairo_fill_preserve().
2327 cairo_fill_extents (cairo_t *cr,
2328 double *x1, double *y1, double *x2, double *y2)
2330 cairo_status_t status;
2332 if (unlikely (cr->status)) {
2345 status = cr->backend->fill_extents (cr, x1, y1, x2, y2);
2346 if (unlikely (status))
2347 _cairo_set_error (cr, status);
2352 * @cr: a cairo context
2354 * Establishes a new clip region by intersecting the current clip
2355 * region with the current path as it would be filled by cairo_fill()
2356 * and according to the current fill rule (see cairo_set_fill_rule()).
2358 * After cairo_clip(), the current path will be cleared from the cairo
2361 * The current clip region affects all drawing operations by
2362 * effectively masking out any changes to the surface that are outside
2363 * the current clip region.
2365 * Calling cairo_clip() can only make the clip region smaller, never
2366 * larger. But the current clip is part of the graphics state, so a
2367 * temporary restriction of the clip region can be achieved by
2368 * calling cairo_clip() within a cairo_save()/cairo_restore()
2369 * pair. The only other means of increasing the size of the clip
2370 * region is cairo_reset_clip().
2373 cairo_clip (cairo_t *cr)
2375 cairo_status_t status;
2377 if (unlikely (cr->status))
2380 status = cr->backend->clip (cr);
2381 if (unlikely (status))
2382 _cairo_set_error (cr, status);
2386 * cairo_clip_preserve:
2387 * @cr: a cairo context
2389 * Establishes a new clip region by intersecting the current clip
2390 * region with the current path as it would be filled by cairo_fill()
2391 * and according to the current fill rule (see cairo_set_fill_rule()).
2393 * Unlike cairo_clip(), cairo_clip_preserve() preserves the path within
2394 * the cairo context.
2396 * The current clip region affects all drawing operations by
2397 * effectively masking out any changes to the surface that are outside
2398 * the current clip region.
2400 * Calling cairo_clip_preserve() can only make the clip region smaller, never
2401 * larger. But the current clip is part of the graphics state, so a
2402 * temporary restriction of the clip region can be achieved by
2403 * calling cairo_clip_preserve() within a cairo_save()/cairo_restore()
2404 * pair. The only other means of increasing the size of the clip
2405 * region is cairo_reset_clip().
2408 cairo_clip_preserve (cairo_t *cr)
2410 cairo_status_t status;
2412 if (unlikely (cr->status))
2415 status = cr->backend->clip_preserve (cr);
2416 if (unlikely (status))
2417 _cairo_set_error (cr, status);
2419 slim_hidden_def(cairo_clip_preserve);
2423 * @cr: a cairo context
2425 * Reset the current clip region to its original, unrestricted
2426 * state. That is, set the clip region to an infinitely large shape
2427 * containing the target surface. Equivalently, if infinity is too
2428 * hard to grasp, one can imagine the clip region being reset to the
2429 * exact bounds of the target surface.
2431 * Note that code meant to be reusable should not call
2432 * cairo_reset_clip() as it will cause results unexpected by
2433 * higher-level code which calls cairo_clip(). Consider using
2434 * cairo_save() and cairo_restore() around cairo_clip() as a more
2435 * robust means of temporarily restricting the clip region.
2438 cairo_reset_clip (cairo_t *cr)
2440 cairo_status_t status;
2442 if (unlikely (cr->status))
2445 status = cr->backend->reset_clip (cr);
2446 if (unlikely (status))
2447 _cairo_set_error (cr, status);
2451 * cairo_clip_extents:
2452 * @cr: a cairo context
2453 * @x1: left of the resulting extents
2454 * @y1: top of the resulting extents
2455 * @x2: right of the resulting extents
2456 * @y2: bottom of the resulting extents
2458 * Computes a bounding box in user coordinates covering the area inside the
2464 cairo_clip_extents (cairo_t *cr,
2465 double *x1, double *y1,
2466 double *x2, double *y2)
2468 cairo_status_t status;
2479 if (unlikely (cr->status))
2482 status = cr->backend->clip_extents (cr, x1, y1, x2, y2);
2483 if (unlikely (status))
2484 _cairo_set_error (cr, status);
2489 * @cr: a cairo context
2490 * @x: X coordinate of the point to test
2491 * @y: Y coordinate of the point to test
2493 * Tests whether the given point is inside the area that would be
2494 * visible through the current clip, i.e. the area that would be filled by
2495 * a cairo_paint() operation.
2497 * See cairo_clip(), and cairo_clip_preserve().
2499 * Return value: A non-zero value if the point is inside, or zero if
2505 cairo_in_clip (cairo_t *cr, double x, double y)
2507 cairo_status_t status;
2508 cairo_bool_t inside = FALSE;
2510 if (unlikely (cr->status))
2513 status = cr->backend->in_clip (cr, x, y, &inside);
2514 if (unlikely (status))
2515 _cairo_set_error (cr, status);
2521 * cairo_copy_clip_rectangle_list:
2522 * @cr: a cairo context
2524 * Gets the current clip region as a list of rectangles in user coordinates.
2525 * Never returns %NULL.
2527 * The status in the list may be %CAIRO_STATUS_CLIP_NOT_REPRESENTABLE to
2528 * indicate that the clip region cannot be represented as a list of
2529 * user-space rectangles. The status may have other values to indicate
2532 * Returns: the current clip region as a list of rectangles in user coordinates,
2533 * which should be destroyed using cairo_rectangle_list_destroy().
2537 cairo_rectangle_list_t *
2538 cairo_copy_clip_rectangle_list (cairo_t *cr)
2540 if (unlikely (cr->status))
2541 return _cairo_rectangle_list_create_in_error (cr->status);
2543 return cr->backend->clip_copy_rectangle_list (cr);
2547 * cairo_select_font_face:
2549 * @family: a font family name, encoded in UTF-8
2550 * @slant: the slant for the font
2551 * @weight: the weight for the font
2553 * Note: The cairo_select_font_face() function call is part of what
2554 * the cairo designers call the "toy" text API. It is convenient for
2555 * short demos and simple programs, but it is not expected to be
2556 * adequate for serious text-using applications.
2558 * Selects a family and style of font from a simplified description as
2559 * a family name, slant and weight. Cairo provides no operation to
2560 * list available family names on the system (this is a "toy",
2561 * remember), but the standard CSS2 generic family names, ("serif",
2562 * "sans-serif", "cursive", "fantasy", "monospace"), are likely to
2565 * If @family starts with the string "@cairo:", or if no native font
2566 * backends are compiled in, cairo will use an internal font family.
2567 * The internal font family recognizes many modifiers in the @family
2568 * string, most notably, it recognizes the string "monospace". That is,
2569 * the family name "@cairo:monospace" will use the monospace version of
2570 * the internal font family.
2572 * For "real" font selection, see the font-backend-specific
2573 * font_face_create functions for the font backend you are using. (For
2574 * example, if you are using the freetype-based cairo-ft font backend,
2575 * see cairo_ft_font_face_create_for_ft_face() or
2576 * cairo_ft_font_face_create_for_pattern().) The resulting font face
2577 * could then be used with cairo_scaled_font_create() and
2578 * cairo_set_scaled_font().
2580 * Similarly, when using the "real" font support, you can call
2581 * directly into the underlying font system, (such as fontconfig or
2582 * freetype), for operations such as listing available fonts, etc.
2584 * It is expected that most applications will need to use a more
2585 * comprehensive font handling and text layout library, (for example,
2586 * pango), in conjunction with cairo.
2588 * If text is drawn without a call to cairo_select_font_face(), (nor
2589 * cairo_set_font_face() nor cairo_set_scaled_font()), the default
2590 * family is platform-specific, but is essentially "sans-serif".
2591 * Default slant is %CAIRO_FONT_SLANT_NORMAL, and default weight is
2592 * %CAIRO_FONT_WEIGHT_NORMAL.
2594 * This function is equivalent to a call to cairo_toy_font_face_create()
2595 * followed by cairo_set_font_face().
2598 cairo_select_font_face (cairo_t *cr,
2600 cairo_font_slant_t slant,
2601 cairo_font_weight_t weight)
2603 cairo_font_face_t *font_face;
2604 cairo_status_t status;
2606 if (unlikely (cr->status))
2609 font_face = cairo_toy_font_face_create (family, slant, weight);
2610 if (unlikely (font_face->status)) {
2611 _cairo_set_error (cr, font_face->status);
2615 status = cr->backend->set_font_face (cr, font_face);
2616 cairo_font_face_destroy (font_face);
2618 if (unlikely (status))
2619 _cairo_set_error (cr, status);
2623 * cairo_font_extents:
2625 * @extents: a #cairo_font_extents_t object into which the results
2628 * Gets the font extents for the currently selected font.
2631 cairo_font_extents (cairo_t *cr,
2632 cairo_font_extents_t *extents)
2634 cairo_status_t status;
2636 extents->ascent = 0.0;
2637 extents->descent = 0.0;
2638 extents->height = 0.0;
2639 extents->max_x_advance = 0.0;
2640 extents->max_y_advance = 0.0;
2642 if (unlikely (cr->status))
2645 status = cr->backend->font_extents (cr, extents);
2646 if (unlikely (status))
2647 _cairo_set_error (cr, status);
2651 * cairo_set_font_face:
2653 * @font_face: a #cairo_font_face_t, or %NULL to restore to the default font
2655 * Replaces the current #cairo_font_face_t object in the #cairo_t with
2656 * @font_face. The replaced font face in the #cairo_t will be
2657 * destroyed if there are no other references to it.
2660 cairo_set_font_face (cairo_t *cr,
2661 cairo_font_face_t *font_face)
2663 cairo_status_t status;
2665 if (unlikely (cr->status))
2668 status = cr->backend->set_font_face (cr, font_face);
2669 if (unlikely (status))
2670 _cairo_set_error (cr, status);
2674 * cairo_get_font_face:
2677 * Gets the current font face for a #cairo_t.
2679 * Return value: the current font face. This object is owned by
2680 * cairo. To keep a reference to it, you must call
2681 * cairo_font_face_reference().
2683 * This function never returns %NULL. If memory cannot be allocated, a
2684 * special "nil" #cairo_font_face_t object will be returned on which
2685 * cairo_font_face_status() returns %CAIRO_STATUS_NO_MEMORY. Using
2686 * this nil object will cause its error state to propagate to other
2687 * objects it is passed to, (for example, calling
2688 * cairo_set_font_face() with a nil font will trigger an error that
2689 * will shutdown the #cairo_t object).
2692 cairo_get_font_face (cairo_t *cr)
2694 if (unlikely (cr->status))
2695 return (cairo_font_face_t*) &_cairo_font_face_nil;
2697 return cr->backend->get_font_face (cr);
2701 * cairo_set_font_size:
2703 * @size: the new font size, in user space units
2705 * Sets the current font matrix to a scale by a factor of @size, replacing
2706 * any font matrix previously set with cairo_set_font_size() or
2707 * cairo_set_font_matrix(). This results in a font size of @size user space
2708 * units. (More precisely, this matrix will result in the font's
2709 * em-square being a @size by @size square in user space.)
2711 * If text is drawn without a call to cairo_set_font_size(), (nor
2712 * cairo_set_font_matrix() nor cairo_set_scaled_font()), the default
2713 * font size is 10.0.
2716 cairo_set_font_size (cairo_t *cr, double size)
2718 cairo_status_t status;
2720 if (unlikely (cr->status))
2723 status = cr->backend->set_font_size (cr, size);
2724 if (unlikely (status))
2725 _cairo_set_error (cr, status);
2727 slim_hidden_def (cairo_set_font_size);
2730 * cairo_set_font_matrix
2732 * @matrix: a #cairo_matrix_t describing a transform to be applied to
2735 * Sets the current font matrix to @matrix. The font matrix gives a
2736 * transformation from the design space of the font (in this space,
2737 * the em-square is 1 unit by 1 unit) to user space. Normally, a
2738 * simple scale is used (see cairo_set_font_size()), but a more
2739 * complex font matrix can be used to shear the font
2740 * or stretch it unequally along the two axes
2743 cairo_set_font_matrix (cairo_t *cr,
2744 const cairo_matrix_t *matrix)
2746 cairo_status_t status;
2748 if (unlikely (cr->status))
2751 status = cr->backend->set_font_matrix (cr, matrix);
2752 if (unlikely (status))
2753 _cairo_set_error (cr, status);
2755 slim_hidden_def (cairo_set_font_matrix);
2758 * cairo_get_font_matrix
2760 * @matrix: return value for the matrix
2762 * Stores the current font matrix into @matrix. See
2763 * cairo_set_font_matrix().
2766 cairo_get_font_matrix (cairo_t *cr, cairo_matrix_t *matrix)
2768 if (unlikely (cr->status)) {
2769 cairo_matrix_init_identity (matrix);
2773 cr->backend->get_font_matrix (cr, matrix);
2777 * cairo_set_font_options:
2779 * @options: font options to use
2781 * Sets a set of custom font rendering options for the #cairo_t.
2782 * Rendering options are derived by merging these options with the
2783 * options derived from underlying surface; if the value in @options
2784 * has a default value (like %CAIRO_ANTIALIAS_DEFAULT), then the value
2785 * from the surface is used.
2788 cairo_set_font_options (cairo_t *cr,
2789 const cairo_font_options_t *options)
2791 cairo_status_t status;
2793 if (unlikely (cr->status))
2796 status = cairo_font_options_status ((cairo_font_options_t *) options);
2797 if (unlikely (status)) {
2798 _cairo_set_error (cr, status);
2802 status = cr->backend->set_font_options (cr, options);
2803 if (unlikely (status))
2804 _cairo_set_error (cr, status);
2806 slim_hidden_def (cairo_set_font_options);
2809 * cairo_get_font_options:
2811 * @options: a #cairo_font_options_t object into which to store
2812 * the retrieved options. All existing values are overwritten
2814 * Retrieves font rendering options set via #cairo_set_font_options.
2815 * Note that the returned options do not include any options derived
2816 * from the underlying surface; they are literally the options
2817 * passed to cairo_set_font_options().
2820 cairo_get_font_options (cairo_t *cr,
2821 cairo_font_options_t *options)
2823 /* check that we aren't trying to overwrite the nil object */
2824 if (cairo_font_options_status (options))
2827 if (unlikely (cr->status)) {
2828 _cairo_font_options_init_default (options);
2832 cr->backend->get_font_options (cr, options);
2836 * cairo_set_scaled_font:
2838 * @scaled_font: a #cairo_scaled_font_t
2840 * Replaces the current font face, font matrix, and font options in
2841 * the #cairo_t with those of the #cairo_scaled_font_t. Except for
2842 * some translation, the current CTM of the #cairo_t should be the
2843 * same as that of the #cairo_scaled_font_t, which can be accessed
2844 * using cairo_scaled_font_get_ctm().
2849 cairo_set_scaled_font (cairo_t *cr,
2850 const cairo_scaled_font_t *scaled_font)
2852 cairo_status_t status;
2854 if (unlikely (cr->status))
2857 if ((scaled_font == NULL)) {
2858 _cairo_set_error (cr, _cairo_error (CAIRO_STATUS_NULL_POINTER));
2862 status = scaled_font->status;
2863 if (unlikely (status)) {
2864 _cairo_set_error (cr, status);
2868 status = cr->backend->set_scaled_font (cr, (cairo_scaled_font_t *) scaled_font);
2869 if (unlikely (status))
2870 _cairo_set_error (cr, status);
2874 * cairo_get_scaled_font:
2877 * Gets the current scaled font for a #cairo_t.
2879 * Return value: the current scaled font. This object is owned by
2880 * cairo. To keep a reference to it, you must call
2881 * cairo_scaled_font_reference().
2883 * This function never returns %NULL. If memory cannot be allocated, a
2884 * special "nil" #cairo_scaled_font_t object will be returned on which
2885 * cairo_scaled_font_status() returns %CAIRO_STATUS_NO_MEMORY. Using
2886 * this nil object will cause its error state to propagate to other
2887 * objects it is passed to, (for example, calling
2888 * cairo_set_scaled_font() with a nil font will trigger an error that
2889 * will shutdown the #cairo_t object).
2893 cairo_scaled_font_t *
2894 cairo_get_scaled_font (cairo_t *cr)
2896 if (unlikely (cr->status))
2897 return _cairo_scaled_font_create_in_error (cr->status);
2899 return cr->backend->get_scaled_font (cr);
2901 slim_hidden_def (cairo_get_scaled_font);
2904 * cairo_text_extents:
2906 * @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
2907 * @extents: a #cairo_text_extents_t object into which the results
2910 * Gets the extents for a string of text. The extents describe a
2911 * user-space rectangle that encloses the "inked" portion of the text,
2912 * (as it would be drawn by cairo_show_text()). Additionally, the
2913 * x_advance and y_advance values indicate the amount by which the
2914 * current point would be advanced by cairo_show_text().
2916 * Note that whitespace characters do not directly contribute to the
2917 * size of the rectangle (extents.width and extents.height). They do
2918 * contribute indirectly by changing the position of non-whitespace
2919 * characters. In particular, trailing whitespace characters are
2920 * likely to not affect the size of the rectangle, though they will
2921 * affect the x_advance and y_advance values.
2924 cairo_text_extents (cairo_t *cr,
2926 cairo_text_extents_t *extents)
2928 cairo_status_t status;
2929 cairo_scaled_font_t *scaled_font;
2930 cairo_glyph_t *glyphs = NULL;
2934 extents->x_bearing = 0.0;
2935 extents->y_bearing = 0.0;
2936 extents->width = 0.0;
2937 extents->height = 0.0;
2938 extents->x_advance = 0.0;
2939 extents->y_advance = 0.0;
2941 if (unlikely (cr->status))
2947 scaled_font = cairo_get_scaled_font (cr);
2948 if (unlikely (scaled_font->status)) {
2949 _cairo_set_error (cr, scaled_font->status);
2953 cairo_get_current_point (cr, &x, &y);
2954 status = cairo_scaled_font_text_to_glyphs (scaled_font,
2957 &glyphs, &num_glyphs,
2960 if (likely (status == CAIRO_STATUS_SUCCESS)) {
2961 status = cr->backend->glyph_extents (cr,
2965 cairo_glyph_free (glyphs);
2967 if (unlikely (status))
2968 _cairo_set_error (cr, status);
2972 * cairo_glyph_extents:
2974 * @glyphs: an array of #cairo_glyph_t objects
2975 * @num_glyphs: the number of elements in @glyphs
2976 * @extents: a #cairo_text_extents_t object into which the results
2979 * Gets the extents for an array of glyphs. The extents describe a
2980 * user-space rectangle that encloses the "inked" portion of the
2981 * glyphs, (as they would be drawn by cairo_show_glyphs()).
2982 * Additionally, the x_advance and y_advance values indicate the
2983 * amount by which the current point would be advanced by
2984 * cairo_show_glyphs().
2986 * Note that whitespace glyphs do not contribute to the size of the
2987 * rectangle (extents.width and extents.height).
2990 cairo_glyph_extents (cairo_t *cr,
2991 const cairo_glyph_t *glyphs,
2993 cairo_text_extents_t *extents)
2995 cairo_status_t status;
2997 extents->x_bearing = 0.0;
2998 extents->y_bearing = 0.0;
2999 extents->width = 0.0;
3000 extents->height = 0.0;
3001 extents->x_advance = 0.0;
3002 extents->y_advance = 0.0;
3004 if (unlikely (cr->status))
3007 if (num_glyphs == 0)
3010 if (unlikely (num_glyphs < 0)) {
3011 _cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
3015 if (unlikely (glyphs == NULL)) {
3016 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3020 status = cr->backend->glyph_extents (cr, glyphs, num_glyphs, extents);
3021 if (unlikely (status))
3022 _cairo_set_error (cr, status);
3027 * @cr: a cairo context
3028 * @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
3030 * A drawing operator that generates the shape from a string of UTF-8
3031 * characters, rendered according to the current font_face, font_size
3032 * (font_matrix), and font_options.
3034 * This function first computes a set of glyphs for the string of
3035 * text. The first glyph is placed so that its origin is at the
3036 * current point. The origin of each subsequent glyph is offset from
3037 * that of the previous glyph by the advance values of the previous
3040 * After this call the current point is moved to the origin of where
3041 * the next glyph would be placed in this same progression. That is,
3042 * the current point will be at the origin of the final glyph offset
3043 * by its advance values. This allows for easy display of a single
3044 * logical string with multiple calls to cairo_show_text().
3046 * Note: The cairo_show_text() function call is part of what the cairo
3047 * designers call the "toy" text API. It is convenient for short demos
3048 * and simple programs, but it is not expected to be adequate for
3049 * serious text-using applications. See cairo_show_glyphs() for the
3050 * "real" text display API in cairo.
3053 cairo_show_text (cairo_t *cr, const char *utf8)
3055 cairo_text_extents_t extents;
3056 cairo_status_t status;
3057 cairo_glyph_t *glyphs, *last_glyph;
3058 cairo_text_cluster_t *clusters;
3059 int utf8_len, num_glyphs, num_clusters;
3060 cairo_text_cluster_flags_t cluster_flags;
3062 cairo_bool_t has_show_text_glyphs;
3063 cairo_glyph_t stack_glyphs[CAIRO_STACK_ARRAY_LENGTH (cairo_glyph_t)];
3064 cairo_text_cluster_t stack_clusters[CAIRO_STACK_ARRAY_LENGTH (cairo_text_cluster_t)];
3065 cairo_scaled_font_t *scaled_font;
3066 cairo_glyph_text_info_t info, *i;
3068 if (unlikely (cr->status))
3074 scaled_font = cairo_get_scaled_font (cr);
3075 if (unlikely (scaled_font->status)) {
3076 _cairo_set_error (cr, scaled_font->status);
3080 utf8_len = strlen (utf8);
3082 has_show_text_glyphs =
3083 cairo_surface_has_show_text_glyphs (cairo_get_target (cr));
3085 glyphs = stack_glyphs;
3086 num_glyphs = ARRAY_LENGTH (stack_glyphs);
3088 if (has_show_text_glyphs) {
3089 clusters = stack_clusters;
3090 num_clusters = ARRAY_LENGTH (stack_clusters);
3096 cairo_get_current_point (cr, &x, &y);
3097 status = cairo_scaled_font_text_to_glyphs (scaled_font,
3100 &glyphs, &num_glyphs,
3101 has_show_text_glyphs ? &clusters : NULL, &num_clusters,
3103 if (unlikely (status))
3106 if (num_glyphs == 0)
3110 if (has_show_text_glyphs) {
3112 info.utf8_len = utf8_len;
3113 info.clusters = clusters;
3114 info.num_clusters = num_clusters;
3115 info.cluster_flags = cluster_flags;
3119 status = cr->backend->glyphs (cr, glyphs, num_glyphs, i);
3120 if (unlikely (status))
3123 last_glyph = &glyphs[num_glyphs - 1];
3124 status = cr->backend->glyph_extents (cr, last_glyph, 1, &extents);
3125 if (unlikely (status))
3128 x = last_glyph->x + extents.x_advance;
3129 y = last_glyph->y + extents.y_advance;
3130 cr->backend->move_to (cr, x, y);
3133 if (glyphs != stack_glyphs)
3134 cairo_glyph_free (glyphs);
3135 if (clusters != stack_clusters)
3136 cairo_text_cluster_free (clusters);
3138 if (unlikely (status))
3139 _cairo_set_error (cr, status);
3143 * cairo_show_glyphs:
3144 * @cr: a cairo context
3145 * @glyphs: array of glyphs to show
3146 * @num_glyphs: number of glyphs to show
3148 * A drawing operator that generates the shape from an array of glyphs,
3149 * rendered according to the current font face, font size
3150 * (font matrix), and font options.
3153 cairo_show_glyphs (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs)
3155 cairo_status_t status;
3157 if (unlikely (cr->status))
3160 if (num_glyphs == 0)
3163 if (num_glyphs < 0) {
3164 _cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
3168 if (glyphs == NULL) {
3169 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3173 status = cr->backend->glyphs (cr, glyphs, num_glyphs, NULL);
3174 if (unlikely (status))
3175 _cairo_set_error (cr, status);
3179 * cairo_show_text_glyphs:
3180 * @cr: a cairo context
3181 * @utf8: a string of text encoded in UTF-8
3182 * @utf8_len: length of @utf8 in bytes, or -1 if it is NUL-terminated
3183 * @glyphs: array of glyphs to show
3184 * @num_glyphs: number of glyphs to show
3185 * @clusters: array of cluster mapping information
3186 * @num_clusters: number of clusters in the mapping
3187 * @cluster_flags: cluster mapping flags
3189 * This operation has rendering effects similar to cairo_show_glyphs()
3190 * but, if the target surface supports it, uses the provided text and
3191 * cluster mapping to embed the text for the glyphs shown in the output.
3192 * If the target does not support the extended attributes, this function
3193 * acts like the basic cairo_show_glyphs() as if it had been passed
3194 * @glyphs and @num_glyphs.
3196 * The mapping between @utf8 and @glyphs is provided by an array of
3197 * <firstterm>clusters</firstterm>. Each cluster covers a number of
3198 * text bytes and glyphs, and neighboring clusters cover neighboring
3199 * areas of @utf8 and @glyphs. The clusters should collectively cover @utf8
3200 * and @glyphs in entirety.
3202 * The first cluster always covers bytes from the beginning of @utf8.
3203 * If @cluster_flags do not have the %CAIRO_TEXT_CLUSTER_FLAG_BACKWARD
3204 * set, the first cluster also covers the beginning
3205 * of @glyphs, otherwise it covers the end of the @glyphs array and
3206 * following clusters move backward.
3208 * See #cairo_text_cluster_t for constraints on valid clusters.
3213 cairo_show_text_glyphs (cairo_t *cr,
3216 const cairo_glyph_t *glyphs,
3218 const cairo_text_cluster_t *clusters,
3220 cairo_text_cluster_flags_t cluster_flags)
3222 cairo_status_t status;
3224 if (unlikely (cr->status))
3227 /* A slew of sanity checks */
3229 /* Special case for NULL and -1 */
3230 if (utf8 == NULL && utf8_len == -1)
3233 /* No NULLs for non-zeros */
3234 if ((num_glyphs && glyphs == NULL) ||
3235 (utf8_len && utf8 == NULL) ||
3236 (num_clusters && clusters == NULL)) {
3237 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3241 /* A -1 for utf8_len means NUL-terminated */
3243 utf8_len = strlen (utf8);
3245 /* Apart from that, no negatives */
3246 if (num_glyphs < 0 || utf8_len < 0 || num_clusters < 0) {
3247 _cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
3251 if (num_glyphs == 0 && utf8_len == 0)
3255 /* Make sure clusters cover the entire glyphs and utf8 arrays,
3256 * and that cluster boundaries are UTF-8 boundaries. */
3257 status = _cairo_validate_text_clusters (utf8, utf8_len,
3259 clusters, num_clusters, cluster_flags);
3260 if (status == CAIRO_STATUS_INVALID_CLUSTERS) {
3261 /* Either got invalid UTF-8 text, or cluster mapping is bad.
3262 * Differentiate those. */
3264 cairo_status_t status2;
3266 status2 = _cairo_utf8_to_ucs4 (utf8, utf8_len, NULL, NULL);
3270 cairo_glyph_text_info_t info;
3273 info.utf8_len = utf8_len;
3274 info.clusters = clusters;
3275 info.num_clusters = num_clusters;
3276 info.cluster_flags = cluster_flags;
3278 status = cr->backend->glyphs (cr, glyphs, num_glyphs, &info);
3281 status = cr->backend->glyphs (cr, glyphs, num_glyphs, NULL);
3283 if (unlikely (status))
3284 _cairo_set_error (cr, status);
3289 * @cr: a cairo context
3290 * @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
3292 * Adds closed paths for text to the current path. The generated
3293 * path if filled, achieves an effect similar to that of
3294 * cairo_show_text().
3296 * Text conversion and positioning is done similar to cairo_show_text().
3298 * Like cairo_show_text(), After this call the current point is
3299 * moved to the origin of where the next glyph would be placed in
3300 * this same progression. That is, the current point will be at
3301 * the origin of the final glyph offset by its advance values.
3302 * This allows for chaining multiple calls to to cairo_text_path()
3303 * without having to set current point in between.
3305 * Note: The cairo_text_path() function call is part of what the cairo
3306 * designers call the "toy" text API. It is convenient for short demos
3307 * and simple programs, but it is not expected to be adequate for
3308 * serious text-using applications. See cairo_glyph_path() for the
3309 * "real" text path API in cairo.
3312 cairo_text_path (cairo_t *cr, const char *utf8)
3314 cairo_status_t status;
3315 cairo_text_extents_t extents;
3316 cairo_glyph_t stack_glyphs[CAIRO_STACK_ARRAY_LENGTH (cairo_glyph_t)];
3317 cairo_glyph_t *glyphs, *last_glyph;
3318 cairo_scaled_font_t *scaled_font;
3322 if (unlikely (cr->status))
3329 glyphs = stack_glyphs;
3330 num_glyphs = ARRAY_LENGTH (stack_glyphs);
3332 scaled_font = cairo_get_scaled_font (cr);
3333 if (unlikely (scaled_font->status)) {
3334 _cairo_set_error (cr, scaled_font->status);
3338 cairo_get_current_point (cr, &x, &y);
3339 status = cairo_scaled_font_text_to_glyphs (scaled_font,
3342 &glyphs, &num_glyphs,
3345 if (num_glyphs == 0)
3348 status = cr->backend->glyph_path (cr, glyphs, num_glyphs);
3350 if (unlikely (status))
3353 last_glyph = &glyphs[num_glyphs - 1];
3354 status = cr->backend->glyph_extents (cr, last_glyph, 1, &extents);
3356 if (unlikely (status))
3359 x = last_glyph->x + extents.x_advance;
3360 y = last_glyph->y + extents.y_advance;
3361 cr->backend->move_to (cr, x, y);
3364 if (glyphs != stack_glyphs)
3365 cairo_glyph_free (glyphs);
3367 if (unlikely (status))
3368 _cairo_set_error (cr, status);
3373 * @cr: a cairo context
3374 * @glyphs: array of glyphs to show
3375 * @num_glyphs: number of glyphs to show
3377 * Adds closed paths for the glyphs to the current path. The generated
3378 * path if filled, achieves an effect similar to that of
3379 * cairo_show_glyphs().
3382 cairo_glyph_path (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs)
3384 cairo_status_t status;
3386 if (unlikely (cr->status))
3389 if (num_glyphs == 0)
3392 if (unlikely (num_glyphs < 0)) {
3393 _cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
3397 if (unlikely (glyphs == NULL)) {
3398 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3402 status = cr->backend->glyph_path (cr, glyphs, num_glyphs);
3403 if (unlikely (status))
3404 _cairo_set_error (cr, status);
3408 * cairo_get_operator:
3409 * @cr: a cairo context
3411 * Gets the current compositing operator for a cairo context.
3413 * Return value: the current compositing operator.
3416 cairo_get_operator (cairo_t *cr)
3418 if (unlikely (cr->status))
3419 return CAIRO_GSTATE_OPERATOR_DEFAULT;
3421 return cr->backend->get_operator (cr);
3426 * cairo_get_opacity:
3427 * @cr: a cairo context
3429 * Gets the current compositing opacity for a cairo context.
3431 * Return value: the current compositing opacity.
3434 cairo_get_opacity (cairo_t *cr)
3436 if (unlikely (cr->status))
3439 return cr->backend->get_opacity (cr);
3444 * cairo_get_tolerance:
3445 * @cr: a cairo context
3447 * Gets the current tolerance value, as set by cairo_set_tolerance().
3449 * Return value: the current tolerance value.
3452 cairo_get_tolerance (cairo_t *cr)
3454 if (unlikely (cr->status))
3455 return CAIRO_GSTATE_TOLERANCE_DEFAULT;
3457 return cr->backend->get_tolerance (cr);
3459 slim_hidden_def (cairo_get_tolerance);
3462 * cairo_get_antialias:
3463 * @cr: a cairo context
3465 * Gets the current shape antialiasing mode, as set by
3466 * cairo_set_antialias().
3468 * Return value: the current shape antialiasing mode.
3471 cairo_get_antialias (cairo_t *cr)
3473 if (unlikely (cr->status))
3474 return CAIRO_ANTIALIAS_DEFAULT;
3476 return cr->backend->get_antialias (cr);
3480 * cairo_has_current_point:
3481 * @cr: a cairo context
3483 * Returns whether a current point is defined on the current path.
3484 * See cairo_get_current_point() for details on the current point.
3486 * Return value: whether a current point is defined.
3491 cairo_has_current_point (cairo_t *cr)
3493 if (unlikely (cr->status))
3496 return cr->backend->has_current_point (cr);
3500 * cairo_get_current_point:
3501 * @cr: a cairo context
3502 * @x: return value for X coordinate of the current point
3503 * @y: return value for Y coordinate of the current point
3505 * Gets the current point of the current path, which is
3506 * conceptually the final point reached by the path so far.
3508 * The current point is returned in the user-space coordinate
3509 * system. If there is no defined current point or if @cr is in an
3510 * error status, @x and @y will both be set to 0.0. It is possible to
3511 * check this in advance with cairo_has_current_point().
3513 * Most path construction functions alter the current point. See the
3514 * following for details on how they affect the current point:
3515 * cairo_new_path(), cairo_new_sub_path(),
3516 * cairo_append_path(), cairo_close_path(),
3517 * cairo_move_to(), cairo_line_to(), cairo_curve_to(),
3518 * cairo_rel_move_to(), cairo_rel_line_to(), cairo_rel_curve_to(),
3519 * cairo_arc(), cairo_arc_negative(), cairo_rectangle(),
3520 * cairo_text_path(), cairo_glyph_path(), cairo_stroke_to_path().
3522 * Some functions use and alter the current point but do not
3523 * otherwise change current path:
3524 * cairo_show_text().
3526 * Some functions unset the current path and as a result, current point:
3527 * cairo_fill(), cairo_stroke().
3530 cairo_get_current_point (cairo_t *cr, double *x_ret, double *y_ret)
3535 if (cr->status == CAIRO_STATUS_SUCCESS &&
3536 cr->backend->has_current_point (cr))
3538 cr->backend->get_current_point (cr, &x, &y);
3546 slim_hidden_def(cairo_get_current_point);
3549 * cairo_get_fill_rule:
3550 * @cr: a cairo context
3552 * Gets the current fill rule, as set by cairo_set_fill_rule().
3554 * Return value: the current fill rule.
3557 cairo_get_fill_rule (cairo_t *cr)
3559 if (unlikely (cr->status))
3560 return CAIRO_GSTATE_FILL_RULE_DEFAULT;
3562 return cr->backend->get_fill_rule (cr);
3566 * cairo_get_line_width:
3567 * @cr: a cairo context
3569 * This function returns the current line width value exactly as set by
3570 * cairo_set_line_width(). Note that the value is unchanged even if
3571 * the CTM has changed between the calls to cairo_set_line_width() and
3572 * cairo_get_line_width().
3574 * Return value: the current line width.
3577 cairo_get_line_width (cairo_t *cr)
3579 if (unlikely (cr->status))
3580 return CAIRO_GSTATE_LINE_WIDTH_DEFAULT;
3582 return cr->backend->get_line_width (cr);
3584 slim_hidden_def (cairo_get_line_width);
3587 * cairo_get_line_cap:
3588 * @cr: a cairo context
3590 * Gets the current line cap style, as set by cairo_set_line_cap().
3592 * Return value: the current line cap style.
3595 cairo_get_line_cap (cairo_t *cr)
3597 if (unlikely (cr->status))
3598 return CAIRO_GSTATE_LINE_CAP_DEFAULT;
3600 return cr->backend->get_line_cap (cr);
3604 * cairo_get_line_join:
3605 * @cr: a cairo context
3607 * Gets the current line join style, as set by cairo_set_line_join().
3609 * Return value: the current line join style.
3612 cairo_get_line_join (cairo_t *cr)
3614 if (unlikely (cr->status))
3615 return CAIRO_GSTATE_LINE_JOIN_DEFAULT;
3617 return cr->backend->get_line_join (cr);
3621 * cairo_get_miter_limit:
3622 * @cr: a cairo context
3624 * Gets the current miter limit, as set by cairo_set_miter_limit().
3626 * Return value: the current miter limit.
3629 cairo_get_miter_limit (cairo_t *cr)
3631 if (unlikely (cr->status))
3632 return CAIRO_GSTATE_MITER_LIMIT_DEFAULT;
3634 return cr->backend->get_miter_limit (cr);
3639 * @cr: a cairo context
3640 * @matrix: return value for the matrix
3642 * Stores the current transformation matrix (CTM) into @matrix.
3645 cairo_get_matrix (cairo_t *cr, cairo_matrix_t *matrix)
3647 if (unlikely (cr->status)) {
3648 cairo_matrix_init_identity (matrix);
3652 cr->backend->get_matrix (cr, matrix);
3654 slim_hidden_def (cairo_get_matrix);
3658 * @cr: a cairo context
3660 * Gets the target surface for the cairo context as passed to
3663 * This function will always return a valid pointer, but the result
3664 * can be a "nil" surface if @cr is already in an error state,
3665 * (ie. cairo_status() <literal>!=</literal> %CAIRO_STATUS_SUCCESS).
3666 * A nil surface is indicated by cairo_surface_status()
3667 * <literal>!=</literal> %CAIRO_STATUS_SUCCESS.
3669 * Return value: the target surface. This object is owned by cairo. To
3670 * keep a reference to it, you must call cairo_surface_reference().
3673 cairo_get_target (cairo_t *cr)
3675 if (unlikely (cr->status))
3676 return _cairo_surface_create_in_error (cr->status);
3678 return cr->backend->get_original_target (cr);
3680 slim_hidden_def (cairo_get_target);
3683 * cairo_get_group_target:
3684 * @cr: a cairo context
3686 * Gets the current destination surface for the context. This is either
3687 * the original target surface as passed to cairo_create() or the target
3688 * surface for the current group as started by the most recent call to
3689 * cairo_push_group() or cairo_push_group_with_content().
3691 * This function will always return a valid pointer, but the result
3692 * can be a "nil" surface if @cr is already in an error state,
3693 * (ie. cairo_status() <literal>!=</literal> %CAIRO_STATUS_SUCCESS).
3694 * A nil surface is indicated by cairo_surface_status()
3695 * <literal>!=</literal> %CAIRO_STATUS_SUCCESS.
3697 * Return value: the target surface. This object is owned by cairo. To
3698 * keep a reference to it, you must call cairo_surface_reference().
3703 cairo_get_group_target (cairo_t *cr)
3705 if (unlikely (cr->status))
3706 return _cairo_surface_create_in_error (cr->status);
3708 return cr->backend->get_current_target (cr);
3713 * @cr: a cairo context
3715 * Creates a copy of the current path and returns it to the user as a
3716 * #cairo_path_t. See #cairo_path_data_t for hints on how to iterate
3717 * over the returned data structure.
3719 * This function will always return a valid pointer, but the result
3720 * will have no data (<literal>data==%NULL</literal> and
3721 * <literal>num_data==0</literal>), if either of the following
3725 * <listitem>If there is insufficient memory to copy the path. In this
3726 * case <literal>path->status</literal> will be set to
3727 * %CAIRO_STATUS_NO_MEMORY.</listitem>
3728 * <listitem>If @cr is already in an error state. In this case
3729 * <literal>path->status</literal> will contain the same status that
3730 * would be returned by cairo_status().</listitem>
3733 * Return value: the copy of the current path. The caller owns the
3734 * returned object and should call cairo_path_destroy() when finished
3738 cairo_copy_path (cairo_t *cr)
3740 if (unlikely (cr->status))
3741 return _cairo_path_create_in_error (cr->status);
3743 return cr->backend->copy_path (cr);
3747 * cairo_copy_path_flat:
3748 * @cr: a cairo context
3750 * Gets a flattened copy of the current path and returns it to the
3751 * user as a #cairo_path_t. See #cairo_path_data_t for hints on
3752 * how to iterate over the returned data structure.
3754 * This function is like cairo_copy_path() except that any curves
3755 * in the path will be approximated with piecewise-linear
3756 * approximations, (accurate to within the current tolerance
3757 * value). That is, the result is guaranteed to not have any elements
3758 * of type %CAIRO_PATH_CURVE_TO which will instead be replaced by a
3759 * series of %CAIRO_PATH_LINE_TO elements.
3761 * This function will always return a valid pointer, but the result
3762 * will have no data (<literal>data==%NULL</literal> and
3763 * <literal>num_data==0</literal>), if either of the following
3767 * <listitem>If there is insufficient memory to copy the path. In this
3768 * case <literal>path->status</literal> will be set to
3769 * %CAIRO_STATUS_NO_MEMORY.</listitem>
3770 * <listitem>If @cr is already in an error state. In this case
3771 * <literal>path->status</literal> will contain the same status that
3772 * would be returned by cairo_status().</listitem>
3775 * Return value: the copy of the current path. The caller owns the
3776 * returned object and should call cairo_path_destroy() when finished
3780 cairo_copy_path_flat (cairo_t *cr)
3782 if (unlikely (cr->status))
3783 return _cairo_path_create_in_error (cr->status);
3785 return cr->backend->copy_path_flat (cr);
3789 * cairo_append_path:
3790 * @cr: a cairo context
3791 * @path: path to be appended
3793 * Append the @path onto the current path. The @path may be either the
3794 * return value from one of cairo_copy_path() or
3795 * cairo_copy_path_flat() or it may be constructed manually. See
3796 * #cairo_path_t for details on how the path data structure should be
3797 * initialized, and note that <literal>path->status</literal> must be
3798 * initialized to %CAIRO_STATUS_SUCCESS.
3801 cairo_append_path (cairo_t *cr,
3802 const cairo_path_t *path)
3804 cairo_status_t status;
3806 if (unlikely (cr->status))
3809 if (unlikely (path == NULL)) {
3810 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3814 if (unlikely (path->status)) {
3815 if (path->status > CAIRO_STATUS_SUCCESS &&
3816 path->status <= CAIRO_STATUS_LAST_STATUS)
3817 _cairo_set_error (cr, path->status);
3819 _cairo_set_error (cr, CAIRO_STATUS_INVALID_STATUS);
3823 if (path->num_data == 0)
3826 if (unlikely (path->data == NULL)) {
3827 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3831 status = cr->backend->append_path (cr, path);
3832 if (unlikely (status))
3833 _cairo_set_error (cr, status);
3838 * @cr: a cairo context
3840 * Checks whether an error has previously occurred for this context.
3842 * Returns: the current status of this context, see #cairo_status_t
3845 cairo_status (cairo_t *cr)
3849 slim_hidden_def (cairo_status);