1 /* -*- Mode: c; c-basic-offset: 4; indent-tabs-mode: t; tab-width: 8; -*- */
2 /* cairo - a vector graphics library with display and print output
4 * Copyright © 2002 University of Southern California
5 * Copyright © 2005 Red Hat, Inc.
6 * Copyright © 2011 Intel Corporation
8 * This library is free software; you can redistribute it and/or
9 * modify it either under the terms of the GNU Lesser General Public
10 * License version 2.1 as published by the Free Software Foundation
11 * (the "LGPL") or, at your option, under the terms of the Mozilla
12 * Public License Version 1.1 (the "MPL"). If you do not alter this
13 * notice, a recipient may use your version of this file under either
14 * the MPL or the LGPL.
16 * You should have received a copy of the LGPL along with this library
17 * in the file COPYING-LGPL-2.1; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA
19 * You should have received a copy of the MPL along with this library
20 * in the file COPYING-MPL-1.1
22 * The contents of this file are subject to the Mozilla Public License
23 * Version 1.1 (the "License"); you may not use this file except in
24 * compliance with the License. You may obtain a copy of the License at
25 * http://www.mozilla.org/MPL/
27 * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
28 * OF ANY KIND, either express or implied. See the LGPL or the MPL for
29 * the specific language governing rights and limitations.
31 * The Original Code is the cairo graphics library.
33 * The Initial Developer of the Original Code is University of Southern
37 * Carl D. Worth <cworth@cworth.org>
38 * Chris Wilson <chris@chris-wilson.co.uk>
42 #include "cairo-private.h"
44 #include "cairo-backend-private.h"
45 #include "cairo-error-private.h"
46 #include "cairo-path-private.h"
47 #include "cairo-pattern-private.h"
48 #include "cairo-surface-private.h"
49 #include "cairo-surface-backend-private.h"
56 * @Short_Description: The cairo drawing context
57 * @See_Also: #cairo_surface_t
59 * #cairo_t is the main object used when drawing with cairo. To
60 * draw with cairo, you create a #cairo_t, set the target surface,
61 * and drawing options for the #cairo_t, create shapes with
62 * functions like cairo_move_to() and cairo_line_to(), and then
63 * draw shapes with cairo_stroke() or cairo_fill().
65 * #cairo_t<!-- -->'s can be pushed to a stack via cairo_save().
66 * They may then safely be changed, without losing the current state.
67 * Use cairo_restore() to restore to the saved state.
73 * @Short_Description: Rendering text and glyphs
74 * @See_Also: #cairo_font_face_t, #cairo_scaled_font_t, cairo_text_path(),
77 * The functions with <emphasis>text</emphasis> in their name form cairo's
78 * <firstterm>toy</firstterm> text API. The toy API takes UTF-8 encoded
79 * text and is limited in its functionality to rendering simple
80 * left-to-right text with no advanced features. That means for example
81 * that most complex scripts like Hebrew, Arabic, and Indic scripts are
82 * out of question. No kerning or correct positioning of diacritical marks
83 * either. The font selection is pretty limited too and doesn't handle the
84 * case that the selected font does not cover the characters in the text.
85 * This set of functions are really that, a toy text API, for testing and
86 * demonstration purposes. Any serious application should avoid them.
88 * The functions with <emphasis>glyphs</emphasis> in their name form cairo's
89 * <firstterm>low-level</firstterm> text API. The low-level API relies on
90 * the user to convert text to a set of glyph indexes and positions. This
91 * is a very hard problem and is best handled by external libraries, like
92 * the pangocairo that is part of the Pango text layout and rendering library.
93 * Pango is available from <ulink
94 * url="http://www.pango.org/">http://www.pango.org/</ulink>.
98 * SECTION:cairo-transforms
99 * @Title: Transformations
100 * @Short_Description: Manipulating the current transformation matrix
101 * @See_Also: #cairo_matrix_t
103 * The current transformation matrix, <firstterm>ctm</firstterm>, is a
104 * two-dimensional affine transformation that maps all coordinates and other
105 * drawing instruments from the <firstterm>user space</firstterm> into the
106 * surface's canonical coordinate system, also known as the <firstterm>device
110 #define DEFINE_NIL_CONTEXT(status) \
112 CAIRO_REFERENCE_COUNT_INVALID, /* ref_count */ \
113 status, /* status */ \
114 { 0, 0, 0, NULL }, /* user_data */ \
118 static const cairo_t _cairo_nil
[] = {
119 DEFINE_NIL_CONTEXT (CAIRO_STATUS_NO_MEMORY
),
120 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_RESTORE
),
121 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_POP_GROUP
),
122 DEFINE_NIL_CONTEXT (CAIRO_STATUS_NO_CURRENT_POINT
),
123 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_MATRIX
),
124 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_STATUS
),
125 DEFINE_NIL_CONTEXT (CAIRO_STATUS_NULL_POINTER
),
126 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_STRING
),
127 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_PATH_DATA
),
128 DEFINE_NIL_CONTEXT (CAIRO_STATUS_READ_ERROR
),
129 DEFINE_NIL_CONTEXT (CAIRO_STATUS_WRITE_ERROR
),
130 DEFINE_NIL_CONTEXT (CAIRO_STATUS_SURFACE_FINISHED
),
131 DEFINE_NIL_CONTEXT (CAIRO_STATUS_SURFACE_TYPE_MISMATCH
),
132 DEFINE_NIL_CONTEXT (CAIRO_STATUS_PATTERN_TYPE_MISMATCH
),
133 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_CONTENT
),
134 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_FORMAT
),
135 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_VISUAL
),
136 DEFINE_NIL_CONTEXT (CAIRO_STATUS_FILE_NOT_FOUND
),
137 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_DASH
),
138 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_DSC_COMMENT
),
139 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_INDEX
),
140 DEFINE_NIL_CONTEXT (CAIRO_STATUS_CLIP_NOT_REPRESENTABLE
),
141 DEFINE_NIL_CONTEXT (CAIRO_STATUS_TEMP_FILE_ERROR
),
142 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_STRIDE
),
143 DEFINE_NIL_CONTEXT (CAIRO_STATUS_FONT_TYPE_MISMATCH
),
144 DEFINE_NIL_CONTEXT (CAIRO_STATUS_USER_FONT_IMMUTABLE
),
145 DEFINE_NIL_CONTEXT (CAIRO_STATUS_USER_FONT_ERROR
),
146 DEFINE_NIL_CONTEXT (CAIRO_STATUS_NEGATIVE_COUNT
),
147 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_CLUSTERS
),
148 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_SLANT
),
149 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_WEIGHT
),
150 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_SIZE
),
151 DEFINE_NIL_CONTEXT (CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED
),
152 DEFINE_NIL_CONTEXT (CAIRO_STATUS_DEVICE_TYPE_MISMATCH
),
153 DEFINE_NIL_CONTEXT (CAIRO_STATUS_DEVICE_ERROR
),
154 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_MESH_CONSTRUCTION
),
155 DEFINE_NIL_CONTEXT (CAIRO_STATUS_DEVICE_FINISHED
),
156 DEFINE_NIL_CONTEXT (CAIRO_STATUS_JBIG2_GLOBAL_MISSING
)
159 COMPILE_TIME_ASSERT (ARRAY_LENGTH (_cairo_nil
) == CAIRO_STATUS_LAST_STATUS
- 1);
163 * @cr: a cairo context
164 * @status: a status value indicating an error
166 * Atomically sets cr->status to @status and calls _cairo_error;
167 * Does nothing if status is %CAIRO_STATUS_SUCCESS.
169 * All assignments of an error status to cr->status should happen
170 * through _cairo_set_error(). Note that due to the nature of the atomic
171 * operation, it is not safe to call this function on the nil objects.
173 * The purpose of this function is to allow the user to set a
174 * breakpoint in _cairo_error() to generate a stack trace for when the
175 * user causes cairo to detect an error.
178 _cairo_set_error (cairo_t
*cr
, cairo_status_t status
)
180 /* Don't overwrite an existing error. This preserves the first
181 * error, which is the most significant. */
182 _cairo_status_set_error (&cr
->status
, _cairo_error (status
));
186 _cairo_create_in_error (cairo_status_t status
)
190 assert (status
!= CAIRO_STATUS_SUCCESS
);
192 cr
= (cairo_t
*) &_cairo_nil
[status
- CAIRO_STATUS_NO_MEMORY
];
193 assert (status
== cr
->status
);
200 * @target: target surface for the context
202 * Creates a new #cairo_t with all graphics state parameters set to
203 * default values and with @target as a target surface. The target
204 * surface should be constructed with a backend-specific function such
205 * as cairo_image_surface_create() (or any other
206 * <function>cairo_<emphasis>backend</emphasis>_surface_create(<!-- -->)</function>
209 * This function references @target, so you can immediately
210 * call cairo_surface_destroy() on it if you don't need to
211 * maintain a separate reference to it.
213 * Return value: a newly allocated #cairo_t with a reference
214 * count of 1. The initial reference count should be released
215 * with cairo_destroy() when you are done using the #cairo_t.
216 * This function never returns %NULL. If memory cannot be
217 * allocated, a special #cairo_t object will be returned on
218 * which cairo_status() returns %CAIRO_STATUS_NO_MEMORY. If
219 * you attempt to target a surface which does not support
220 * writing (such as #cairo_mime_surface_t) then a
221 * %CAIRO_STATUS_WRITE_ERROR will be raised. You can use this
222 * object normally, but no drawing will be done.
227 cairo_create (cairo_surface_t
*target
)
229 if (unlikely (target
== NULL
))
230 return _cairo_create_in_error (_cairo_error (CAIRO_STATUS_NULL_POINTER
));
231 if (unlikely (target
->status
))
232 return _cairo_create_in_error (target
->status
);
233 if (unlikely (target
->finished
))
234 return _cairo_create_in_error (_cairo_error (CAIRO_STATUS_SURFACE_FINISHED
));
236 if (target
->backend
->create_context
== NULL
)
237 return _cairo_create_in_error (_cairo_error (CAIRO_STATUS_WRITE_ERROR
));
239 return target
->backend
->create_context (target
);
242 slim_hidden_def (cairo_create
);
245 _cairo_init (cairo_t
*cr
,
246 const cairo_backend_t
*backend
)
248 CAIRO_REFERENCE_COUNT_INIT (&cr
->ref_count
, 1);
249 cr
->status
= CAIRO_STATUS_SUCCESS
;
250 _cairo_user_data_array_init (&cr
->user_data
);
252 cr
->backend
= backend
;
259 * Increases the reference count on @cr by one. This prevents
260 * @cr from being destroyed until a matching call to cairo_destroy()
263 * The number of references to a #cairo_t can be get using
264 * cairo_get_reference_count().
266 * Return value: the referenced #cairo_t.
271 cairo_reference (cairo_t
*cr
)
273 if (cr
== NULL
|| CAIRO_REFERENCE_COUNT_IS_INVALID (&cr
->ref_count
))
276 assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&cr
->ref_count
));
278 _cairo_reference_count_inc (&cr
->ref_count
);
284 _cairo_fini (cairo_t
*cr
)
286 _cairo_user_data_array_fini (&cr
->user_data
);
293 * Decreases the reference count on @cr by one. If the result
294 * is zero, then @cr and all associated resources are freed.
295 * See cairo_reference().
300 cairo_destroy (cairo_t
*cr
)
302 if (cr
== NULL
|| CAIRO_REFERENCE_COUNT_IS_INVALID (&cr
->ref_count
))
305 assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&cr
->ref_count
));
307 if (! _cairo_reference_count_dec_and_test (&cr
->ref_count
))
310 cr
->backend
->destroy (cr
);
312 slim_hidden_def (cairo_destroy
);
315 * cairo_get_user_data:
317 * @key: the address of the #cairo_user_data_key_t the user data was
320 * Return user data previously attached to @cr using the specified
321 * key. If no user data has been attached with the given key this
322 * function returns %NULL.
324 * Return value: the user data previously attached or %NULL.
329 cairo_get_user_data (cairo_t
*cr
,
330 const cairo_user_data_key_t
*key
)
332 return _cairo_user_data_array_get_data (&cr
->user_data
, key
);
336 * cairo_set_user_data:
338 * @key: the address of a #cairo_user_data_key_t to attach the user data to
339 * @user_data: the user data to attach to the #cairo_t
340 * @destroy: a #cairo_destroy_func_t which will be called when the
341 * #cairo_t is destroyed or when new user data is attached using the
344 * Attach user data to @cr. To remove user data from a surface,
345 * call this function with the key that was used to set it and %NULL
348 * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a
349 * slot could not be allocated for the user data.
354 cairo_set_user_data (cairo_t
*cr
,
355 const cairo_user_data_key_t
*key
,
357 cairo_destroy_func_t destroy
)
359 if (CAIRO_REFERENCE_COUNT_IS_INVALID (&cr
->ref_count
))
362 return _cairo_user_data_array_set_data (&cr
->user_data
,
363 key
, user_data
, destroy
);
367 * cairo_get_reference_count:
370 * Returns the current reference count of @cr.
372 * Return value: the current reference count of @cr. If the
373 * object is a nil object, 0 will be returned.
378 cairo_get_reference_count (cairo_t
*cr
)
380 if (cr
== NULL
|| CAIRO_REFERENCE_COUNT_IS_INVALID (&cr
->ref_count
))
383 return CAIRO_REFERENCE_COUNT_GET_VALUE (&cr
->ref_count
);
390 * Makes a copy of the current state of @cr and saves it
391 * on an internal stack of saved states for @cr. When
392 * cairo_restore() is called, @cr will be restored to
393 * the saved state. Multiple calls to cairo_save() and
394 * cairo_restore() can be nested; each call to cairo_restore()
395 * restores the state from the matching paired cairo_save().
397 * It isn't necessary to clear all saved states before
398 * a #cairo_t is freed. If the reference count of a #cairo_t
399 * drops to zero in response to a call to cairo_destroy(),
400 * any saved states will be freed along with the #cairo_t.
405 cairo_save (cairo_t
*cr
)
407 cairo_status_t status
;
409 if (unlikely (cr
->status
))
412 status
= cr
->backend
->save (cr
);
413 if (unlikely (status
))
414 _cairo_set_error (cr
, status
);
416 slim_hidden_def(cairo_save
);
422 * Restores @cr to the state saved by a preceding call to
423 * cairo_save() and removes that state from the stack of
429 cairo_restore (cairo_t
*cr
)
431 cairo_status_t status
;
433 if (unlikely (cr
->status
))
436 status
= cr
->backend
->restore (cr
);
437 if (unlikely (status
))
438 _cairo_set_error (cr
, status
);
440 slim_hidden_def(cairo_restore
);
444 * @cr: a cairo context
446 * Temporarily redirects drawing to an intermediate surface known as a
447 * group. The redirection lasts until the group is completed by a call
448 * to cairo_pop_group() or cairo_pop_group_to_source(). These calls
449 * provide the result of any drawing to the group as a pattern,
450 * (either as an explicit object, or set as the source pattern).
452 * This group functionality can be convenient for performing
453 * intermediate compositing. One common use of a group is to render
454 * objects as opaque within the group, (so that they occlude each
455 * other), and then blend the result with translucence onto the
458 * Groups can be nested arbitrarily deep by making balanced calls to
459 * cairo_push_group()/cairo_pop_group(). Each call pushes/pops the new
460 * target group onto/from a stack.
462 * The cairo_push_group() function calls cairo_save() so that any
463 * changes to the graphics state will not be visible outside the
464 * group, (the pop_group functions call cairo_restore()).
466 * By default the intermediate group will have a content type of
467 * %CAIRO_CONTENT_COLOR_ALPHA. Other content types can be chosen for
468 * the group by using cairo_push_group_with_content() instead.
470 * As an example, here is how one might fill and stroke a path with
471 * translucence, but without any portion of the fill being visible
474 * <informalexample><programlisting>
475 * cairo_push_group (cr);
476 * cairo_set_source (cr, fill_pattern);
477 * cairo_fill_preserve (cr);
478 * cairo_set_source (cr, stroke_pattern);
480 * cairo_pop_group_to_source (cr);
481 * cairo_paint_with_alpha (cr, alpha);
482 * </programlisting></informalexample>
487 cairo_push_group (cairo_t
*cr
)
489 cairo_push_group_with_content (cr
, CAIRO_CONTENT_COLOR_ALPHA
);
493 * cairo_push_group_with_content:
494 * @cr: a cairo context
495 * @content: a #cairo_content_t indicating the type of group that
498 * Temporarily redirects drawing to an intermediate surface known as a
499 * group. The redirection lasts until the group is completed by a call
500 * to cairo_pop_group() or cairo_pop_group_to_source(). These calls
501 * provide the result of any drawing to the group as a pattern,
502 * (either as an explicit object, or set as the source pattern).
504 * The group will have a content type of @content. The ability to
505 * control this content type is the only distinction between this
506 * function and cairo_push_group() which you should see for a more
507 * detailed description of group rendering.
512 cairo_push_group_with_content (cairo_t
*cr
, cairo_content_t content
)
514 cairo_status_t status
;
516 if (unlikely (cr
->status
))
519 status
= cr
->backend
->push_group (cr
, content
);
520 if (unlikely (status
))
521 _cairo_set_error (cr
, status
);
523 slim_hidden_def(cairo_push_group_with_content
);
527 * @cr: a cairo context
529 * Terminates the redirection begun by a call to cairo_push_group() or
530 * cairo_push_group_with_content() and returns a new pattern
531 * containing the results of all drawing operations performed to the
534 * The cairo_pop_group() function calls cairo_restore(), (balancing a
535 * call to cairo_save() by the push_group function), so that any
536 * changes to the graphics state will not be visible outside the
539 * Return value: a newly created (surface) pattern containing the
540 * results of all drawing operations performed to the group. The
541 * caller owns the returned object and should call
542 * cairo_pattern_destroy() when finished with it.
547 cairo_pop_group (cairo_t
*cr
)
549 cairo_pattern_t
*group_pattern
;
551 if (unlikely (cr
->status
))
552 return _cairo_pattern_create_in_error (cr
->status
);
554 group_pattern
= cr
->backend
->pop_group (cr
);
555 if (unlikely (group_pattern
->status
))
556 _cairo_set_error (cr
, group_pattern
->status
);
558 return group_pattern
;
560 slim_hidden_def(cairo_pop_group
);
563 * cairo_pop_group_to_source:
564 * @cr: a cairo context
566 * Terminates the redirection begun by a call to cairo_push_group() or
567 * cairo_push_group_with_content() and installs the resulting pattern
568 * as the source pattern in the given cairo context.
570 * The behavior of this function is equivalent to the sequence of
573 * <informalexample><programlisting>
574 * cairo_pattern_t *group = cairo_pop_group (cr);
575 * cairo_set_source (cr, group);
576 * cairo_pattern_destroy (group);
577 * </programlisting></informalexample>
579 * but is more convenient as their is no need for a variable to store
580 * the short-lived pointer to the pattern.
582 * The cairo_pop_group() function calls cairo_restore(), (balancing a
583 * call to cairo_save() by the push_group function), so that any
584 * changes to the graphics state will not be visible outside the
590 cairo_pop_group_to_source (cairo_t
*cr
)
592 cairo_pattern_t
*group_pattern
;
594 group_pattern
= cairo_pop_group (cr
);
595 cairo_set_source (cr
, group_pattern
);
596 cairo_pattern_destroy (group_pattern
);
600 * cairo_set_operator:
602 * @op: a compositing operator, specified as a #cairo_operator_t
604 * Sets the compositing operator to be used for all drawing
605 * operations. See #cairo_operator_t for details on the semantics of
606 * each available compositing operator.
608 * The default operator is %CAIRO_OPERATOR_OVER.
613 cairo_set_operator (cairo_t
*cr
, cairo_operator_t op
)
615 cairo_status_t status
;
617 if (unlikely (cr
->status
))
620 status
= cr
->backend
->set_operator (cr
, op
);
621 if (unlikely (status
))
622 _cairo_set_error (cr
, status
);
624 slim_hidden_def (cairo_set_operator
);
631 * @opacity: the level of opacity to use when compositing
633 * Sets the compositing opacity to be used for all drawing
634 * operations. The effect is to fade out the operations
635 * using the alpha value.
637 * The default opacity is 1.
642 cairo_set_opacity (cairo_t
*cr
, double opacity
)
644 cairo_status_t status
;
646 if (unlikely (cr
->status
))
649 status
= cr
->backend
->set_opacity (cr
, opacity
);
650 if (unlikely (status
))
651 _cairo_set_error (cr
, status
);
656 * cairo_set_source_rgb:
657 * @cr: a cairo context
658 * @red: red component of color
659 * @green: green component of color
660 * @blue: blue component of color
662 * Sets the source pattern within @cr to an opaque color. This opaque
663 * color will then be used for any subsequent drawing operation until
664 * a new source pattern is set.
666 * The color components are floating point numbers in the range 0 to
667 * 1. If the values passed in are outside that range, they will be
670 * The default source pattern is opaque black, (that is, it is
671 * equivalent to cairo_set_source_rgb(cr, 0.0, 0.0, 0.0)).
676 cairo_set_source_rgb (cairo_t
*cr
, double red
, double green
, double blue
)
678 cairo_status_t status
;
680 if (unlikely (cr
->status
))
683 status
= cr
->backend
->set_source_rgba (cr
, red
, green
, blue
, 1.);
684 if (unlikely (status
))
685 _cairo_set_error (cr
, status
);
687 slim_hidden_def (cairo_set_source_rgb
);
690 * cairo_set_source_rgba:
691 * @cr: a cairo context
692 * @red: red component of color
693 * @green: green component of color
694 * @blue: blue component of color
695 * @alpha: alpha component of color
697 * Sets the source pattern within @cr to a translucent color. This
698 * color will then be used for any subsequent drawing operation until
699 * a new source pattern is set.
701 * The color and alpha components are floating point numbers in the
702 * range 0 to 1. If the values passed in are outside that range, they
705 * The default source pattern is opaque black, (that is, it is
706 * equivalent to cairo_set_source_rgba(cr, 0.0, 0.0, 0.0, 1.0)).
711 cairo_set_source_rgba (cairo_t
*cr
,
712 double red
, double green
, double blue
,
715 cairo_status_t status
;
717 if (unlikely (cr
->status
))
720 status
= cr
->backend
->set_source_rgba (cr
, red
, green
, blue
, alpha
);
721 if (unlikely (status
))
722 _cairo_set_error (cr
, status
);
726 * cairo_set_source_surface:
727 * @cr: a cairo context
728 * @surface: a surface to be used to set the source pattern
729 * @x: User-space X coordinate for surface origin
730 * @y: User-space Y coordinate for surface origin
732 * This is a convenience function for creating a pattern from @surface
733 * and setting it as the source in @cr with cairo_set_source().
735 * The @x and @y parameters give the user-space coordinate at which
736 * the surface origin should appear. (The surface origin is its
737 * upper-left corner before any transformation has been applied.) The
738 * @x and @y parameters are negated and then set as translation values
739 * in the pattern matrix.
741 * Other than the initial translation pattern matrix, as described
742 * above, all other pattern attributes, (such as its extend mode), are
743 * set to the default values as in cairo_pattern_create_for_surface().
744 * The resulting pattern can be queried with cairo_get_source() so
745 * that these attributes can be modified if desired, (eg. to create a
746 * repeating pattern with cairo_pattern_set_extend()).
751 cairo_set_source_surface (cairo_t
*cr
,
752 cairo_surface_t
*surface
,
756 cairo_status_t status
;
758 if (unlikely (cr
->status
))
761 if (unlikely (surface
== NULL
)) {
762 _cairo_set_error (cr
, CAIRO_STATUS_NULL_POINTER
);
766 status
= cr
->backend
->set_source_surface (cr
, surface
, x
, y
);
767 if (unlikely (status
))
768 _cairo_set_error (cr
, status
);
770 slim_hidden_def (cairo_set_source_surface
);
774 * @cr: a cairo context
775 * @source: a #cairo_pattern_t to be used as the source for
776 * subsequent drawing operations.
778 * Sets the source pattern within @cr to @source. This pattern
779 * will then be used for any subsequent drawing operation until a new
780 * source pattern is set.
782 * Note: The pattern's transformation matrix will be locked to the
783 * user space in effect at the time of cairo_set_source(). This means
784 * that further modifications of the current transformation matrix
785 * will not affect the source pattern. See cairo_pattern_set_matrix().
787 * The default source pattern is a solid pattern that is opaque black,
788 * (that is, it is equivalent to cairo_set_source_rgb(cr, 0.0, 0.0,
794 cairo_set_source (cairo_t
*cr
, cairo_pattern_t
*source
)
796 cairo_status_t status
;
798 if (unlikely (cr
->status
))
801 if (unlikely (source
== NULL
)) {
802 _cairo_set_error (cr
, CAIRO_STATUS_NULL_POINTER
);
806 if (unlikely (source
->status
)) {
807 _cairo_set_error (cr
, source
->status
);
811 status
= cr
->backend
->set_source (cr
, source
);
812 if (unlikely (status
))
813 _cairo_set_error (cr
, status
);
815 slim_hidden_def (cairo_set_source
);
819 * @cr: a cairo context
821 * Gets the current source pattern for @cr.
823 * Return value: the current source pattern. This object is owned by
824 * cairo. To keep a reference to it, you must call
825 * cairo_pattern_reference().
830 cairo_get_source (cairo_t
*cr
)
832 if (unlikely (cr
->status
))
833 return _cairo_pattern_create_in_error (cr
->status
);
835 return cr
->backend
->get_source (cr
);
839 * cairo_set_tolerance:
841 * @tolerance: the tolerance, in device units (typically pixels)
843 * Sets the tolerance used when converting paths into trapezoids.
844 * Curved segments of the path will be subdivided until the maximum
845 * deviation between the original path and the polygonal approximation
846 * is less than @tolerance. The default value is 0.1. A larger
847 * value will give better performance, a smaller value, better
848 * appearance. (Reducing the value from the default value of 0.1
849 * is unlikely to improve appearance significantly.) The accuracy of paths
850 * within Cairo is limited by the precision of its internal arithmetic, and
851 * the prescribed @tolerance is restricted to the smallest
852 * representable internal value.
857 cairo_set_tolerance (cairo_t
*cr
, double tolerance
)
859 cairo_status_t status
;
861 if (unlikely (cr
->status
))
864 status
= cr
->backend
->set_tolerance (cr
, tolerance
);
865 if (unlikely (status
))
866 _cairo_set_error (cr
, status
);
868 slim_hidden_def (cairo_set_tolerance
);
871 * cairo_set_antialias:
873 * @antialias: the new antialiasing mode
875 * Set the antialiasing mode of the rasterizer used for drawing shapes.
876 * This value is a hint, and a particular backend may or may not support
877 * a particular value. At the current time, no backend supports
878 * %CAIRO_ANTIALIAS_SUBPIXEL when drawing shapes.
880 * Note that this option does not affect text rendering, instead see
881 * cairo_font_options_set_antialias().
886 cairo_set_antialias (cairo_t
*cr
, cairo_antialias_t antialias
)
888 cairo_status_t status
;
890 if (unlikely (cr
->status
))
893 status
= cr
->backend
->set_antialias (cr
, antialias
);
894 if (unlikely (status
))
895 _cairo_set_error (cr
, status
);
899 * cairo_set_fill_rule:
901 * @fill_rule: a fill rule, specified as a #cairo_fill_rule_t
903 * Set the current fill rule within the cairo context. The fill rule
904 * is used to determine which regions are inside or outside a complex
905 * (potentially self-intersecting) path. The current fill rule affects
906 * both cairo_fill() and cairo_clip(). See #cairo_fill_rule_t for details
907 * on the semantics of each available fill rule.
909 * The default fill rule is %CAIRO_FILL_RULE_WINDING.
914 cairo_set_fill_rule (cairo_t
*cr
, cairo_fill_rule_t fill_rule
)
916 cairo_status_t status
;
918 if (unlikely (cr
->status
))
921 status
= cr
->backend
->set_fill_rule (cr
, fill_rule
);
922 if (unlikely (status
))
923 _cairo_set_error (cr
, status
);
927 * cairo_set_line_width:
929 * @width: a line width
931 * Sets the current line width within the cairo context. The line
932 * width value specifies the diameter of a pen that is circular in
933 * user space, (though device-space pen may be an ellipse in general
934 * due to scaling/shear/rotation of the CTM).
936 * Note: When the description above refers to user space and CTM it
937 * refers to the user space and CTM in effect at the time of the
938 * stroking operation, not the user space and CTM in effect at the
939 * time of the call to cairo_set_line_width(). The simplest usage
940 * makes both of these spaces identical. That is, if there is no
941 * change to the CTM between a call to cairo_set_line_width() and the
942 * stroking operation, then one can just pass user-space values to
943 * cairo_set_line_width() and ignore this note.
945 * As with the other stroke parameters, the current line width is
946 * examined by cairo_stroke(), cairo_stroke_extents(), and
947 * cairo_stroke_to_path(), but does not have any effect during path
950 * The default line width value is 2.0.
955 cairo_set_line_width (cairo_t
*cr
, double width
)
957 cairo_status_t status
;
959 if (unlikely (cr
->status
))
965 status
= cr
->backend
->set_line_width (cr
, width
);
966 if (unlikely (status
))
967 _cairo_set_error (cr
, status
);
969 slim_hidden_def (cairo_set_line_width
);
972 * cairo_set_line_cap:
973 * @cr: a cairo context
974 * @line_cap: a line cap style
976 * Sets the current line cap style within the cairo context. See
977 * #cairo_line_cap_t for details about how the available line cap
980 * As with the other stroke parameters, the current line cap style is
981 * examined by cairo_stroke(), cairo_stroke_extents(), and
982 * cairo_stroke_to_path(), but does not have any effect during path
985 * The default line cap style is %CAIRO_LINE_CAP_BUTT.
990 cairo_set_line_cap (cairo_t
*cr
, cairo_line_cap_t line_cap
)
992 cairo_status_t status
;
994 if (unlikely (cr
->status
))
997 status
= cr
->backend
->set_line_cap (cr
, line_cap
);
998 if (unlikely (status
))
999 _cairo_set_error (cr
, status
);
1001 slim_hidden_def (cairo_set_line_cap
);
1004 * cairo_set_line_join:
1005 * @cr: a cairo context
1006 * @line_join: a line join style
1008 * Sets the current line join style within the cairo context. See
1009 * #cairo_line_join_t for details about how the available line join
1012 * As with the other stroke parameters, the current line join style is
1013 * examined by cairo_stroke(), cairo_stroke_extents(), and
1014 * cairo_stroke_to_path(), but does not have any effect during path
1017 * The default line join style is %CAIRO_LINE_JOIN_MITER.
1022 cairo_set_line_join (cairo_t
*cr
, cairo_line_join_t line_join
)
1024 cairo_status_t status
;
1026 if (unlikely (cr
->status
))
1029 status
= cr
->backend
->set_line_join (cr
, line_join
);
1030 if (unlikely (status
))
1031 _cairo_set_error (cr
, status
);
1033 slim_hidden_def (cairo_set_line_join
);
1037 * @cr: a cairo context
1038 * @dashes: an array specifying alternate lengths of on and off stroke portions
1039 * @num_dashes: the length of the dashes array
1040 * @offset: an offset into the dash pattern at which the stroke should start
1042 * Sets the dash pattern to be used by cairo_stroke(). A dash pattern
1043 * is specified by @dashes, an array of positive values. Each value
1044 * provides the length of alternate "on" and "off" portions of the
1045 * stroke. The @offset specifies an offset into the pattern at which
1046 * the stroke begins.
1048 * Each "on" segment will have caps applied as if the segment were a
1049 * separate sub-path. In particular, it is valid to use an "on" length
1050 * of 0.0 with %CAIRO_LINE_CAP_ROUND or %CAIRO_LINE_CAP_SQUARE in order
1051 * to distributed dots or squares along a path.
1053 * Note: The length values are in user-space units as evaluated at the
1054 * time of stroking. This is not necessarily the same as the user
1055 * space at the time of cairo_set_dash().
1057 * If @num_dashes is 0 dashing is disabled.
1059 * If @num_dashes is 1 a symmetric pattern is assumed with alternating
1060 * on and off portions of the size specified by the single value in
1063 * If any value in @dashes is negative, or if all values are 0, then
1064 * @cr will be put into an error state with a status of
1065 * %CAIRO_STATUS_INVALID_DASH.
1070 cairo_set_dash (cairo_t
*cr
,
1071 const double *dashes
,
1075 cairo_status_t status
;
1077 if (unlikely (cr
->status
))
1080 status
= cr
->backend
->set_dash (cr
, dashes
, num_dashes
, offset
);
1081 if (unlikely (status
))
1082 _cairo_set_error (cr
, status
);
1086 * cairo_get_dash_count:
1089 * This function returns the length of the dash array in @cr (0 if dashing
1090 * is not currently in effect).
1092 * See also cairo_set_dash() and cairo_get_dash().
1094 * Return value: the length of the dash array, or 0 if no dash array set.
1099 cairo_get_dash_count (cairo_t
*cr
)
1103 if (unlikely (cr
->status
))
1106 cr
->backend
->get_dash (cr
, NULL
, &num_dashes
, NULL
);
1114 * @dashes: return value for the dash array, or %NULL
1115 * @offset: return value for the current dash offset, or %NULL
1117 * Gets the current dash array. If not %NULL, @dashes should be big
1118 * enough to hold at least the number of values returned by
1119 * cairo_get_dash_count().
1124 cairo_get_dash (cairo_t
*cr
,
1128 if (unlikely (cr
->status
))
1131 cr
->backend
->get_dash (cr
, dashes
, NULL
, offset
);
1135 * cairo_set_miter_limit:
1136 * @cr: a cairo context
1137 * @limit: miter limit to set
1139 * Sets the current miter limit within the cairo context.
1141 * If the current line join style is set to %CAIRO_LINE_JOIN_MITER
1142 * (see cairo_set_line_join()), the miter limit is used to determine
1143 * whether the lines should be joined with a bevel instead of a miter.
1144 * Cairo divides the length of the miter by the line width.
1145 * If the result is greater than the miter limit, the style is
1146 * converted to a bevel.
1148 * As with the other stroke parameters, the current line miter limit is
1149 * examined by cairo_stroke(), cairo_stroke_extents(), and
1150 * cairo_stroke_to_path(), but does not have any effect during path
1153 * The default miter limit value is 10.0, which will convert joins
1154 * with interior angles less than 11 degrees to bevels instead of
1155 * miters. For reference, a miter limit of 2.0 makes the miter cutoff
1156 * at 60 degrees, and a miter limit of 1.414 makes the cutoff at 90
1159 * A miter limit for a desired angle can be computed as: miter limit =
1165 cairo_set_miter_limit (cairo_t
*cr
, double limit
)
1167 cairo_status_t status
;
1169 if (unlikely (cr
->status
))
1172 status
= cr
->backend
->set_miter_limit (cr
, limit
);
1173 if (unlikely (status
))
1174 _cairo_set_error (cr
, status
);
1179 * @cr: a cairo context
1180 * @tx: amount to translate in the X direction
1181 * @ty: amount to translate in the Y direction
1183 * Modifies the current transformation matrix (CTM) by translating the
1184 * user-space origin by (@tx, @ty). This offset is interpreted as a
1185 * user-space coordinate according to the CTM in place before the new
1186 * call to cairo_translate(). In other words, the translation of the
1187 * user-space origin takes place after any existing transformation.
1192 cairo_translate (cairo_t
*cr
, double tx
, double ty
)
1194 cairo_status_t status
;
1196 if (unlikely (cr
->status
))
1199 status
= cr
->backend
->translate (cr
, tx
, ty
);
1200 if (unlikely (status
))
1201 _cairo_set_error (cr
, status
);
1203 slim_hidden_def (cairo_translate
);
1207 * @cr: a cairo context
1208 * @sx: scale factor for the X dimension
1209 * @sy: scale factor for the Y dimension
1211 * Modifies the current transformation matrix (CTM) by scaling the X
1212 * and Y user-space axes by @sx and @sy respectively. The scaling of
1213 * the axes takes place after any existing transformation of user
1219 cairo_scale (cairo_t
*cr
, double sx
, double sy
)
1221 cairo_status_t status
;
1223 if (unlikely (cr
->status
))
1226 status
= cr
->backend
->scale (cr
, sx
, sy
);
1227 if (unlikely (status
))
1228 _cairo_set_error (cr
, status
);
1230 slim_hidden_def (cairo_scale
);
1234 * @cr: a cairo context
1235 * @angle: angle (in radians) by which the user-space axes will be
1238 * Modifies the current transformation matrix (CTM) by rotating the
1239 * user-space axes by @angle radians. The rotation of the axes takes
1240 * places after any existing transformation of user space. The
1241 * rotation direction for positive angles is from the positive X axis
1242 * toward the positive Y axis.
1247 cairo_rotate (cairo_t
*cr
, double angle
)
1249 cairo_status_t status
;
1251 if (unlikely (cr
->status
))
1254 status
= cr
->backend
->rotate (cr
, angle
);
1255 if (unlikely (status
))
1256 _cairo_set_error (cr
, status
);
1261 * @cr: a cairo context
1262 * @matrix: a transformation to be applied to the user-space axes
1264 * Modifies the current transformation matrix (CTM) by applying
1265 * @matrix as an additional transformation. The new transformation of
1266 * user space takes place after any existing transformation.
1271 cairo_transform (cairo_t
*cr
,
1272 const cairo_matrix_t
*matrix
)
1274 cairo_status_t status
;
1276 if (unlikely (cr
->status
))
1279 status
= cr
->backend
->transform (cr
, matrix
);
1280 if (unlikely (status
))
1281 _cairo_set_error (cr
, status
);
1283 slim_hidden_def (cairo_transform
);
1287 * @cr: a cairo context
1288 * @matrix: a transformation matrix from user space to device space
1290 * Modifies the current transformation matrix (CTM) by setting it
1296 cairo_set_matrix (cairo_t
*cr
,
1297 const cairo_matrix_t
*matrix
)
1299 cairo_status_t status
;
1301 if (unlikely (cr
->status
))
1304 status
= cr
->backend
->set_matrix (cr
, matrix
);
1305 if (unlikely (status
))
1306 _cairo_set_error (cr
, status
);
1308 slim_hidden_def (cairo_set_matrix
);
1311 * cairo_identity_matrix:
1312 * @cr: a cairo context
1314 * Resets the current transformation matrix (CTM) by setting it equal
1315 * to the identity matrix. That is, the user-space and device-space
1316 * axes will be aligned and one user-space unit will transform to one
1317 * device-space unit.
1322 cairo_identity_matrix (cairo_t
*cr
)
1324 cairo_status_t status
;
1326 if (unlikely (cr
->status
))
1329 status
= cr
->backend
->set_identity_matrix (cr
);
1330 if (unlikely (status
))
1331 _cairo_set_error (cr
, status
);
1335 * cairo_user_to_device:
1336 * @cr: a cairo context
1337 * @x: X value of coordinate (in/out parameter)
1338 * @y: Y value of coordinate (in/out parameter)
1340 * Transform a coordinate from user space to device space by
1341 * multiplying the given point by the current transformation matrix
1347 cairo_user_to_device (cairo_t
*cr
, double *x
, double *y
)
1349 if (unlikely (cr
->status
))
1352 cr
->backend
->user_to_device (cr
, x
, y
);
1354 slim_hidden_def (cairo_user_to_device
);
1357 * cairo_user_to_device_distance:
1358 * @cr: a cairo context
1359 * @dx: X component of a distance vector (in/out parameter)
1360 * @dy: Y component of a distance vector (in/out parameter)
1362 * Transform a distance vector from user space to device space. This
1363 * function is similar to cairo_user_to_device() except that the
1364 * translation components of the CTM will be ignored when transforming
1370 cairo_user_to_device_distance (cairo_t
*cr
, double *dx
, double *dy
)
1372 if (unlikely (cr
->status
))
1375 cr
->backend
->user_to_device_distance (cr
, dx
, dy
);
1377 slim_hidden_def (cairo_user_to_device_distance
);
1380 * cairo_device_to_user:
1382 * @x: X value of coordinate (in/out parameter)
1383 * @y: Y value of coordinate (in/out parameter)
1385 * Transform a coordinate from device space to user space by
1386 * multiplying the given point by the inverse of the current
1387 * transformation matrix (CTM).
1392 cairo_device_to_user (cairo_t
*cr
, double *x
, double *y
)
1394 if (unlikely (cr
->status
))
1397 cr
->backend
->device_to_user (cr
, x
, y
);
1399 slim_hidden_def (cairo_device_to_user
);
1402 * cairo_device_to_user_distance:
1403 * @cr: a cairo context
1404 * @dx: X component of a distance vector (in/out parameter)
1405 * @dy: Y component of a distance vector (in/out parameter)
1407 * Transform a distance vector from device space to user space. This
1408 * function is similar to cairo_device_to_user() except that the
1409 * translation components of the inverse CTM will be ignored when
1410 * transforming (@dx,@dy).
1415 cairo_device_to_user_distance (cairo_t
*cr
, double *dx
, double *dy
)
1417 if (unlikely (cr
->status
))
1420 cr
->backend
->device_to_user_distance (cr
, dx
, dy
);
1425 * @cr: a cairo context
1427 * Clears the current path. After this call there will be no path and
1433 cairo_new_path (cairo_t
*cr
)
1435 cairo_status_t status
;
1437 if (unlikely (cr
->status
))
1440 status
= cr
->backend
->new_path (cr
);
1441 if (unlikely (status
))
1442 _cairo_set_error (cr
, status
);
1444 slim_hidden_def(cairo_new_path
);
1447 * cairo_new_sub_path:
1448 * @cr: a cairo context
1450 * Begin a new sub-path. Note that the existing path is not
1451 * affected. After this call there will be no current point.
1453 * In many cases, this call is not needed since new sub-paths are
1454 * frequently started with cairo_move_to().
1456 * A call to cairo_new_sub_path() is particularly useful when
1457 * beginning a new sub-path with one of the cairo_arc() calls. This
1458 * makes things easier as it is no longer necessary to manually
1459 * compute the arc's initial coordinates for a call to
1465 cairo_new_sub_path (cairo_t
*cr
)
1467 cairo_status_t status
;
1469 if (unlikely (cr
->status
))
1472 status
= cr
->backend
->new_sub_path (cr
);
1473 if (unlikely (status
))
1474 _cairo_set_error (cr
, status
);
1479 * @cr: a cairo context
1480 * @x: the X coordinate of the new position
1481 * @y: the Y coordinate of the new position
1483 * Begin a new sub-path. After this call the current point will be (@x,
1489 cairo_move_to (cairo_t
*cr
, double x
, double y
)
1491 cairo_status_t status
;
1493 if (unlikely (cr
->status
))
1496 status
= cr
->backend
->move_to (cr
, x
, y
);
1497 if (unlikely (status
))
1498 _cairo_set_error (cr
, status
);
1500 slim_hidden_def(cairo_move_to
);
1505 * @cr: a cairo context
1506 * @x: the X coordinate of the end of the new line
1507 * @y: the Y coordinate of the end of the new line
1509 * Adds a line to the path from the current point to position (@x, @y)
1510 * in user-space coordinates. After this call the current point
1513 * If there is no current point before the call to cairo_line_to()
1514 * this function will behave as cairo_move_to(@cr, @x, @y).
1519 cairo_line_to (cairo_t
*cr
, double x
, double y
)
1521 cairo_status_t status
;
1523 if (unlikely (cr
->status
))
1526 status
= cr
->backend
->line_to (cr
, x
, y
);
1527 if (unlikely (status
))
1528 _cairo_set_error (cr
, status
);
1530 slim_hidden_def (cairo_line_to
);
1534 * @cr: a cairo context
1535 * @x1: the X coordinate of the first control point
1536 * @y1: the Y coordinate of the first control point
1537 * @x2: the X coordinate of the second control point
1538 * @y2: the Y coordinate of the second control point
1539 * @x3: the X coordinate of the end of the curve
1540 * @y3: the Y coordinate of the end of the curve
1542 * Adds a cubic Bézier spline to the path from the current point to
1543 * position (@x3, @y3) in user-space coordinates, using (@x1, @y1) and
1544 * (@x2, @y2) as the control points. After this call the current point
1545 * will be (@x3, @y3).
1547 * If there is no current point before the call to cairo_curve_to()
1548 * this function will behave as if preceded by a call to
1549 * cairo_move_to(@cr, @x1, @y1).
1554 cairo_curve_to (cairo_t
*cr
,
1555 double x1
, double y1
,
1556 double x2
, double y2
,
1557 double x3
, double y3
)
1559 cairo_status_t status
;
1561 if (unlikely (cr
->status
))
1564 status
= cr
->backend
->curve_to (cr
,
1568 if (unlikely (status
))
1569 _cairo_set_error (cr
, status
);
1571 slim_hidden_def (cairo_curve_to
);
1575 * @cr: a cairo context
1576 * @xc: X position of the center of the arc
1577 * @yc: Y position of the center of the arc
1578 * @radius: the radius of the arc
1579 * @angle1: the start angle, in radians
1580 * @angle2: the end angle, in radians
1582 * Adds a circular arc of the given @radius to the current path. The
1583 * arc is centered at (@xc, @yc), begins at @angle1 and proceeds in
1584 * the direction of increasing angles to end at @angle2. If @angle2 is
1585 * less than @angle1 it will be progressively increased by
1586 * <literal>2*M_PI</literal> until it is greater than @angle1.
1588 * If there is a current point, an initial line segment will be added
1589 * to the path to connect the current point to the beginning of the
1590 * arc. If this initial line is undesired, it can be avoided by
1591 * calling cairo_new_sub_path() before calling cairo_arc().
1593 * Angles are measured in radians. An angle of 0.0 is in the direction
1594 * of the positive X axis (in user space). An angle of
1595 * <literal>M_PI/2.0</literal> radians (90 degrees) is in the
1596 * direction of the positive Y axis (in user space). Angles increase
1597 * in the direction from the positive X axis toward the positive Y
1598 * axis. So with the default transformation matrix, angles increase in
1599 * a clockwise direction.
1601 * (To convert from degrees to radians, use <literal>degrees * (M_PI /
1604 * This function gives the arc in the direction of increasing angles;
1605 * see cairo_arc_negative() to get the arc in the direction of
1606 * decreasing angles.
1608 * The arc is circular in user space. To achieve an elliptical arc,
1609 * you can scale the current transformation matrix by different
1610 * amounts in the X and Y directions. For example, to draw an ellipse
1611 * in the box given by @x, @y, @width, @height:
1613 * <informalexample><programlisting>
1615 * cairo_translate (cr, x + width / 2., y + height / 2.);
1616 * cairo_scale (cr, width / 2., height / 2.);
1617 * cairo_arc (cr, 0., 0., 1., 0., 2 * M_PI);
1618 * cairo_restore (cr);
1619 * </programlisting></informalexample>
1624 cairo_arc (cairo_t
*cr
,
1625 double xc
, double yc
,
1627 double angle1
, double angle2
)
1629 cairo_status_t status
;
1631 if (unlikely (cr
->status
))
1634 if (angle2
< angle1
) {
1635 /* increase angle2 by multiples of full circle until it
1636 * satisfies angle2 >= angle1 */
1637 angle2
= fmod (angle2
- angle1
, 2 * M_PI
);
1643 status
= cr
->backend
->arc (cr
, xc
, yc
, radius
, angle1
, angle2
, TRUE
);
1644 if (unlikely (status
))
1645 _cairo_set_error (cr
, status
);
1649 * cairo_arc_negative:
1650 * @cr: a cairo context
1651 * @xc: X position of the center of the arc
1652 * @yc: Y position of the center of the arc
1653 * @radius: the radius of the arc
1654 * @angle1: the start angle, in radians
1655 * @angle2: the end angle, in radians
1657 * Adds a circular arc of the given @radius to the current path. The
1658 * arc is centered at (@xc, @yc), begins at @angle1 and proceeds in
1659 * the direction of decreasing angles to end at @angle2. If @angle2 is
1660 * greater than @angle1 it will be progressively decreased by
1661 * <literal>2*M_PI</literal> until it is less than @angle1.
1663 * See cairo_arc() for more details. This function differs only in the
1664 * direction of the arc between the two angles.
1669 cairo_arc_negative (cairo_t
*cr
,
1670 double xc
, double yc
,
1672 double angle1
, double angle2
)
1674 cairo_status_t status
;
1676 if (unlikely (cr
->status
))
1679 if (angle2
> angle1
) {
1680 /* decrease angle2 by multiples of full circle until it
1681 * satisfies angle2 <= angle1 */
1682 angle2
= fmod (angle2
- angle1
, 2 * M_PI
);
1688 status
= cr
->backend
->arc (cr
, xc
, yc
, radius
, angle1
, angle2
, FALSE
);
1689 if (unlikely (status
))
1690 _cairo_set_error (cr
, status
);
1695 cairo_arc_to (cairo_t *cr,
1696 double x1, double y1,
1697 double x2, double y2,
1700 cairo_status_t status;
1702 if (unlikely (cr->status))
1705 status = cr->backend->arc_to (cr, x1, y1, x2, y2, radius);
1706 if (unlikely (status))
1707 _cairo_set_error (cr, status);
1711 cairo_rel_arc_to (cairo_t *cr,
1712 double dx1, double dy1,
1713 double dx2, double dy2,
1716 cairo_status_t status;
1718 if (unlikely (cr->status))
1721 status = cr->backend->rel_arc_to (cr, dx1, dy1, dx2, dy2, radius);
1722 if (unlikely (status))
1723 _cairo_set_error (cr, status);
1728 * cairo_rel_move_to:
1729 * @cr: a cairo context
1733 * Begin a new sub-path. After this call the current point will offset
1736 * Given a current point of (x, y), cairo_rel_move_to(@cr, @dx, @dy)
1737 * is logically equivalent to cairo_move_to(@cr, x + @dx, y + @dy).
1739 * It is an error to call this function with no current point. Doing
1740 * so will cause @cr to shutdown with a status of
1741 * %CAIRO_STATUS_NO_CURRENT_POINT.
1746 cairo_rel_move_to (cairo_t
*cr
, double dx
, double dy
)
1748 cairo_status_t status
;
1750 if (unlikely (cr
->status
))
1753 status
= cr
->backend
->rel_move_to (cr
, dx
, dy
);
1754 if (unlikely (status
))
1755 _cairo_set_error (cr
, status
);
1759 * cairo_rel_line_to:
1760 * @cr: a cairo context
1761 * @dx: the X offset to the end of the new line
1762 * @dy: the Y offset to the end of the new line
1764 * Relative-coordinate version of cairo_line_to(). Adds a line to the
1765 * path from the current point to a point that is offset from the
1766 * current point by (@dx, @dy) in user space. After this call the
1767 * current point will be offset by (@dx, @dy).
1769 * Given a current point of (x, y), cairo_rel_line_to(@cr, @dx, @dy)
1770 * is logically equivalent to cairo_line_to(@cr, x + @dx, y + @dy).
1772 * It is an error to call this function with no current point. Doing
1773 * so will cause @cr to shutdown with a status of
1774 * %CAIRO_STATUS_NO_CURRENT_POINT.
1779 cairo_rel_line_to (cairo_t
*cr
, double dx
, double dy
)
1781 cairo_status_t status
;
1783 if (unlikely (cr
->status
))
1786 status
= cr
->backend
->rel_line_to (cr
, dx
, dy
);
1787 if (unlikely (status
))
1788 _cairo_set_error (cr
, status
);
1790 slim_hidden_def(cairo_rel_line_to
);
1793 * cairo_rel_curve_to:
1794 * @cr: a cairo context
1795 * @dx1: the X offset to the first control point
1796 * @dy1: the Y offset to the first control point
1797 * @dx2: the X offset to the second control point
1798 * @dy2: the Y offset to the second control point
1799 * @dx3: the X offset to the end of the curve
1800 * @dy3: the Y offset to the end of the curve
1802 * Relative-coordinate version of cairo_curve_to(). All offsets are
1803 * relative to the current point. Adds a cubic Bézier spline to the
1804 * path from the current point to a point offset from the current
1805 * point by (@dx3, @dy3), using points offset by (@dx1, @dy1) and
1806 * (@dx2, @dy2) as the control points. After this call the current
1807 * point will be offset by (@dx3, @dy3).
1809 * Given a current point of (x, y), cairo_rel_curve_to(@cr, @dx1,
1810 * @dy1, @dx2, @dy2, @dx3, @dy3) is logically equivalent to
1811 * cairo_curve_to(@cr, x+@dx1, y+@dy1, x+@dx2, y+@dy2, x+@dx3, y+@dy3).
1813 * It is an error to call this function with no current point. Doing
1814 * so will cause @cr to shutdown with a status of
1815 * %CAIRO_STATUS_NO_CURRENT_POINT.
1820 cairo_rel_curve_to (cairo_t
*cr
,
1821 double dx1
, double dy1
,
1822 double dx2
, double dy2
,
1823 double dx3
, double dy3
)
1825 cairo_status_t status
;
1827 if (unlikely (cr
->status
))
1830 status
= cr
->backend
->rel_curve_to (cr
,
1834 if (unlikely (status
))
1835 _cairo_set_error (cr
, status
);
1840 * @cr: a cairo context
1841 * @x: the X coordinate of the top left corner of the rectangle
1842 * @y: the Y coordinate to the top left corner of the rectangle
1843 * @width: the width of the rectangle
1844 * @height: the height of the rectangle
1846 * Adds a closed sub-path rectangle of the given size to the current
1847 * path at position (@x, @y) in user-space coordinates.
1849 * This function is logically equivalent to:
1850 * <informalexample><programlisting>
1851 * cairo_move_to (cr, x, y);
1852 * cairo_rel_line_to (cr, width, 0);
1853 * cairo_rel_line_to (cr, 0, height);
1854 * cairo_rel_line_to (cr, -width, 0);
1855 * cairo_close_path (cr);
1856 * </programlisting></informalexample>
1861 cairo_rectangle (cairo_t
*cr
,
1863 double width
, double height
)
1865 cairo_status_t status
;
1867 if (unlikely (cr
->status
))
1870 status
= cr
->backend
->rectangle (cr
, x
, y
, width
, height
);
1871 if (unlikely (status
))
1872 _cairo_set_error (cr
, status
);
1878 cairo_stroke_to_path (cairo_t
*cr
)
1880 cairo_status_t status
;
1882 if (unlikely (cr
->status
))
1885 /* The code in _cairo_recording_surface_get_path has a poorman's stroke_to_path */
1887 status
= _cairo_gstate_stroke_path (cr
->gstate
);
1888 if (unlikely (status
))
1889 _cairo_set_error (cr
, status
);
1895 * @cr: a cairo context
1897 * Adds a line segment to the path from the current point to the
1898 * beginning of the current sub-path, (the most recent point passed to
1899 * cairo_move_to()), and closes this sub-path. After this call the
1900 * current point will be at the joined endpoint of the sub-path.
1902 * The behavior of cairo_close_path() is distinct from simply calling
1903 * cairo_line_to() with the equivalent coordinate in the case of
1904 * stroking. When a closed sub-path is stroked, there are no caps on
1905 * the ends of the sub-path. Instead, there is a line join connecting
1906 * the final and initial segments of the sub-path.
1908 * If there is no current point before the call to cairo_close_path(),
1909 * this function will have no effect.
1911 * Note: As of cairo version 1.2.4 any call to cairo_close_path() will
1912 * place an explicit MOVE_TO element into the path immediately after
1913 * the CLOSE_PATH element, (which can be seen in cairo_copy_path() for
1914 * example). This can simplify path processing in some cases as it may
1915 * not be necessary to save the "last move_to point" during processing
1916 * as the MOVE_TO immediately after the CLOSE_PATH will provide that
1922 cairo_close_path (cairo_t
*cr
)
1924 cairo_status_t status
;
1926 if (unlikely (cr
->status
))
1929 status
= cr
->backend
->close_path (cr
);
1930 if (unlikely (status
))
1931 _cairo_set_error (cr
, status
);
1933 slim_hidden_def(cairo_close_path
);
1936 * cairo_path_extents:
1937 * @cr: a cairo context
1938 * @x1: left of the resulting extents
1939 * @y1: top of the resulting extents
1940 * @x2: right of the resulting extents
1941 * @y2: bottom of the resulting extents
1943 * Computes a bounding box in user-space coordinates covering the
1944 * points on the current path. If the current path is empty, returns
1945 * an empty rectangle ((0,0), (0,0)). Stroke parameters, fill rule,
1946 * surface dimensions and clipping are not taken into account.
1948 * Contrast with cairo_fill_extents() and cairo_stroke_extents() which
1949 * return the extents of only the area that would be "inked" by
1950 * the corresponding drawing operations.
1952 * The result of cairo_path_extents() is defined as equivalent to the
1953 * limit of cairo_stroke_extents() with %CAIRO_LINE_CAP_ROUND as the
1954 * line width approaches 0.0, (but never reaching the empty-rectangle
1955 * returned by cairo_stroke_extents() for a line width of 0.0).
1957 * Specifically, this means that zero-area sub-paths such as
1958 * cairo_move_to();cairo_line_to() segments, (even degenerate cases
1959 * where the coordinates to both calls are identical), will be
1960 * considered as contributing to the extents. However, a lone
1961 * cairo_move_to() will not contribute to the results of
1962 * cairo_path_extents().
1967 cairo_path_extents (cairo_t
*cr
,
1968 double *x1
, double *y1
, double *x2
, double *y2
)
1970 if (unlikely (cr
->status
)) {
1983 cr
->backend
->path_extents (cr
, x1
, y1
, x2
, y2
);
1988 * @cr: a cairo context
1990 * A drawing operator that paints the current source everywhere within
1991 * the current clip region.
1996 cairo_paint (cairo_t
*cr
)
1998 cairo_status_t status
;
2000 if (unlikely (cr
->status
))
2003 status
= cr
->backend
->paint (cr
);
2004 if (unlikely (status
))
2005 _cairo_set_error (cr
, status
);
2007 slim_hidden_def (cairo_paint
);
2010 * cairo_paint_with_alpha:
2011 * @cr: a cairo context
2012 * @alpha: alpha value, between 0 (transparent) and 1 (opaque)
2014 * A drawing operator that paints the current source everywhere within
2015 * the current clip region using a mask of constant alpha value
2016 * @alpha. The effect is similar to cairo_paint(), but the drawing
2017 * is faded out using the alpha value.
2022 cairo_paint_with_alpha (cairo_t
*cr
,
2025 cairo_status_t status
;
2027 if (unlikely (cr
->status
))
2030 status
= cr
->backend
->paint_with_alpha (cr
, alpha
);
2031 if (unlikely (status
))
2032 _cairo_set_error (cr
, status
);
2037 * @cr: a cairo context
2038 * @pattern: a #cairo_pattern_t
2040 * A drawing operator that paints the current source
2041 * using the alpha channel of @pattern as a mask. (Opaque
2042 * areas of @pattern are painted with the source, transparent
2043 * areas are not painted.)
2048 cairo_mask (cairo_t
*cr
,
2049 cairo_pattern_t
*pattern
)
2051 cairo_status_t status
;
2053 if (unlikely (cr
->status
))
2056 if (unlikely (pattern
== NULL
)) {
2057 _cairo_set_error (cr
, CAIRO_STATUS_NULL_POINTER
);
2061 if (unlikely (pattern
->status
)) {
2062 _cairo_set_error (cr
, pattern
->status
);
2066 status
= cr
->backend
->mask (cr
, pattern
);
2067 if (unlikely (status
))
2068 _cairo_set_error (cr
, status
);
2070 slim_hidden_def (cairo_mask
);
2073 * cairo_mask_surface:
2074 * @cr: a cairo context
2075 * @surface: a #cairo_surface_t
2076 * @surface_x: X coordinate at which to place the origin of @surface
2077 * @surface_y: Y coordinate at which to place the origin of @surface
2079 * A drawing operator that paints the current source
2080 * using the alpha channel of @surface as a mask. (Opaque
2081 * areas of @surface are painted with the source, transparent
2082 * areas are not painted.)
2087 cairo_mask_surface (cairo_t
*cr
,
2088 cairo_surface_t
*surface
,
2092 cairo_pattern_t
*pattern
;
2093 cairo_matrix_t matrix
;
2095 if (unlikely (cr
->status
))
2098 pattern
= cairo_pattern_create_for_surface (surface
);
2100 cairo_matrix_init_translate (&matrix
, - surface_x
, - surface_y
);
2101 cairo_pattern_set_matrix (pattern
, &matrix
);
2103 cairo_mask (cr
, pattern
);
2105 cairo_pattern_destroy (pattern
);
2110 * @cr: a cairo context
2112 * A drawing operator that strokes the current path according to the
2113 * current line width, line join, line cap, and dash settings. After
2114 * cairo_stroke(), the current path will be cleared from the cairo
2115 * context. See cairo_set_line_width(), cairo_set_line_join(),
2116 * cairo_set_line_cap(), cairo_set_dash(), and
2117 * cairo_stroke_preserve().
2119 * Note: Degenerate segments and sub-paths are treated specially and
2120 * provide a useful result. These can result in two different
2123 * 1. Zero-length "on" segments set in cairo_set_dash(). If the cap
2124 * style is %CAIRO_LINE_CAP_ROUND or %CAIRO_LINE_CAP_SQUARE then these
2125 * segments will be drawn as circular dots or squares respectively. In
2126 * the case of %CAIRO_LINE_CAP_SQUARE, the orientation of the squares
2127 * is determined by the direction of the underlying path.
2129 * 2. A sub-path created by cairo_move_to() followed by either a
2130 * cairo_close_path() or one or more calls to cairo_line_to() to the
2131 * same coordinate as the cairo_move_to(). If the cap style is
2132 * %CAIRO_LINE_CAP_ROUND then these sub-paths will be drawn as circular
2133 * dots. Note that in the case of %CAIRO_LINE_CAP_SQUARE a degenerate
2134 * sub-path will not be drawn at all, (since the correct orientation
2135 * is indeterminate).
2137 * In no case will a cap style of %CAIRO_LINE_CAP_BUTT cause anything
2138 * to be drawn in the case of either degenerate segments or sub-paths.
2143 cairo_stroke (cairo_t
*cr
)
2145 cairo_status_t status
;
2147 if (unlikely (cr
->status
))
2150 status
= cr
->backend
->stroke (cr
);
2151 if (unlikely (status
))
2152 _cairo_set_error (cr
, status
);
2154 slim_hidden_def(cairo_stroke
);
2157 * cairo_stroke_preserve:
2158 * @cr: a cairo context
2160 * A drawing operator that strokes the current path according to the
2161 * current line width, line join, line cap, and dash settings. Unlike
2162 * cairo_stroke(), cairo_stroke_preserve() preserves the path within the
2165 * See cairo_set_line_width(), cairo_set_line_join(),
2166 * cairo_set_line_cap(), cairo_set_dash(), and
2167 * cairo_stroke_preserve().
2172 cairo_stroke_preserve (cairo_t
*cr
)
2174 cairo_status_t status
;
2176 if (unlikely (cr
->status
))
2179 status
= cr
->backend
->stroke_preserve (cr
);
2180 if (unlikely (status
))
2181 _cairo_set_error (cr
, status
);
2183 slim_hidden_def(cairo_stroke_preserve
);
2187 * @cr: a cairo context
2189 * A drawing operator that fills the current path according to the
2190 * current fill rule, (each sub-path is implicitly closed before being
2191 * filled). After cairo_fill(), the current path will be cleared from
2192 * the cairo context. See cairo_set_fill_rule() and
2193 * cairo_fill_preserve().
2198 cairo_fill (cairo_t
*cr
)
2200 cairo_status_t status
;
2202 if (unlikely (cr
->status
))
2205 status
= cr
->backend
->fill (cr
);
2206 if (unlikely (status
))
2207 _cairo_set_error (cr
, status
);
2211 * cairo_fill_preserve:
2212 * @cr: a cairo context
2214 * A drawing operator that fills the current path according to the
2215 * current fill rule, (each sub-path is implicitly closed before being
2216 * filled). Unlike cairo_fill(), cairo_fill_preserve() preserves the
2217 * path within the cairo context.
2219 * See cairo_set_fill_rule() and cairo_fill().
2224 cairo_fill_preserve (cairo_t
*cr
)
2226 cairo_status_t status
;
2228 if (unlikely (cr
->status
))
2231 status
= cr
->backend
->fill_preserve (cr
);
2232 if (unlikely (status
))
2233 _cairo_set_error (cr
, status
);
2235 slim_hidden_def(cairo_fill_preserve
);
2239 * @cr: a cairo context
2241 * Emits the current page for backends that support multiple pages, but
2242 * doesn't clear it, so, the contents of the current page will be retained
2243 * for the next page too. Use cairo_show_page() if you want to get an
2244 * empty page after the emission.
2246 * This is a convenience function that simply calls
2247 * cairo_surface_copy_page() on @cr's target.
2252 cairo_copy_page (cairo_t
*cr
)
2254 cairo_status_t status
;
2256 if (unlikely (cr
->status
))
2259 status
= cr
->backend
->copy_page (cr
);
2260 if (unlikely (status
))
2261 _cairo_set_error (cr
, status
);
2266 * @cr: a cairo context
2268 * Emits and clears the current page for backends that support multiple
2269 * pages. Use cairo_copy_page() if you don't want to clear the page.
2271 * This is a convenience function that simply calls
2272 * cairo_surface_show_page() on @cr's target.
2277 cairo_show_page (cairo_t
*cr
)
2279 cairo_status_t status
;
2281 if (unlikely (cr
->status
))
2284 status
= cr
->backend
->show_page (cr
);
2285 if (unlikely (status
))
2286 _cairo_set_error (cr
, status
);
2291 * @cr: a cairo context
2292 * @x: X coordinate of the point to test
2293 * @y: Y coordinate of the point to test
2295 * Tests whether the given point is inside the area that would be
2296 * affected by a cairo_stroke() operation given the current path and
2297 * stroking parameters. Surface dimensions and clipping are not taken
2300 * See cairo_stroke(), cairo_set_line_width(), cairo_set_line_join(),
2301 * cairo_set_line_cap(), cairo_set_dash(), and
2302 * cairo_stroke_preserve().
2304 * Return value: A non-zero value if the point is inside, or zero if
2310 cairo_in_stroke (cairo_t
*cr
, double x
, double y
)
2312 cairo_status_t status
;
2313 cairo_bool_t inside
= FALSE
;
2315 if (unlikely (cr
->status
))
2318 status
= cr
->backend
->in_stroke (cr
, x
, y
, &inside
);
2319 if (unlikely (status
))
2320 _cairo_set_error (cr
, status
);
2327 * @cr: a cairo context
2328 * @x: X coordinate of the point to test
2329 * @y: Y coordinate of the point to test
2331 * Tests whether the given point is inside the area that would be
2332 * affected by a cairo_fill() operation given the current path and
2333 * filling parameters. Surface dimensions and clipping are not taken
2336 * See cairo_fill(), cairo_set_fill_rule() and cairo_fill_preserve().
2338 * Return value: A non-zero value if the point is inside, or zero if
2344 cairo_in_fill (cairo_t
*cr
, double x
, double y
)
2346 cairo_status_t status
;
2347 cairo_bool_t inside
= FALSE
;
2349 if (unlikely (cr
->status
))
2352 status
= cr
->backend
->in_fill (cr
, x
, y
, &inside
);
2353 if (unlikely (status
))
2354 _cairo_set_error (cr
, status
);
2360 * cairo_stroke_extents:
2361 * @cr: a cairo context
2362 * @x1: left of the resulting extents
2363 * @y1: top of the resulting extents
2364 * @x2: right of the resulting extents
2365 * @y2: bottom of the resulting extents
2367 * Computes a bounding box in user coordinates covering the area that
2368 * would be affected, (the "inked" area), by a cairo_stroke()
2369 * operation given the current path and stroke parameters.
2370 * If the current path is empty, returns an empty rectangle ((0,0), (0,0)).
2371 * Surface dimensions and clipping are not taken into account.
2373 * Note that if the line width is set to exactly zero, then
2374 * cairo_stroke_extents() will return an empty rectangle. Contrast with
2375 * cairo_path_extents() which can be used to compute the non-empty
2376 * bounds as the line width approaches zero.
2378 * Note that cairo_stroke_extents() must necessarily do more work to
2379 * compute the precise inked areas in light of the stroke parameters,
2380 * so cairo_path_extents() may be more desirable for sake of
2381 * performance if non-inked path extents are desired.
2383 * See cairo_stroke(), cairo_set_line_width(), cairo_set_line_join(),
2384 * cairo_set_line_cap(), cairo_set_dash(), and
2385 * cairo_stroke_preserve().
2390 cairo_stroke_extents (cairo_t
*cr
,
2391 double *x1
, double *y1
, double *x2
, double *y2
)
2393 cairo_status_t status
;
2395 if (unlikely (cr
->status
)) {
2408 status
= cr
->backend
->stroke_extents (cr
, x1
, y1
, x2
, y2
);
2409 if (unlikely (status
))
2410 _cairo_set_error (cr
, status
);
2414 * cairo_fill_extents:
2415 * @cr: a cairo context
2416 * @x1: left of the resulting extents
2417 * @y1: top of the resulting extents
2418 * @x2: right of the resulting extents
2419 * @y2: bottom of the resulting extents
2421 * Computes a bounding box in user coordinates covering the area that
2422 * would be affected, (the "inked" area), by a cairo_fill() operation
2423 * given the current path and fill parameters. If the current path is
2424 * empty, returns an empty rectangle ((0,0), (0,0)). Surface
2425 * dimensions and clipping are not taken into account.
2427 * Contrast with cairo_path_extents(), which is similar, but returns
2428 * non-zero extents for some paths with no inked area, (such as a
2429 * simple line segment).
2431 * Note that cairo_fill_extents() must necessarily do more work to
2432 * compute the precise inked areas in light of the fill rule, so
2433 * cairo_path_extents() may be more desirable for sake of performance
2434 * if the non-inked path extents are desired.
2436 * See cairo_fill(), cairo_set_fill_rule() and cairo_fill_preserve().
2441 cairo_fill_extents (cairo_t
*cr
,
2442 double *x1
, double *y1
, double *x2
, double *y2
)
2444 cairo_status_t status
;
2446 if (unlikely (cr
->status
)) {
2459 status
= cr
->backend
->fill_extents (cr
, x1
, y1
, x2
, y2
);
2460 if (unlikely (status
))
2461 _cairo_set_error (cr
, status
);
2466 * @cr: a cairo context
2468 * Establishes a new clip region by intersecting the current clip
2469 * region with the current path as it would be filled by cairo_fill()
2470 * and according to the current fill rule (see cairo_set_fill_rule()).
2472 * After cairo_clip(), the current path will be cleared from the cairo
2475 * The current clip region affects all drawing operations by
2476 * effectively masking out any changes to the surface that are outside
2477 * the current clip region.
2479 * Calling cairo_clip() can only make the clip region smaller, never
2480 * larger. But the current clip is part of the graphics state, so a
2481 * temporary restriction of the clip region can be achieved by
2482 * calling cairo_clip() within a cairo_save()/cairo_restore()
2483 * pair. The only other means of increasing the size of the clip
2484 * region is cairo_reset_clip().
2489 cairo_clip (cairo_t
*cr
)
2491 cairo_status_t status
;
2493 if (unlikely (cr
->status
))
2496 status
= cr
->backend
->clip (cr
);
2497 if (unlikely (status
))
2498 _cairo_set_error (cr
, status
);
2502 * cairo_clip_preserve:
2503 * @cr: a cairo context
2505 * Establishes a new clip region by intersecting the current clip
2506 * region with the current path as it would be filled by cairo_fill()
2507 * and according to the current fill rule (see cairo_set_fill_rule()).
2509 * Unlike cairo_clip(), cairo_clip_preserve() preserves the path within
2510 * the cairo context.
2512 * The current clip region affects all drawing operations by
2513 * effectively masking out any changes to the surface that are outside
2514 * the current clip region.
2516 * Calling cairo_clip_preserve() can only make the clip region smaller, never
2517 * larger. But the current clip is part of the graphics state, so a
2518 * temporary restriction of the clip region can be achieved by
2519 * calling cairo_clip_preserve() within a cairo_save()/cairo_restore()
2520 * pair. The only other means of increasing the size of the clip
2521 * region is cairo_reset_clip().
2526 cairo_clip_preserve (cairo_t
*cr
)
2528 cairo_status_t status
;
2530 if (unlikely (cr
->status
))
2533 status
= cr
->backend
->clip_preserve (cr
);
2534 if (unlikely (status
))
2535 _cairo_set_error (cr
, status
);
2537 slim_hidden_def(cairo_clip_preserve
);
2541 * @cr: a cairo context
2543 * Reset the current clip region to its original, unrestricted
2544 * state. That is, set the clip region to an infinitely large shape
2545 * containing the target surface. Equivalently, if infinity is too
2546 * hard to grasp, one can imagine the clip region being reset to the
2547 * exact bounds of the target surface.
2549 * Note that code meant to be reusable should not call
2550 * cairo_reset_clip() as it will cause results unexpected by
2551 * higher-level code which calls cairo_clip(). Consider using
2552 * cairo_save() and cairo_restore() around cairo_clip() as a more
2553 * robust means of temporarily restricting the clip region.
2558 cairo_reset_clip (cairo_t
*cr
)
2560 cairo_status_t status
;
2562 if (unlikely (cr
->status
))
2565 status
= cr
->backend
->reset_clip (cr
);
2566 if (unlikely (status
))
2567 _cairo_set_error (cr
, status
);
2571 * cairo_clip_extents:
2572 * @cr: a cairo context
2573 * @x1: left of the resulting extents
2574 * @y1: top of the resulting extents
2575 * @x2: right of the resulting extents
2576 * @y2: bottom of the resulting extents
2578 * Computes a bounding box in user coordinates covering the area inside the
2584 cairo_clip_extents (cairo_t
*cr
,
2585 double *x1
, double *y1
,
2586 double *x2
, double *y2
)
2588 cairo_status_t status
;
2599 if (unlikely (cr
->status
))
2602 status
= cr
->backend
->clip_extents (cr
, x1
, y1
, x2
, y2
);
2603 if (unlikely (status
))
2604 _cairo_set_error (cr
, status
);
2609 * @cr: a cairo context
2610 * @x: X coordinate of the point to test
2611 * @y: Y coordinate of the point to test
2613 * Tests whether the given point is inside the area that would be
2614 * visible through the current clip, i.e. the area that would be filled by
2615 * a cairo_paint() operation.
2617 * See cairo_clip(), and cairo_clip_preserve().
2619 * Return value: A non-zero value if the point is inside, or zero if
2625 cairo_in_clip (cairo_t
*cr
, double x
, double y
)
2627 cairo_status_t status
;
2628 cairo_bool_t inside
= FALSE
;
2630 if (unlikely (cr
->status
))
2633 status
= cr
->backend
->in_clip (cr
, x
, y
, &inside
);
2634 if (unlikely (status
))
2635 _cairo_set_error (cr
, status
);
2641 * cairo_copy_clip_rectangle_list:
2642 * @cr: a cairo context
2644 * Gets the current clip region as a list of rectangles in user coordinates.
2645 * Never returns %NULL.
2647 * The status in the list may be %CAIRO_STATUS_CLIP_NOT_REPRESENTABLE to
2648 * indicate that the clip region cannot be represented as a list of
2649 * user-space rectangles. The status may have other values to indicate
2652 * Returns: the current clip region as a list of rectangles in user coordinates,
2653 * which should be destroyed using cairo_rectangle_list_destroy().
2657 cairo_rectangle_list_t
*
2658 cairo_copy_clip_rectangle_list (cairo_t
*cr
)
2660 if (unlikely (cr
->status
))
2661 return _cairo_rectangle_list_create_in_error (cr
->status
);
2663 return cr
->backend
->clip_copy_rectangle_list (cr
);
2667 * cairo_select_font_face:
2669 * @family: a font family name, encoded in UTF-8
2670 * @slant: the slant for the font
2671 * @weight: the weight for the font
2673 * Note: The cairo_select_font_face() function call is part of what
2674 * the cairo designers call the "toy" text API. It is convenient for
2675 * short demos and simple programs, but it is not expected to be
2676 * adequate for serious text-using applications.
2678 * Selects a family and style of font from a simplified description as
2679 * a family name, slant and weight. Cairo provides no operation to
2680 * list available family names on the system (this is a "toy",
2681 * remember), but the standard CSS2 generic family names, ("serif",
2682 * "sans-serif", "cursive", "fantasy", "monospace"), are likely to
2685 * If @family starts with the string "@cairo:", or if no native font
2686 * backends are compiled in, cairo will use an internal font family.
2687 * The internal font family recognizes many modifiers in the @family
2688 * string, most notably, it recognizes the string "monospace". That is,
2689 * the family name "@cairo:monospace" will use the monospace version of
2690 * the internal font family.
2692 * For "real" font selection, see the font-backend-specific
2693 * font_face_create functions for the font backend you are using. (For
2694 * example, if you are using the freetype-based cairo-ft font backend,
2695 * see cairo_ft_font_face_create_for_ft_face() or
2696 * cairo_ft_font_face_create_for_pattern().) The resulting font face
2697 * could then be used with cairo_scaled_font_create() and
2698 * cairo_set_scaled_font().
2700 * Similarly, when using the "real" font support, you can call
2701 * directly into the underlying font system, (such as fontconfig or
2702 * freetype), for operations such as listing available fonts, etc.
2704 * It is expected that most applications will need to use a more
2705 * comprehensive font handling and text layout library, (for example,
2706 * pango), in conjunction with cairo.
2708 * If text is drawn without a call to cairo_select_font_face(), (nor
2709 * cairo_set_font_face() nor cairo_set_scaled_font()), the default
2710 * family is platform-specific, but is essentially "sans-serif".
2711 * Default slant is %CAIRO_FONT_SLANT_NORMAL, and default weight is
2712 * %CAIRO_FONT_WEIGHT_NORMAL.
2714 * This function is equivalent to a call to cairo_toy_font_face_create()
2715 * followed by cairo_set_font_face().
2720 cairo_select_font_face (cairo_t
*cr
,
2722 cairo_font_slant_t slant
,
2723 cairo_font_weight_t weight
)
2725 cairo_font_face_t
*font_face
;
2726 cairo_status_t status
;
2728 if (unlikely (cr
->status
))
2731 font_face
= cairo_toy_font_face_create (family
, slant
, weight
);
2732 if (unlikely (font_face
->status
)) {
2733 _cairo_set_error (cr
, font_face
->status
);
2737 status
= cr
->backend
->set_font_face (cr
, font_face
);
2738 cairo_font_face_destroy (font_face
);
2740 if (unlikely (status
))
2741 _cairo_set_error (cr
, status
);
2745 * cairo_font_extents:
2747 * @extents: a #cairo_font_extents_t object into which the results
2750 * Gets the font extents for the currently selected font.
2755 cairo_font_extents (cairo_t
*cr
,
2756 cairo_font_extents_t
*extents
)
2758 cairo_status_t status
;
2760 extents
->ascent
= 0.0;
2761 extents
->descent
= 0.0;
2762 extents
->height
= 0.0;
2763 extents
->max_x_advance
= 0.0;
2764 extents
->max_y_advance
= 0.0;
2766 if (unlikely (cr
->status
))
2769 status
= cr
->backend
->font_extents (cr
, extents
);
2770 if (unlikely (status
))
2771 _cairo_set_error (cr
, status
);
2775 * cairo_set_font_face:
2777 * @font_face: a #cairo_font_face_t, or %NULL to restore to the default font
2779 * Replaces the current #cairo_font_face_t object in the #cairo_t with
2780 * @font_face. The replaced font face in the #cairo_t will be
2781 * destroyed if there are no other references to it.
2786 cairo_set_font_face (cairo_t
*cr
,
2787 cairo_font_face_t
*font_face
)
2789 cairo_status_t status
;
2791 if (unlikely (cr
->status
))
2794 status
= cr
->backend
->set_font_face (cr
, font_face
);
2795 if (unlikely (status
))
2796 _cairo_set_error (cr
, status
);
2800 * cairo_get_font_face:
2803 * Gets the current font face for a #cairo_t.
2805 * Return value: the current font face. This object is owned by
2806 * cairo. To keep a reference to it, you must call
2807 * cairo_font_face_reference().
2809 * This function never returns %NULL. If memory cannot be allocated, a
2810 * special "nil" #cairo_font_face_t object will be returned on which
2811 * cairo_font_face_status() returns %CAIRO_STATUS_NO_MEMORY. Using
2812 * this nil object will cause its error state to propagate to other
2813 * objects it is passed to, (for example, calling
2814 * cairo_set_font_face() with a nil font will trigger an error that
2815 * will shutdown the #cairo_t object).
2820 cairo_get_font_face (cairo_t
*cr
)
2822 if (unlikely (cr
->status
))
2823 return (cairo_font_face_t
*) &_cairo_font_face_nil
;
2825 return cr
->backend
->get_font_face (cr
);
2829 * cairo_set_font_size:
2831 * @size: the new font size, in user space units
2833 * Sets the current font matrix to a scale by a factor of @size, replacing
2834 * any font matrix previously set with cairo_set_font_size() or
2835 * cairo_set_font_matrix(). This results in a font size of @size user space
2836 * units. (More precisely, this matrix will result in the font's
2837 * em-square being a @size by @size square in user space.)
2839 * If text is drawn without a call to cairo_set_font_size(), (nor
2840 * cairo_set_font_matrix() nor cairo_set_scaled_font()), the default
2841 * font size is 10.0.
2846 cairo_set_font_size (cairo_t
*cr
, double size
)
2848 cairo_status_t status
;
2850 if (unlikely (cr
->status
))
2853 status
= cr
->backend
->set_font_size (cr
, size
);
2854 if (unlikely (status
))
2855 _cairo_set_error (cr
, status
);
2857 slim_hidden_def (cairo_set_font_size
);
2860 * cairo_set_font_matrix:
2862 * @matrix: a #cairo_matrix_t describing a transform to be applied to
2865 * Sets the current font matrix to @matrix. The font matrix gives a
2866 * transformation from the design space of the font (in this space,
2867 * the em-square is 1 unit by 1 unit) to user space. Normally, a
2868 * simple scale is used (see cairo_set_font_size()), but a more
2869 * complex font matrix can be used to shear the font
2870 * or stretch it unequally along the two axes
2875 cairo_set_font_matrix (cairo_t
*cr
,
2876 const cairo_matrix_t
*matrix
)
2878 cairo_status_t status
;
2880 if (unlikely (cr
->status
))
2883 status
= cr
->backend
->set_font_matrix (cr
, matrix
);
2884 if (unlikely (status
))
2885 _cairo_set_error (cr
, status
);
2887 slim_hidden_def (cairo_set_font_matrix
);
2890 * cairo_get_font_matrix:
2892 * @matrix: return value for the matrix
2894 * Stores the current font matrix into @matrix. See
2895 * cairo_set_font_matrix().
2900 cairo_get_font_matrix (cairo_t
*cr
, cairo_matrix_t
*matrix
)
2902 if (unlikely (cr
->status
)) {
2903 cairo_matrix_init_identity (matrix
);
2907 cr
->backend
->get_font_matrix (cr
, matrix
);
2911 * cairo_set_font_options:
2913 * @options: font options to use
2915 * Sets a set of custom font rendering options for the #cairo_t.
2916 * Rendering options are derived by merging these options with the
2917 * options derived from underlying surface; if the value in @options
2918 * has a default value (like %CAIRO_ANTIALIAS_DEFAULT), then the value
2919 * from the surface is used.
2924 cairo_set_font_options (cairo_t
*cr
,
2925 const cairo_font_options_t
*options
)
2927 cairo_status_t status
;
2929 if (unlikely (cr
->status
))
2932 status
= cairo_font_options_status ((cairo_font_options_t
*) options
);
2933 if (unlikely (status
)) {
2934 _cairo_set_error (cr
, status
);
2938 status
= cr
->backend
->set_font_options (cr
, options
);
2939 if (unlikely (status
))
2940 _cairo_set_error (cr
, status
);
2942 slim_hidden_def (cairo_set_font_options
);
2945 * cairo_get_font_options:
2947 * @options: a #cairo_font_options_t object into which to store
2948 * the retrieved options. All existing values are overwritten
2950 * Retrieves font rendering options set via #cairo_set_font_options.
2951 * Note that the returned options do not include any options derived
2952 * from the underlying surface; they are literally the options
2953 * passed to cairo_set_font_options().
2958 cairo_get_font_options (cairo_t
*cr
,
2959 cairo_font_options_t
*options
)
2961 /* check that we aren't trying to overwrite the nil object */
2962 if (cairo_font_options_status (options
))
2965 if (unlikely (cr
->status
)) {
2966 _cairo_font_options_init_default (options
);
2970 cr
->backend
->get_font_options (cr
, options
);
2974 * cairo_set_scaled_font:
2976 * @scaled_font: a #cairo_scaled_font_t
2978 * Replaces the current font face, font matrix, and font options in
2979 * the #cairo_t with those of the #cairo_scaled_font_t. Except for
2980 * some translation, the current CTM of the #cairo_t should be the
2981 * same as that of the #cairo_scaled_font_t, which can be accessed
2982 * using cairo_scaled_font_get_ctm().
2987 cairo_set_scaled_font (cairo_t
*cr
,
2988 const cairo_scaled_font_t
*scaled_font
)
2990 cairo_status_t status
;
2992 if (unlikely (cr
->status
))
2995 if ((scaled_font
== NULL
)) {
2996 _cairo_set_error (cr
, _cairo_error (CAIRO_STATUS_NULL_POINTER
));
3000 status
= scaled_font
->status
;
3001 if (unlikely (status
)) {
3002 _cairo_set_error (cr
, status
);
3006 status
= cr
->backend
->set_scaled_font (cr
, (cairo_scaled_font_t
*) scaled_font
);
3007 if (unlikely (status
))
3008 _cairo_set_error (cr
, status
);
3012 * cairo_get_scaled_font:
3015 * Gets the current scaled font for a #cairo_t.
3017 * Return value: the current scaled font. This object is owned by
3018 * cairo. To keep a reference to it, you must call
3019 * cairo_scaled_font_reference().
3021 * This function never returns %NULL. If memory cannot be allocated, a
3022 * special "nil" #cairo_scaled_font_t object will be returned on which
3023 * cairo_scaled_font_status() returns %CAIRO_STATUS_NO_MEMORY. Using
3024 * this nil object will cause its error state to propagate to other
3025 * objects it is passed to, (for example, calling
3026 * cairo_set_scaled_font() with a nil font will trigger an error that
3027 * will shutdown the #cairo_t object).
3031 cairo_scaled_font_t
*
3032 cairo_get_scaled_font (cairo_t
*cr
)
3034 if (unlikely (cr
->status
))
3035 return _cairo_scaled_font_create_in_error (cr
->status
);
3037 return cr
->backend
->get_scaled_font (cr
);
3039 slim_hidden_def (cairo_get_scaled_font
);
3042 * cairo_text_extents:
3044 * @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
3045 * @extents: a #cairo_text_extents_t object into which the results
3048 * Gets the extents for a string of text. The extents describe a
3049 * user-space rectangle that encloses the "inked" portion of the text,
3050 * (as it would be drawn by cairo_show_text()). Additionally, the
3051 * x_advance and y_advance values indicate the amount by which the
3052 * current point would be advanced by cairo_show_text().
3054 * Note that whitespace characters do not directly contribute to the
3055 * size of the rectangle (extents.width and extents.height). They do
3056 * contribute indirectly by changing the position of non-whitespace
3057 * characters. In particular, trailing whitespace characters are
3058 * likely to not affect the size of the rectangle, though they will
3059 * affect the x_advance and y_advance values.
3064 cairo_text_extents (cairo_t
*cr
,
3066 cairo_text_extents_t
*extents
)
3068 cairo_status_t status
;
3069 cairo_scaled_font_t
*scaled_font
;
3070 cairo_glyph_t
*glyphs
= NULL
;
3074 extents
->x_bearing
= 0.0;
3075 extents
->y_bearing
= 0.0;
3076 extents
->width
= 0.0;
3077 extents
->height
= 0.0;
3078 extents
->x_advance
= 0.0;
3079 extents
->y_advance
= 0.0;
3081 if (unlikely (cr
->status
))
3087 scaled_font
= cairo_get_scaled_font (cr
);
3088 if (unlikely (scaled_font
->status
)) {
3089 _cairo_set_error (cr
, scaled_font
->status
);
3093 cairo_get_current_point (cr
, &x
, &y
);
3094 status
= cairo_scaled_font_text_to_glyphs (scaled_font
,
3097 &glyphs
, &num_glyphs
,
3100 if (likely (status
== CAIRO_STATUS_SUCCESS
)) {
3101 status
= cr
->backend
->glyph_extents (cr
,
3105 cairo_glyph_free (glyphs
);
3107 if (unlikely (status
))
3108 _cairo_set_error (cr
, status
);
3112 * cairo_glyph_extents:
3114 * @glyphs: an array of #cairo_glyph_t objects
3115 * @num_glyphs: the number of elements in @glyphs
3116 * @extents: a #cairo_text_extents_t object into which the results
3119 * Gets the extents for an array of glyphs. The extents describe a
3120 * user-space rectangle that encloses the "inked" portion of the
3121 * glyphs, (as they would be drawn by cairo_show_glyphs()).
3122 * Additionally, the x_advance and y_advance values indicate the
3123 * amount by which the current point would be advanced by
3124 * cairo_show_glyphs().
3126 * Note that whitespace glyphs do not contribute to the size of the
3127 * rectangle (extents.width and extents.height).
3132 cairo_glyph_extents (cairo_t
*cr
,
3133 const cairo_glyph_t
*glyphs
,
3135 cairo_text_extents_t
*extents
)
3137 cairo_status_t status
;
3139 extents
->x_bearing
= 0.0;
3140 extents
->y_bearing
= 0.0;
3141 extents
->width
= 0.0;
3142 extents
->height
= 0.0;
3143 extents
->x_advance
= 0.0;
3144 extents
->y_advance
= 0.0;
3146 if (unlikely (cr
->status
))
3149 if (num_glyphs
== 0)
3152 if (unlikely (num_glyphs
< 0)) {
3153 _cairo_set_error (cr
, CAIRO_STATUS_NEGATIVE_COUNT
);
3157 if (unlikely (glyphs
== NULL
)) {
3158 _cairo_set_error (cr
, CAIRO_STATUS_NULL_POINTER
);
3162 status
= cr
->backend
->glyph_extents (cr
, glyphs
, num_glyphs
, extents
);
3163 if (unlikely (status
))
3164 _cairo_set_error (cr
, status
);
3169 * @cr: a cairo context
3170 * @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
3172 * A drawing operator that generates the shape from a string of UTF-8
3173 * characters, rendered according to the current font_face, font_size
3174 * (font_matrix), and font_options.
3176 * This function first computes a set of glyphs for the string of
3177 * text. The first glyph is placed so that its origin is at the
3178 * current point. The origin of each subsequent glyph is offset from
3179 * that of the previous glyph by the advance values of the previous
3182 * After this call the current point is moved to the origin of where
3183 * the next glyph would be placed in this same progression. That is,
3184 * the current point will be at the origin of the final glyph offset
3185 * by its advance values. This allows for easy display of a single
3186 * logical string with multiple calls to cairo_show_text().
3188 * Note: The cairo_show_text() function call is part of what the cairo
3189 * designers call the "toy" text API. It is convenient for short demos
3190 * and simple programs, but it is not expected to be adequate for
3191 * serious text-using applications. See cairo_show_glyphs() for the
3192 * "real" text display API in cairo.
3197 cairo_show_text (cairo_t
*cr
, const char *utf8
)
3199 cairo_text_extents_t extents
;
3200 cairo_status_t status
;
3201 cairo_glyph_t
*glyphs
, *last_glyph
;
3202 cairo_text_cluster_t
*clusters
;
3203 int utf8_len
, num_glyphs
, num_clusters
;
3204 cairo_text_cluster_flags_t cluster_flags
;
3206 cairo_bool_t has_show_text_glyphs
;
3207 cairo_glyph_t stack_glyphs
[CAIRO_STACK_ARRAY_LENGTH (cairo_glyph_t
)];
3208 cairo_text_cluster_t stack_clusters
[CAIRO_STACK_ARRAY_LENGTH (cairo_text_cluster_t
)];
3209 cairo_scaled_font_t
*scaled_font
;
3210 cairo_glyph_text_info_t info
, *i
;
3212 if (unlikely (cr
->status
))
3218 scaled_font
= cairo_get_scaled_font (cr
);
3219 if (unlikely (scaled_font
->status
)) {
3220 _cairo_set_error (cr
, scaled_font
->status
);
3224 utf8_len
= strlen (utf8
);
3226 has_show_text_glyphs
=
3227 cairo_surface_has_show_text_glyphs (cairo_get_target (cr
));
3229 glyphs
= stack_glyphs
;
3230 num_glyphs
= ARRAY_LENGTH (stack_glyphs
);
3232 if (has_show_text_glyphs
) {
3233 clusters
= stack_clusters
;
3234 num_clusters
= ARRAY_LENGTH (stack_clusters
);
3240 cairo_get_current_point (cr
, &x
, &y
);
3241 status
= cairo_scaled_font_text_to_glyphs (scaled_font
,
3244 &glyphs
, &num_glyphs
,
3245 has_show_text_glyphs
? &clusters
: NULL
, &num_clusters
,
3247 if (unlikely (status
))
3250 if (num_glyphs
== 0)
3254 if (has_show_text_glyphs
) {
3256 info
.utf8_len
= utf8_len
;
3257 info
.clusters
= clusters
;
3258 info
.num_clusters
= num_clusters
;
3259 info
.cluster_flags
= cluster_flags
;
3263 status
= cr
->backend
->glyphs (cr
, glyphs
, num_glyphs
, i
);
3264 if (unlikely (status
))
3267 last_glyph
= &glyphs
[num_glyphs
- 1];
3268 status
= cr
->backend
->glyph_extents (cr
, last_glyph
, 1, &extents
);
3269 if (unlikely (status
))
3272 x
= last_glyph
->x
+ extents
.x_advance
;
3273 y
= last_glyph
->y
+ extents
.y_advance
;
3274 cr
->backend
->move_to (cr
, x
, y
);
3277 if (glyphs
!= stack_glyphs
)
3278 cairo_glyph_free (glyphs
);
3279 if (clusters
!= stack_clusters
)
3280 cairo_text_cluster_free (clusters
);
3282 if (unlikely (status
))
3283 _cairo_set_error (cr
, status
);
3287 * cairo_show_glyphs:
3288 * @cr: a cairo context
3289 * @glyphs: array of glyphs to show
3290 * @num_glyphs: number of glyphs to show
3292 * A drawing operator that generates the shape from an array of glyphs,
3293 * rendered according to the current font face, font size
3294 * (font matrix), and font options.
3299 cairo_show_glyphs (cairo_t
*cr
, const cairo_glyph_t
*glyphs
, int num_glyphs
)
3301 cairo_status_t status
;
3303 if (unlikely (cr
->status
))
3306 if (num_glyphs
== 0)
3309 if (num_glyphs
< 0) {
3310 _cairo_set_error (cr
, CAIRO_STATUS_NEGATIVE_COUNT
);
3314 if (glyphs
== NULL
) {
3315 _cairo_set_error (cr
, CAIRO_STATUS_NULL_POINTER
);
3319 status
= cr
->backend
->glyphs (cr
, glyphs
, num_glyphs
, NULL
);
3320 if (unlikely (status
))
3321 _cairo_set_error (cr
, status
);
3325 * cairo_show_text_glyphs:
3326 * @cr: a cairo context
3327 * @utf8: a string of text encoded in UTF-8
3328 * @utf8_len: length of @utf8 in bytes, or -1 if it is NUL-terminated
3329 * @glyphs: array of glyphs to show
3330 * @num_glyphs: number of glyphs to show
3331 * @clusters: array of cluster mapping information
3332 * @num_clusters: number of clusters in the mapping
3333 * @cluster_flags: cluster mapping flags
3335 * This operation has rendering effects similar to cairo_show_glyphs()
3336 * but, if the target surface supports it, uses the provided text and
3337 * cluster mapping to embed the text for the glyphs shown in the output.
3338 * If the target does not support the extended attributes, this function
3339 * acts like the basic cairo_show_glyphs() as if it had been passed
3340 * @glyphs and @num_glyphs.
3342 * The mapping between @utf8 and @glyphs is provided by an array of
3343 * <firstterm>clusters</firstterm>. Each cluster covers a number of
3344 * text bytes and glyphs, and neighboring clusters cover neighboring
3345 * areas of @utf8 and @glyphs. The clusters should collectively cover @utf8
3346 * and @glyphs in entirety.
3348 * The first cluster always covers bytes from the beginning of @utf8.
3349 * If @cluster_flags do not have the %CAIRO_TEXT_CLUSTER_FLAG_BACKWARD
3350 * set, the first cluster also covers the beginning
3351 * of @glyphs, otherwise it covers the end of the @glyphs array and
3352 * following clusters move backward.
3354 * See #cairo_text_cluster_t for constraints on valid clusters.
3359 cairo_show_text_glyphs (cairo_t
*cr
,
3362 const cairo_glyph_t
*glyphs
,
3364 const cairo_text_cluster_t
*clusters
,
3366 cairo_text_cluster_flags_t cluster_flags
)
3368 cairo_status_t status
;
3370 if (unlikely (cr
->status
))
3373 /* A slew of sanity checks */
3375 /* Special case for NULL and -1 */
3376 if (utf8
== NULL
&& utf8_len
== -1)
3379 /* No NULLs for non-zeros */
3380 if ((num_glyphs
&& glyphs
== NULL
) ||
3381 (utf8_len
&& utf8
== NULL
) ||
3382 (num_clusters
&& clusters
== NULL
)) {
3383 _cairo_set_error (cr
, CAIRO_STATUS_NULL_POINTER
);
3387 /* A -1 for utf8_len means NUL-terminated */
3389 utf8_len
= strlen (utf8
);
3391 /* Apart from that, no negatives */
3392 if (num_glyphs
< 0 || utf8_len
< 0 || num_clusters
< 0) {
3393 _cairo_set_error (cr
, CAIRO_STATUS_NEGATIVE_COUNT
);
3397 if (num_glyphs
== 0 && utf8_len
== 0)
3401 /* Make sure clusters cover the entire glyphs and utf8 arrays,
3402 * and that cluster boundaries are UTF-8 boundaries. */
3403 status
= _cairo_validate_text_clusters (utf8
, utf8_len
,
3405 clusters
, num_clusters
, cluster_flags
);
3406 if (status
== CAIRO_STATUS_INVALID_CLUSTERS
) {
3407 /* Either got invalid UTF-8 text, or cluster mapping is bad.
3408 * Differentiate those. */
3410 cairo_status_t status2
;
3412 status2
= _cairo_utf8_to_ucs4 (utf8
, utf8_len
, NULL
, NULL
);
3416 cairo_glyph_text_info_t info
;
3419 info
.utf8_len
= utf8_len
;
3420 info
.clusters
= clusters
;
3421 info
.num_clusters
= num_clusters
;
3422 info
.cluster_flags
= cluster_flags
;
3424 status
= cr
->backend
->glyphs (cr
, glyphs
, num_glyphs
, &info
);
3427 status
= cr
->backend
->glyphs (cr
, glyphs
, num_glyphs
, NULL
);
3429 if (unlikely (status
))
3430 _cairo_set_error (cr
, status
);
3435 * @cr: a cairo context
3436 * @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
3438 * Adds closed paths for text to the current path. The generated
3439 * path if filled, achieves an effect similar to that of
3440 * cairo_show_text().
3442 * Text conversion and positioning is done similar to cairo_show_text().
3444 * Like cairo_show_text(), After this call the current point is
3445 * moved to the origin of where the next glyph would be placed in
3446 * this same progression. That is, the current point will be at
3447 * the origin of the final glyph offset by its advance values.
3448 * This allows for chaining multiple calls to to cairo_text_path()
3449 * without having to set current point in between.
3451 * Note: The cairo_text_path() function call is part of what the cairo
3452 * designers call the "toy" text API. It is convenient for short demos
3453 * and simple programs, but it is not expected to be adequate for
3454 * serious text-using applications. See cairo_glyph_path() for the
3455 * "real" text path API in cairo.
3460 cairo_text_path (cairo_t
*cr
, const char *utf8
)
3462 cairo_status_t status
;
3463 cairo_text_extents_t extents
;
3464 cairo_glyph_t stack_glyphs
[CAIRO_STACK_ARRAY_LENGTH (cairo_glyph_t
)];
3465 cairo_glyph_t
*glyphs
, *last_glyph
;
3466 cairo_scaled_font_t
*scaled_font
;
3470 if (unlikely (cr
->status
))
3477 glyphs
= stack_glyphs
;
3478 num_glyphs
= ARRAY_LENGTH (stack_glyphs
);
3480 scaled_font
= cairo_get_scaled_font (cr
);
3481 if (unlikely (scaled_font
->status
)) {
3482 _cairo_set_error (cr
, scaled_font
->status
);
3486 cairo_get_current_point (cr
, &x
, &y
);
3487 status
= cairo_scaled_font_text_to_glyphs (scaled_font
,
3490 &glyphs
, &num_glyphs
,
3493 if (num_glyphs
== 0)
3496 status
= cr
->backend
->glyph_path (cr
, glyphs
, num_glyphs
);
3498 if (unlikely (status
))
3501 last_glyph
= &glyphs
[num_glyphs
- 1];
3502 status
= cr
->backend
->glyph_extents (cr
, last_glyph
, 1, &extents
);
3504 if (unlikely (status
))
3507 x
= last_glyph
->x
+ extents
.x_advance
;
3508 y
= last_glyph
->y
+ extents
.y_advance
;
3509 cr
->backend
->move_to (cr
, x
, y
);
3512 if (glyphs
!= stack_glyphs
)
3513 cairo_glyph_free (glyphs
);
3515 if (unlikely (status
))
3516 _cairo_set_error (cr
, status
);
3521 * @cr: a cairo context
3522 * @glyphs: array of glyphs to show
3523 * @num_glyphs: number of glyphs to show
3525 * Adds closed paths for the glyphs to the current path. The generated
3526 * path if filled, achieves an effect similar to that of
3527 * cairo_show_glyphs().
3532 cairo_glyph_path (cairo_t
*cr
, const cairo_glyph_t
*glyphs
, int num_glyphs
)
3534 cairo_status_t status
;
3536 if (unlikely (cr
->status
))
3539 if (num_glyphs
== 0)
3542 if (unlikely (num_glyphs
< 0)) {
3543 _cairo_set_error (cr
, CAIRO_STATUS_NEGATIVE_COUNT
);
3547 if (unlikely (glyphs
== NULL
)) {
3548 _cairo_set_error (cr
, CAIRO_STATUS_NULL_POINTER
);
3552 status
= cr
->backend
->glyph_path (cr
, glyphs
, num_glyphs
);
3553 if (unlikely (status
))
3554 _cairo_set_error (cr
, status
);
3558 * cairo_get_operator:
3559 * @cr: a cairo context
3561 * Gets the current compositing operator for a cairo context.
3563 * Return value: the current compositing operator.
3568 cairo_get_operator (cairo_t
*cr
)
3570 if (unlikely (cr
->status
))
3571 return CAIRO_GSTATE_OPERATOR_DEFAULT
;
3573 return cr
->backend
->get_operator (cr
);
3578 * cairo_get_opacity:
3579 * @cr: a cairo context
3581 * Gets the current compositing opacity for a cairo context.
3583 * Return value: the current compositing opacity.
3588 cairo_get_opacity (cairo_t
*cr
)
3590 if (unlikely (cr
->status
))
3593 return cr
->backend
->get_opacity (cr
);
3598 * cairo_get_tolerance:
3599 * @cr: a cairo context
3601 * Gets the current tolerance value, as set by cairo_set_tolerance().
3603 * Return value: the current tolerance value.
3608 cairo_get_tolerance (cairo_t
*cr
)
3610 if (unlikely (cr
->status
))
3611 return CAIRO_GSTATE_TOLERANCE_DEFAULT
;
3613 return cr
->backend
->get_tolerance (cr
);
3615 slim_hidden_def (cairo_get_tolerance
);
3618 * cairo_get_antialias:
3619 * @cr: a cairo context
3621 * Gets the current shape antialiasing mode, as set by
3622 * cairo_set_antialias().
3624 * Return value: the current shape antialiasing mode.
3629 cairo_get_antialias (cairo_t
*cr
)
3631 if (unlikely (cr
->status
))
3632 return CAIRO_ANTIALIAS_DEFAULT
;
3634 return cr
->backend
->get_antialias (cr
);
3638 * cairo_has_current_point:
3639 * @cr: a cairo context
3641 * Returns whether a current point is defined on the current path.
3642 * See cairo_get_current_point() for details on the current point.
3644 * Return value: whether a current point is defined.
3649 cairo_has_current_point (cairo_t
*cr
)
3651 if (unlikely (cr
->status
))
3654 return cr
->backend
->has_current_point (cr
);
3658 * cairo_get_current_point:
3659 * @cr: a cairo context
3660 * @x: return value for X coordinate of the current point
3661 * @y: return value for Y coordinate of the current point
3663 * Gets the current point of the current path, which is
3664 * conceptually the final point reached by the path so far.
3666 * The current point is returned in the user-space coordinate
3667 * system. If there is no defined current point or if @cr is in an
3668 * error status, @x and @y will both be set to 0.0. It is possible to
3669 * check this in advance with cairo_has_current_point().
3671 * Most path construction functions alter the current point. See the
3672 * following for details on how they affect the current point:
3673 * cairo_new_path(), cairo_new_sub_path(),
3674 * cairo_append_path(), cairo_close_path(),
3675 * cairo_move_to(), cairo_line_to(), cairo_curve_to(),
3676 * cairo_rel_move_to(), cairo_rel_line_to(), cairo_rel_curve_to(),
3677 * cairo_arc(), cairo_arc_negative(), cairo_rectangle(),
3678 * cairo_text_path(), cairo_glyph_path(), cairo_stroke_to_path().
3680 * Some functions use and alter the current point but do not
3681 * otherwise change current path:
3682 * cairo_show_text().
3684 * Some functions unset the current path and as a result, current point:
3685 * cairo_fill(), cairo_stroke().
3690 cairo_get_current_point (cairo_t
*cr
, double *x_ret
, double *y_ret
)
3695 if (cr
->status
== CAIRO_STATUS_SUCCESS
&&
3696 cr
->backend
->has_current_point (cr
))
3698 cr
->backend
->get_current_point (cr
, &x
, &y
);
3706 slim_hidden_def(cairo_get_current_point
);
3709 * cairo_get_fill_rule:
3710 * @cr: a cairo context
3712 * Gets the current fill rule, as set by cairo_set_fill_rule().
3714 * Return value: the current fill rule.
3719 cairo_get_fill_rule (cairo_t
*cr
)
3721 if (unlikely (cr
->status
))
3722 return CAIRO_GSTATE_FILL_RULE_DEFAULT
;
3724 return cr
->backend
->get_fill_rule (cr
);
3728 * cairo_get_line_width:
3729 * @cr: a cairo context
3731 * This function returns the current line width value exactly as set by
3732 * cairo_set_line_width(). Note that the value is unchanged even if
3733 * the CTM has changed between the calls to cairo_set_line_width() and
3734 * cairo_get_line_width().
3736 * Return value: the current line width.
3741 cairo_get_line_width (cairo_t
*cr
)
3743 if (unlikely (cr
->status
))
3744 return CAIRO_GSTATE_LINE_WIDTH_DEFAULT
;
3746 return cr
->backend
->get_line_width (cr
);
3748 slim_hidden_def (cairo_get_line_width
);
3751 * cairo_get_line_cap:
3752 * @cr: a cairo context
3754 * Gets the current line cap style, as set by cairo_set_line_cap().
3756 * Return value: the current line cap style.
3761 cairo_get_line_cap (cairo_t
*cr
)
3763 if (unlikely (cr
->status
))
3764 return CAIRO_GSTATE_LINE_CAP_DEFAULT
;
3766 return cr
->backend
->get_line_cap (cr
);
3770 * cairo_get_line_join:
3771 * @cr: a cairo context
3773 * Gets the current line join style, as set by cairo_set_line_join().
3775 * Return value: the current line join style.
3780 cairo_get_line_join (cairo_t
*cr
)
3782 if (unlikely (cr
->status
))
3783 return CAIRO_GSTATE_LINE_JOIN_DEFAULT
;
3785 return cr
->backend
->get_line_join (cr
);
3789 * cairo_get_miter_limit:
3790 * @cr: a cairo context
3792 * Gets the current miter limit, as set by cairo_set_miter_limit().
3794 * Return value: the current miter limit.
3799 cairo_get_miter_limit (cairo_t
*cr
)
3801 if (unlikely (cr
->status
))
3802 return CAIRO_GSTATE_MITER_LIMIT_DEFAULT
;
3804 return cr
->backend
->get_miter_limit (cr
);
3809 * @cr: a cairo context
3810 * @matrix: return value for the matrix
3812 * Stores the current transformation matrix (CTM) into @matrix.
3817 cairo_get_matrix (cairo_t
*cr
, cairo_matrix_t
*matrix
)
3819 if (unlikely (cr
->status
)) {
3820 cairo_matrix_init_identity (matrix
);
3824 cr
->backend
->get_matrix (cr
, matrix
);
3826 slim_hidden_def (cairo_get_matrix
);
3830 * @cr: a cairo context
3832 * Gets the target surface for the cairo context as passed to
3835 * This function will always return a valid pointer, but the result
3836 * can be a "nil" surface if @cr is already in an error state,
3837 * (ie. cairo_status() <literal>!=</literal> %CAIRO_STATUS_SUCCESS).
3838 * A nil surface is indicated by cairo_surface_status()
3839 * <literal>!=</literal> %CAIRO_STATUS_SUCCESS.
3841 * Return value: the target surface. This object is owned by cairo. To
3842 * keep a reference to it, you must call cairo_surface_reference().
3847 cairo_get_target (cairo_t
*cr
)
3849 if (unlikely (cr
->status
))
3850 return _cairo_surface_create_in_error (cr
->status
);
3852 return cr
->backend
->get_original_target (cr
);
3854 slim_hidden_def (cairo_get_target
);
3857 * cairo_get_group_target:
3858 * @cr: a cairo context
3860 * Gets the current destination surface for the context. This is either
3861 * the original target surface as passed to cairo_create() or the target
3862 * surface for the current group as started by the most recent call to
3863 * cairo_push_group() or cairo_push_group_with_content().
3865 * This function will always return a valid pointer, but the result
3866 * can be a "nil" surface if @cr is already in an error state,
3867 * (ie. cairo_status() <literal>!=</literal> %CAIRO_STATUS_SUCCESS).
3868 * A nil surface is indicated by cairo_surface_status()
3869 * <literal>!=</literal> %CAIRO_STATUS_SUCCESS.
3871 * Return value: the target surface. This object is owned by cairo. To
3872 * keep a reference to it, you must call cairo_surface_reference().
3877 cairo_get_group_target (cairo_t
*cr
)
3879 if (unlikely (cr
->status
))
3880 return _cairo_surface_create_in_error (cr
->status
);
3882 return cr
->backend
->get_current_target (cr
);
3887 * @cr: a cairo context
3889 * Creates a copy of the current path and returns it to the user as a
3890 * #cairo_path_t. See #cairo_path_data_t for hints on how to iterate
3891 * over the returned data structure.
3893 * This function will always return a valid pointer, but the result
3894 * will have no data (<literal>data==%NULL</literal> and
3895 * <literal>num_data==0</literal>), if either of the following
3899 * <listitem>If there is insufficient memory to copy the path. In this
3900 * case <literal>path->status</literal> will be set to
3901 * %CAIRO_STATUS_NO_MEMORY.</listitem>
3902 * <listitem>If @cr is already in an error state. In this case
3903 * <literal>path->status</literal> will contain the same status that
3904 * would be returned by cairo_status().</listitem>
3907 * Return value: the copy of the current path. The caller owns the
3908 * returned object and should call cairo_path_destroy() when finished
3914 cairo_copy_path (cairo_t
*cr
)
3916 if (unlikely (cr
->status
))
3917 return _cairo_path_create_in_error (cr
->status
);
3919 return cr
->backend
->copy_path (cr
);
3923 * cairo_copy_path_flat:
3924 * @cr: a cairo context
3926 * Gets a flattened copy of the current path and returns it to the
3927 * user as a #cairo_path_t. See #cairo_path_data_t for hints on
3928 * how to iterate over the returned data structure.
3930 * This function is like cairo_copy_path() except that any curves
3931 * in the path will be approximated with piecewise-linear
3932 * approximations, (accurate to within the current tolerance
3933 * value). That is, the result is guaranteed to not have any elements
3934 * of type %CAIRO_PATH_CURVE_TO which will instead be replaced by a
3935 * series of %CAIRO_PATH_LINE_TO elements.
3937 * This function will always return a valid pointer, but the result
3938 * will have no data (<literal>data==%NULL</literal> and
3939 * <literal>num_data==0</literal>), if either of the following
3943 * <listitem>If there is insufficient memory to copy the path. In this
3944 * case <literal>path->status</literal> will be set to
3945 * %CAIRO_STATUS_NO_MEMORY.</listitem>
3946 * <listitem>If @cr is already in an error state. In this case
3947 * <literal>path->status</literal> will contain the same status that
3948 * would be returned by cairo_status().</listitem>
3951 * Return value: the copy of the current path. The caller owns the
3952 * returned object and should call cairo_path_destroy() when finished
3958 cairo_copy_path_flat (cairo_t
*cr
)
3960 if (unlikely (cr
->status
))
3961 return _cairo_path_create_in_error (cr
->status
);
3963 return cr
->backend
->copy_path_flat (cr
);
3967 * cairo_append_path:
3968 * @cr: a cairo context
3969 * @path: path to be appended
3971 * Append the @path onto the current path. The @path may be either the
3972 * return value from one of cairo_copy_path() or
3973 * cairo_copy_path_flat() or it may be constructed manually. See
3974 * #cairo_path_t for details on how the path data structure should be
3975 * initialized, and note that <literal>path->status</literal> must be
3976 * initialized to %CAIRO_STATUS_SUCCESS.
3981 cairo_append_path (cairo_t
*cr
,
3982 const cairo_path_t
*path
)
3984 cairo_status_t status
;
3986 if (unlikely (cr
->status
))
3989 if (unlikely (path
== NULL
)) {
3990 _cairo_set_error (cr
, CAIRO_STATUS_NULL_POINTER
);
3994 if (unlikely (path
->status
)) {
3995 if (path
->status
> CAIRO_STATUS_SUCCESS
&&
3996 path
->status
<= CAIRO_STATUS_LAST_STATUS
)
3997 _cairo_set_error (cr
, path
->status
);
3999 _cairo_set_error (cr
, CAIRO_STATUS_INVALID_STATUS
);
4003 if (path
->num_data
== 0)
4006 if (unlikely (path
->data
== NULL
)) {
4007 _cairo_set_error (cr
, CAIRO_STATUS_NULL_POINTER
);
4011 status
= cr
->backend
->append_path (cr
, path
);
4012 if (unlikely (status
))
4013 _cairo_set_error (cr
, status
);
4018 * @cr: a cairo context
4020 * Checks whether an error has previously occurred for this context.
4022 * Returns: the current status of this context, see #cairo_status_t
4027 cairo_status (cairo_t
*cr
)
4031 slim_hidden_def (cairo_status
);