Subversion Repositories Kolibri OS

Rev

Go to most recent revision | Blame | Last modification | View Log | Download | RSS feed

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