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
3 *
4 * Copyright © 2002 University of Southern California
5 * Copyright © 2005 Red Hat, Inc.
6 * Copyright © 2011 Intel Corporation
7 *
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.
15 *
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
21 *
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/
26 *
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.
30 *
31 * The Original Code is the cairo graphics library.
32 *
33 * The Initial Developer of the Original Code is University of Southern
34 * California.
35 *
36 * Contributor(s):
37 * Carl D. Worth <cworth@cworth.org>
38 * Chris Wilson <chris@chris-wilson.co.uk>
39 */
40
41 #include "cairoint.h"
42 #include "cairo-private.h"
43
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"
50
51 #include <assert.h>
52
53 /**
54 * SECTION:cairo
55 * @Title: cairo_t
56 * @Short_Description: The cairo drawing context
57 * @See_Also: #cairo_surface_t
58 *
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().
64 *
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.
68 **/
69
70 /**
71 * SECTION:cairo-text
72 * @Title: text
73 * @Short_Description: Rendering text and glyphs
74 * @See_Also: #cairo_font_face_t, #cairo_scaled_font_t, cairo_text_path(),
75 * cairo_glyph_path()
76 *
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.
87 *
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>.
95 **/
96
97 /**
98 * SECTION:cairo-transforms
99 * @Title: Transformations
100 * @Short_Description: Manipulating the current transformation matrix
101 * @See_Also: #cairo_matrix_t
102 *
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
107 * space</firstterm>.
108 **/
109
110 /**
111 * SECTION:cairo-tag
112 * @Title: Tags and Links
113 * @Short_Description: Hyperlinks and document structure
114 * @See_Also: #cairo_pdf_surface_t
115 *
116 * The tag functions provide the ability to specify hyperlinks and
117 * document logical structure on supported backends. The following tags are supported:
118 * * [Link][link] - Create a hyperlink
119 * * [Destinations][dest] - Create a hyperlink destination
120 * * [Document Structure Tags][doc-struct] - Create PDF Document Structure
121 *
122 * # Link Tags # {#link}
123 * A hyperlink is specified by enclosing the hyperlink text with the %CAIRO_TAG_LINK tag.
124 *
125 * For example:
126 * <informalexample><programlisting>
127 * cairo_tag_begin (cr, CAIRO_TAG_LINK, "uri='https://cairographics.org'");
128 * cairo_move_to (cr, 50, 50);
129 * cairo_show_text (cr, "This is a link to the cairo website.");
130 * cairo_tag_end (cr, CAIRO_TAG_LINK);
131 * </programlisting></informalexample>
132 *
133 * The PDF backend uses one or more rectangles to define the clickable
134 * area of the link. By default cairo will use the extents of the
135 * drawing operations enclosed by the begin/end link tags to define the
136 * clickable area. In some cases, such as a link split across two
137 * lines, the default rectangle is undesirable.
138 *
139 * @rect: [optional] The "rect" attribute allows the application to
140 * specify one or more rectangles that form the clickable region. The
141 * value of this attribute is an array of floats. Each rectangle is
142 * specified by four elements in the array: x, y, width, height. The
143 * array size must be a multiple of four.
144 *
145 * An example of creating a link with user specified clickable region:
146 * <informalexample><programlisting>
147 * struct text {
148 * const char *s;
149 * double x, y;
150 * };
151 * const struct text text1 = { "This link is split", 450, 70 };
152 * const struct text text2 = { "across two lines", 50, 70 };
153 * cairo_text_extents_t text1_extents;
154 * cairo_text_extents_t text2_extents;
155 * char attribs[100];
156 *
157 * cairo_text_extents (cr, text1.s, &text1_extents);
158 * cairo_text_extents (cr, text2.s, &text2_extents);
159 * sprintf (attribs,
160 * "rect=[%f %f %f %f %f %f %f %f] uri='https://cairographics.org'",
161 * text1_extents.x_bearing + text1.x,
162 * text1_extents.y_bearing + text1.y,
163 * text1_extents.width,
164 * text1_extents.height,
165 * text2_extents.x_bearing + text2.x,
166 * text2_extents.y_bearing + text2.y,
167 * text2_extents.width,
168 * text2_extents.height);
169 *
170 * cairo_tag_begin (cr, CAIRO_TAG_LINK, attribs);
171 * cairo_move_to (cr, text1.x, text1.y);
172 * cairo_show_text (cr, text1.s);
173 * cairo_move_to (cr, text2.x, text2.y);
174 * cairo_show_text (cr, text2.s);
175 * cairo_tag_end (cr, CAIRO_TAG_LINK);
176 * </programlisting></informalexample>
177 *
178 * There are three types of links. Each type has its own attributes as detailed below.
179 * * [Internal Links][internal-link] - A link to a location in the same document
180 * * [URI Links][uri-link] - A link to a Uniform resource identifier
181 * * [File Links][file-link] - A link to a location in another document
182 *
183 * ## Internal Links ## {#internal-link}
184 * An internal link is a link to a location in the same document. The destination
185 * is specified with either:
186 *
187 * @dest: a UTF-8 string specifying the destination in the PDF file to link
188 * to. Destinations are created with the %CAIRO_TAG_DEST tag.
189 *
190 * or the two attributes:
191 *
192 * @page: An integer specifying the page number in the PDF file to link to.
193 *
194 * @pos: [optional] An array of two floats specifying the x,y position
195 * on the page.
196 *
197 * An example of the link attributes to link to a page and x,y position:
198 * <programlisting>
199 * "page=3 pos=[3.1 6.2]"
200 * </programlisting>
201 *
202 * ## URI Links ## {#uri-link}
203 * A URI link is a link to a Uniform Resource Identifier ([RFC 2396](http://tools.ietf.org/html/rfc2396)).
204 *
205 * A URI is specified with the following attribute:
206 *
207 * @uri: An ASCII string specifying the URI.
208 *
209 * An example of the link attributes to the cairo website:
210 * <programlisting>
211 * "uri='https://cairographics.org'"
212 * </programlisting>
213 *
214 * ## File Links ## {#file-link}
215 * A file link is a link a location in another PDF file.
216 *
217 * The file attribute (required) specifies the name of the PDF file:
218 *
219 * @file: File name of PDF file to link to.
220 *
221 * The position is specified by either:
222 *
223 * @dest: a UTF-8 string specifying the named destination in the PDF file.
224 *
225 * or
226 *
227 * @page: An integer specifying the page number in the PDF file.
228 *
229 * @pos: [optional] An array of two floats specifying the x,y
230 * position on the page. Position coordinates in external files are in PDF
231 * coordinates (0,0 at bottom left).
232 *
233 * An example of the link attributes to PDF file:
234 * <programlisting>
235 * "file='document.pdf' page=16 pos=[25 40]"
236 * </programlisting>
237 *
238 * # Destination Tags # {#dest}
239 *
240 * A destination is specified by enclosing the destination drawing
241 * operations with the %CAIRO_TAG_DEST tag.
242 *
243 * @name: [required] A UTF-8 string specifying the name of this destination.
244 *
245 * @x: [optional] A float specifying the x coordinate of destination
246 * position on this page. If not specified the default
247 * x coordinate is the left side of the extents of the
248 * operations enclosed by the %CAIRO_TAG_DEST begin/end tags. If
249 * no operations are enclosed, the x coordidate is 0.
250 *
251 * @y: [optional] A float specifying the y coordinate of destination
252 * position on this page. If not specified the default
253 * y coordinate is the top of the extents of the
254 * operations enclosed by the %CAIRO_TAG_DEST begin/end tags. If
255 * no operations are enclosed, the y coordidate is 0.
256 *
257 * @internal: A boolean that if true, the destination name may be
258 * omitted from PDF where possible. In this case, links
259 * refer directly to the page and position instead of via
260 * the named destination table. Note that if this
261 * destination is referenced by another PDF (see [File Links][file-link]),
262 * this attribute must be false. Default is false.
263 *
264 * <informalexample><programlisting>
265 * /* Create a hyperlink */
266 * cairo_tag_begin (cr, CAIRO_TAG_LINK, "dest='mydest' internal");
267 * cairo_move_to (cr, 50, 50);
268 * cairo_show_text (cr, "This is a hyperlink.");
269 * cairo_tag_end (cr, CAIRO_TAG_LINK);
270 *
271 * /* Create a destination */
272 * cairo_tag_begin (cr, CAIRO_TAG_DEST, "name='mydest'");
273 * cairo_move_to (cr, 50, 250);
274 * cairo_show_text (cr, "This paragraph is the destination of the above link.");
275 * cairo_tag_end (cr, CAIRO_TAG_DEST);
276 * </programlisting></informalexample>
277 *
278 * # Document Structure (PDF) # {#doc-struct}
279 *
280 * The document structure tags provide a means of specifying structural information
281 * such as headers, paragraphs, tables, and figures. The inclusion of structural information facilitates:
282 * * Extraction of text and graphics for copy and paste
283 * * Reflow of text and graphics in the viewer
284 * * Processing text eg searching and indexing
285 * * Conversion to other formats
286 * * Accessability support
287 *
288 * The list of structure types is specified in section 14.8.4 of the
289 * [PDF Reference](http://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/PDF32000_2008.pdf).
290 *
291 * Note the PDF "Link" structure tag is the same as the cairo %CAIRO_TAG_LINK tag.
292 *
293 * The following example creates a document structure for a document containing two section, each with
294 * a header and a paragraph.
295 *
296 * <informalexample><programlisting>
297 * cairo_tag_begin (cr, "Document", NULL);
298 *
299 * cairo_tag_begin (cr, "Sect", NULL);
300 * cairo_tag_begin (cr, "H1", NULL);
301 * cairo_show_text (cr, "Heading 1");
302 * cairo_tag_end (cr, "H1");
303 *
304 * cairo_tag_begin (cr, "P", NULL);
305 * cairo_show_text (cr, "Paragraph 1");
306 * cairo_tag_end (cr, "P");
307 * cairo_tag_end (cr, "Sect");
308 *
309 * cairo_tag_begin (cr, "Sect", NULL);
310 * cairo_tag_begin (cr, "H1", NULL);
311 * cairo_show_text (cr, "Heading 2");
312 * cairo_tag_end (cr, "H1");
313 *
314 * cairo_tag_begin (cr, "P", NULL);
315 * cairo_show_text (cr, "Paragraph 2");
316 * cairo_tag_end (cr, "P");
317 * cairo_tag_end (cr, "Sect");
318 *
319 * cairo_tag_end (cr, "Document");
320 * </programlisting></informalexample>
321 *
322 **/
323
324 #define DEFINE_NIL_CONTEXT(status) \
325 { \
326 CAIRO_REFERENCE_COUNT_INVALID, /* ref_count */ \
327 status, /* status */ \
328 { 0, 0, 0, NULL }, /* user_data */ \
329 NULL \
330 }
331
332 static const cairo_t _cairo_nil[] = {
333 DEFINE_NIL_CONTEXT (CAIRO_STATUS_NO_MEMORY),
334 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_RESTORE),
335 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_POP_GROUP),
336 DEFINE_NIL_CONTEXT (CAIRO_STATUS_NO_CURRENT_POINT),
337 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_MATRIX),
338 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_STATUS),
339 DEFINE_NIL_CONTEXT (CAIRO_STATUS_NULL_POINTER),
340 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_STRING),
341 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_PATH_DATA),
342 DEFINE_NIL_CONTEXT (CAIRO_STATUS_READ_ERROR),
343 DEFINE_NIL_CONTEXT (CAIRO_STATUS_WRITE_ERROR),
344 DEFINE_NIL_CONTEXT (CAIRO_STATUS_SURFACE_FINISHED),
345 DEFINE_NIL_CONTEXT (CAIRO_STATUS_SURFACE_TYPE_MISMATCH),
346 DEFINE_NIL_CONTEXT (CAIRO_STATUS_PATTERN_TYPE_MISMATCH),
347 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_CONTENT),
348 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_FORMAT),
349 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_VISUAL),
350 DEFINE_NIL_CONTEXT (CAIRO_STATUS_FILE_NOT_FOUND),
351 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_DASH),
352 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_DSC_COMMENT),
353 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_INDEX),
354 DEFINE_NIL_CONTEXT (CAIRO_STATUS_CLIP_NOT_REPRESENTABLE),
355 DEFINE_NIL_CONTEXT (CAIRO_STATUS_TEMP_FILE_ERROR),
356 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_STRIDE),
357 DEFINE_NIL_CONTEXT (CAIRO_STATUS_FONT_TYPE_MISMATCH),
358 DEFINE_NIL_CONTEXT (CAIRO_STATUS_USER_FONT_IMMUTABLE),
359 DEFINE_NIL_CONTEXT (CAIRO_STATUS_USER_FONT_ERROR),
360 DEFINE_NIL_CONTEXT (CAIRO_STATUS_NEGATIVE_COUNT),
361 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_CLUSTERS),
362 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_SLANT),
363 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_WEIGHT),
364 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_SIZE),
365 DEFINE_NIL_CONTEXT (CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED),
366 DEFINE_NIL_CONTEXT (CAIRO_STATUS_DEVICE_TYPE_MISMATCH),
367 DEFINE_NIL_CONTEXT (CAIRO_STATUS_DEVICE_ERROR),
368 DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_MESH_CONSTRUCTION),
369 DEFINE_NIL_CONTEXT (CAIRO_STATUS_DEVICE_FINISHED),
370 DEFINE_NIL_CONTEXT (CAIRO_STATUS_JBIG2_GLOBAL_MISSING),
371 DEFINE_NIL_CONTEXT (CAIRO_STATUS_PNG_ERROR),
372 DEFINE_NIL_CONTEXT (CAIRO_STATUS_FREETYPE_ERROR),
373 DEFINE_NIL_CONTEXT (CAIRO_STATUS_WIN32_GDI_ERROR),
374 DEFINE_NIL_CONTEXT (CAIRO_STATUS_TAG_ERROR)
375
376 };
377 COMPILE_TIME_ASSERT (ARRAY_LENGTH (_cairo_nil) == CAIRO_STATUS_LAST_STATUS - 1);
378
379 /**
380 * _cairo_set_error:
381 * @cr: a cairo context
382 * @status: a status value indicating an error
383 *
384 * Atomically sets cr->status to @status and calls _cairo_error;
385 * Does nothing if status is %CAIRO_STATUS_SUCCESS.
386 *
387 * All assignments of an error status to cr->status should happen
388 * through _cairo_set_error(). Note that due to the nature of the atomic
389 * operation, it is not safe to call this function on the nil objects.
390 *
391 * The purpose of this function is to allow the user to set a
392 * breakpoint in _cairo_error() to generate a stack trace for when the
393 * user causes cairo to detect an error.
394 **/
395 static void
_cairo_set_error(cairo_t * cr,cairo_status_t status)396 _cairo_set_error (cairo_t *cr, cairo_status_t status)
397 {
398 /* Don't overwrite an existing error. This preserves the first
399 * error, which is the most significant. */
400 _cairo_status_set_error (&cr->status, _cairo_error (status));
401 }
402
403 cairo_t *
_cairo_create_in_error(cairo_status_t status)404 _cairo_create_in_error (cairo_status_t status)
405 {
406 cairo_t *cr;
407
408 assert (status != CAIRO_STATUS_SUCCESS);
409
410 cr = (cairo_t *) &_cairo_nil[status - CAIRO_STATUS_NO_MEMORY];
411 assert (status == cr->status);
412
413 return cr;
414 }
415
416 /**
417 * cairo_create:
418 * @target: target surface for the context
419 *
420 * Creates a new #cairo_t with all graphics state parameters set to
421 * default values and with @target as a target surface. The target
422 * surface should be constructed with a backend-specific function such
423 * as cairo_image_surface_create() (or any other
424 * <function>cairo_<emphasis>backend</emphasis>_surface_create(<!-- -->)</function>
425 * variant).
426 *
427 * This function references @target, so you can immediately
428 * call cairo_surface_destroy() on it if you don't need to
429 * maintain a separate reference to it.
430 *
431 * Return value: a newly allocated #cairo_t with a reference
432 * count of 1. The initial reference count should be released
433 * with cairo_destroy() when you are done using the #cairo_t.
434 * This function never returns %NULL. If memory cannot be
435 * allocated, a special #cairo_t object will be returned on
436 * which cairo_status() returns %CAIRO_STATUS_NO_MEMORY. If
437 * you attempt to target a surface which does not support
438 * writing (such as #cairo_mime_surface_t) then a
439 * %CAIRO_STATUS_WRITE_ERROR will be raised. You can use this
440 * object normally, but no drawing will be done.
441 *
442 * Since: 1.0
443 **/
444 cairo_t *
cairo_create(cairo_surface_t * target)445 cairo_create (cairo_surface_t *target)
446 {
447 if (unlikely (target == NULL))
448 return _cairo_create_in_error (_cairo_error (CAIRO_STATUS_NULL_POINTER));
449 if (unlikely (target->status))
450 return _cairo_create_in_error (target->status);
451 if (unlikely (target->finished))
452 return _cairo_create_in_error (_cairo_error (CAIRO_STATUS_SURFACE_FINISHED));
453
454 if (target->backend->create_context == NULL)
455 return _cairo_create_in_error (_cairo_error (CAIRO_STATUS_WRITE_ERROR));
456
457 return target->backend->create_context (target);
458
459 }
460 slim_hidden_def (cairo_create);
461
462 void
_cairo_init(cairo_t * cr,const cairo_backend_t * backend)463 _cairo_init (cairo_t *cr,
464 const cairo_backend_t *backend)
465 {
466 CAIRO_REFERENCE_COUNT_INIT (&cr->ref_count, 1);
467 cr->status = CAIRO_STATUS_SUCCESS;
468 _cairo_user_data_array_init (&cr->user_data);
469
470 cr->backend = backend;
471 }
472
473 /**
474 * cairo_reference:
475 * @cr: a #cairo_t
476 *
477 * Increases the reference count on @cr by one. This prevents
478 * @cr from being destroyed until a matching call to cairo_destroy()
479 * is made.
480 *
481 * Use cairo_get_reference_count() to get the number of references to
482 * a #cairo_t.
483 *
484 * Return value: the referenced #cairo_t.
485 *
486 * Since: 1.0
487 **/
488 cairo_t *
cairo_reference(cairo_t * cr)489 cairo_reference (cairo_t *cr)
490 {
491 if (cr == NULL || CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
492 return cr;
493
494 assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&cr->ref_count));
495
496 _cairo_reference_count_inc (&cr->ref_count);
497
498 return cr;
499 }
500
501 void
_cairo_fini(cairo_t * cr)502 _cairo_fini (cairo_t *cr)
503 {
504 _cairo_user_data_array_fini (&cr->user_data);
505 }
506
507 /**
508 * cairo_destroy:
509 * @cr: a #cairo_t
510 *
511 * Decreases the reference count on @cr by one. If the result
512 * is zero, then @cr and all associated resources are freed.
513 * See cairo_reference().
514 *
515 * Since: 1.0
516 **/
517 void
cairo_destroy(cairo_t * cr)518 cairo_destroy (cairo_t *cr)
519 {
520 if (cr == NULL || CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
521 return;
522
523 assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&cr->ref_count));
524
525 if (! _cairo_reference_count_dec_and_test (&cr->ref_count))
526 return;
527
528 cr->backend->destroy (cr);
529 }
530 slim_hidden_def (cairo_destroy);
531
532 /**
533 * cairo_get_user_data:
534 * @cr: a #cairo_t
535 * @key: the address of the #cairo_user_data_key_t the user data was
536 * attached to
537 *
538 * Return user data previously attached to @cr using the specified
539 * key. If no user data has been attached with the given key this
540 * function returns %NULL.
541 *
542 * Return value: the user data previously attached or %NULL.
543 *
544 * Since: 1.4
545 **/
546 void *
cairo_get_user_data(cairo_t * cr,const cairo_user_data_key_t * key)547 cairo_get_user_data (cairo_t *cr,
548 const cairo_user_data_key_t *key)
549 {
550 return _cairo_user_data_array_get_data (&cr->user_data, key);
551 }
552
553 /**
554 * cairo_set_user_data:
555 * @cr: a #cairo_t
556 * @key: the address of a #cairo_user_data_key_t to attach the user data to
557 * @user_data: the user data to attach to the #cairo_t
558 * @destroy: a #cairo_destroy_func_t which will be called when the
559 * #cairo_t is destroyed or when new user data is attached using the
560 * same key.
561 *
562 * Attach user data to @cr. To remove user data from a surface,
563 * call this function with the key that was used to set it and %NULL
564 * for @data.
565 *
566 * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a
567 * slot could not be allocated for the user data.
568 *
569 * Since: 1.4
570 **/
571 cairo_status_t
cairo_set_user_data(cairo_t * cr,const cairo_user_data_key_t * key,void * user_data,cairo_destroy_func_t destroy)572 cairo_set_user_data (cairo_t *cr,
573 const cairo_user_data_key_t *key,
574 void *user_data,
575 cairo_destroy_func_t destroy)
576 {
577 if (CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
578 return cr->status;
579
580 return _cairo_user_data_array_set_data (&cr->user_data,
581 key, user_data, destroy);
582 }
583
584 /**
585 * cairo_get_reference_count:
586 * @cr: a #cairo_t
587 *
588 * Returns the current reference count of @cr.
589 *
590 * Return value: the current reference count of @cr. If the
591 * object is a nil object, 0 will be returned.
592 *
593 * Since: 1.4
594 **/
595 unsigned int
cairo_get_reference_count(cairo_t * cr)596 cairo_get_reference_count (cairo_t *cr)
597 {
598 if (cr == NULL || CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
599 return 0;
600
601 return CAIRO_REFERENCE_COUNT_GET_VALUE (&cr->ref_count);
602 }
603
604 /**
605 * cairo_save:
606 * @cr: a #cairo_t
607 *
608 * Makes a copy of the current state of @cr and saves it
609 * on an internal stack of saved states for @cr. When
610 * cairo_restore() is called, @cr will be restored to
611 * the saved state. Multiple calls to cairo_save() and
612 * cairo_restore() can be nested; each call to cairo_restore()
613 * restores the state from the matching paired cairo_save().
614 *
615 * It isn't necessary to clear all saved states before
616 * a #cairo_t is freed. If the reference count of a #cairo_t
617 * drops to zero in response to a call to cairo_destroy(),
618 * any saved states will be freed along with the #cairo_t.
619 *
620 * Since: 1.0
621 **/
622 void
cairo_save(cairo_t * cr)623 cairo_save (cairo_t *cr)
624 {
625 cairo_status_t status;
626
627 if (unlikely (cr->status))
628 return;
629
630 status = cr->backend->save (cr);
631 if (unlikely (status))
632 _cairo_set_error (cr, status);
633 }
634 slim_hidden_def(cairo_save);
635
636 /**
637 * cairo_restore:
638 * @cr: a #cairo_t
639 *
640 * Restores @cr to the state saved by a preceding call to
641 * cairo_save() and removes that state from the stack of
642 * saved states.
643 *
644 * Since: 1.0
645 **/
646 void
cairo_restore(cairo_t * cr)647 cairo_restore (cairo_t *cr)
648 {
649 cairo_status_t status;
650
651 if (unlikely (cr->status))
652 return;
653
654 status = cr->backend->restore (cr);
655 if (unlikely (status))
656 _cairo_set_error (cr, status);
657 }
658 slim_hidden_def(cairo_restore);
659
660 /**
661 * cairo_push_group:
662 * @cr: a cairo context
663 *
664 * Temporarily redirects drawing to an intermediate surface known as a
665 * group. The redirection lasts until the group is completed by a call
666 * to cairo_pop_group() or cairo_pop_group_to_source(). These calls
667 * provide the result of any drawing to the group as a pattern,
668 * (either as an explicit object, or set as the source pattern).
669 *
670 * This group functionality can be convenient for performing
671 * intermediate compositing. One common use of a group is to render
672 * objects as opaque within the group, (so that they occlude each
673 * other), and then blend the result with translucence onto the
674 * destination.
675 *
676 * Groups can be nested arbitrarily deep by making balanced calls to
677 * cairo_push_group()/cairo_pop_group(). Each call pushes/pops the new
678 * target group onto/from a stack.
679 *
680 * The cairo_push_group() function calls cairo_save() so that any
681 * changes to the graphics state will not be visible outside the
682 * group, (the pop_group functions call cairo_restore()).
683 *
684 * By default the intermediate group will have a content type of
685 * %CAIRO_CONTENT_COLOR_ALPHA. Other content types can be chosen for
686 * the group by using cairo_push_group_with_content() instead.
687 *
688 * As an example, here is how one might fill and stroke a path with
689 * translucence, but without any portion of the fill being visible
690 * under the stroke:
691 *
692 * <informalexample><programlisting>
693 * cairo_push_group (cr);
694 * cairo_set_source (cr, fill_pattern);
695 * cairo_fill_preserve (cr);
696 * cairo_set_source (cr, stroke_pattern);
697 * cairo_stroke (cr);
698 * cairo_pop_group_to_source (cr);
699 * cairo_paint_with_alpha (cr, alpha);
700 * </programlisting></informalexample>
701 *
702 * Since: 1.2
703 **/
704 void
cairo_push_group(cairo_t * cr)705 cairo_push_group (cairo_t *cr)
706 {
707 cairo_push_group_with_content (cr, CAIRO_CONTENT_COLOR_ALPHA);
708 }
709
710 /**
711 * cairo_push_group_with_content:
712 * @cr: a cairo context
713 * @content: a #cairo_content_t indicating the type of group that
714 * will be created
715 *
716 * Temporarily redirects drawing to an intermediate surface known as a
717 * group. The redirection lasts until the group is completed by a call
718 * to cairo_pop_group() or cairo_pop_group_to_source(). These calls
719 * provide the result of any drawing to the group as a pattern,
720 * (either as an explicit object, or set as the source pattern).
721 *
722 * The group will have a content type of @content. The ability to
723 * control this content type is the only distinction between this
724 * function and cairo_push_group() which you should see for a more
725 * detailed description of group rendering.
726 *
727 * Since: 1.2
728 **/
729 void
cairo_push_group_with_content(cairo_t * cr,cairo_content_t content)730 cairo_push_group_with_content (cairo_t *cr, cairo_content_t content)
731 {
732 cairo_status_t status;
733
734 if (unlikely (cr->status))
735 return;
736
737 status = cr->backend->push_group (cr, content);
738 if (unlikely (status))
739 _cairo_set_error (cr, status);
740 }
741 slim_hidden_def(cairo_push_group_with_content);
742
743 /**
744 * cairo_pop_group:
745 * @cr: a cairo context
746 *
747 * Terminates the redirection begun by a call to cairo_push_group() or
748 * cairo_push_group_with_content() and returns a new pattern
749 * containing the results of all drawing operations performed to the
750 * group.
751 *
752 * The cairo_pop_group() function calls cairo_restore(), (balancing a
753 * call to cairo_save() by the push_group function), so that any
754 * changes to the graphics state will not be visible outside the
755 * group.
756 *
757 * Return value: a newly created (surface) pattern containing the
758 * results of all drawing operations performed to the group. The
759 * caller owns the returned object and should call
760 * cairo_pattern_destroy() when finished with it.
761 *
762 * Since: 1.2
763 **/
764 cairo_pattern_t *
cairo_pop_group(cairo_t * cr)765 cairo_pop_group (cairo_t *cr)
766 {
767 cairo_pattern_t *group_pattern;
768
769 if (unlikely (cr->status))
770 return _cairo_pattern_create_in_error (cr->status);
771
772 group_pattern = cr->backend->pop_group (cr);
773 if (unlikely (group_pattern->status))
774 _cairo_set_error (cr, group_pattern->status);
775
776 return group_pattern;
777 }
778 slim_hidden_def(cairo_pop_group);
779
780 /**
781 * cairo_pop_group_to_source:
782 * @cr: a cairo context
783 *
784 * Terminates the redirection begun by a call to cairo_push_group() or
785 * cairo_push_group_with_content() and installs the resulting pattern
786 * as the source pattern in the given cairo context.
787 *
788 * The behavior of this function is equivalent to the sequence of
789 * operations:
790 *
791 * <informalexample><programlisting>
792 * cairo_pattern_t *group = cairo_pop_group (cr);
793 * cairo_set_source (cr, group);
794 * cairo_pattern_destroy (group);
795 * </programlisting></informalexample>
796 *
797 * but is more convenient as their is no need for a variable to store
798 * the short-lived pointer to the pattern.
799 *
800 * The cairo_pop_group() function calls cairo_restore(), (balancing a
801 * call to cairo_save() by the push_group function), so that any
802 * changes to the graphics state will not be visible outside the
803 * group.
804 *
805 * Since: 1.2
806 **/
807 void
cairo_pop_group_to_source(cairo_t * cr)808 cairo_pop_group_to_source (cairo_t *cr)
809 {
810 cairo_pattern_t *group_pattern;
811
812 group_pattern = cairo_pop_group (cr);
813 cairo_set_source (cr, group_pattern);
814 cairo_pattern_destroy (group_pattern);
815 }
816
817 /**
818 * cairo_set_operator:
819 * @cr: a #cairo_t
820 * @op: a compositing operator, specified as a #cairo_operator_t
821 *
822 * Sets the compositing operator to be used for all drawing
823 * operations. See #cairo_operator_t for details on the semantics of
824 * each available compositing operator.
825 *
826 * The default operator is %CAIRO_OPERATOR_OVER.
827 *
828 * Since: 1.0
829 **/
830 void
cairo_set_operator(cairo_t * cr,cairo_operator_t op)831 cairo_set_operator (cairo_t *cr, cairo_operator_t op)
832 {
833 cairo_status_t status;
834
835 if (unlikely (cr->status))
836 return;
837
838 status = cr->backend->set_operator (cr, op);
839 if (unlikely (status))
840 _cairo_set_error (cr, status);
841 }
842 slim_hidden_def (cairo_set_operator);
843
844
845 #if 0
846 /*
847 * cairo_set_opacity:
848 * @cr: a #cairo_t
849 * @opacity: the level of opacity to use when compositing
850 *
851 * Sets the compositing opacity to be used for all drawing
852 * operations. The effect is to fade out the operations
853 * using the alpha value.
854 *
855 * The default opacity is 1.
856 */
857 void
858 cairo_set_opacity (cairo_t *cr, double opacity)
859 {
860 cairo_status_t status;
861
862 if (unlikely (cr->status))
863 return;
864
865 status = cr->backend->set_opacity (cr, opacity);
866 if (unlikely (status))
867 _cairo_set_error (cr, status);
868 }
869 #endif
870
871 /**
872 * cairo_set_source_rgb:
873 * @cr: a cairo context
874 * @red: red component of color
875 * @green: green component of color
876 * @blue: blue component of color
877 *
878 * Sets the source pattern within @cr to an opaque color. This opaque
879 * color will then be used for any subsequent drawing operation until
880 * a new source pattern is set.
881 *
882 * The color components are floating point numbers in the range 0 to
883 * 1. If the values passed in are outside that range, they will be
884 * clamped.
885 *
886 * The default source pattern is opaque black, (that is, it is
887 * equivalent to cairo_set_source_rgb(cr, 0.0, 0.0, 0.0)).
888 *
889 * Since: 1.0
890 **/
891 void
cairo_set_source_rgb(cairo_t * cr,double red,double green,double blue)892 cairo_set_source_rgb (cairo_t *cr, double red, double green, double blue)
893 {
894 cairo_status_t status;
895
896 if (unlikely (cr->status))
897 return;
898
899 status = cr->backend->set_source_rgba (cr, red, green, blue, 1.);
900 if (unlikely (status))
901 _cairo_set_error (cr, status);
902 }
903 slim_hidden_def (cairo_set_source_rgb);
904
905 /**
906 * cairo_set_source_rgba:
907 * @cr: a cairo context
908 * @red: red component of color
909 * @green: green component of color
910 * @blue: blue component of color
911 * @alpha: alpha component of color
912 *
913 * Sets the source pattern within @cr to a translucent color. This
914 * color will then be used for any subsequent drawing operation until
915 * a new source pattern is set.
916 *
917 * The color and alpha components are floating point numbers in the
918 * range 0 to 1. If the values passed in are outside that range, they
919 * will be clamped.
920 *
921 * The default source pattern is opaque black, (that is, it is
922 * equivalent to cairo_set_source_rgba(cr, 0.0, 0.0, 0.0, 1.0)).
923 *
924 * Since: 1.0
925 **/
926 void
cairo_set_source_rgba(cairo_t * cr,double red,double green,double blue,double alpha)927 cairo_set_source_rgba (cairo_t *cr,
928 double red, double green, double blue,
929 double alpha)
930 {
931 cairo_status_t status;
932
933 if (unlikely (cr->status))
934 return;
935
936 status = cr->backend->set_source_rgba (cr, red, green, blue, alpha);
937 if (unlikely (status))
938 _cairo_set_error (cr, status);
939 }
940
941 /**
942 * cairo_set_source_surface:
943 * @cr: a cairo context
944 * @surface: a surface to be used to set the source pattern
945 * @x: User-space X coordinate for surface origin
946 * @y: User-space Y coordinate for surface origin
947 *
948 * This is a convenience function for creating a pattern from @surface
949 * and setting it as the source in @cr with cairo_set_source().
950 *
951 * The @x and @y parameters give the user-space coordinate at which
952 * the surface origin should appear. (The surface origin is its
953 * upper-left corner before any transformation has been applied.) The
954 * @x and @y parameters are negated and then set as translation values
955 * in the pattern matrix.
956 *
957 * Other than the initial translation pattern matrix, as described
958 * above, all other pattern attributes, (such as its extend mode), are
959 * set to the default values as in cairo_pattern_create_for_surface().
960 * The resulting pattern can be queried with cairo_get_source() so
961 * that these attributes can be modified if desired, (eg. to create a
962 * repeating pattern with cairo_pattern_set_extend()).
963 *
964 * Since: 1.0
965 **/
966 void
cairo_set_source_surface(cairo_t * cr,cairo_surface_t * surface,double x,double y)967 cairo_set_source_surface (cairo_t *cr,
968 cairo_surface_t *surface,
969 double x,
970 double y)
971 {
972 cairo_status_t status;
973
974 if (unlikely (cr->status))
975 return;
976
977 if (unlikely (surface == NULL)) {
978 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
979 return;
980 }
981
982 status = cr->backend->set_source_surface (cr, surface, x, y);
983 if (unlikely (status))
984 _cairo_set_error (cr, status);
985 }
986 slim_hidden_def (cairo_set_source_surface);
987
988 /**
989 * cairo_set_source:
990 * @cr: a cairo context
991 * @source: a #cairo_pattern_t to be used as the source for
992 * subsequent drawing operations.
993 *
994 * Sets the source pattern within @cr to @source. This pattern
995 * will then be used for any subsequent drawing operation until a new
996 * source pattern is set.
997 *
998 * Note: The pattern's transformation matrix will be locked to the
999 * user space in effect at the time of cairo_set_source(). This means
1000 * that further modifications of the current transformation matrix
1001 * will not affect the source pattern. See cairo_pattern_set_matrix().
1002 *
1003 * The default source pattern is a solid pattern that is opaque black,
1004 * (that is, it is equivalent to cairo_set_source_rgb(cr, 0.0, 0.0,
1005 * 0.0)).
1006 *
1007 * Since: 1.0
1008 **/
1009 void
cairo_set_source(cairo_t * cr,cairo_pattern_t * source)1010 cairo_set_source (cairo_t *cr, cairo_pattern_t *source)
1011 {
1012 cairo_status_t status;
1013
1014 if (unlikely (cr->status))
1015 return;
1016
1017 if (unlikely (source == NULL)) {
1018 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
1019 return;
1020 }
1021
1022 if (unlikely (source->status)) {
1023 _cairo_set_error (cr, source->status);
1024 return;
1025 }
1026
1027 status = cr->backend->set_source (cr, source);
1028 if (unlikely (status))
1029 _cairo_set_error (cr, status);
1030 }
1031 slim_hidden_def (cairo_set_source);
1032
1033 /**
1034 * cairo_get_source:
1035 * @cr: a cairo context
1036 *
1037 * Gets the current source pattern for @cr.
1038 *
1039 * Return value: the current source pattern. This object is owned by
1040 * cairo. To keep a reference to it, you must call
1041 * cairo_pattern_reference().
1042 *
1043 * Since: 1.0
1044 **/
1045 cairo_pattern_t *
cairo_get_source(cairo_t * cr)1046 cairo_get_source (cairo_t *cr)
1047 {
1048 if (unlikely (cr->status))
1049 return _cairo_pattern_create_in_error (cr->status);
1050
1051 return cr->backend->get_source (cr);
1052 }
1053
1054 /**
1055 * cairo_set_tolerance:
1056 * @cr: a #cairo_t
1057 * @tolerance: the tolerance, in device units (typically pixels)
1058 *
1059 * Sets the tolerance used when converting paths into trapezoids.
1060 * Curved segments of the path will be subdivided until the maximum
1061 * deviation between the original path and the polygonal approximation
1062 * is less than @tolerance. The default value is 0.1. A larger
1063 * value will give better performance, a smaller value, better
1064 * appearance. (Reducing the value from the default value of 0.1
1065 * is unlikely to improve appearance significantly.) The accuracy of paths
1066 * within Cairo is limited by the precision of its internal arithmetic, and
1067 * the prescribed @tolerance is restricted to the smallest
1068 * representable internal value.
1069 *
1070 * Since: 1.0
1071 **/
1072 void
cairo_set_tolerance(cairo_t * cr,double tolerance)1073 cairo_set_tolerance (cairo_t *cr, double tolerance)
1074 {
1075 cairo_status_t status;
1076
1077 if (unlikely (cr->status))
1078 return;
1079
1080 status = cr->backend->set_tolerance (cr, tolerance);
1081 if (unlikely (status))
1082 _cairo_set_error (cr, status);
1083 }
1084 slim_hidden_def (cairo_set_tolerance);
1085
1086 /**
1087 * cairo_set_antialias:
1088 * @cr: a #cairo_t
1089 * @antialias: the new antialiasing mode
1090 *
1091 * Set the antialiasing mode of the rasterizer used for drawing shapes.
1092 * This value is a hint, and a particular backend may or may not support
1093 * a particular value. At the current time, no backend supports
1094 * %CAIRO_ANTIALIAS_SUBPIXEL when drawing shapes.
1095 *
1096 * Note that this option does not affect text rendering, instead see
1097 * cairo_font_options_set_antialias().
1098 *
1099 * Since: 1.0
1100 **/
1101 void
cairo_set_antialias(cairo_t * cr,cairo_antialias_t antialias)1102 cairo_set_antialias (cairo_t *cr, cairo_antialias_t antialias)
1103 {
1104 cairo_status_t status;
1105
1106 if (unlikely (cr->status))
1107 return;
1108
1109 status = cr->backend->set_antialias (cr, antialias);
1110 if (unlikely (status))
1111 _cairo_set_error (cr, status);
1112 }
1113
1114 /**
1115 * cairo_set_fill_rule:
1116 * @cr: a #cairo_t
1117 * @fill_rule: a fill rule, specified as a #cairo_fill_rule_t
1118 *
1119 * Set the current fill rule within the cairo context. The fill rule
1120 * is used to determine which regions are inside or outside a complex
1121 * (potentially self-intersecting) path. The current fill rule affects
1122 * both cairo_fill() and cairo_clip(). See #cairo_fill_rule_t for details
1123 * on the semantics of each available fill rule.
1124 *
1125 * The default fill rule is %CAIRO_FILL_RULE_WINDING.
1126 *
1127 * Since: 1.0
1128 **/
1129 void
cairo_set_fill_rule(cairo_t * cr,cairo_fill_rule_t fill_rule)1130 cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule)
1131 {
1132 cairo_status_t status;
1133
1134 if (unlikely (cr->status))
1135 return;
1136
1137 status = cr->backend->set_fill_rule (cr, fill_rule);
1138 if (unlikely (status))
1139 _cairo_set_error (cr, status);
1140 }
1141
1142 /**
1143 * cairo_set_line_width:
1144 * @cr: a #cairo_t
1145 * @width: a line width
1146 *
1147 * Sets the current line width within the cairo context. The line
1148 * width value specifies the diameter of a pen that is circular in
1149 * user space, (though device-space pen may be an ellipse in general
1150 * due to scaling/shear/rotation of the CTM).
1151 *
1152 * Note: When the description above refers to user space and CTM it
1153 * refers to the user space and CTM in effect at the time of the
1154 * stroking operation, not the user space and CTM in effect at the
1155 * time of the call to cairo_set_line_width(). The simplest usage
1156 * makes both of these spaces identical. That is, if there is no
1157 * change to the CTM between a call to cairo_set_line_width() and the
1158 * stroking operation, then one can just pass user-space values to
1159 * cairo_set_line_width() and ignore this note.
1160 *
1161 * As with the other stroke parameters, the current line width is
1162 * examined by cairo_stroke(), cairo_stroke_extents(), and
1163 * cairo_stroke_to_path(), but does not have any effect during path
1164 * construction.
1165 *
1166 * The default line width value is 2.0.
1167 *
1168 * Since: 1.0
1169 **/
1170 void
cairo_set_line_width(cairo_t * cr,double width)1171 cairo_set_line_width (cairo_t *cr, double width)
1172 {
1173 cairo_status_t status;
1174
1175 if (unlikely (cr->status))
1176 return;
1177
1178 if (width < 0.)
1179 width = 0.;
1180
1181 status = cr->backend->set_line_width (cr, width);
1182 if (unlikely (status))
1183 _cairo_set_error (cr, status);
1184 }
1185 slim_hidden_def (cairo_set_line_width);
1186
1187 /**
1188 * cairo_set_line_cap:
1189 * @cr: a cairo context
1190 * @line_cap: a line cap style
1191 *
1192 * Sets the current line cap style within the cairo context. See
1193 * #cairo_line_cap_t for details about how the available line cap
1194 * styles are drawn.
1195 *
1196 * As with the other stroke parameters, the current line cap style is
1197 * examined by cairo_stroke(), cairo_stroke_extents(), and
1198 * cairo_stroke_to_path(), but does not have any effect during path
1199 * construction.
1200 *
1201 * The default line cap style is %CAIRO_LINE_CAP_BUTT.
1202 *
1203 * Since: 1.0
1204 **/
1205 void
cairo_set_line_cap(cairo_t * cr,cairo_line_cap_t line_cap)1206 cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap)
1207 {
1208 cairo_status_t status;
1209
1210 if (unlikely (cr->status))
1211 return;
1212
1213 status = cr->backend->set_line_cap (cr, line_cap);
1214 if (unlikely (status))
1215 _cairo_set_error (cr, status);
1216 }
1217 slim_hidden_def (cairo_set_line_cap);
1218
1219 /**
1220 * cairo_set_line_join:
1221 * @cr: a cairo context
1222 * @line_join: a line join style
1223 *
1224 * Sets the current line join style within the cairo context. See
1225 * #cairo_line_join_t for details about how the available line join
1226 * styles are drawn.
1227 *
1228 * As with the other stroke parameters, the current line join style is
1229 * examined by cairo_stroke(), cairo_stroke_extents(), and
1230 * cairo_stroke_to_path(), but does not have any effect during path
1231 * construction.
1232 *
1233 * The default line join style is %CAIRO_LINE_JOIN_MITER.
1234 *
1235 * Since: 1.0
1236 **/
1237 void
cairo_set_line_join(cairo_t * cr,cairo_line_join_t line_join)1238 cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join)
1239 {
1240 cairo_status_t status;
1241
1242 if (unlikely (cr->status))
1243 return;
1244
1245 status = cr->backend->set_line_join (cr, line_join);
1246 if (unlikely (status))
1247 _cairo_set_error (cr, status);
1248 }
1249 slim_hidden_def (cairo_set_line_join);
1250
1251 /**
1252 * cairo_set_dash:
1253 * @cr: a cairo context
1254 * @dashes: an array specifying alternate lengths of on and off stroke portions
1255 * @num_dashes: the length of the dashes array
1256 * @offset: an offset into the dash pattern at which the stroke should start
1257 *
1258 * Sets the dash pattern to be used by cairo_stroke(). A dash pattern
1259 * is specified by @dashes, an array of positive values. Each value
1260 * provides the length of alternate "on" and "off" portions of the
1261 * stroke. The @offset specifies an offset into the pattern at which
1262 * the stroke begins.
1263 *
1264 * Each "on" segment will have caps applied as if the segment were a
1265 * separate sub-path. In particular, it is valid to use an "on" length
1266 * of 0.0 with %CAIRO_LINE_CAP_ROUND or %CAIRO_LINE_CAP_SQUARE in order
1267 * to distributed dots or squares along a path.
1268 *
1269 * Note: The length values are in user-space units as evaluated at the
1270 * time of stroking. This is not necessarily the same as the user
1271 * space at the time of cairo_set_dash().
1272 *
1273 * If @num_dashes is 0 dashing is disabled.
1274 *
1275 * If @num_dashes is 1 a symmetric pattern is assumed with alternating
1276 * on and off portions of the size specified by the single value in
1277 * @dashes.
1278 *
1279 * If any value in @dashes is negative, or if all values are 0, then
1280 * @cr will be put into an error state with a status of
1281 * %CAIRO_STATUS_INVALID_DASH.
1282 *
1283 * Since: 1.0
1284 **/
1285 void
cairo_set_dash(cairo_t * cr,const double * dashes,int num_dashes,double offset)1286 cairo_set_dash (cairo_t *cr,
1287 const double *dashes,
1288 int num_dashes,
1289 double offset)
1290 {
1291 cairo_status_t status;
1292
1293 if (unlikely (cr->status))
1294 return;
1295
1296 status = cr->backend->set_dash (cr, dashes, num_dashes, offset);
1297 if (unlikely (status))
1298 _cairo_set_error (cr, status);
1299 }
1300
1301 /**
1302 * cairo_get_dash_count:
1303 * @cr: a #cairo_t
1304 *
1305 * This function returns the length of the dash array in @cr (0 if dashing
1306 * is not currently in effect).
1307 *
1308 * See also cairo_set_dash() and cairo_get_dash().
1309 *
1310 * Return value: the length of the dash array, or 0 if no dash array set.
1311 *
1312 * Since: 1.4
1313 **/
1314 int
cairo_get_dash_count(cairo_t * cr)1315 cairo_get_dash_count (cairo_t *cr)
1316 {
1317 int num_dashes;
1318
1319 if (unlikely (cr->status))
1320 return 0;
1321
1322 cr->backend->get_dash (cr, NULL, &num_dashes, NULL);
1323
1324 return num_dashes;
1325 }
1326
1327 /**
1328 * cairo_get_dash:
1329 * @cr: a #cairo_t
1330 * @dashes: return value for the dash array, or %NULL
1331 * @offset: return value for the current dash offset, or %NULL
1332 *
1333 * Gets the current dash array. If not %NULL, @dashes should be big
1334 * enough to hold at least the number of values returned by
1335 * cairo_get_dash_count().
1336 *
1337 * Since: 1.4
1338 **/
1339 void
cairo_get_dash(cairo_t * cr,double * dashes,double * offset)1340 cairo_get_dash (cairo_t *cr,
1341 double *dashes,
1342 double *offset)
1343 {
1344 if (unlikely (cr->status))
1345 return;
1346
1347 cr->backend->get_dash (cr, dashes, NULL, offset);
1348 }
1349
1350 /**
1351 * cairo_set_miter_limit:
1352 * @cr: a cairo context
1353 * @limit: miter limit to set
1354 *
1355 * Sets the current miter limit within the cairo context.
1356 *
1357 * If the current line join style is set to %CAIRO_LINE_JOIN_MITER
1358 * (see cairo_set_line_join()), the miter limit is used to determine
1359 * whether the lines should be joined with a bevel instead of a miter.
1360 * Cairo divides the length of the miter by the line width.
1361 * If the result is greater than the miter limit, the style is
1362 * converted to a bevel.
1363 *
1364 * As with the other stroke parameters, the current line miter limit is
1365 * examined by cairo_stroke(), cairo_stroke_extents(), and
1366 * cairo_stroke_to_path(), but does not have any effect during path
1367 * construction.
1368 *
1369 * The default miter limit value is 10.0, which will convert joins
1370 * with interior angles less than 11 degrees to bevels instead of
1371 * miters. For reference, a miter limit of 2.0 makes the miter cutoff
1372 * at 60 degrees, and a miter limit of 1.414 makes the cutoff at 90
1373 * degrees.
1374 *
1375 * A miter limit for a desired angle can be computed as: miter limit =
1376 * 1/sin(angle/2)
1377 *
1378 * Since: 1.0
1379 **/
1380 void
cairo_set_miter_limit(cairo_t * cr,double limit)1381 cairo_set_miter_limit (cairo_t *cr, double limit)
1382 {
1383 cairo_status_t status;
1384
1385 if (unlikely (cr->status))
1386 return;
1387
1388 status = cr->backend->set_miter_limit (cr, limit);
1389 if (unlikely (status))
1390 _cairo_set_error (cr, status);
1391 }
1392
1393 /**
1394 * cairo_translate:
1395 * @cr: a cairo context
1396 * @tx: amount to translate in the X direction
1397 * @ty: amount to translate in the Y direction
1398 *
1399 * Modifies the current transformation matrix (CTM) by translating the
1400 * user-space origin by (@tx, @ty). This offset is interpreted as a
1401 * user-space coordinate according to the CTM in place before the new
1402 * call to cairo_translate(). In other words, the translation of the
1403 * user-space origin takes place after any existing transformation.
1404 *
1405 * Since: 1.0
1406 **/
1407 void
cairo_translate(cairo_t * cr,double tx,double ty)1408 cairo_translate (cairo_t *cr, double tx, double ty)
1409 {
1410 cairo_status_t status;
1411
1412 if (unlikely (cr->status))
1413 return;
1414
1415 status = cr->backend->translate (cr, tx, ty);
1416 if (unlikely (status))
1417 _cairo_set_error (cr, status);
1418 }
1419 slim_hidden_def (cairo_translate);
1420
1421 /**
1422 * cairo_scale:
1423 * @cr: a cairo context
1424 * @sx: scale factor for the X dimension
1425 * @sy: scale factor for the Y dimension
1426 *
1427 * Modifies the current transformation matrix (CTM) by scaling the X
1428 * and Y user-space axes by @sx and @sy respectively. The scaling of
1429 * the axes takes place after any existing transformation of user
1430 * space.
1431 *
1432 * Since: 1.0
1433 **/
1434 void
cairo_scale(cairo_t * cr,double sx,double sy)1435 cairo_scale (cairo_t *cr, double sx, double sy)
1436 {
1437 cairo_status_t status;
1438
1439 if (unlikely (cr->status))
1440 return;
1441
1442 status = cr->backend->scale (cr, sx, sy);
1443 if (unlikely (status))
1444 _cairo_set_error (cr, status);
1445 }
1446 slim_hidden_def (cairo_scale);
1447
1448 /**
1449 * cairo_rotate:
1450 * @cr: a cairo context
1451 * @angle: angle (in radians) by which the user-space axes will be
1452 * rotated
1453 *
1454 * Modifies the current transformation matrix (CTM) by rotating the
1455 * user-space axes by @angle radians. The rotation of the axes takes
1456 * places after any existing transformation of user space. The
1457 * rotation direction for positive angles is from the positive X axis
1458 * toward the positive Y axis.
1459 *
1460 * Since: 1.0
1461 **/
1462 void
cairo_rotate(cairo_t * cr,double angle)1463 cairo_rotate (cairo_t *cr, double angle)
1464 {
1465 cairo_status_t status;
1466
1467 if (unlikely (cr->status))
1468 return;
1469
1470 status = cr->backend->rotate (cr, angle);
1471 if (unlikely (status))
1472 _cairo_set_error (cr, status);
1473 }
1474
1475 /**
1476 * cairo_transform:
1477 * @cr: a cairo context
1478 * @matrix: a transformation to be applied to the user-space axes
1479 *
1480 * Modifies the current transformation matrix (CTM) by applying
1481 * @matrix as an additional transformation. The new transformation of
1482 * user space takes place after any existing transformation.
1483 *
1484 * Since: 1.0
1485 **/
1486 void
cairo_transform(cairo_t * cr,const cairo_matrix_t * matrix)1487 cairo_transform (cairo_t *cr,
1488 const cairo_matrix_t *matrix)
1489 {
1490 cairo_status_t status;
1491
1492 if (unlikely (cr->status))
1493 return;
1494
1495 status = cr->backend->transform (cr, matrix);
1496 if (unlikely (status))
1497 _cairo_set_error (cr, status);
1498 }
1499 slim_hidden_def (cairo_transform);
1500
1501 /**
1502 * cairo_set_matrix:
1503 * @cr: a cairo context
1504 * @matrix: a transformation matrix from user space to device space
1505 *
1506 * Modifies the current transformation matrix (CTM) by setting it
1507 * equal to @matrix.
1508 *
1509 * Since: 1.0
1510 **/
1511 void
cairo_set_matrix(cairo_t * cr,const cairo_matrix_t * matrix)1512 cairo_set_matrix (cairo_t *cr,
1513 const cairo_matrix_t *matrix)
1514 {
1515 cairo_status_t status;
1516
1517 if (unlikely (cr->status))
1518 return;
1519
1520 status = cr->backend->set_matrix (cr, matrix);
1521 if (unlikely (status))
1522 _cairo_set_error (cr, status);
1523 }
1524 slim_hidden_def (cairo_set_matrix);
1525
1526 /**
1527 * cairo_identity_matrix:
1528 * @cr: a cairo context
1529 *
1530 * Resets the current transformation matrix (CTM) by setting it equal
1531 * to the identity matrix. That is, the user-space and device-space
1532 * axes will be aligned and one user-space unit will transform to one
1533 * device-space unit.
1534 *
1535 * Since: 1.0
1536 **/
1537 void
cairo_identity_matrix(cairo_t * cr)1538 cairo_identity_matrix (cairo_t *cr)
1539 {
1540 cairo_status_t status;
1541
1542 if (unlikely (cr->status))
1543 return;
1544
1545 status = cr->backend->set_identity_matrix (cr);
1546 if (unlikely (status))
1547 _cairo_set_error (cr, status);
1548 }
1549
1550 /**
1551 * cairo_user_to_device:
1552 * @cr: a cairo context
1553 * @x: X value of coordinate (in/out parameter)
1554 * @y: Y value of coordinate (in/out parameter)
1555 *
1556 * Transform a coordinate from user space to device space by
1557 * multiplying the given point by the current transformation matrix
1558 * (CTM).
1559 *
1560 * Since: 1.0
1561 **/
1562 void
cairo_user_to_device(cairo_t * cr,double * x,double * y)1563 cairo_user_to_device (cairo_t *cr, double *x, double *y)
1564 {
1565 if (unlikely (cr->status))
1566 return;
1567
1568 cr->backend->user_to_device (cr, x, y);
1569 }
1570 slim_hidden_def (cairo_user_to_device);
1571
1572 /**
1573 * cairo_user_to_device_distance:
1574 * @cr: a cairo context
1575 * @dx: X component of a distance vector (in/out parameter)
1576 * @dy: Y component of a distance vector (in/out parameter)
1577 *
1578 * Transform a distance vector from user space to device space. This
1579 * function is similar to cairo_user_to_device() except that the
1580 * translation components of the CTM will be ignored when transforming
1581 * (@dx,@dy).
1582 *
1583 * Since: 1.0
1584 **/
1585 void
cairo_user_to_device_distance(cairo_t * cr,double * dx,double * dy)1586 cairo_user_to_device_distance (cairo_t *cr, double *dx, double *dy)
1587 {
1588 if (unlikely (cr->status))
1589 return;
1590
1591 cr->backend->user_to_device_distance (cr, dx, dy);
1592 }
1593 slim_hidden_def (cairo_user_to_device_distance);
1594
1595 /**
1596 * cairo_device_to_user:
1597 * @cr: a cairo
1598 * @x: X value of coordinate (in/out parameter)
1599 * @y: Y value of coordinate (in/out parameter)
1600 *
1601 * Transform a coordinate from device space to user space by
1602 * multiplying the given point by the inverse of the current
1603 * transformation matrix (CTM).
1604 *
1605 * Since: 1.0
1606 **/
1607 void
cairo_device_to_user(cairo_t * cr,double * x,double * y)1608 cairo_device_to_user (cairo_t *cr, double *x, double *y)
1609 {
1610 if (unlikely (cr->status))
1611 return;
1612
1613 cr->backend->device_to_user (cr, x, y);
1614 }
1615 slim_hidden_def (cairo_device_to_user);
1616
1617 /**
1618 * cairo_device_to_user_distance:
1619 * @cr: a cairo context
1620 * @dx: X component of a distance vector (in/out parameter)
1621 * @dy: Y component of a distance vector (in/out parameter)
1622 *
1623 * Transform a distance vector from device space to user space. This
1624 * function is similar to cairo_device_to_user() except that the
1625 * translation components of the inverse CTM will be ignored when
1626 * transforming (@dx,@dy).
1627 *
1628 * Since: 1.0
1629 **/
1630 void
cairo_device_to_user_distance(cairo_t * cr,double * dx,double * dy)1631 cairo_device_to_user_distance (cairo_t *cr, double *dx, double *dy)
1632 {
1633 if (unlikely (cr->status))
1634 return;
1635
1636 cr->backend->device_to_user_distance (cr, dx, dy);
1637 }
1638
1639 /**
1640 * cairo_new_path:
1641 * @cr: a cairo context
1642 *
1643 * Clears the current path. After this call there will be no path and
1644 * no current point.
1645 *
1646 * Since: 1.0
1647 **/
1648 void
cairo_new_path(cairo_t * cr)1649 cairo_new_path (cairo_t *cr)
1650 {
1651 cairo_status_t status;
1652
1653 if (unlikely (cr->status))
1654 return;
1655
1656 status = cr->backend->new_path (cr);
1657 if (unlikely (status))
1658 _cairo_set_error (cr, status);
1659 }
1660 slim_hidden_def(cairo_new_path);
1661
1662 /**
1663 * cairo_new_sub_path:
1664 * @cr: a cairo context
1665 *
1666 * Begin a new sub-path. Note that the existing path is not
1667 * affected. After this call there will be no current point.
1668 *
1669 * In many cases, this call is not needed since new sub-paths are
1670 * frequently started with cairo_move_to().
1671 *
1672 * A call to cairo_new_sub_path() is particularly useful when
1673 * beginning a new sub-path with one of the cairo_arc() calls. This
1674 * makes things easier as it is no longer necessary to manually
1675 * compute the arc's initial coordinates for a call to
1676 * cairo_move_to().
1677 *
1678 * Since: 1.2
1679 **/
1680 void
cairo_new_sub_path(cairo_t * cr)1681 cairo_new_sub_path (cairo_t *cr)
1682 {
1683 cairo_status_t status;
1684
1685 if (unlikely (cr->status))
1686 return;
1687
1688 status = cr->backend->new_sub_path (cr);
1689 if (unlikely (status))
1690 _cairo_set_error (cr, status);
1691 }
1692
1693 /**
1694 * cairo_move_to:
1695 * @cr: a cairo context
1696 * @x: the X coordinate of the new position
1697 * @y: the Y coordinate of the new position
1698 *
1699 * Begin a new sub-path. After this call the current point will be (@x,
1700 * @y).
1701 *
1702 * Since: 1.0
1703 **/
1704 void
cairo_move_to(cairo_t * cr,double x,double y)1705 cairo_move_to (cairo_t *cr, double x, double y)
1706 {
1707 cairo_status_t status;
1708
1709 if (unlikely (cr->status))
1710 return;
1711
1712 status = cr->backend->move_to (cr, x, y);
1713 if (unlikely (status))
1714 _cairo_set_error (cr, status);
1715 }
1716 slim_hidden_def(cairo_move_to);
1717
1718
1719 /**
1720 * cairo_line_to:
1721 * @cr: a cairo context
1722 * @x: the X coordinate of the end of the new line
1723 * @y: the Y coordinate of the end of the new line
1724 *
1725 * Adds a line to the path from the current point to position (@x, @y)
1726 * in user-space coordinates. After this call the current point
1727 * will be (@x, @y).
1728 *
1729 * If there is no current point before the call to cairo_line_to()
1730 * this function will behave as cairo_move_to(@cr, @x, @y).
1731 *
1732 * Since: 1.0
1733 **/
1734 void
cairo_line_to(cairo_t * cr,double x,double y)1735 cairo_line_to (cairo_t *cr, double x, double y)
1736 {
1737 cairo_status_t status;
1738
1739 if (unlikely (cr->status))
1740 return;
1741
1742 status = cr->backend->line_to (cr, x, y);
1743 if (unlikely (status))
1744 _cairo_set_error (cr, status);
1745 }
1746 slim_hidden_def (cairo_line_to);
1747
1748 /**
1749 * cairo_curve_to:
1750 * @cr: a cairo context
1751 * @x1: the X coordinate of the first control point
1752 * @y1: the Y coordinate of the first control point
1753 * @x2: the X coordinate of the second control point
1754 * @y2: the Y coordinate of the second control point
1755 * @x3: the X coordinate of the end of the curve
1756 * @y3: the Y coordinate of the end of the curve
1757 *
1758 * Adds a cubic Bézier spline to the path from the current point to
1759 * position (@x3, @y3) in user-space coordinates, using (@x1, @y1) and
1760 * (@x2, @y2) as the control points. After this call the current point
1761 * will be (@x3, @y3).
1762 *
1763 * If there is no current point before the call to cairo_curve_to()
1764 * this function will behave as if preceded by a call to
1765 * cairo_move_to(@cr, @x1, @y1).
1766 *
1767 * Since: 1.0
1768 **/
1769 void
cairo_curve_to(cairo_t * cr,double x1,double y1,double x2,double y2,double x3,double y3)1770 cairo_curve_to (cairo_t *cr,
1771 double x1, double y1,
1772 double x2, double y2,
1773 double x3, double y3)
1774 {
1775 cairo_status_t status;
1776
1777 if (unlikely (cr->status))
1778 return;
1779
1780 status = cr->backend->curve_to (cr,
1781 x1, y1,
1782 x2, y2,
1783 x3, y3);
1784 if (unlikely (status))
1785 _cairo_set_error (cr, status);
1786 }
1787 slim_hidden_def (cairo_curve_to);
1788
1789 /**
1790 * cairo_arc:
1791 * @cr: a cairo context
1792 * @xc: X position of the center of the arc
1793 * @yc: Y position of the center of the arc
1794 * @radius: the radius of the arc
1795 * @angle1: the start angle, in radians
1796 * @angle2: the end angle, in radians
1797 *
1798 * Adds a circular arc of the given @radius to the current path. The
1799 * arc is centered at (@xc, @yc), begins at @angle1 and proceeds in
1800 * the direction of increasing angles to end at @angle2. If @angle2 is
1801 * less than @angle1 it will be progressively increased by
1802 * <literal>2*M_PI</literal> until it is greater than @angle1.
1803 *
1804 * If there is a current point, an initial line segment will be added
1805 * to the path to connect the current point to the beginning of the
1806 * arc. If this initial line is undesired, it can be avoided by
1807 * calling cairo_new_sub_path() before calling cairo_arc().
1808 *
1809 * Angles are measured in radians. An angle of 0.0 is in the direction
1810 * of the positive X axis (in user space). An angle of
1811 * <literal>M_PI/2.0</literal> radians (90 degrees) is in the
1812 * direction of the positive Y axis (in user space). Angles increase
1813 * in the direction from the positive X axis toward the positive Y
1814 * axis. So with the default transformation matrix, angles increase in
1815 * a clockwise direction.
1816 *
1817 * (To convert from degrees to radians, use <literal>degrees * (M_PI /
1818 * 180.)</literal>.)
1819 *
1820 * This function gives the arc in the direction of increasing angles;
1821 * see cairo_arc_negative() to get the arc in the direction of
1822 * decreasing angles.
1823 *
1824 * The arc is circular in user space. To achieve an elliptical arc,
1825 * you can scale the current transformation matrix by different
1826 * amounts in the X and Y directions. For example, to draw an ellipse
1827 * in the box given by @x, @y, @width, @height:
1828 *
1829 * <informalexample><programlisting>
1830 * cairo_save (cr);
1831 * cairo_translate (cr, x + width / 2., y + height / 2.);
1832 * cairo_scale (cr, width / 2., height / 2.);
1833 * cairo_arc (cr, 0., 0., 1., 0., 2 * M_PI);
1834 * cairo_restore (cr);
1835 * </programlisting></informalexample>
1836 *
1837 * Since: 1.0
1838 **/
1839 void
cairo_arc(cairo_t * cr,double xc,double yc,double radius,double angle1,double angle2)1840 cairo_arc (cairo_t *cr,
1841 double xc, double yc,
1842 double radius,
1843 double angle1, double angle2)
1844 {
1845 cairo_status_t status;
1846
1847 if (unlikely (cr->status))
1848 return;
1849
1850 if (angle2 < angle1) {
1851 /* increase angle2 by multiples of full circle until it
1852 * satisfies angle2 >= angle1 */
1853 angle2 = fmod (angle2 - angle1, 2 * M_PI);
1854 if (angle2 < 0)
1855 angle2 += 2 * M_PI;
1856 angle2 += angle1;
1857 }
1858
1859 status = cr->backend->arc (cr, xc, yc, radius, angle1, angle2, TRUE);
1860 if (unlikely (status))
1861 _cairo_set_error (cr, status);
1862 }
1863
1864 /**
1865 * cairo_arc_negative:
1866 * @cr: a cairo context
1867 * @xc: X position of the center of the arc
1868 * @yc: Y position of the center of the arc
1869 * @radius: the radius of the arc
1870 * @angle1: the start angle, in radians
1871 * @angle2: the end angle, in radians
1872 *
1873 * Adds a circular arc of the given @radius to the current path. The
1874 * arc is centered at (@xc, @yc), begins at @angle1 and proceeds in
1875 * the direction of decreasing angles to end at @angle2. If @angle2 is
1876 * greater than @angle1 it will be progressively decreased by
1877 * <literal>2*M_PI</literal> until it is less than @angle1.
1878 *
1879 * See cairo_arc() for more details. This function differs only in the
1880 * direction of the arc between the two angles.
1881 *
1882 * Since: 1.0
1883 **/
1884 void
cairo_arc_negative(cairo_t * cr,double xc,double yc,double radius,double angle1,double angle2)1885 cairo_arc_negative (cairo_t *cr,
1886 double xc, double yc,
1887 double radius,
1888 double angle1, double angle2)
1889 {
1890 cairo_status_t status;
1891
1892 if (unlikely (cr->status))
1893 return;
1894
1895 if (angle2 > angle1) {
1896 /* decrease angle2 by multiples of full circle until it
1897 * satisfies angle2 <= angle1 */
1898 angle2 = fmod (angle2 - angle1, 2 * M_PI);
1899 if (angle2 > 0)
1900 angle2 -= 2 * M_PI;
1901 angle2 += angle1;
1902 }
1903
1904 status = cr->backend->arc (cr, xc, yc, radius, angle1, angle2, FALSE);
1905 if (unlikely (status))
1906 _cairo_set_error (cr, status);
1907 }
1908
1909 /* XXX: NYI
1910 void
1911 cairo_arc_to (cairo_t *cr,
1912 double x1, double y1,
1913 double x2, double y2,
1914 double radius)
1915 {
1916 cairo_status_t status;
1917
1918 if (unlikely (cr->status))
1919 return;
1920
1921 status = cr->backend->arc_to (cr, x1, y1, x2, y2, radius);
1922 if (unlikely (status))
1923 _cairo_set_error (cr, status);
1924 }
1925
1926 void
1927 cairo_rel_arc_to (cairo_t *cr,
1928 double dx1, double dy1,
1929 double dx2, double dy2,
1930 double radius)
1931 {
1932 cairo_status_t status;
1933
1934 if (unlikely (cr->status))
1935 return;
1936
1937 status = cr->backend->rel_arc_to (cr, dx1, dy1, dx2, dy2, radius);
1938 if (unlikely (status))
1939 _cairo_set_error (cr, status);
1940 }
1941 */
1942
1943 /**
1944 * cairo_rel_move_to:
1945 * @cr: a cairo context
1946 * @dx: the X offset
1947 * @dy: the Y offset
1948 *
1949 * Begin a new sub-path. After this call the current point will offset
1950 * by (@x, @y).
1951 *
1952 * Given a current point of (x, y), cairo_rel_move_to(@cr, @dx, @dy)
1953 * is logically equivalent to cairo_move_to(@cr, x + @dx, y + @dy).
1954 *
1955 * It is an error to call this function with no current point. Doing
1956 * so will cause @cr to shutdown with a status of
1957 * %CAIRO_STATUS_NO_CURRENT_POINT.
1958 *
1959 * Since: 1.0
1960 **/
1961 void
cairo_rel_move_to(cairo_t * cr,double dx,double dy)1962 cairo_rel_move_to (cairo_t *cr, double dx, double dy)
1963 {
1964 cairo_status_t status;
1965
1966 if (unlikely (cr->status))
1967 return;
1968
1969 status = cr->backend->rel_move_to (cr, dx, dy);
1970 if (unlikely (status))
1971 _cairo_set_error (cr, status);
1972 }
1973
1974 /**
1975 * cairo_rel_line_to:
1976 * @cr: a cairo context
1977 * @dx: the X offset to the end of the new line
1978 * @dy: the Y offset to the end of the new line
1979 *
1980 * Relative-coordinate version of cairo_line_to(). Adds a line to the
1981 * path from the current point to a point that is offset from the
1982 * current point by (@dx, @dy) in user space. After this call the
1983 * current point will be offset by (@dx, @dy).
1984 *
1985 * Given a current point of (x, y), cairo_rel_line_to(@cr, @dx, @dy)
1986 * is logically equivalent to cairo_line_to(@cr, x + @dx, y + @dy).
1987 *
1988 * It is an error to call this function with no current point. Doing
1989 * so will cause @cr to shutdown with a status of
1990 * %CAIRO_STATUS_NO_CURRENT_POINT.
1991 *
1992 * Since: 1.0
1993 **/
1994 void
cairo_rel_line_to(cairo_t * cr,double dx,double dy)1995 cairo_rel_line_to (cairo_t *cr, double dx, double dy)
1996 {
1997 cairo_status_t status;
1998
1999 if (unlikely (cr->status))
2000 return;
2001
2002 status = cr->backend->rel_line_to (cr, dx, dy);
2003 if (unlikely (status))
2004 _cairo_set_error (cr, status);
2005 }
2006 slim_hidden_def(cairo_rel_line_to);
2007
2008 /**
2009 * cairo_rel_curve_to:
2010 * @cr: a cairo context
2011 * @dx1: the X offset to the first control point
2012 * @dy1: the Y offset to the first control point
2013 * @dx2: the X offset to the second control point
2014 * @dy2: the Y offset to the second control point
2015 * @dx3: the X offset to the end of the curve
2016 * @dy3: the Y offset to the end of the curve
2017 *
2018 * Relative-coordinate version of cairo_curve_to(). All offsets are
2019 * relative to the current point. Adds a cubic Bézier spline to the
2020 * path from the current point to a point offset from the current
2021 * point by (@dx3, @dy3), using points offset by (@dx1, @dy1) and
2022 * (@dx2, @dy2) as the control points. After this call the current
2023 * point will be offset by (@dx3, @dy3).
2024 *
2025 * Given a current point of (x, y), cairo_rel_curve_to(@cr, @dx1,
2026 * @dy1, @dx2, @dy2, @dx3, @dy3) is logically equivalent to
2027 * cairo_curve_to(@cr, x+@dx1, y+@dy1, x+@dx2, y+@dy2, x+@dx3, y+@dy3).
2028 *
2029 * It is an error to call this function with no current point. Doing
2030 * so will cause @cr to shutdown with a status of
2031 * %CAIRO_STATUS_NO_CURRENT_POINT.
2032 *
2033 * Since: 1.0
2034 **/
2035 void
cairo_rel_curve_to(cairo_t * cr,double dx1,double dy1,double dx2,double dy2,double dx3,double dy3)2036 cairo_rel_curve_to (cairo_t *cr,
2037 double dx1, double dy1,
2038 double dx2, double dy2,
2039 double dx3, double dy3)
2040 {
2041 cairo_status_t status;
2042
2043 if (unlikely (cr->status))
2044 return;
2045
2046 status = cr->backend->rel_curve_to (cr,
2047 dx1, dy1,
2048 dx2, dy2,
2049 dx3, dy3);
2050 if (unlikely (status))
2051 _cairo_set_error (cr, status);
2052 }
2053
2054 /**
2055 * cairo_rectangle:
2056 * @cr: a cairo context
2057 * @x: the X coordinate of the top left corner of the rectangle
2058 * @y: the Y coordinate to the top left corner of the rectangle
2059 * @width: the width of the rectangle
2060 * @height: the height of the rectangle
2061 *
2062 * Adds a closed sub-path rectangle of the given size to the current
2063 * path at position (@x, @y) in user-space coordinates.
2064 *
2065 * This function is logically equivalent to:
2066 * <informalexample><programlisting>
2067 * cairo_move_to (cr, x, y);
2068 * cairo_rel_line_to (cr, width, 0);
2069 * cairo_rel_line_to (cr, 0, height);
2070 * cairo_rel_line_to (cr, -width, 0);
2071 * cairo_close_path (cr);
2072 * </programlisting></informalexample>
2073 *
2074 * Since: 1.0
2075 **/
2076 void
cairo_rectangle(cairo_t * cr,double x,double y,double width,double height)2077 cairo_rectangle (cairo_t *cr,
2078 double x, double y,
2079 double width, double height)
2080 {
2081 cairo_status_t status;
2082
2083 if (unlikely (cr->status))
2084 return;
2085
2086 status = cr->backend->rectangle (cr, x, y, width, height);
2087 if (unlikely (status))
2088 _cairo_set_error (cr, status);
2089 }
2090
2091 #if 0
2092 /* XXX: NYI */
2093 void
2094 cairo_stroke_to_path (cairo_t *cr)
2095 {
2096 cairo_status_t status;
2097
2098 if (unlikely (cr->status))
2099 return;
2100
2101 /* The code in _cairo_recording_surface_get_path has a poorman's stroke_to_path */
2102
2103 status = _cairo_gstate_stroke_path (cr->gstate);
2104 if (unlikely (status))
2105 _cairo_set_error (cr, status);
2106 }
2107 #endif
2108
2109 /**
2110 * cairo_close_path:
2111 * @cr: a cairo context
2112 *
2113 * Adds a line segment to the path from the current point to the
2114 * beginning of the current sub-path, (the most recent point passed to
2115 * cairo_move_to()), and closes this sub-path. After this call the
2116 * current point will be at the joined endpoint of the sub-path.
2117 *
2118 * The behavior of cairo_close_path() is distinct from simply calling
2119 * cairo_line_to() with the equivalent coordinate in the case of
2120 * stroking. When a closed sub-path is stroked, there are no caps on
2121 * the ends of the sub-path. Instead, there is a line join connecting
2122 * the final and initial segments of the sub-path.
2123 *
2124 * If there is no current point before the call to cairo_close_path(),
2125 * this function will have no effect.
2126 *
2127 * Note: As of cairo version 1.2.4 any call to cairo_close_path() will
2128 * place an explicit MOVE_TO element into the path immediately after
2129 * the CLOSE_PATH element, (which can be seen in cairo_copy_path() for
2130 * example). This can simplify path processing in some cases as it may
2131 * not be necessary to save the "last move_to point" during processing
2132 * as the MOVE_TO immediately after the CLOSE_PATH will provide that
2133 * point.
2134 *
2135 * Since: 1.0
2136 **/
2137 void
cairo_close_path(cairo_t * cr)2138 cairo_close_path (cairo_t *cr)
2139 {
2140 cairo_status_t status;
2141
2142 if (unlikely (cr->status))
2143 return;
2144
2145 status = cr->backend->close_path (cr);
2146 if (unlikely (status))
2147 _cairo_set_error (cr, status);
2148 }
2149 slim_hidden_def(cairo_close_path);
2150
2151 /**
2152 * cairo_path_extents:
2153 * @cr: a cairo context
2154 * @x1: left of the resulting extents
2155 * @y1: top of the resulting extents
2156 * @x2: right of the resulting extents
2157 * @y2: bottom of the resulting extents
2158 *
2159 * Computes a bounding box in user-space coordinates covering the
2160 * points on the current path. If the current path is empty, returns
2161 * an empty rectangle ((0,0), (0,0)). Stroke parameters, fill rule,
2162 * surface dimensions and clipping are not taken into account.
2163 *
2164 * Contrast with cairo_fill_extents() and cairo_stroke_extents() which
2165 * return the extents of only the area that would be "inked" by
2166 * the corresponding drawing operations.
2167 *
2168 * The result of cairo_path_extents() is defined as equivalent to the
2169 * limit of cairo_stroke_extents() with %CAIRO_LINE_CAP_ROUND as the
2170 * line width approaches 0.0, (but never reaching the empty-rectangle
2171 * returned by cairo_stroke_extents() for a line width of 0.0).
2172 *
2173 * Specifically, this means that zero-area sub-paths such as
2174 * cairo_move_to();cairo_line_to() segments, (even degenerate cases
2175 * where the coordinates to both calls are identical), will be
2176 * considered as contributing to the extents. However, a lone
2177 * cairo_move_to() will not contribute to the results of
2178 * cairo_path_extents().
2179 *
2180 * Since: 1.6
2181 **/
2182 void
cairo_path_extents(cairo_t * cr,double * x1,double * y1,double * x2,double * y2)2183 cairo_path_extents (cairo_t *cr,
2184 double *x1, double *y1, double *x2, double *y2)
2185 {
2186 if (unlikely (cr->status)) {
2187 if (x1)
2188 *x1 = 0.0;
2189 if (y1)
2190 *y1 = 0.0;
2191 if (x2)
2192 *x2 = 0.0;
2193 if (y2)
2194 *y2 = 0.0;
2195
2196 return;
2197 }
2198
2199 cr->backend->path_extents (cr, x1, y1, x2, y2);
2200 }
2201
2202 /**
2203 * cairo_paint:
2204 * @cr: a cairo context
2205 *
2206 * A drawing operator that paints the current source everywhere within
2207 * the current clip region.
2208 *
2209 * Since: 1.0
2210 **/
2211 void
cairo_paint(cairo_t * cr)2212 cairo_paint (cairo_t *cr)
2213 {
2214 cairo_status_t status;
2215
2216 if (unlikely (cr->status))
2217 return;
2218
2219 status = cr->backend->paint (cr);
2220 if (unlikely (status))
2221 _cairo_set_error (cr, status);
2222 }
2223 slim_hidden_def (cairo_paint);
2224
2225 /**
2226 * cairo_paint_with_alpha:
2227 * @cr: a cairo context
2228 * @alpha: alpha value, between 0 (transparent) and 1 (opaque)
2229 *
2230 * A drawing operator that paints the current source everywhere within
2231 * the current clip region using a mask of constant alpha value
2232 * @alpha. The effect is similar to cairo_paint(), but the drawing
2233 * is faded out using the alpha value.
2234 *
2235 * Since: 1.0
2236 **/
2237 void
cairo_paint_with_alpha(cairo_t * cr,double alpha)2238 cairo_paint_with_alpha (cairo_t *cr,
2239 double alpha)
2240 {
2241 cairo_status_t status;
2242
2243 if (unlikely (cr->status))
2244 return;
2245
2246 status = cr->backend->paint_with_alpha (cr, alpha);
2247 if (unlikely (status))
2248 _cairo_set_error (cr, status);
2249 }
2250
2251 /**
2252 * cairo_mask:
2253 * @cr: a cairo context
2254 * @pattern: a #cairo_pattern_t
2255 *
2256 * A drawing operator that paints the current source
2257 * using the alpha channel of @pattern as a mask. (Opaque
2258 * areas of @pattern are painted with the source, transparent
2259 * areas are not painted.)
2260 *
2261 * Since: 1.0
2262 **/
2263 void
cairo_mask(cairo_t * cr,cairo_pattern_t * pattern)2264 cairo_mask (cairo_t *cr,
2265 cairo_pattern_t *pattern)
2266 {
2267 cairo_status_t status;
2268
2269 if (unlikely (cr->status))
2270 return;
2271
2272 if (unlikely (pattern == NULL)) {
2273 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
2274 return;
2275 }
2276
2277 if (unlikely (pattern->status)) {
2278 _cairo_set_error (cr, pattern->status);
2279 return;
2280 }
2281
2282 status = cr->backend->mask (cr, pattern);
2283 if (unlikely (status))
2284 _cairo_set_error (cr, status);
2285 }
2286 slim_hidden_def (cairo_mask);
2287
2288 /**
2289 * cairo_mask_surface:
2290 * @cr: a cairo context
2291 * @surface: a #cairo_surface_t
2292 * @surface_x: X coordinate at which to place the origin of @surface
2293 * @surface_y: Y coordinate at which to place the origin of @surface
2294 *
2295 * A drawing operator that paints the current source
2296 * using the alpha channel of @surface as a mask. (Opaque
2297 * areas of @surface are painted with the source, transparent
2298 * areas are not painted.)
2299 *
2300 * Since: 1.0
2301 **/
2302 void
cairo_mask_surface(cairo_t * cr,cairo_surface_t * surface,double surface_x,double surface_y)2303 cairo_mask_surface (cairo_t *cr,
2304 cairo_surface_t *surface,
2305 double surface_x,
2306 double surface_y)
2307 {
2308 cairo_pattern_t *pattern;
2309 cairo_matrix_t matrix;
2310
2311 if (unlikely (cr->status))
2312 return;
2313
2314 pattern = cairo_pattern_create_for_surface (surface);
2315
2316 cairo_matrix_init_translate (&matrix, - surface_x, - surface_y);
2317 cairo_pattern_set_matrix (pattern, &matrix);
2318
2319 cairo_mask (cr, pattern);
2320
2321 cairo_pattern_destroy (pattern);
2322 }
2323
2324 /**
2325 * cairo_stroke:
2326 * @cr: a cairo context
2327 *
2328 * A drawing operator that strokes the current path according to the
2329 * current line width, line join, line cap, and dash settings. After
2330 * cairo_stroke(), the current path will be cleared from the cairo
2331 * context. See cairo_set_line_width(), cairo_set_line_join(),
2332 * cairo_set_line_cap(), cairo_set_dash(), and
2333 * cairo_stroke_preserve().
2334 *
2335 * Note: Degenerate segments and sub-paths are treated specially and
2336 * provide a useful result. These can result in two different
2337 * situations:
2338 *
2339 * 1. Zero-length "on" segments set in cairo_set_dash(). If the cap
2340 * style is %CAIRO_LINE_CAP_ROUND or %CAIRO_LINE_CAP_SQUARE then these
2341 * segments will be drawn as circular dots or squares respectively. In
2342 * the case of %CAIRO_LINE_CAP_SQUARE, the orientation of the squares
2343 * is determined by the direction of the underlying path.
2344 *
2345 * 2. A sub-path created by cairo_move_to() followed by either a
2346 * cairo_close_path() or one or more calls to cairo_line_to() to the
2347 * same coordinate as the cairo_move_to(). If the cap style is
2348 * %CAIRO_LINE_CAP_ROUND then these sub-paths will be drawn as circular
2349 * dots. Note that in the case of %CAIRO_LINE_CAP_SQUARE a degenerate
2350 * sub-path will not be drawn at all, (since the correct orientation
2351 * is indeterminate).
2352 *
2353 * In no case will a cap style of %CAIRO_LINE_CAP_BUTT cause anything
2354 * to be drawn in the case of either degenerate segments or sub-paths.
2355 *
2356 * Since: 1.0
2357 **/
2358 void
cairo_stroke(cairo_t * cr)2359 cairo_stroke (cairo_t *cr)
2360 {
2361 cairo_status_t status;
2362
2363 if (unlikely (cr->status))
2364 return;
2365
2366 status = cr->backend->stroke (cr);
2367 if (unlikely (status))
2368 _cairo_set_error (cr, status);
2369 }
2370 slim_hidden_def(cairo_stroke);
2371
2372 /**
2373 * cairo_stroke_preserve:
2374 * @cr: a cairo context
2375 *
2376 * A drawing operator that strokes the current path according to the
2377 * current line width, line join, line cap, and dash settings. Unlike
2378 * cairo_stroke(), cairo_stroke_preserve() preserves the path within the
2379 * cairo context.
2380 *
2381 * See cairo_set_line_width(), cairo_set_line_join(),
2382 * cairo_set_line_cap(), cairo_set_dash(), and
2383 * cairo_stroke_preserve().
2384 *
2385 * Since: 1.0
2386 **/
2387 void
cairo_stroke_preserve(cairo_t * cr)2388 cairo_stroke_preserve (cairo_t *cr)
2389 {
2390 cairo_status_t status;
2391
2392 if (unlikely (cr->status))
2393 return;
2394
2395 status = cr->backend->stroke_preserve (cr);
2396 if (unlikely (status))
2397 _cairo_set_error (cr, status);
2398 }
2399 slim_hidden_def(cairo_stroke_preserve);
2400
2401 /**
2402 * cairo_fill:
2403 * @cr: a cairo context
2404 *
2405 * A drawing operator that fills the current path according to the
2406 * current fill rule, (each sub-path is implicitly closed before being
2407 * filled). After cairo_fill(), the current path will be cleared from
2408 * the cairo context. See cairo_set_fill_rule() and
2409 * cairo_fill_preserve().
2410 *
2411 * Since: 1.0
2412 **/
2413 void
cairo_fill(cairo_t * cr)2414 cairo_fill (cairo_t *cr)
2415 {
2416 cairo_status_t status;
2417
2418 if (unlikely (cr->status))
2419 return;
2420
2421 status = cr->backend->fill (cr);
2422 if (unlikely (status))
2423 _cairo_set_error (cr, status);
2424 }
2425
2426 /**
2427 * cairo_fill_preserve:
2428 * @cr: a cairo context
2429 *
2430 * A drawing operator that fills the current path according to the
2431 * current fill rule, (each sub-path is implicitly closed before being
2432 * filled). Unlike cairo_fill(), cairo_fill_preserve() preserves the
2433 * path within the cairo context.
2434 *
2435 * See cairo_set_fill_rule() and cairo_fill().
2436 *
2437 * Since: 1.0
2438 **/
2439 void
cairo_fill_preserve(cairo_t * cr)2440 cairo_fill_preserve (cairo_t *cr)
2441 {
2442 cairo_status_t status;
2443
2444 if (unlikely (cr->status))
2445 return;
2446
2447 status = cr->backend->fill_preserve (cr);
2448 if (unlikely (status))
2449 _cairo_set_error (cr, status);
2450 }
2451 slim_hidden_def(cairo_fill_preserve);
2452
2453 /**
2454 * cairo_copy_page:
2455 * @cr: a cairo context
2456 *
2457 * Emits the current page for backends that support multiple pages, but
2458 * doesn't clear it, so, the contents of the current page will be retained
2459 * for the next page too. Use cairo_show_page() if you want to get an
2460 * empty page after the emission.
2461 *
2462 * This is a convenience function that simply calls
2463 * cairo_surface_copy_page() on @cr's target.
2464 *
2465 * Since: 1.0
2466 **/
2467 void
cairo_copy_page(cairo_t * cr)2468 cairo_copy_page (cairo_t *cr)
2469 {
2470 cairo_status_t status;
2471
2472 if (unlikely (cr->status))
2473 return;
2474
2475 status = cr->backend->copy_page (cr);
2476 if (unlikely (status))
2477 _cairo_set_error (cr, status);
2478 }
2479
2480 /**
2481 * cairo_show_page:
2482 * @cr: a cairo context
2483 *
2484 * Emits and clears the current page for backends that support multiple
2485 * pages. Use cairo_copy_page() if you don't want to clear the page.
2486 *
2487 * This is a convenience function that simply calls
2488 * cairo_surface_show_page() on @cr's target.
2489 *
2490 * Since: 1.0
2491 **/
2492 void
cairo_show_page(cairo_t * cr)2493 cairo_show_page (cairo_t *cr)
2494 {
2495 cairo_status_t status;
2496
2497 if (unlikely (cr->status))
2498 return;
2499
2500 status = cr->backend->show_page (cr);
2501 if (unlikely (status))
2502 _cairo_set_error (cr, status);
2503 }
2504
2505 /**
2506 * cairo_in_stroke:
2507 * @cr: a cairo context
2508 * @x: X coordinate of the point to test
2509 * @y: Y coordinate of the point to test
2510 *
2511 * Tests whether the given point is inside the area that would be
2512 * affected by a cairo_stroke() operation given the current path and
2513 * stroking parameters. Surface dimensions and clipping are not taken
2514 * into account.
2515 *
2516 * See cairo_stroke(), cairo_set_line_width(), cairo_set_line_join(),
2517 * cairo_set_line_cap(), cairo_set_dash(), and
2518 * cairo_stroke_preserve().
2519 *
2520 * Return value: A non-zero value if the point is inside, or zero if
2521 * outside.
2522 *
2523 * Since: 1.0
2524 **/
2525 cairo_bool_t
cairo_in_stroke(cairo_t * cr,double x,double y)2526 cairo_in_stroke (cairo_t *cr, double x, double y)
2527 {
2528 cairo_status_t status;
2529 cairo_bool_t inside = FALSE;
2530
2531 if (unlikely (cr->status))
2532 return FALSE;
2533
2534 status = cr->backend->in_stroke (cr, x, y, &inside);
2535 if (unlikely (status))
2536 _cairo_set_error (cr, status);
2537
2538 return inside;
2539 }
2540
2541 /**
2542 * cairo_in_fill:
2543 * @cr: a cairo context
2544 * @x: X coordinate of the point to test
2545 * @y: Y coordinate of the point to test
2546 *
2547 * Tests whether the given point is inside the area that would be
2548 * affected by a cairo_fill() operation given the current path and
2549 * filling parameters. Surface dimensions and clipping are not taken
2550 * into account.
2551 *
2552 * See cairo_fill(), cairo_set_fill_rule() and cairo_fill_preserve().
2553 *
2554 * Return value: A non-zero value if the point is inside, or zero if
2555 * outside.
2556 *
2557 * Since: 1.0
2558 **/
2559 cairo_bool_t
cairo_in_fill(cairo_t * cr,double x,double y)2560 cairo_in_fill (cairo_t *cr, double x, double y)
2561 {
2562 cairo_status_t status;
2563 cairo_bool_t inside = FALSE;
2564
2565 if (unlikely (cr->status))
2566 return FALSE;
2567
2568 status = cr->backend->in_fill (cr, x, y, &inside);
2569 if (unlikely (status))
2570 _cairo_set_error (cr, status);
2571
2572 return inside;
2573 }
2574
2575 /**
2576 * cairo_stroke_extents:
2577 * @cr: a cairo context
2578 * @x1: left of the resulting extents
2579 * @y1: top of the resulting extents
2580 * @x2: right of the resulting extents
2581 * @y2: bottom of the resulting extents
2582 *
2583 * Computes a bounding box in user coordinates covering the area that
2584 * would be affected, (the "inked" area), by a cairo_stroke()
2585 * operation given the current path and stroke parameters.
2586 * If the current path is empty, returns an empty rectangle ((0,0), (0,0)).
2587 * Surface dimensions and clipping are not taken into account.
2588 *
2589 * Note that if the line width is set to exactly zero, then
2590 * cairo_stroke_extents() will return an empty rectangle. Contrast with
2591 * cairo_path_extents() which can be used to compute the non-empty
2592 * bounds as the line width approaches zero.
2593 *
2594 * Note that cairo_stroke_extents() must necessarily do more work to
2595 * compute the precise inked areas in light of the stroke parameters,
2596 * so cairo_path_extents() may be more desirable for sake of
2597 * performance if non-inked path extents are desired.
2598 *
2599 * See cairo_stroke(), cairo_set_line_width(), cairo_set_line_join(),
2600 * cairo_set_line_cap(), cairo_set_dash(), and
2601 * cairo_stroke_preserve().
2602 *
2603 * Since: 1.0
2604 **/
2605 void
cairo_stroke_extents(cairo_t * cr,double * x1,double * y1,double * x2,double * y2)2606 cairo_stroke_extents (cairo_t *cr,
2607 double *x1, double *y1, double *x2, double *y2)
2608 {
2609 cairo_status_t status;
2610
2611 if (unlikely (cr->status)) {
2612 if (x1)
2613 *x1 = 0.0;
2614 if (y1)
2615 *y1 = 0.0;
2616 if (x2)
2617 *x2 = 0.0;
2618 if (y2)
2619 *y2 = 0.0;
2620
2621 return;
2622 }
2623
2624 status = cr->backend->stroke_extents (cr, x1, y1, x2, y2);
2625 if (unlikely (status))
2626 _cairo_set_error (cr, status);
2627 }
2628
2629 /**
2630 * cairo_fill_extents:
2631 * @cr: a cairo context
2632 * @x1: left of the resulting extents
2633 * @y1: top of the resulting extents
2634 * @x2: right of the resulting extents
2635 * @y2: bottom of the resulting extents
2636 *
2637 * Computes a bounding box in user coordinates covering the area that
2638 * would be affected, (the "inked" area), by a cairo_fill() operation
2639 * given the current path and fill parameters. If the current path is
2640 * empty, returns an empty rectangle ((0,0), (0,0)). Surface
2641 * dimensions and clipping are not taken into account.
2642 *
2643 * Contrast with cairo_path_extents(), which is similar, but returns
2644 * non-zero extents for some paths with no inked area, (such as a
2645 * simple line segment).
2646 *
2647 * Note that cairo_fill_extents() must necessarily do more work to
2648 * compute the precise inked areas in light of the fill rule, so
2649 * cairo_path_extents() may be more desirable for sake of performance
2650 * if the non-inked path extents are desired.
2651 *
2652 * See cairo_fill(), cairo_set_fill_rule() and cairo_fill_preserve().
2653 *
2654 * Since: 1.0
2655 **/
2656 void
cairo_fill_extents(cairo_t * cr,double * x1,double * y1,double * x2,double * y2)2657 cairo_fill_extents (cairo_t *cr,
2658 double *x1, double *y1, double *x2, double *y2)
2659 {
2660 cairo_status_t status;
2661
2662 if (unlikely (cr->status)) {
2663 if (x1)
2664 *x1 = 0.0;
2665 if (y1)
2666 *y1 = 0.0;
2667 if (x2)
2668 *x2 = 0.0;
2669 if (y2)
2670 *y2 = 0.0;
2671
2672 return;
2673 }
2674
2675 status = cr->backend->fill_extents (cr, x1, y1, x2, y2);
2676 if (unlikely (status))
2677 _cairo_set_error (cr, status);
2678 }
2679
2680 /**
2681 * cairo_clip:
2682 * @cr: a cairo context
2683 *
2684 * Establishes a new clip region by intersecting the current clip
2685 * region with the current path as it would be filled by cairo_fill()
2686 * and according to the current fill rule (see cairo_set_fill_rule()).
2687 *
2688 * After cairo_clip(), the current path will be cleared from the cairo
2689 * context.
2690 *
2691 * The current clip region affects all drawing operations by
2692 * effectively masking out any changes to the surface that are outside
2693 * the current clip region.
2694 *
2695 * Calling cairo_clip() can only make the clip region smaller, never
2696 * larger. But the current clip is part of the graphics state, so a
2697 * temporary restriction of the clip region can be achieved by
2698 * calling cairo_clip() within a cairo_save()/cairo_restore()
2699 * pair. The only other means of increasing the size of the clip
2700 * region is cairo_reset_clip().
2701 *
2702 * Since: 1.0
2703 **/
2704 void
cairo_clip(cairo_t * cr)2705 cairo_clip (cairo_t *cr)
2706 {
2707 cairo_status_t status;
2708
2709 if (unlikely (cr->status))
2710 return;
2711
2712 status = cr->backend->clip (cr);
2713 if (unlikely (status))
2714 _cairo_set_error (cr, status);
2715 }
2716
2717 /**
2718 * cairo_clip_preserve:
2719 * @cr: a cairo context
2720 *
2721 * Establishes a new clip region by intersecting the current clip
2722 * region with the current path as it would be filled by cairo_fill()
2723 * and according to the current fill rule (see cairo_set_fill_rule()).
2724 *
2725 * Unlike cairo_clip(), cairo_clip_preserve() preserves the path within
2726 * the cairo context.
2727 *
2728 * The current clip region affects all drawing operations by
2729 * effectively masking out any changes to the surface that are outside
2730 * the current clip region.
2731 *
2732 * Calling cairo_clip_preserve() can only make the clip region smaller, never
2733 * larger. But the current clip is part of the graphics state, so a
2734 * temporary restriction of the clip region can be achieved by
2735 * calling cairo_clip_preserve() within a cairo_save()/cairo_restore()
2736 * pair. The only other means of increasing the size of the clip
2737 * region is cairo_reset_clip().
2738 *
2739 * Since: 1.0
2740 **/
2741 void
cairo_clip_preserve(cairo_t * cr)2742 cairo_clip_preserve (cairo_t *cr)
2743 {
2744 cairo_status_t status;
2745
2746 if (unlikely (cr->status))
2747 return;
2748
2749 status = cr->backend->clip_preserve (cr);
2750 if (unlikely (status))
2751 _cairo_set_error (cr, status);
2752 }
2753 slim_hidden_def(cairo_clip_preserve);
2754
2755 /**
2756 * cairo_reset_clip:
2757 * @cr: a cairo context
2758 *
2759 * Reset the current clip region to its original, unrestricted
2760 * state. That is, set the clip region to an infinitely large shape
2761 * containing the target surface. Equivalently, if infinity is too
2762 * hard to grasp, one can imagine the clip region being reset to the
2763 * exact bounds of the target surface.
2764 *
2765 * Note that code meant to be reusable should not call
2766 * cairo_reset_clip() as it will cause results unexpected by
2767 * higher-level code which calls cairo_clip(). Consider using
2768 * cairo_save() and cairo_restore() around cairo_clip() as a more
2769 * robust means of temporarily restricting the clip region.
2770 *
2771 * Since: 1.0
2772 **/
2773 void
cairo_reset_clip(cairo_t * cr)2774 cairo_reset_clip (cairo_t *cr)
2775 {
2776 cairo_status_t status;
2777
2778 if (unlikely (cr->status))
2779 return;
2780
2781 status = cr->backend->reset_clip (cr);
2782 if (unlikely (status))
2783 _cairo_set_error (cr, status);
2784 }
2785
2786 /**
2787 * cairo_clip_extents:
2788 * @cr: a cairo context
2789 * @x1: left of the resulting extents
2790 * @y1: top of the resulting extents
2791 * @x2: right of the resulting extents
2792 * @y2: bottom of the resulting extents
2793 *
2794 * Computes a bounding box in user coordinates covering the area inside the
2795 * current clip.
2796 *
2797 * Since: 1.4
2798 **/
2799 void
cairo_clip_extents(cairo_t * cr,double * x1,double * y1,double * x2,double * y2)2800 cairo_clip_extents (cairo_t *cr,
2801 double *x1, double *y1,
2802 double *x2, double *y2)
2803 {
2804 cairo_status_t status;
2805
2806 if (x1)
2807 *x1 = 0.0;
2808 if (y1)
2809 *y1 = 0.0;
2810 if (x2)
2811 *x2 = 0.0;
2812 if (y2)
2813 *y2 = 0.0;
2814
2815 if (unlikely (cr->status))
2816 return;
2817
2818 status = cr->backend->clip_extents (cr, x1, y1, x2, y2);
2819 if (unlikely (status))
2820 _cairo_set_error (cr, status);
2821 }
2822
2823 /**
2824 * cairo_in_clip:
2825 * @cr: a cairo context
2826 * @x: X coordinate of the point to test
2827 * @y: Y coordinate of the point to test
2828 *
2829 * Tests whether the given point is inside the area that would be
2830 * visible through the current clip, i.e. the area that would be filled by
2831 * a cairo_paint() operation.
2832 *
2833 * See cairo_clip(), and cairo_clip_preserve().
2834 *
2835 * Return value: A non-zero value if the point is inside, or zero if
2836 * outside.
2837 *
2838 * Since: 1.10
2839 **/
2840 cairo_bool_t
cairo_in_clip(cairo_t * cr,double x,double y)2841 cairo_in_clip (cairo_t *cr, double x, double y)
2842 {
2843 cairo_status_t status;
2844 cairo_bool_t inside = FALSE;
2845
2846 if (unlikely (cr->status))
2847 return FALSE;
2848
2849 status = cr->backend->in_clip (cr, x, y, &inside);
2850 if (unlikely (status))
2851 _cairo_set_error (cr, status);
2852
2853 return inside;
2854 }
2855
2856 /**
2857 * cairo_copy_clip_rectangle_list:
2858 * @cr: a cairo context
2859 *
2860 * Gets the current clip region as a list of rectangles in user coordinates.
2861 * Never returns %NULL.
2862 *
2863 * The status in the list may be %CAIRO_STATUS_CLIP_NOT_REPRESENTABLE to
2864 * indicate that the clip region cannot be represented as a list of
2865 * user-space rectangles. The status may have other values to indicate
2866 * other errors.
2867 *
2868 * Returns: the current clip region as a list of rectangles in user coordinates,
2869 * which should be destroyed using cairo_rectangle_list_destroy().
2870 *
2871 * Since: 1.4
2872 **/
2873 cairo_rectangle_list_t *
cairo_copy_clip_rectangle_list(cairo_t * cr)2874 cairo_copy_clip_rectangle_list (cairo_t *cr)
2875 {
2876 if (unlikely (cr->status))
2877 return _cairo_rectangle_list_create_in_error (cr->status);
2878
2879 return cr->backend->clip_copy_rectangle_list (cr);
2880 }
2881
2882 /**
2883 * CAIRO_TAG_DEST:
2884 *
2885 * Create a destination for a hyperlink. Destination tag attributes
2886 * are detailed at [Destinations][dests].
2887 *
2888 * Since: 1.16
2889 **/
2890
2891 /**
2892 * CAIRO_TAG_LINK:
2893 *
2894 * Create hyperlink. Link tag attributes are detailed at
2895 * [Links][links].
2896 *
2897 * Since: 1.16
2898 **/
2899
2900 /**
2901 * cairo_tag_begin:
2902 * @cr: a cairo context
2903 * @tag_name: tag name
2904 * @attributes: tag attributes
2905 *
2906 * Marks the beginning of the @tag_name structure. Call
2907 * cairo_tag_end() with the same @tag_name to mark the end of the
2908 * structure.
2909 *
2910 * The attributes string is of the form "key1=value2 key2=value2 ...".
2911 * Values may be boolean (true/false or 1/0), integer, float, string,
2912 * or an array.
2913 *
2914 * String values are enclosed in single quotes
2915 * ('). Single quotes and backslashes inside the string should be
2916 * escaped with a backslash.
2917 *
2918 * Boolean values may be set to true by only
2919 * specifying the key. eg the attribute string "key" is the equivalent
2920 * to "key=true".
2921 *
2922 * Arrays are enclosed in '[]'. eg "rect=[1.2 4.3 2.0 3.0]".
2923 *
2924 * If no attributes are required, @attributes can be an empty string or NULL.
2925 *
2926 * See [Tags and Links Description][cairo-Tags-and-Links.description]
2927 * for the list of tags and attributes.
2928 *
2929 * Invalid nesting of tags or invalid attributes will cause @cr to
2930 * shutdown with a status of %CAIRO_STATUS_TAG_ERROR.
2931 *
2932 * See cairo_tag_end().
2933 *
2934 * Since: 1.16
2935 **/
2936 void
cairo_tag_begin(cairo_t * cr,const char * tag_name,const char * attributes)2937 cairo_tag_begin (cairo_t *cr, const char *tag_name, const char *attributes)
2938 {
2939 cairo_status_t status;
2940
2941 if (unlikely (cr->status))
2942 return;
2943
2944 status = cr->backend->tag_begin (cr, tag_name, attributes);
2945 if (unlikely (status))
2946 _cairo_set_error (cr, status);
2947 }
2948
2949 /**
2950 * cairo_tag_end:
2951 * @cr: a cairo context
2952 * @tag_name: tag name
2953 *
2954 * Marks the end of the @tag_name structure.
2955 *
2956 * Invalid nesting of tags will cause @cr to shutdown with a status of
2957 * %CAIRO_STATUS_TAG_ERROR.
2958 *
2959 * See cairo_tag_begin().
2960 *
2961 * Since: 1.16
2962 **/
2963 cairo_public void
cairo_tag_end(cairo_t * cr,const char * tag_name)2964 cairo_tag_end (cairo_t *cr, const char *tag_name)
2965 {
2966 cairo_status_t status;
2967
2968 if (unlikely (cr->status))
2969 return;
2970
2971 status = cr->backend->tag_end (cr, tag_name);
2972 if (unlikely (status))
2973 _cairo_set_error (cr, status);
2974 }
2975
2976 /**
2977 * cairo_select_font_face:
2978 * @cr: a #cairo_t
2979 * @family: a font family name, encoded in UTF-8
2980 * @slant: the slant for the font
2981 * @weight: the weight for the font
2982 *
2983 * Note: The cairo_select_font_face() function call is part of what
2984 * the cairo designers call the "toy" text API. It is convenient for
2985 * short demos and simple programs, but it is not expected to be
2986 * adequate for serious text-using applications.
2987 *
2988 * Selects a family and style of font from a simplified description as
2989 * a family name, slant and weight. Cairo provides no operation to
2990 * list available family names on the system (this is a "toy",
2991 * remember), but the standard CSS2 generic family names, ("serif",
2992 * "sans-serif", "cursive", "fantasy", "monospace"), are likely to
2993 * work as expected.
2994 *
2995 * If @family starts with the string "@cairo:", or if no native font
2996 * backends are compiled in, cairo will use an internal font family.
2997 * The internal font family recognizes many modifiers in the @family
2998 * string, most notably, it recognizes the string "monospace". That is,
2999 * the family name "@cairo:monospace" will use the monospace version of
3000 * the internal font family.
3001 *
3002 * For "real" font selection, see the font-backend-specific
3003 * font_face_create functions for the font backend you are using. (For
3004 * example, if you are using the freetype-based cairo-ft font backend,
3005 * see cairo_ft_font_face_create_for_ft_face() or
3006 * cairo_ft_font_face_create_for_pattern().) The resulting font face
3007 * could then be used with cairo_scaled_font_create() and
3008 * cairo_set_scaled_font().
3009 *
3010 * Similarly, when using the "real" font support, you can call
3011 * directly into the underlying font system, (such as fontconfig or
3012 * freetype), for operations such as listing available fonts, etc.
3013 *
3014 * It is expected that most applications will need to use a more
3015 * comprehensive font handling and text layout library, (for example,
3016 * pango), in conjunction with cairo.
3017 *
3018 * If text is drawn without a call to cairo_select_font_face(), (nor
3019 * cairo_set_font_face() nor cairo_set_scaled_font()), the default
3020 * family is platform-specific, but is essentially "sans-serif".
3021 * Default slant is %CAIRO_FONT_SLANT_NORMAL, and default weight is
3022 * %CAIRO_FONT_WEIGHT_NORMAL.
3023 *
3024 * This function is equivalent to a call to cairo_toy_font_face_create()
3025 * followed by cairo_set_font_face().
3026 *
3027 * Since: 1.0
3028 **/
3029 void
cairo_select_font_face(cairo_t * cr,const char * family,cairo_font_slant_t slant,cairo_font_weight_t weight)3030 cairo_select_font_face (cairo_t *cr,
3031 const char *family,
3032 cairo_font_slant_t slant,
3033 cairo_font_weight_t weight)
3034 {
3035 cairo_font_face_t *font_face;
3036 cairo_status_t status;
3037
3038 if (unlikely (cr->status))
3039 return;
3040
3041 font_face = cairo_toy_font_face_create (family, slant, weight);
3042 if (unlikely (font_face->status)) {
3043 _cairo_set_error (cr, font_face->status);
3044 return;
3045 }
3046
3047 status = cr->backend->set_font_face (cr, font_face);
3048 cairo_font_face_destroy (font_face);
3049
3050 if (unlikely (status))
3051 _cairo_set_error (cr, status);
3052 }
3053
3054 /**
3055 * cairo_font_extents:
3056 * @cr: a #cairo_t
3057 * @extents: a #cairo_font_extents_t object into which the results
3058 * will be stored.
3059 *
3060 * Gets the font extents for the currently selected font.
3061 *
3062 * Since: 1.0
3063 **/
3064 void
cairo_font_extents(cairo_t * cr,cairo_font_extents_t * extents)3065 cairo_font_extents (cairo_t *cr,
3066 cairo_font_extents_t *extents)
3067 {
3068 cairo_status_t status;
3069
3070 extents->ascent = 0.0;
3071 extents->descent = 0.0;
3072 extents->height = 0.0;
3073 extents->max_x_advance = 0.0;
3074 extents->max_y_advance = 0.0;
3075
3076 if (unlikely (cr->status))
3077 return;
3078
3079 status = cr->backend->font_extents (cr, extents);
3080 if (unlikely (status))
3081 _cairo_set_error (cr, status);
3082 }
3083
3084 /**
3085 * cairo_set_font_face:
3086 * @cr: a #cairo_t
3087 * @font_face: a #cairo_font_face_t, or %NULL to restore to the default font
3088 *
3089 * Replaces the current #cairo_font_face_t object in the #cairo_t with
3090 * @font_face. The replaced font face in the #cairo_t will be
3091 * destroyed if there are no other references to it.
3092 *
3093 * Since: 1.0
3094 **/
3095 void
cairo_set_font_face(cairo_t * cr,cairo_font_face_t * font_face)3096 cairo_set_font_face (cairo_t *cr,
3097 cairo_font_face_t *font_face)
3098 {
3099 cairo_status_t status;
3100
3101 if (unlikely (cr->status))
3102 return;
3103
3104 status = cr->backend->set_font_face (cr, font_face);
3105 if (unlikely (status))
3106 _cairo_set_error (cr, status);
3107 }
3108
3109 /**
3110 * cairo_get_font_face:
3111 * @cr: a #cairo_t
3112 *
3113 * Gets the current font face for a #cairo_t.
3114 *
3115 * Return value: the current font face. This object is owned by
3116 * cairo. To keep a reference to it, you must call
3117 * cairo_font_face_reference().
3118 *
3119 * This function never returns %NULL. If memory cannot be allocated, a
3120 * special "nil" #cairo_font_face_t object will be returned on which
3121 * cairo_font_face_status() returns %CAIRO_STATUS_NO_MEMORY. Using
3122 * this nil object will cause its error state to propagate to other
3123 * objects it is passed to, (for example, calling
3124 * cairo_set_font_face() with a nil font will trigger an error that
3125 * will shutdown the #cairo_t object).
3126 *
3127 * Since: 1.0
3128 **/
3129 cairo_font_face_t *
cairo_get_font_face(cairo_t * cr)3130 cairo_get_font_face (cairo_t *cr)
3131 {
3132 if (unlikely (cr->status))
3133 return (cairo_font_face_t*) &_cairo_font_face_nil;
3134
3135 return cr->backend->get_font_face (cr);
3136 }
3137
3138 /**
3139 * cairo_set_font_size:
3140 * @cr: a #cairo_t
3141 * @size: the new font size, in user space units
3142 *
3143 * Sets the current font matrix to a scale by a factor of @size, replacing
3144 * any font matrix previously set with cairo_set_font_size() or
3145 * cairo_set_font_matrix(). This results in a font size of @size user space
3146 * units. (More precisely, this matrix will result in the font's
3147 * em-square being a @size by @size square in user space.)
3148 *
3149 * If text is drawn without a call to cairo_set_font_size(), (nor
3150 * cairo_set_font_matrix() nor cairo_set_scaled_font()), the default
3151 * font size is 10.0.
3152 *
3153 * Since: 1.0
3154 **/
3155 void
cairo_set_font_size(cairo_t * cr,double size)3156 cairo_set_font_size (cairo_t *cr, double size)
3157 {
3158 cairo_status_t status;
3159
3160 if (unlikely (cr->status))
3161 return;
3162
3163 status = cr->backend->set_font_size (cr, size);
3164 if (unlikely (status))
3165 _cairo_set_error (cr, status);
3166 }
3167 slim_hidden_def (cairo_set_font_size);
3168
3169 /**
3170 * cairo_set_font_matrix:
3171 * @cr: a #cairo_t
3172 * @matrix: a #cairo_matrix_t describing a transform to be applied to
3173 * the current font.
3174 *
3175 * Sets the current font matrix to @matrix. The font matrix gives a
3176 * transformation from the design space of the font (in this space,
3177 * the em-square is 1 unit by 1 unit) to user space. Normally, a
3178 * simple scale is used (see cairo_set_font_size()), but a more
3179 * complex font matrix can be used to shear the font
3180 * or stretch it unequally along the two axes
3181 *
3182 * Since: 1.0
3183 **/
3184 void
cairo_set_font_matrix(cairo_t * cr,const cairo_matrix_t * matrix)3185 cairo_set_font_matrix (cairo_t *cr,
3186 const cairo_matrix_t *matrix)
3187 {
3188 cairo_status_t status;
3189
3190 if (unlikely (cr->status))
3191 return;
3192
3193 status = cr->backend->set_font_matrix (cr, matrix);
3194 if (unlikely (status))
3195 _cairo_set_error (cr, status);
3196 }
3197 slim_hidden_def (cairo_set_font_matrix);
3198
3199 /**
3200 * cairo_get_font_matrix:
3201 * @cr: a #cairo_t
3202 * @matrix: return value for the matrix
3203 *
3204 * Stores the current font matrix into @matrix. See
3205 * cairo_set_font_matrix().
3206 *
3207 * Since: 1.0
3208 **/
3209 void
cairo_get_font_matrix(cairo_t * cr,cairo_matrix_t * matrix)3210 cairo_get_font_matrix (cairo_t *cr, cairo_matrix_t *matrix)
3211 {
3212 if (unlikely (cr->status)) {
3213 cairo_matrix_init_identity (matrix);
3214 return;
3215 }
3216
3217 cr->backend->get_font_matrix (cr, matrix);
3218 }
3219
3220 /**
3221 * cairo_set_font_options:
3222 * @cr: a #cairo_t
3223 * @options: font options to use
3224 *
3225 * Sets a set of custom font rendering options for the #cairo_t.
3226 * Rendering options are derived by merging these options with the
3227 * options derived from underlying surface; if the value in @options
3228 * has a default value (like %CAIRO_ANTIALIAS_DEFAULT), then the value
3229 * from the surface is used.
3230 *
3231 * Since: 1.0
3232 **/
3233 void
cairo_set_font_options(cairo_t * cr,const cairo_font_options_t * options)3234 cairo_set_font_options (cairo_t *cr,
3235 const cairo_font_options_t *options)
3236 {
3237 cairo_status_t status;
3238
3239 if (unlikely (cr->status))
3240 return;
3241
3242 status = cairo_font_options_status ((cairo_font_options_t *) options);
3243 if (unlikely (status)) {
3244 _cairo_set_error (cr, status);
3245 return;
3246 }
3247
3248 status = cr->backend->set_font_options (cr, options);
3249 if (unlikely (status))
3250 _cairo_set_error (cr, status);
3251 }
3252 slim_hidden_def (cairo_set_font_options);
3253
3254 /**
3255 * cairo_get_font_options:
3256 * @cr: a #cairo_t
3257 * @options: a #cairo_font_options_t object into which to store
3258 * the retrieved options. All existing values are overwritten
3259 *
3260 * Retrieves font rendering options set via #cairo_set_font_options.
3261 * Note that the returned options do not include any options derived
3262 * from the underlying surface; they are literally the options
3263 * passed to cairo_set_font_options().
3264 *
3265 * Since: 1.0
3266 **/
3267 void
cairo_get_font_options(cairo_t * cr,cairo_font_options_t * options)3268 cairo_get_font_options (cairo_t *cr,
3269 cairo_font_options_t *options)
3270 {
3271 /* check that we aren't trying to overwrite the nil object */
3272 if (cairo_font_options_status (options))
3273 return;
3274
3275 if (unlikely (cr->status)) {
3276 _cairo_font_options_init_default (options);
3277 return;
3278 }
3279
3280 cr->backend->get_font_options (cr, options);
3281 }
3282
3283 /**
3284 * cairo_set_scaled_font:
3285 * @cr: a #cairo_t
3286 * @scaled_font: a #cairo_scaled_font_t
3287 *
3288 * Replaces the current font face, font matrix, and font options in
3289 * the #cairo_t with those of the #cairo_scaled_font_t. Except for
3290 * some translation, the current CTM of the #cairo_t should be the
3291 * same as that of the #cairo_scaled_font_t, which can be accessed
3292 * using cairo_scaled_font_get_ctm().
3293 *
3294 * Since: 1.2
3295 **/
3296 void
cairo_set_scaled_font(cairo_t * cr,const cairo_scaled_font_t * scaled_font)3297 cairo_set_scaled_font (cairo_t *cr,
3298 const cairo_scaled_font_t *scaled_font)
3299 {
3300 cairo_status_t status;
3301
3302 if (unlikely (cr->status))
3303 return;
3304
3305 if ((scaled_font == NULL)) {
3306 _cairo_set_error (cr, _cairo_error (CAIRO_STATUS_NULL_POINTER));
3307 return;
3308 }
3309
3310 status = scaled_font->status;
3311 if (unlikely (status)) {
3312 _cairo_set_error (cr, status);
3313 return;
3314 }
3315
3316 status = cr->backend->set_scaled_font (cr, (cairo_scaled_font_t *) scaled_font);
3317 if (unlikely (status))
3318 _cairo_set_error (cr, status);
3319 }
3320
3321 /**
3322 * cairo_get_scaled_font:
3323 * @cr: a #cairo_t
3324 *
3325 * Gets the current scaled font for a #cairo_t.
3326 *
3327 * Return value: the current scaled font. This object is owned by
3328 * cairo. To keep a reference to it, you must call
3329 * cairo_scaled_font_reference().
3330 *
3331 * This function never returns %NULL. If memory cannot be allocated, a
3332 * special "nil" #cairo_scaled_font_t object will be returned on which
3333 * cairo_scaled_font_status() returns %CAIRO_STATUS_NO_MEMORY. Using
3334 * this nil object will cause its error state to propagate to other
3335 * objects it is passed to, (for example, calling
3336 * cairo_set_scaled_font() with a nil font will trigger an error that
3337 * will shutdown the #cairo_t object).
3338 *
3339 * Since: 1.4
3340 **/
3341 cairo_scaled_font_t *
cairo_get_scaled_font(cairo_t * cr)3342 cairo_get_scaled_font (cairo_t *cr)
3343 {
3344 if (unlikely (cr->status))
3345 return _cairo_scaled_font_create_in_error (cr->status);
3346
3347 return cr->backend->get_scaled_font (cr);
3348 }
3349 slim_hidden_def (cairo_get_scaled_font);
3350
3351 /**
3352 * cairo_text_extents:
3353 * @cr: a #cairo_t
3354 * @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
3355 * @extents: a #cairo_text_extents_t object into which the results
3356 * will be stored
3357 *
3358 * Gets the extents for a string of text. The extents describe a
3359 * user-space rectangle that encloses the "inked" portion of the text,
3360 * (as it would be drawn by cairo_show_text()). Additionally, the
3361 * x_advance and y_advance values indicate the amount by which the
3362 * current point would be advanced by cairo_show_text().
3363 *
3364 * Note that whitespace characters do not directly contribute to the
3365 * size of the rectangle (extents.width and extents.height). They do
3366 * contribute indirectly by changing the position of non-whitespace
3367 * characters. In particular, trailing whitespace characters are
3368 * likely to not affect the size of the rectangle, though they will
3369 * affect the x_advance and y_advance values.
3370 *
3371 * Since: 1.0
3372 **/
3373 void
cairo_text_extents(cairo_t * cr,const char * utf8,cairo_text_extents_t * extents)3374 cairo_text_extents (cairo_t *cr,
3375 const char *utf8,
3376 cairo_text_extents_t *extents)
3377 {
3378 cairo_status_t status;
3379 cairo_scaled_font_t *scaled_font;
3380 cairo_glyph_t *glyphs = NULL;
3381 int num_glyphs = 0;
3382 double x, y;
3383
3384 extents->x_bearing = 0.0;
3385 extents->y_bearing = 0.0;
3386 extents->width = 0.0;
3387 extents->height = 0.0;
3388 extents->x_advance = 0.0;
3389 extents->y_advance = 0.0;
3390
3391 if (unlikely (cr->status))
3392 return;
3393
3394 if (utf8 == NULL)
3395 return;
3396
3397 scaled_font = cairo_get_scaled_font (cr);
3398 if (unlikely (scaled_font->status)) {
3399 _cairo_set_error (cr, scaled_font->status);
3400 return;
3401 }
3402
3403 cairo_get_current_point (cr, &x, &y);
3404 status = cairo_scaled_font_text_to_glyphs (scaled_font,
3405 x, y,
3406 utf8, -1,
3407 &glyphs, &num_glyphs,
3408 NULL, NULL, NULL);
3409
3410 if (likely (status == CAIRO_STATUS_SUCCESS)) {
3411 status = cr->backend->glyph_extents (cr,
3412 glyphs, num_glyphs,
3413 extents);
3414 }
3415 cairo_glyph_free (glyphs);
3416
3417 if (unlikely (status))
3418 _cairo_set_error (cr, status);
3419 }
3420
3421 /**
3422 * cairo_glyph_extents:
3423 * @cr: a #cairo_t
3424 * @glyphs: an array of #cairo_glyph_t objects
3425 * @num_glyphs: the number of elements in @glyphs
3426 * @extents: a #cairo_text_extents_t object into which the results
3427 * will be stored
3428 *
3429 * Gets the extents for an array of glyphs. The extents describe a
3430 * user-space rectangle that encloses the "inked" portion of the
3431 * glyphs, (as they would be drawn by cairo_show_glyphs()).
3432 * Additionally, the x_advance and y_advance values indicate the
3433 * amount by which the current point would be advanced by
3434 * cairo_show_glyphs().
3435 *
3436 * Note that whitespace glyphs do not contribute to the size of the
3437 * rectangle (extents.width and extents.height).
3438 *
3439 * Since: 1.0
3440 **/
3441 void
cairo_glyph_extents(cairo_t * cr,const cairo_glyph_t * glyphs,int num_glyphs,cairo_text_extents_t * extents)3442 cairo_glyph_extents (cairo_t *cr,
3443 const cairo_glyph_t *glyphs,
3444 int num_glyphs,
3445 cairo_text_extents_t *extents)
3446 {
3447 cairo_status_t status;
3448
3449 extents->x_bearing = 0.0;
3450 extents->y_bearing = 0.0;
3451 extents->width = 0.0;
3452 extents->height = 0.0;
3453 extents->x_advance = 0.0;
3454 extents->y_advance = 0.0;
3455
3456 if (unlikely (cr->status))
3457 return;
3458
3459 if (num_glyphs == 0)
3460 return;
3461
3462 if (unlikely (num_glyphs < 0)) {
3463 _cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
3464 return;
3465 }
3466
3467 if (unlikely (glyphs == NULL)) {
3468 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3469 return;
3470 }
3471
3472 status = cr->backend->glyph_extents (cr, glyphs, num_glyphs, extents);
3473 if (unlikely (status))
3474 _cairo_set_error (cr, status);
3475 }
3476
3477 /**
3478 * cairo_show_text:
3479 * @cr: a cairo context
3480 * @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
3481 *
3482 * A drawing operator that generates the shape from a string of UTF-8
3483 * characters, rendered according to the current font_face, font_size
3484 * (font_matrix), and font_options.
3485 *
3486 * This function first computes a set of glyphs for the string of
3487 * text. The first glyph is placed so that its origin is at the
3488 * current point. The origin of each subsequent glyph is offset from
3489 * that of the previous glyph by the advance values of the previous
3490 * glyph.
3491 *
3492 * After this call the current point is moved to the origin of where
3493 * the next glyph would be placed in this same progression. That is,
3494 * the current point will be at the origin of the final glyph offset
3495 * by its advance values. This allows for easy display of a single
3496 * logical string with multiple calls to cairo_show_text().
3497 *
3498 * Note: The cairo_show_text() function call is part of what the cairo
3499 * designers call the "toy" text API. It is convenient for short demos
3500 * and simple programs, but it is not expected to be adequate for
3501 * serious text-using applications. See cairo_show_glyphs() for the
3502 * "real" text display API in cairo.
3503 *
3504 * Since: 1.0
3505 **/
3506 void
cairo_show_text(cairo_t * cr,const char * utf8)3507 cairo_show_text (cairo_t *cr, const char *utf8)
3508 {
3509 cairo_text_extents_t extents;
3510 cairo_status_t status;
3511 cairo_glyph_t *glyphs, *last_glyph;
3512 cairo_text_cluster_t *clusters;
3513 int utf8_len, num_glyphs, num_clusters;
3514 cairo_text_cluster_flags_t cluster_flags;
3515 double x, y;
3516 cairo_bool_t has_show_text_glyphs;
3517 cairo_glyph_t stack_glyphs[CAIRO_STACK_ARRAY_LENGTH (cairo_glyph_t)];
3518 cairo_text_cluster_t stack_clusters[CAIRO_STACK_ARRAY_LENGTH (cairo_text_cluster_t)];
3519 cairo_scaled_font_t *scaled_font;
3520 cairo_glyph_text_info_t info, *i;
3521
3522 if (unlikely (cr->status))
3523 return;
3524
3525 if (utf8 == NULL)
3526 return;
3527
3528 scaled_font = cairo_get_scaled_font (cr);
3529 if (unlikely (scaled_font->status)) {
3530 _cairo_set_error (cr, scaled_font->status);
3531 return;
3532 }
3533
3534 utf8_len = strlen (utf8);
3535
3536 has_show_text_glyphs =
3537 cairo_surface_has_show_text_glyphs (cairo_get_target (cr));
3538
3539 glyphs = stack_glyphs;
3540 num_glyphs = ARRAY_LENGTH (stack_glyphs);
3541
3542 if (has_show_text_glyphs) {
3543 clusters = stack_clusters;
3544 num_clusters = ARRAY_LENGTH (stack_clusters);
3545 } else {
3546 clusters = NULL;
3547 num_clusters = 0;
3548 }
3549
3550 cairo_get_current_point (cr, &x, &y);
3551 status = cairo_scaled_font_text_to_glyphs (scaled_font,
3552 x, y,
3553 utf8, utf8_len,
3554 &glyphs, &num_glyphs,
3555 has_show_text_glyphs ? &clusters : NULL, &num_clusters,
3556 &cluster_flags);
3557 if (unlikely (status))
3558 goto BAIL;
3559
3560 if (num_glyphs == 0)
3561 return;
3562
3563 i = NULL;
3564 if (has_show_text_glyphs) {
3565 info.utf8 = utf8;
3566 info.utf8_len = utf8_len;
3567 info.clusters = clusters;
3568 info.num_clusters = num_clusters;
3569 info.cluster_flags = cluster_flags;
3570 i = &info;
3571 }
3572
3573 status = cr->backend->glyphs (cr, glyphs, num_glyphs, i);
3574 if (unlikely (status))
3575 goto BAIL;
3576
3577 last_glyph = &glyphs[num_glyphs - 1];
3578 status = cr->backend->glyph_extents (cr, last_glyph, 1, &extents);
3579 if (unlikely (status))
3580 goto BAIL;
3581
3582 x = last_glyph->x + extents.x_advance;
3583 y = last_glyph->y + extents.y_advance;
3584 cr->backend->move_to (cr, x, y);
3585
3586 BAIL:
3587 if (glyphs != stack_glyphs)
3588 cairo_glyph_free (glyphs);
3589 if (clusters != stack_clusters)
3590 cairo_text_cluster_free (clusters);
3591
3592 if (unlikely (status))
3593 _cairo_set_error (cr, status);
3594 }
3595
3596 /**
3597 * cairo_show_glyphs:
3598 * @cr: a cairo context
3599 * @glyphs: array of glyphs to show
3600 * @num_glyphs: number of glyphs to show
3601 *
3602 * A drawing operator that generates the shape from an array of glyphs,
3603 * rendered according to the current font face, font size
3604 * (font matrix), and font options.
3605 *
3606 * Since: 1.0
3607 **/
3608 void
cairo_show_glyphs(cairo_t * cr,const cairo_glyph_t * glyphs,int num_glyphs)3609 cairo_show_glyphs (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs)
3610 {
3611 cairo_status_t status;
3612
3613 if (unlikely (cr->status))
3614 return;
3615
3616 if (num_glyphs == 0)
3617 return;
3618
3619 if (num_glyphs < 0) {
3620 _cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
3621 return;
3622 }
3623
3624 if (glyphs == NULL) {
3625 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3626 return;
3627 }
3628
3629 status = cr->backend->glyphs (cr, glyphs, num_glyphs, NULL);
3630 if (unlikely (status))
3631 _cairo_set_error (cr, status);
3632 }
3633
3634 /**
3635 * cairo_show_text_glyphs:
3636 * @cr: a cairo context
3637 * @utf8: a string of text encoded in UTF-8
3638 * @utf8_len: length of @utf8 in bytes, or -1 if it is NUL-terminated
3639 * @glyphs: array of glyphs to show
3640 * @num_glyphs: number of glyphs to show
3641 * @clusters: array of cluster mapping information
3642 * @num_clusters: number of clusters in the mapping
3643 * @cluster_flags: cluster mapping flags
3644 *
3645 * This operation has rendering effects similar to cairo_show_glyphs()
3646 * but, if the target surface supports it, uses the provided text and
3647 * cluster mapping to embed the text for the glyphs shown in the output.
3648 * If the target does not support the extended attributes, this function
3649 * acts like the basic cairo_show_glyphs() as if it had been passed
3650 * @glyphs and @num_glyphs.
3651 *
3652 * The mapping between @utf8 and @glyphs is provided by an array of
3653 * <firstterm>clusters</firstterm>. Each cluster covers a number of
3654 * text bytes and glyphs, and neighboring clusters cover neighboring
3655 * areas of @utf8 and @glyphs. The clusters should collectively cover @utf8
3656 * and @glyphs in entirety.
3657 *
3658 * The first cluster always covers bytes from the beginning of @utf8.
3659 * If @cluster_flags do not have the %CAIRO_TEXT_CLUSTER_FLAG_BACKWARD
3660 * set, the first cluster also covers the beginning
3661 * of @glyphs, otherwise it covers the end of the @glyphs array and
3662 * following clusters move backward.
3663 *
3664 * See #cairo_text_cluster_t for constraints on valid clusters.
3665 *
3666 * Since: 1.8
3667 **/
3668 void
cairo_show_text_glyphs(cairo_t * cr,const char * utf8,int utf8_len,const cairo_glyph_t * glyphs,int num_glyphs,const cairo_text_cluster_t * clusters,int num_clusters,cairo_text_cluster_flags_t cluster_flags)3669 cairo_show_text_glyphs (cairo_t *cr,
3670 const char *utf8,
3671 int utf8_len,
3672 const cairo_glyph_t *glyphs,
3673 int num_glyphs,
3674 const cairo_text_cluster_t *clusters,
3675 int num_clusters,
3676 cairo_text_cluster_flags_t cluster_flags)
3677 {
3678 cairo_status_t status;
3679
3680 if (unlikely (cr->status))
3681 return;
3682
3683 /* A slew of sanity checks */
3684
3685 /* Special case for NULL and -1 */
3686 if (utf8 == NULL && utf8_len == -1)
3687 utf8_len = 0;
3688
3689 /* No NULLs for non-zeros */
3690 if ((num_glyphs && glyphs == NULL) ||
3691 (utf8_len && utf8 == NULL) ||
3692 (num_clusters && clusters == NULL)) {
3693 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3694 return;
3695 }
3696
3697 /* A -1 for utf8_len means NUL-terminated */
3698 if (utf8_len == -1)
3699 utf8_len = strlen (utf8);
3700
3701 /* Apart from that, no negatives */
3702 if (num_glyphs < 0 || utf8_len < 0 || num_clusters < 0) {
3703 _cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
3704 return;
3705 }
3706
3707 if (num_glyphs == 0 && utf8_len == 0)
3708 return;
3709
3710 if (utf8) {
3711 /* Make sure clusters cover the entire glyphs and utf8 arrays,
3712 * and that cluster boundaries are UTF-8 boundaries. */
3713 status = _cairo_validate_text_clusters (utf8, utf8_len,
3714 glyphs, num_glyphs,
3715 clusters, num_clusters, cluster_flags);
3716 if (status == CAIRO_STATUS_INVALID_CLUSTERS) {
3717 /* Either got invalid UTF-8 text, or cluster mapping is bad.
3718 * Differentiate those. */
3719
3720 cairo_status_t status2;
3721
3722 status2 = _cairo_utf8_to_ucs4 (utf8, utf8_len, NULL, NULL);
3723 if (status2)
3724 status = status2;
3725 } else {
3726 cairo_glyph_text_info_t info;
3727
3728 info.utf8 = utf8;
3729 info.utf8_len = utf8_len;
3730 info.clusters = clusters;
3731 info.num_clusters = num_clusters;
3732 info.cluster_flags = cluster_flags;
3733
3734 status = cr->backend->glyphs (cr, glyphs, num_glyphs, &info);
3735 }
3736 } else {
3737 status = cr->backend->glyphs (cr, glyphs, num_glyphs, NULL);
3738 }
3739 if (unlikely (status))
3740 _cairo_set_error (cr, status);
3741 }
3742
3743 /**
3744 * cairo_text_path:
3745 * @cr: a cairo context
3746 * @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
3747 *
3748 * Adds closed paths for text to the current path. The generated
3749 * path if filled, achieves an effect similar to that of
3750 * cairo_show_text().
3751 *
3752 * Text conversion and positioning is done similar to cairo_show_text().
3753 *
3754 * Like cairo_show_text(), After this call the current point is
3755 * moved to the origin of where the next glyph would be placed in
3756 * this same progression. That is, the current point will be at
3757 * the origin of the final glyph offset by its advance values.
3758 * This allows for chaining multiple calls to to cairo_text_path()
3759 * without having to set current point in between.
3760 *
3761 * Note: The cairo_text_path() function call is part of what the cairo
3762 * designers call the "toy" text API. It is convenient for short demos
3763 * and simple programs, but it is not expected to be adequate for
3764 * serious text-using applications. See cairo_glyph_path() for the
3765 * "real" text path API in cairo.
3766 *
3767 * Since: 1.0
3768 **/
3769 void
cairo_text_path(cairo_t * cr,const char * utf8)3770 cairo_text_path (cairo_t *cr, const char *utf8)
3771 {
3772 cairo_status_t status;
3773 cairo_text_extents_t extents;
3774 cairo_glyph_t stack_glyphs[CAIRO_STACK_ARRAY_LENGTH (cairo_glyph_t)];
3775 cairo_glyph_t *glyphs, *last_glyph;
3776 cairo_scaled_font_t *scaled_font;
3777 int num_glyphs;
3778 double x, y;
3779
3780 if (unlikely (cr->status))
3781 return;
3782
3783 if (utf8 == NULL)
3784 return;
3785
3786
3787 glyphs = stack_glyphs;
3788 num_glyphs = ARRAY_LENGTH (stack_glyphs);
3789
3790 scaled_font = cairo_get_scaled_font (cr);
3791 if (unlikely (scaled_font->status)) {
3792 _cairo_set_error (cr, scaled_font->status);
3793 return;
3794 }
3795
3796 cairo_get_current_point (cr, &x, &y);
3797 status = cairo_scaled_font_text_to_glyphs (scaled_font,
3798 x, y,
3799 utf8, -1,
3800 &glyphs, &num_glyphs,
3801 NULL, NULL, NULL);
3802
3803 if (num_glyphs == 0)
3804 return;
3805
3806 status = cr->backend->glyph_path (cr, glyphs, num_glyphs);
3807
3808 if (unlikely (status))
3809 goto BAIL;
3810
3811 last_glyph = &glyphs[num_glyphs - 1];
3812 status = cr->backend->glyph_extents (cr, last_glyph, 1, &extents);
3813
3814 if (unlikely (status))
3815 goto BAIL;
3816
3817 x = last_glyph->x + extents.x_advance;
3818 y = last_glyph->y + extents.y_advance;
3819 cr->backend->move_to (cr, x, y);
3820
3821 BAIL:
3822 if (glyphs != stack_glyphs)
3823 cairo_glyph_free (glyphs);
3824
3825 if (unlikely (status))
3826 _cairo_set_error (cr, status);
3827 }
3828
3829 /**
3830 * cairo_glyph_path:
3831 * @cr: a cairo context
3832 * @glyphs: array of glyphs to show
3833 * @num_glyphs: number of glyphs to show
3834 *
3835 * Adds closed paths for the glyphs to the current path. The generated
3836 * path if filled, achieves an effect similar to that of
3837 * cairo_show_glyphs().
3838 *
3839 * Since: 1.0
3840 **/
3841 void
cairo_glyph_path(cairo_t * cr,const cairo_glyph_t * glyphs,int num_glyphs)3842 cairo_glyph_path (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs)
3843 {
3844 cairo_status_t status;
3845
3846 if (unlikely (cr->status))
3847 return;
3848
3849 if (num_glyphs == 0)
3850 return;
3851
3852 if (unlikely (num_glyphs < 0)) {
3853 _cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
3854 return;
3855 }
3856
3857 if (unlikely (glyphs == NULL)) {
3858 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
3859 return;
3860 }
3861
3862 status = cr->backend->glyph_path (cr, glyphs, num_glyphs);
3863 if (unlikely (status))
3864 _cairo_set_error (cr, status);
3865 }
3866
3867 /**
3868 * cairo_get_operator:
3869 * @cr: a cairo context
3870 *
3871 * Gets the current compositing operator for a cairo context.
3872 *
3873 * Return value: the current compositing operator.
3874 *
3875 * Since: 1.0
3876 **/
3877 cairo_operator_t
cairo_get_operator(cairo_t * cr)3878 cairo_get_operator (cairo_t *cr)
3879 {
3880 if (unlikely (cr->status))
3881 return CAIRO_GSTATE_OPERATOR_DEFAULT;
3882
3883 return cr->backend->get_operator (cr);
3884 }
3885
3886 #if 0
3887 /**
3888 * cairo_get_opacity:
3889 * @cr: a cairo context
3890 *
3891 * Gets the current compositing opacity for a cairo context.
3892 *
3893 * Return value: the current compositing opacity.
3894 *
3895 * Since: TBD
3896 **/
3897 double
3898 cairo_get_opacity (cairo_t *cr)
3899 {
3900 if (unlikely (cr->status))
3901 return 1.;
3902
3903 return cr->backend->get_opacity (cr);
3904 }
3905 #endif
3906
3907 /**
3908 * cairo_get_tolerance:
3909 * @cr: a cairo context
3910 *
3911 * Gets the current tolerance value, as set by cairo_set_tolerance().
3912 *
3913 * Return value: the current tolerance value.
3914 *
3915 * Since: 1.0
3916 **/
3917 double
cairo_get_tolerance(cairo_t * cr)3918 cairo_get_tolerance (cairo_t *cr)
3919 {
3920 if (unlikely (cr->status))
3921 return CAIRO_GSTATE_TOLERANCE_DEFAULT;
3922
3923 return cr->backend->get_tolerance (cr);
3924 }
3925 slim_hidden_def (cairo_get_tolerance);
3926
3927 /**
3928 * cairo_get_antialias:
3929 * @cr: a cairo context
3930 *
3931 * Gets the current shape antialiasing mode, as set by
3932 * cairo_set_antialias().
3933 *
3934 * Return value: the current shape antialiasing mode.
3935 *
3936 * Since: 1.0
3937 **/
3938 cairo_antialias_t
cairo_get_antialias(cairo_t * cr)3939 cairo_get_antialias (cairo_t *cr)
3940 {
3941 if (unlikely (cr->status))
3942 return CAIRO_ANTIALIAS_DEFAULT;
3943
3944 return cr->backend->get_antialias (cr);
3945 }
3946
3947 /**
3948 * cairo_has_current_point:
3949 * @cr: a cairo context
3950 *
3951 * Returns whether a current point is defined on the current path.
3952 * See cairo_get_current_point() for details on the current point.
3953 *
3954 * Return value: whether a current point is defined.
3955 *
3956 * Since: 1.6
3957 **/
3958 cairo_bool_t
cairo_has_current_point(cairo_t * cr)3959 cairo_has_current_point (cairo_t *cr)
3960 {
3961 if (unlikely (cr->status))
3962 return FALSE;
3963
3964 return cr->backend->has_current_point (cr);
3965 }
3966
3967 /**
3968 * cairo_get_current_point:
3969 * @cr: a cairo context
3970 * @x: return value for X coordinate of the current point
3971 * @y: return value for Y coordinate of the current point
3972 *
3973 * Gets the current point of the current path, which is
3974 * conceptually the final point reached by the path so far.
3975 *
3976 * The current point is returned in the user-space coordinate
3977 * system. If there is no defined current point or if @cr is in an
3978 * error status, @x and @y will both be set to 0.0. It is possible to
3979 * check this in advance with cairo_has_current_point().
3980 *
3981 * Most path construction functions alter the current point. See the
3982 * following for details on how they affect the current point:
3983 * cairo_new_path(), cairo_new_sub_path(),
3984 * cairo_append_path(), cairo_close_path(),
3985 * cairo_move_to(), cairo_line_to(), cairo_curve_to(),
3986 * cairo_rel_move_to(), cairo_rel_line_to(), cairo_rel_curve_to(),
3987 * cairo_arc(), cairo_arc_negative(), cairo_rectangle(),
3988 * cairo_text_path(), cairo_glyph_path(), cairo_stroke_to_path().
3989 *
3990 * Some functions use and alter the current point but do not
3991 * otherwise change current path:
3992 * cairo_show_text().
3993 *
3994 * Some functions unset the current path and as a result, current point:
3995 * cairo_fill(), cairo_stroke().
3996 *
3997 * Since: 1.0
3998 **/
3999 void
cairo_get_current_point(cairo_t * cr,double * x_ret,double * y_ret)4000 cairo_get_current_point (cairo_t *cr, double *x_ret, double *y_ret)
4001 {
4002 double x, y;
4003
4004 x = y = 0;
4005 if (cr->status == CAIRO_STATUS_SUCCESS &&
4006 cr->backend->has_current_point (cr))
4007 {
4008 cr->backend->get_current_point (cr, &x, &y);
4009 }
4010
4011 if (x_ret)
4012 *x_ret = x;
4013 if (y_ret)
4014 *y_ret = y;
4015 }
4016 slim_hidden_def(cairo_get_current_point);
4017
4018 /**
4019 * cairo_get_fill_rule:
4020 * @cr: a cairo context
4021 *
4022 * Gets the current fill rule, as set by cairo_set_fill_rule().
4023 *
4024 * Return value: the current fill rule.
4025 *
4026 * Since: 1.0
4027 **/
4028 cairo_fill_rule_t
cairo_get_fill_rule(cairo_t * cr)4029 cairo_get_fill_rule (cairo_t *cr)
4030 {
4031 if (unlikely (cr->status))
4032 return CAIRO_GSTATE_FILL_RULE_DEFAULT;
4033
4034 return cr->backend->get_fill_rule (cr);
4035 }
4036
4037 /**
4038 * cairo_get_line_width:
4039 * @cr: a cairo context
4040 *
4041 * This function returns the current line width value exactly as set by
4042 * cairo_set_line_width(). Note that the value is unchanged even if
4043 * the CTM has changed between the calls to cairo_set_line_width() and
4044 * cairo_get_line_width().
4045 *
4046 * Return value: the current line width.
4047 *
4048 * Since: 1.0
4049 **/
4050 double
cairo_get_line_width(cairo_t * cr)4051 cairo_get_line_width (cairo_t *cr)
4052 {
4053 if (unlikely (cr->status))
4054 return CAIRO_GSTATE_LINE_WIDTH_DEFAULT;
4055
4056 return cr->backend->get_line_width (cr);
4057 }
4058 slim_hidden_def (cairo_get_line_width);
4059
4060 /**
4061 * cairo_get_line_cap:
4062 * @cr: a cairo context
4063 *
4064 * Gets the current line cap style, as set by cairo_set_line_cap().
4065 *
4066 * Return value: the current line cap style.
4067 *
4068 * Since: 1.0
4069 **/
4070 cairo_line_cap_t
cairo_get_line_cap(cairo_t * cr)4071 cairo_get_line_cap (cairo_t *cr)
4072 {
4073 if (unlikely (cr->status))
4074 return CAIRO_GSTATE_LINE_CAP_DEFAULT;
4075
4076 return cr->backend->get_line_cap (cr);
4077 }
4078
4079 /**
4080 * cairo_get_line_join:
4081 * @cr: a cairo context
4082 *
4083 * Gets the current line join style, as set by cairo_set_line_join().
4084 *
4085 * Return value: the current line join style.
4086 *
4087 * Since: 1.0
4088 **/
4089 cairo_line_join_t
cairo_get_line_join(cairo_t * cr)4090 cairo_get_line_join (cairo_t *cr)
4091 {
4092 if (unlikely (cr->status))
4093 return CAIRO_GSTATE_LINE_JOIN_DEFAULT;
4094
4095 return cr->backend->get_line_join (cr);
4096 }
4097
4098 /**
4099 * cairo_get_miter_limit:
4100 * @cr: a cairo context
4101 *
4102 * Gets the current miter limit, as set by cairo_set_miter_limit().
4103 *
4104 * Return value: the current miter limit.
4105 *
4106 * Since: 1.0
4107 **/
4108 double
cairo_get_miter_limit(cairo_t * cr)4109 cairo_get_miter_limit (cairo_t *cr)
4110 {
4111 if (unlikely (cr->status))
4112 return CAIRO_GSTATE_MITER_LIMIT_DEFAULT;
4113
4114 return cr->backend->get_miter_limit (cr);
4115 }
4116
4117 /**
4118 * cairo_get_matrix:
4119 * @cr: a cairo context
4120 * @matrix: return value for the matrix
4121 *
4122 * Stores the current transformation matrix (CTM) into @matrix.
4123 *
4124 * Since: 1.0
4125 **/
4126 void
cairo_get_matrix(cairo_t * cr,cairo_matrix_t * matrix)4127 cairo_get_matrix (cairo_t *cr, cairo_matrix_t *matrix)
4128 {
4129 if (unlikely (cr->status)) {
4130 cairo_matrix_init_identity (matrix);
4131 return;
4132 }
4133
4134 cr->backend->get_matrix (cr, matrix);
4135 }
4136 slim_hidden_def (cairo_get_matrix);
4137
4138 /**
4139 * cairo_get_target:
4140 * @cr: a cairo context
4141 *
4142 * Gets the target surface for the cairo context as passed to
4143 * cairo_create().
4144 *
4145 * This function will always return a valid pointer, but the result
4146 * can be a "nil" surface if @cr is already in an error state,
4147 * (ie. cairo_status() <literal>!=</literal> %CAIRO_STATUS_SUCCESS).
4148 * A nil surface is indicated by cairo_surface_status()
4149 * <literal>!=</literal> %CAIRO_STATUS_SUCCESS.
4150 *
4151 * Return value: the target surface. This object is owned by cairo. To
4152 * keep a reference to it, you must call cairo_surface_reference().
4153 *
4154 * Since: 1.0
4155 **/
4156 cairo_surface_t *
cairo_get_target(cairo_t * cr)4157 cairo_get_target (cairo_t *cr)
4158 {
4159 if (unlikely (cr->status))
4160 return _cairo_surface_create_in_error (cr->status);
4161
4162 return cr->backend->get_original_target (cr);
4163 }
4164 slim_hidden_def (cairo_get_target);
4165
4166 /**
4167 * cairo_get_group_target:
4168 * @cr: a cairo context
4169 *
4170 * Gets the current destination surface for the context. This is either
4171 * the original target surface as passed to cairo_create() or the target
4172 * surface for the current group as started by the most recent call to
4173 * cairo_push_group() or cairo_push_group_with_content().
4174 *
4175 * This function will always return a valid pointer, but the result
4176 * can be a "nil" surface if @cr is already in an error state,
4177 * (ie. cairo_status() <literal>!=</literal> %CAIRO_STATUS_SUCCESS).
4178 * A nil surface is indicated by cairo_surface_status()
4179 * <literal>!=</literal> %CAIRO_STATUS_SUCCESS.
4180 *
4181 * Return value: the target surface. This object is owned by cairo. To
4182 * keep a reference to it, you must call cairo_surface_reference().
4183 *
4184 * Since: 1.2
4185 **/
4186 cairo_surface_t *
cairo_get_group_target(cairo_t * cr)4187 cairo_get_group_target (cairo_t *cr)
4188 {
4189 if (unlikely (cr->status))
4190 return _cairo_surface_create_in_error (cr->status);
4191
4192 return cr->backend->get_current_target (cr);
4193 }
4194
4195 /**
4196 * cairo_copy_path:
4197 * @cr: a cairo context
4198 *
4199 * Creates a copy of the current path and returns it to the user as a
4200 * #cairo_path_t. See #cairo_path_data_t for hints on how to iterate
4201 * over the returned data structure.
4202 *
4203 * This function will always return a valid pointer, but the result
4204 * will have no data (<literal>data==%NULL</literal> and
4205 * <literal>num_data==0</literal>), if either of the following
4206 * conditions hold:
4207 *
4208 * <orderedlist>
4209 * <listitem>If there is insufficient memory to copy the path. In this
4210 * case <literal>path->status</literal> will be set to
4211 * %CAIRO_STATUS_NO_MEMORY.</listitem>
4212 * <listitem>If @cr is already in an error state. In this case
4213 * <literal>path->status</literal> will contain the same status that
4214 * would be returned by cairo_status().</listitem>
4215 * </orderedlist>
4216 *
4217 * Return value: the copy of the current path. The caller owns the
4218 * returned object and should call cairo_path_destroy() when finished
4219 * with it.
4220 *
4221 * Since: 1.0
4222 **/
4223 cairo_path_t *
cairo_copy_path(cairo_t * cr)4224 cairo_copy_path (cairo_t *cr)
4225 {
4226 if (unlikely (cr->status))
4227 return _cairo_path_create_in_error (cr->status);
4228
4229 return cr->backend->copy_path (cr);
4230 }
4231
4232 /**
4233 * cairo_copy_path_flat:
4234 * @cr: a cairo context
4235 *
4236 * Gets a flattened copy of the current path and returns it to the
4237 * user as a #cairo_path_t. See #cairo_path_data_t for hints on
4238 * how to iterate over the returned data structure.
4239 *
4240 * This function is like cairo_copy_path() except that any curves
4241 * in the path will be approximated with piecewise-linear
4242 * approximations, (accurate to within the current tolerance
4243 * value). That is, the result is guaranteed to not have any elements
4244 * of type %CAIRO_PATH_CURVE_TO which will instead be replaced by a
4245 * series of %CAIRO_PATH_LINE_TO elements.
4246 *
4247 * This function will always return a valid pointer, but the result
4248 * will have no data (<literal>data==%NULL</literal> and
4249 * <literal>num_data==0</literal>), if either of the following
4250 * conditions hold:
4251 *
4252 * <orderedlist>
4253 * <listitem>If there is insufficient memory to copy the path. In this
4254 * case <literal>path->status</literal> will be set to
4255 * %CAIRO_STATUS_NO_MEMORY.</listitem>
4256 * <listitem>If @cr is already in an error state. In this case
4257 * <literal>path->status</literal> will contain the same status that
4258 * would be returned by cairo_status().</listitem>
4259 * </orderedlist>
4260 *
4261 * Return value: the copy of the current path. The caller owns the
4262 * returned object and should call cairo_path_destroy() when finished
4263 * with it.
4264 *
4265 * Since: 1.0
4266 **/
4267 cairo_path_t *
cairo_copy_path_flat(cairo_t * cr)4268 cairo_copy_path_flat (cairo_t *cr)
4269 {
4270 if (unlikely (cr->status))
4271 return _cairo_path_create_in_error (cr->status);
4272
4273 return cr->backend->copy_path_flat (cr);
4274 }
4275
4276 /**
4277 * cairo_append_path:
4278 * @cr: a cairo context
4279 * @path: path to be appended
4280 *
4281 * Append the @path onto the current path. The @path may be either the
4282 * return value from one of cairo_copy_path() or
4283 * cairo_copy_path_flat() or it may be constructed manually. See
4284 * #cairo_path_t for details on how the path data structure should be
4285 * initialized, and note that <literal>path->status</literal> must be
4286 * initialized to %CAIRO_STATUS_SUCCESS.
4287 *
4288 * Since: 1.0
4289 **/
4290 void
cairo_append_path(cairo_t * cr,const cairo_path_t * path)4291 cairo_append_path (cairo_t *cr,
4292 const cairo_path_t *path)
4293 {
4294 cairo_status_t status;
4295
4296 if (unlikely (cr->status))
4297 return;
4298
4299 if (unlikely (path == NULL)) {
4300 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
4301 return;
4302 }
4303
4304 if (unlikely (path->status)) {
4305 if (path->status > CAIRO_STATUS_SUCCESS &&
4306 path->status <= CAIRO_STATUS_LAST_STATUS)
4307 _cairo_set_error (cr, path->status);
4308 else
4309 _cairo_set_error (cr, CAIRO_STATUS_INVALID_STATUS);
4310 return;
4311 }
4312
4313 if (path->num_data == 0)
4314 return;
4315
4316 if (unlikely (path->data == NULL)) {
4317 _cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
4318 return;
4319 }
4320
4321 status = cr->backend->append_path (cr, path);
4322 if (unlikely (status))
4323 _cairo_set_error (cr, status);
4324 }
4325
4326 /**
4327 * cairo_status:
4328 * @cr: a cairo context
4329 *
4330 * Checks whether an error has previously occurred for this context.
4331 *
4332 * Returns: the current status of this context, see #cairo_status_t
4333 *
4334 * Since: 1.0
4335 **/
4336 cairo_status_t
cairo_status(cairo_t * cr)4337 cairo_status (cairo_t *cr)
4338 {
4339 return cr->status;
4340 }
4341 slim_hidden_def (cairo_status);
4342