Subversion Repositories Kolibri OS

Rev

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