Subversion Repositories Kolibri OS

Rev

Blame | Last modification | View Log | RSS feed

  1. /* cairo - a vector graphics library with display and print output
  2.  *
  3.  * Copyright © 2002 University of Southern California
  4.  * Copyright © 2005 Red Hat, Inc.
  5.  *
  6.  * This library is free software; you can redistribute it and/or
  7.  * modify it either under the terms of the GNU Lesser General Public
  8.  * License version 2.1 as published by the Free Software Foundation
  9.  * (the "LGPL") or, at your option, under the terms of the Mozilla
  10.  * Public License Version 1.1 (the "MPL"). If you do not alter this
  11.  * notice, a recipient may use your version of this file under either
  12.  * the MPL or the LGPL.
  13.  *
  14.  * You should have received a copy of the LGPL along with this library
  15.  * in the file COPYING-LGPL-2.1; if not, write to the Free Software
  16.  * Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA
  17.  * You should have received a copy of the MPL along with this library
  18.  * in the file COPYING-MPL-1.1
  19.  *
  20.  * The contents of this file are subject to the Mozilla Public License
  21.  * Version 1.1 (the "License"); you may not use this file except in
  22.  * compliance with the License. You may obtain a copy of the License at
  23.  * http://www.mozilla.org/MPL/
  24.  *
  25.  * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
  26.  * OF ANY KIND, either express or implied. See the LGPL or the MPL for
  27.  * the specific language governing rights and limitations.
  28.  *
  29.  * The Original Code is the cairo graphics library.
  30.  *
  31.  * The Initial Developer of the Original Code is University of Southern
  32.  * California.
  33.  *
  34.  * Contributor(s):
  35.  *      Carl D. Worth <cworth@cworth.org>
  36.  */
  37.  
  38. #ifndef CAIRO_H
  39. #define CAIRO_H
  40.  
  41. #include "cairo-version.h"
  42. #include "cairo-features.h"
  43. #include "cairo-deprecated.h"
  44.  
  45. #ifdef  __cplusplus
  46. # define CAIRO_BEGIN_DECLS  extern "C" {
  47. # define CAIRO_END_DECLS    }
  48. #else
  49. # define CAIRO_BEGIN_DECLS
  50. # define CAIRO_END_DECLS
  51. #endif
  52.  
  53. #ifndef cairo_public
  54. # if defined (_MSC_VER) && ! defined (CAIRO_WIN32_STATIC_BUILD)
  55. #  define cairo_public __declspec(dllimport)
  56. # else
  57. #  define cairo_public
  58. # endif
  59. #endif
  60.  
  61. CAIRO_BEGIN_DECLS
  62.  
  63. #define CAIRO_VERSION_ENCODE(major, minor, micro) (     \
  64.           ((major) * 10000)                             \
  65.         + ((minor) *   100)                             \
  66.         + ((micro) *     1))
  67.  
  68. #define CAIRO_VERSION CAIRO_VERSION_ENCODE(     \
  69.         CAIRO_VERSION_MAJOR,                    \
  70.         CAIRO_VERSION_MINOR,                    \
  71.         CAIRO_VERSION_MICRO)
  72.  
  73.  
  74. #define CAIRO_VERSION_STRINGIZE_(major, minor, micro)   \
  75.         #major"."#minor"."#micro
  76. #define CAIRO_VERSION_STRINGIZE(major, minor, micro)    \
  77.         CAIRO_VERSION_STRINGIZE_(major, minor, micro)
  78.  
  79. #define CAIRO_VERSION_STRING CAIRO_VERSION_STRINGIZE(   \
  80.         CAIRO_VERSION_MAJOR,                            \
  81.         CAIRO_VERSION_MINOR,                            \
  82.         CAIRO_VERSION_MICRO)
  83.  
  84.  
  85. cairo_public int
  86. cairo_version (void);
  87.  
  88. cairo_public const char*
  89. cairo_version_string (void);
  90.  
  91. /**
  92.  * cairo_bool_t:
  93.  *
  94.  * #cairo_bool_t is used for boolean values. Returns of type
  95.  * #cairo_bool_t will always be either 0 or 1, but testing against
  96.  * these values explicitly is not encouraged; just use the
  97.  * value as a boolean condition.
  98.  *
  99.  * <informalexample><programlisting>
  100.  *  if (cairo_in_stroke (cr, x, y)) {
  101.  *      /<!-- -->* do something *<!-- -->/
  102.  *  }
  103.  * </programlisting></informalexample>
  104.  *
  105.  * Since: 1.0
  106.  **/
  107. typedef int cairo_bool_t;
  108.  
  109. /**
  110.  * cairo_t:
  111.  *
  112.  * A #cairo_t contains the current state of the rendering device,
  113.  * including coordinates of yet to be drawn shapes.
  114.  *
  115.  * Cairo contexts, as #cairo_t objects are named, are central to
  116.  * cairo and all drawing with cairo is always done to a #cairo_t
  117.  * object.
  118.  *
  119.  * Memory management of #cairo_t is done with
  120.  * cairo_reference() and cairo_destroy().
  121.  *
  122.  * Since: 1.0
  123.  **/
  124. typedef struct _cairo cairo_t;
  125.  
  126. /**
  127.  * cairo_surface_t:
  128.  *
  129.  * A #cairo_surface_t represents an image, either as the destination
  130.  * of a drawing operation or as source when drawing onto another
  131.  * surface.  To draw to a #cairo_surface_t, create a cairo context
  132.  * with the surface as the target, using cairo_create().
  133.  *
  134.  * There are different subtypes of #cairo_surface_t for
  135.  * different drawing backends; for example, cairo_image_surface_create()
  136.  * creates a bitmap image in memory.
  137.  * The type of a surface can be queried with cairo_surface_get_type().
  138.  *
  139.  * The initial contents of a surface after creation depend upon the manner
  140.  * of its creation. If cairo creates the surface and backing storage for
  141.  * the user, it will be initially cleared; for example,
  142.  * cairo_image_surface_create() and cairo_surface_create_similar().
  143.  * Alternatively, if the user passes in a reference to some backing storage
  144.  * and asks cairo to wrap that in a #cairo_surface_t, then the contents are
  145.  * not modified; for example, cairo_image_surface_create_for_data() and
  146.  * cairo_xlib_surface_create().
  147.  *
  148.  * Memory management of #cairo_surface_t is done with
  149.  * cairo_surface_reference() and cairo_surface_destroy().
  150.  *
  151.  * Since: 1.0
  152.  **/
  153. typedef struct _cairo_surface cairo_surface_t;
  154.  
  155. /**
  156.  * cairo_device_t:
  157.  *
  158.  * A #cairo_device_t represents the driver interface for drawing
  159.  * operations to a #cairo_surface_t.  There are different subtypes of
  160.  * #cairo_device_t for different drawing backends; for example,
  161.  * cairo_egl_device_create() creates a device that wraps an EGL display and
  162.  * context.
  163.  *
  164.  * The type of a device can be queried with cairo_device_get_type().
  165.  *
  166.  * Memory management of #cairo_device_t is done with
  167.  * cairo_device_reference() and cairo_device_destroy().
  168.  *
  169.  * Since: 1.10
  170.  **/
  171. typedef struct _cairo_device cairo_device_t;
  172.  
  173. /**
  174.  * cairo_matrix_t:
  175.  * @xx: xx component of the affine transformation
  176.  * @yx: yx component of the affine transformation
  177.  * @xy: xy component of the affine transformation
  178.  * @yy: yy component of the affine transformation
  179.  * @x0: X translation component of the affine transformation
  180.  * @y0: Y translation component of the affine transformation
  181.  *
  182.  * A #cairo_matrix_t holds an affine transformation, such as a scale,
  183.  * rotation, shear, or a combination of those. The transformation of
  184.  * a point (x, y) is given by:
  185.  * <programlisting>
  186.  *     x_new = xx * x + xy * y + x0;
  187.  *     y_new = yx * x + yy * y + y0;
  188.  * </programlisting>
  189.  *
  190.  * Since: 1.0
  191.  **/
  192. typedef struct _cairo_matrix {
  193.     double xx; double yx;
  194.     double xy; double yy;
  195.     double x0; double y0;
  196. } cairo_matrix_t;
  197.  
  198. /**
  199.  * cairo_pattern_t:
  200.  *
  201.  * A #cairo_pattern_t represents a source when drawing onto a
  202.  * surface. There are different subtypes of #cairo_pattern_t,
  203.  * for different types of sources; for example,
  204.  * cairo_pattern_create_rgb() creates a pattern for a solid
  205.  * opaque color.
  206.  *
  207.  * Other than various
  208.  * <function>cairo_pattern_create_<emphasis>type</emphasis>()</function>
  209.  * functions, some of the pattern types can be implicitly created using various
  210.  * <function>cairo_set_source_<emphasis>type</emphasis>()</function> functions;
  211.  * for example cairo_set_source_rgb().
  212.  *
  213.  * The type of a pattern can be queried with cairo_pattern_get_type().
  214.  *
  215.  * Memory management of #cairo_pattern_t is done with
  216.  * cairo_pattern_reference() and cairo_pattern_destroy().
  217.  *
  218.  * Since: 1.0
  219.  **/
  220. typedef struct _cairo_pattern cairo_pattern_t;
  221.  
  222. /**
  223.  * cairo_destroy_func_t:
  224.  * @data: The data element being destroyed.
  225.  *
  226.  * #cairo_destroy_func_t the type of function which is called when a
  227.  * data element is destroyed. It is passed the pointer to the data
  228.  * element and should free any memory and resources allocated for it.
  229.  *
  230.  * Since: 1.0
  231.  **/
  232. typedef void (*cairo_destroy_func_t) (void *data);
  233.  
  234. /**
  235.  * cairo_user_data_key_t:
  236.  * @unused: not used; ignore.
  237.  *
  238.  * #cairo_user_data_key_t is used for attaching user data to cairo
  239.  * data structures.  The actual contents of the struct is never used,
  240.  * and there is no need to initialize the object; only the unique
  241.  * address of a #cairo_data_key_t object is used.  Typically, you
  242.  * would just use the address of a static #cairo_data_key_t object.
  243.  *
  244.  * Since: 1.0
  245.  **/
  246. typedef struct _cairo_user_data_key {
  247.     int unused;
  248. } cairo_user_data_key_t;
  249.  
  250. /**
  251.  * cairo_status_t:
  252.  * @CAIRO_STATUS_SUCCESS: no error has occurred (Since 1.0)
  253.  * @CAIRO_STATUS_NO_MEMORY: out of memory (Since 1.0)
  254.  * @CAIRO_STATUS_INVALID_RESTORE: cairo_restore() called without matching cairo_save() (Since 1.0)
  255.  * @CAIRO_STATUS_INVALID_POP_GROUP: no saved group to pop, i.e. cairo_pop_group() without matching cairo_push_group() (Since 1.0)
  256.  * @CAIRO_STATUS_NO_CURRENT_POINT: no current point defined (Since 1.0)
  257.  * @CAIRO_STATUS_INVALID_MATRIX: invalid matrix (not invertible) (Since 1.0)
  258.  * @CAIRO_STATUS_INVALID_STATUS: invalid value for an input #cairo_status_t (Since 1.0)
  259.  * @CAIRO_STATUS_NULL_POINTER: %NULL pointer (Since 1.0)
  260.  * @CAIRO_STATUS_INVALID_STRING: input string not valid UTF-8 (Since 1.0)
  261.  * @CAIRO_STATUS_INVALID_PATH_DATA: input path data not valid (Since 1.0)
  262.  * @CAIRO_STATUS_READ_ERROR: error while reading from input stream (Since 1.0)
  263.  * @CAIRO_STATUS_WRITE_ERROR: error while writing to output stream (Since 1.0)
  264.  * @CAIRO_STATUS_SURFACE_FINISHED: target surface has been finished (Since 1.0)
  265.  * @CAIRO_STATUS_SURFACE_TYPE_MISMATCH: the surface type is not appropriate for the operation (Since 1.0)
  266.  * @CAIRO_STATUS_PATTERN_TYPE_MISMATCH: the pattern type is not appropriate for the operation (Since 1.0)
  267.  * @CAIRO_STATUS_INVALID_CONTENT: invalid value for an input #cairo_content_t (Since 1.0)
  268.  * @CAIRO_STATUS_INVALID_FORMAT: invalid value for an input #cairo_format_t (Since 1.0)
  269.  * @CAIRO_STATUS_INVALID_VISUAL: invalid value for an input Visual* (Since 1.0)
  270.  * @CAIRO_STATUS_FILE_NOT_FOUND: file not found (Since 1.0)
  271.  * @CAIRO_STATUS_INVALID_DASH: invalid value for a dash setting (Since 1.0)
  272.  * @CAIRO_STATUS_INVALID_DSC_COMMENT: invalid value for a DSC comment (Since 1.2)
  273.  * @CAIRO_STATUS_INVALID_INDEX: invalid index passed to getter (Since 1.4)
  274.  * @CAIRO_STATUS_CLIP_NOT_REPRESENTABLE: clip region not representable in desired format (Since 1.4)
  275.  * @CAIRO_STATUS_TEMP_FILE_ERROR: error creating or writing to a temporary file (Since 1.6)
  276.  * @CAIRO_STATUS_INVALID_STRIDE: invalid value for stride (Since 1.6)
  277.  * @CAIRO_STATUS_FONT_TYPE_MISMATCH: the font type is not appropriate for the operation (Since 1.8)
  278.  * @CAIRO_STATUS_USER_FONT_IMMUTABLE: the user-font is immutable (Since 1.8)
  279.  * @CAIRO_STATUS_USER_FONT_ERROR: error occurred in a user-font callback function (Since 1.8)
  280.  * @CAIRO_STATUS_NEGATIVE_COUNT: negative number used where it is not allowed (Since 1.8)
  281.  * @CAIRO_STATUS_INVALID_CLUSTERS: input clusters do not represent the accompanying text and glyph array (Since 1.8)
  282.  * @CAIRO_STATUS_INVALID_SLANT: invalid value for an input #cairo_font_slant_t (Since 1.8)
  283.  * @CAIRO_STATUS_INVALID_WEIGHT: invalid value for an input #cairo_font_weight_t (Since 1.8)
  284.  * @CAIRO_STATUS_INVALID_SIZE: invalid value (typically too big) for the size of the input (surface, pattern, etc.) (Since 1.10)
  285.  * @CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED: user-font method not implemented (Since 1.10)
  286.  * @CAIRO_STATUS_DEVICE_TYPE_MISMATCH: the device type is not appropriate for the operation (Since 1.10)
  287.  * @CAIRO_STATUS_DEVICE_ERROR: an operation to the device caused an unspecified error (Since 1.10)
  288.  * @CAIRO_STATUS_INVALID_MESH_CONSTRUCTION: a mesh pattern
  289.  *   construction operation was used outside of a
  290.  *   cairo_mesh_pattern_begin_patch()/cairo_mesh_pattern_end_patch()
  291.  *   pair (Since 1.12)
  292.  * @CAIRO_STATUS_DEVICE_FINISHED: target device has been finished (Since 1.12)
  293.  * @CAIRO_STATUS_LAST_STATUS: this is a special value indicating the number of
  294.  *   status values defined in this enumeration.  When using this value, note
  295.  *   that the version of cairo at run-time may have additional status values
  296.  *   defined than the value of this symbol at compile-time. (Since 1.10)
  297.  *
  298.  * #cairo_status_t is used to indicate errors that can occur when
  299.  * using Cairo. In some cases it is returned directly by functions.
  300.  * but when using #cairo_t, the last error, if any, is stored in
  301.  * the context and can be retrieved with cairo_status().
  302.  *
  303.  * New entries may be added in future versions.  Use cairo_status_to_string()
  304.  * to get a human-readable representation of an error message.
  305.  *
  306.  * Since: 1.0
  307.  **/
  308. typedef enum _cairo_status {
  309.     CAIRO_STATUS_SUCCESS = 0,
  310.  
  311.     CAIRO_STATUS_NO_MEMORY,
  312.     CAIRO_STATUS_INVALID_RESTORE,
  313.     CAIRO_STATUS_INVALID_POP_GROUP,
  314.     CAIRO_STATUS_NO_CURRENT_POINT,
  315.     CAIRO_STATUS_INVALID_MATRIX,
  316.     CAIRO_STATUS_INVALID_STATUS,
  317.     CAIRO_STATUS_NULL_POINTER,
  318.     CAIRO_STATUS_INVALID_STRING,
  319.     CAIRO_STATUS_INVALID_PATH_DATA,
  320.     CAIRO_STATUS_READ_ERROR,
  321.     CAIRO_STATUS_WRITE_ERROR,
  322.     CAIRO_STATUS_SURFACE_FINISHED,
  323.     CAIRO_STATUS_SURFACE_TYPE_MISMATCH,
  324.     CAIRO_STATUS_PATTERN_TYPE_MISMATCH,
  325.     CAIRO_STATUS_INVALID_CONTENT,
  326.     CAIRO_STATUS_INVALID_FORMAT,
  327.     CAIRO_STATUS_INVALID_VISUAL,
  328.     CAIRO_STATUS_FILE_NOT_FOUND,
  329.     CAIRO_STATUS_INVALID_DASH,
  330.     CAIRO_STATUS_INVALID_DSC_COMMENT,
  331.     CAIRO_STATUS_INVALID_INDEX,
  332.     CAIRO_STATUS_CLIP_NOT_REPRESENTABLE,
  333.     CAIRO_STATUS_TEMP_FILE_ERROR,
  334.     CAIRO_STATUS_INVALID_STRIDE,
  335.     CAIRO_STATUS_FONT_TYPE_MISMATCH,
  336.     CAIRO_STATUS_USER_FONT_IMMUTABLE,
  337.     CAIRO_STATUS_USER_FONT_ERROR,
  338.     CAIRO_STATUS_NEGATIVE_COUNT,
  339.     CAIRO_STATUS_INVALID_CLUSTERS,
  340.     CAIRO_STATUS_INVALID_SLANT,
  341.     CAIRO_STATUS_INVALID_WEIGHT,
  342.     CAIRO_STATUS_INVALID_SIZE,
  343.     CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED,
  344.     CAIRO_STATUS_DEVICE_TYPE_MISMATCH,
  345.     CAIRO_STATUS_DEVICE_ERROR,
  346.     CAIRO_STATUS_INVALID_MESH_CONSTRUCTION,
  347.     CAIRO_STATUS_DEVICE_FINISHED,
  348.  
  349.     CAIRO_STATUS_LAST_STATUS
  350. } cairo_status_t;
  351.  
  352. /**
  353.  * cairo_content_t:
  354.  * @CAIRO_CONTENT_COLOR: The surface will hold color content only. (Since 1.0)
  355.  * @CAIRO_CONTENT_ALPHA: The surface will hold alpha content only. (Since 1.0)
  356.  * @CAIRO_CONTENT_COLOR_ALPHA: The surface will hold color and alpha content. (Since 1.0)
  357.  *
  358.  * #cairo_content_t is used to describe the content that a surface will
  359.  * contain, whether color information, alpha information (translucence
  360.  * vs. opacity), or both.
  361.  *
  362.  * Note: The large values here are designed to keep #cairo_content_t
  363.  * values distinct from #cairo_format_t values so that the
  364.  * implementation can detect the error if users confuse the two types.
  365.  *
  366.  * Since: 1.0
  367.  **/
  368. typedef enum _cairo_content {
  369.     CAIRO_CONTENT_COLOR         = 0x1000,
  370.     CAIRO_CONTENT_ALPHA         = 0x2000,
  371.     CAIRO_CONTENT_COLOR_ALPHA   = 0x3000
  372. } cairo_content_t;
  373.  
  374. /**
  375.  * cairo_format_t:
  376.  * @CAIRO_FORMAT_INVALID: no such format exists or is supported.
  377.  * @CAIRO_FORMAT_ARGB32: each pixel is a 32-bit quantity, with
  378.  *   alpha in the upper 8 bits, then red, then green, then blue.
  379.  *   The 32-bit quantities are stored native-endian. Pre-multiplied
  380.  *   alpha is used. (That is, 50% transparent red is 0x80800000,
  381.  *   not 0x80ff0000.) (Since 1.0)
  382.  * @CAIRO_FORMAT_RGB24: each pixel is a 32-bit quantity, with
  383.  *   the upper 8 bits unused. Red, Green, and Blue are stored
  384.  *   in the remaining 24 bits in that order. (Since 1.0)
  385.  * @CAIRO_FORMAT_A8: each pixel is a 8-bit quantity holding
  386.  *   an alpha value. (Since 1.0)
  387.  * @CAIRO_FORMAT_A1: each pixel is a 1-bit quantity holding
  388.  *   an alpha value. Pixels are packed together into 32-bit
  389.  *   quantities. The ordering of the bits matches the
  390.  *   endianess of the platform. On a big-endian machine, the
  391.  *   first pixel is in the uppermost bit, on a little-endian
  392.  *   machine the first pixel is in the least-significant bit. (Since 1.0)
  393.  * @CAIRO_FORMAT_RGB16_565: each pixel is a 16-bit quantity
  394.  *   with red in the upper 5 bits, then green in the middle
  395.  *   6 bits, and blue in the lower 5 bits. (Since 1.2)
  396.  * @CAIRO_FORMAT_RGB30: like RGB24 but with 10bpc. (Since 1.12)
  397.  *
  398.  * #cairo_format_t is used to identify the memory format of
  399.  * image data.
  400.  *
  401.  * New entries may be added in future versions.
  402.  *
  403.  * Since: 1.0
  404.  **/
  405. typedef enum _cairo_format {
  406.     CAIRO_FORMAT_INVALID   = -1,
  407.     CAIRO_FORMAT_ARGB32    = 0,
  408.     CAIRO_FORMAT_RGB24     = 1,
  409.     CAIRO_FORMAT_A8        = 2,
  410.     CAIRO_FORMAT_A1        = 3,
  411.     CAIRO_FORMAT_RGB16_565 = 4,
  412.     CAIRO_FORMAT_RGB30     = 5
  413. } cairo_format_t;
  414.  
  415.  
  416. /**
  417.  * cairo_write_func_t:
  418.  * @closure: the output closure
  419.  * @data: the buffer containing the data to write
  420.  * @length: the amount of data to write
  421.  *
  422.  * #cairo_write_func_t is the type of function which is called when a
  423.  * backend needs to write data to an output stream.  It is passed the
  424.  * closure which was specified by the user at the time the write
  425.  * function was registered, the data to write and the length of the
  426.  * data in bytes.  The write function should return
  427.  * %CAIRO_STATUS_SUCCESS if all the data was successfully written,
  428.  * %CAIRO_STATUS_WRITE_ERROR otherwise.
  429.  *
  430.  * Returns: the status code of the write operation
  431.  *
  432.  * Since: 1.0
  433.  **/
  434. typedef cairo_status_t (*cairo_write_func_t) (void                *closure,
  435.                                               const unsigned char *data,
  436.                                               unsigned int         length);
  437.  
  438. /**
  439.  * cairo_read_func_t:
  440.  * @closure: the input closure
  441.  * @data: the buffer into which to read the data
  442.  * @length: the amount of data to read
  443.  *
  444.  * #cairo_read_func_t is the type of function which is called when a
  445.  * backend needs to read data from an input stream.  It is passed the
  446.  * closure which was specified by the user at the time the read
  447.  * function was registered, the buffer to read the data into and the
  448.  * length of the data in bytes.  The read function should return
  449.  * %CAIRO_STATUS_SUCCESS if all the data was successfully read,
  450.  * %CAIRO_STATUS_READ_ERROR otherwise.
  451.  *
  452.  * Returns: the status code of the read operation
  453.  *
  454.  * Since: 1.0
  455.  **/
  456. typedef cairo_status_t (*cairo_read_func_t) (void               *closure,
  457.                                              unsigned char      *data,
  458.                                              unsigned int       length);
  459.  
  460. /**
  461.  * cairo_rectangle_int_t:
  462.  * @x: X coordinate of the left side of the rectangle
  463.  * @y: Y coordinate of the the top side of the rectangle
  464.  * @width: width of the rectangle
  465.  * @height: height of the rectangle
  466.  *
  467.  * A data structure for holding a rectangle with integer coordinates.
  468.  *
  469.  * Since: 1.10
  470.  **/
  471.  
  472. typedef struct _cairo_rectangle_int {
  473.     int x, y;
  474.     int width, height;
  475. } cairo_rectangle_int_t;
  476.  
  477.  
  478. /* Functions for manipulating state objects */
  479. cairo_public cairo_t *
  480. cairo_create (cairo_surface_t *target);
  481.  
  482. cairo_public cairo_t *
  483. cairo_reference (cairo_t *cr);
  484.  
  485. cairo_public void
  486. cairo_destroy (cairo_t *cr);
  487.  
  488. cairo_public unsigned int
  489. cairo_get_reference_count (cairo_t *cr);
  490.  
  491. cairo_public void *
  492. cairo_get_user_data (cairo_t                     *cr,
  493.                      const cairo_user_data_key_t *key);
  494.  
  495. cairo_public cairo_status_t
  496. cairo_set_user_data (cairo_t                     *cr,
  497.                      const cairo_user_data_key_t *key,
  498.                      void                        *user_data,
  499.                      cairo_destroy_func_t         destroy);
  500.  
  501. cairo_public void
  502. cairo_save (cairo_t *cr);
  503.  
  504. cairo_public void
  505. cairo_restore (cairo_t *cr);
  506.  
  507. cairo_public void
  508. cairo_push_group (cairo_t *cr);
  509.  
  510. cairo_public void
  511. cairo_push_group_with_content (cairo_t *cr, cairo_content_t content);
  512.  
  513. cairo_public cairo_pattern_t *
  514. cairo_pop_group (cairo_t *cr);
  515.  
  516. cairo_public void
  517. cairo_pop_group_to_source (cairo_t *cr);
  518.  
  519. /* Modify state */
  520.  
  521. /**
  522.  * cairo_operator_t:
  523.  * @CAIRO_OPERATOR_CLEAR: clear destination layer (bounded) (Since 1.0)
  524.  * @CAIRO_OPERATOR_SOURCE: replace destination layer (bounded) (Since 1.0)
  525.  * @CAIRO_OPERATOR_OVER: draw source layer on top of destination layer
  526.  * (bounded) (Since 1.0)
  527.  * @CAIRO_OPERATOR_IN: draw source where there was destination content
  528.  * (unbounded) (Since 1.0)
  529.  * @CAIRO_OPERATOR_OUT: draw source where there was no destination
  530.  * content (unbounded) (Since 1.0)
  531.  * @CAIRO_OPERATOR_ATOP: draw source on top of destination content and
  532.  * only there (Since 1.0)
  533.  * @CAIRO_OPERATOR_DEST: ignore the source (Since 1.0)
  534.  * @CAIRO_OPERATOR_DEST_OVER: draw destination on top of source (Since 1.0)
  535.  * @CAIRO_OPERATOR_DEST_IN: leave destination only where there was
  536.  * source content (unbounded) (Since 1.0)
  537.  * @CAIRO_OPERATOR_DEST_OUT: leave destination only where there was no
  538.  * source content (Since 1.0)
  539.  * @CAIRO_OPERATOR_DEST_ATOP: leave destination on top of source content
  540.  * and only there (unbounded) (Since 1.0)
  541.  * @CAIRO_OPERATOR_XOR: source and destination are shown where there is only
  542.  * one of them (Since 1.0)
  543.  * @CAIRO_OPERATOR_ADD: source and destination layers are accumulated (Since 1.0)
  544.  * @CAIRO_OPERATOR_SATURATE: like over, but assuming source and dest are
  545.  * disjoint geometries (Since 1.0)
  546.  * @CAIRO_OPERATOR_MULTIPLY: source and destination layers are multiplied.
  547.  * This causes the result to be at least as dark as the darker inputs. (Since 1.10)
  548.  * @CAIRO_OPERATOR_SCREEN: source and destination are complemented and
  549.  * multiplied. This causes the result to be at least as light as the lighter
  550.  * inputs. (Since 1.10)
  551.  * @CAIRO_OPERATOR_OVERLAY: multiplies or screens, depending on the
  552.  * lightness of the destination color. (Since 1.10)
  553.  * @CAIRO_OPERATOR_DARKEN: replaces the destination with the source if it
  554.  * is darker, otherwise keeps the source. (Since 1.10)
  555.  * @CAIRO_OPERATOR_LIGHTEN: replaces the destination with the source if it
  556.  * is lighter, otherwise keeps the source. (Since 1.10)
  557.  * @CAIRO_OPERATOR_COLOR_DODGE: brightens the destination color to reflect
  558.  * the source color. (Since 1.10)
  559.  * @CAIRO_OPERATOR_COLOR_BURN: darkens the destination color to reflect
  560.  * the source color. (Since 1.10)
  561.  * @CAIRO_OPERATOR_HARD_LIGHT: Multiplies or screens, dependent on source
  562.  * color. (Since 1.10)
  563.  * @CAIRO_OPERATOR_SOFT_LIGHT: Darkens or lightens, dependent on source
  564.  * color. (Since 1.10)
  565.  * @CAIRO_OPERATOR_DIFFERENCE: Takes the difference of the source and
  566.  * destination color. (Since 1.10)
  567.  * @CAIRO_OPERATOR_EXCLUSION: Produces an effect similar to difference, but
  568.  * with lower contrast. (Since 1.10)
  569.  * @CAIRO_OPERATOR_HSL_HUE: Creates a color with the hue of the source
  570.  * and the saturation and luminosity of the target. (Since 1.10)
  571.  * @CAIRO_OPERATOR_HSL_SATURATION: Creates a color with the saturation
  572.  * of the source and the hue and luminosity of the target. Painting with
  573.  * this mode onto a gray area produces no change. (Since 1.10)
  574.  * @CAIRO_OPERATOR_HSL_COLOR: Creates a color with the hue and saturation
  575.  * of the source and the luminosity of the target. This preserves the gray
  576.  * levels of the target and is useful for coloring monochrome images or
  577.  * tinting color images. (Since 1.10)
  578.  * @CAIRO_OPERATOR_HSL_LUMINOSITY: Creates a color with the luminosity of
  579.  * the source and the hue and saturation of the target. This produces an
  580.  * inverse effect to @CAIRO_OPERATOR_HSL_COLOR. (Since 1.10)
  581.  *
  582.  * #cairo_operator_t is used to set the compositing operator for all cairo
  583.  * drawing operations.
  584.  *
  585.  * The default operator is %CAIRO_OPERATOR_OVER.
  586.  *
  587.  * The operators marked as <firstterm>unbounded</firstterm> modify their
  588.  * destination even outside of the mask layer (that is, their effect is not
  589.  * bound by the mask layer).  However, their effect can still be limited by
  590.  * way of clipping.
  591.  *
  592.  * To keep things simple, the operator descriptions here
  593.  * document the behavior for when both source and destination are either fully
  594.  * transparent or fully opaque.  The actual implementation works for
  595.  * translucent layers too.
  596.  * For a more detailed explanation of the effects of each operator, including
  597.  * the mathematical definitions, see
  598.  * <ulink url="http://cairographics.org/operators/">http://cairographics.org/operators/</ulink>.
  599.  *
  600.  * Since: 1.0
  601.  **/
  602. typedef enum _cairo_operator {
  603.     CAIRO_OPERATOR_CLEAR,
  604.  
  605.     CAIRO_OPERATOR_SOURCE,
  606.     CAIRO_OPERATOR_OVER,
  607.     CAIRO_OPERATOR_IN,
  608.     CAIRO_OPERATOR_OUT,
  609.     CAIRO_OPERATOR_ATOP,
  610.  
  611.     CAIRO_OPERATOR_DEST,
  612.     CAIRO_OPERATOR_DEST_OVER,
  613.     CAIRO_OPERATOR_DEST_IN,
  614.     CAIRO_OPERATOR_DEST_OUT,
  615.     CAIRO_OPERATOR_DEST_ATOP,
  616.  
  617.     CAIRO_OPERATOR_XOR,
  618.     CAIRO_OPERATOR_ADD,
  619.     CAIRO_OPERATOR_SATURATE,
  620.  
  621.     CAIRO_OPERATOR_MULTIPLY,
  622.     CAIRO_OPERATOR_SCREEN,
  623.     CAIRO_OPERATOR_OVERLAY,
  624.     CAIRO_OPERATOR_DARKEN,
  625.     CAIRO_OPERATOR_LIGHTEN,
  626.     CAIRO_OPERATOR_COLOR_DODGE,
  627.     CAIRO_OPERATOR_COLOR_BURN,
  628.     CAIRO_OPERATOR_HARD_LIGHT,
  629.     CAIRO_OPERATOR_SOFT_LIGHT,
  630.     CAIRO_OPERATOR_DIFFERENCE,
  631.     CAIRO_OPERATOR_EXCLUSION,
  632.     CAIRO_OPERATOR_HSL_HUE,
  633.     CAIRO_OPERATOR_HSL_SATURATION,
  634.     CAIRO_OPERATOR_HSL_COLOR,
  635.     CAIRO_OPERATOR_HSL_LUMINOSITY
  636. } cairo_operator_t;
  637.  
  638. cairo_public void
  639. cairo_set_operator (cairo_t *cr, cairo_operator_t op);
  640.  
  641. cairo_public void
  642. cairo_set_source (cairo_t *cr, cairo_pattern_t *source);
  643.  
  644. cairo_public void
  645. cairo_set_source_rgb (cairo_t *cr, double red, double green, double blue);
  646.  
  647. cairo_public void
  648. cairo_set_source_rgba (cairo_t *cr,
  649.                        double red, double green, double blue,
  650.                        double alpha);
  651.  
  652. cairo_public void
  653. cairo_set_source_surface (cairo_t         *cr,
  654.                           cairo_surface_t *surface,
  655.                           double           x,
  656.                           double           y);
  657.  
  658. cairo_public void
  659. cairo_set_tolerance (cairo_t *cr, double tolerance);
  660.  
  661. /**
  662.  * cairo_antialias_t:
  663.  * @CAIRO_ANTIALIAS_DEFAULT: Use the default antialiasing for
  664.  *   the subsystem and target device, since 1.0
  665.  * @CAIRO_ANTIALIAS_NONE: Use a bilevel alpha mask, since 1.0
  666.  * @CAIRO_ANTIALIAS_GRAY: Perform single-color antialiasing (using
  667.  *  shades of gray for black text on a white background, for example), since 1.0
  668.  * @CAIRO_ANTIALIAS_SUBPIXEL: Perform antialiasing by taking
  669.  *  advantage of the order of subpixel elements on devices
  670.  *  such as LCD panels, since 1.0
  671.  * @CAIRO_ANTIALIAS_FAST: Hint that the backend should perform some
  672.  * antialiasing but prefer speed over quality, since 1.12
  673.  * @CAIRO_ANTIALIAS_GOOD: The backend should balance quality against
  674.  * performance, since 1.12
  675.  * @CAIRO_ANTIALIAS_BEST: Hint that the backend should render at the highest
  676.  * quality, sacrificing speed if necessary, since 1.12
  677.  *
  678.  * Specifies the type of antialiasing to do when rendering text or shapes.
  679.  *
  680.  * As it is not necessarily clear from the above what advantages a particular
  681.  * antialias method provides, since 1.12, there is also a set of hints:
  682.  * @CAIRO_ANTIALIAS_FAST: Allow the backend to degrade raster quality for speed
  683.  * @CAIRO_ANTIALIAS_GOOD: A balance between speed and quality
  684.  * @CAIRO_ANTIALIAS_BEST: A high-fidelity, but potentially slow, raster mode
  685.  *
  686.  * These make no guarantee on how the backend will perform its rasterisation
  687.  * (if it even rasterises!), nor that they have any differing effect other
  688.  * than to enable some form of antialiasing. In the case of glyph rendering,
  689.  * @CAIRO_ANTIALIAS_FAST and @CAIRO_ANTIALIAS_GOOD will be mapped to
  690.  * @CAIRO_ANTIALIAS_GRAY, with @CAIRO_ANTALIAS_BEST being equivalent to
  691.  * @CAIRO_ANTIALIAS_SUBPIXEL.
  692.  *
  693.  * The interpretation of @CAIRO_ANTIALIAS_DEFAULT is left entirely up to
  694.  * the backend, typically this will be similar to @CAIRO_ANTIALIAS_GOOD.
  695.  *
  696.  * Since: 1.0
  697.  **/
  698. typedef enum _cairo_antialias {
  699.     CAIRO_ANTIALIAS_DEFAULT,
  700.  
  701.     /* method */
  702.     CAIRO_ANTIALIAS_NONE,
  703.     CAIRO_ANTIALIAS_GRAY,
  704.     CAIRO_ANTIALIAS_SUBPIXEL,
  705.  
  706.     /* hints */
  707.     CAIRO_ANTIALIAS_FAST,
  708.     CAIRO_ANTIALIAS_GOOD,
  709.     CAIRO_ANTIALIAS_BEST
  710. } cairo_antialias_t;
  711.  
  712. cairo_public void
  713. cairo_set_antialias (cairo_t *cr, cairo_antialias_t antialias);
  714.  
  715. /**
  716.  * cairo_fill_rule_t:
  717.  * @CAIRO_FILL_RULE_WINDING: If the path crosses the ray from
  718.  * left-to-right, counts +1. If the path crosses the ray
  719.  * from right to left, counts -1. (Left and right are determined
  720.  * from the perspective of looking along the ray from the starting
  721.  * point.) If the total count is non-zero, the point will be filled. (Since 1.0)
  722.  * @CAIRO_FILL_RULE_EVEN_ODD: Counts the total number of
  723.  * intersections, without regard to the orientation of the contour. If
  724.  * the total number of intersections is odd, the point will be
  725.  * filled. (Since 1.0)
  726.  *
  727.  * #cairo_fill_rule_t is used to select how paths are filled. For both
  728.  * fill rules, whether or not a point is included in the fill is
  729.  * determined by taking a ray from that point to infinity and looking
  730.  * at intersections with the path. The ray can be in any direction,
  731.  * as long as it doesn't pass through the end point of a segment
  732.  * or have a tricky intersection such as intersecting tangent to the path.
  733.  * (Note that filling is not actually implemented in this way. This
  734.  * is just a description of the rule that is applied.)
  735.  *
  736.  * The default fill rule is %CAIRO_FILL_RULE_WINDING.
  737.  *
  738.  * New entries may be added in future versions.
  739.  *
  740.  * Since: 1.0
  741.  **/
  742. typedef enum _cairo_fill_rule {
  743.     CAIRO_FILL_RULE_WINDING,
  744.     CAIRO_FILL_RULE_EVEN_ODD
  745. } cairo_fill_rule_t;
  746.  
  747. cairo_public void
  748. cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule);
  749.  
  750. cairo_public void
  751. cairo_set_line_width (cairo_t *cr, double width);
  752.  
  753. /**
  754.  * cairo_line_cap_t:
  755.  * @CAIRO_LINE_CAP_BUTT: start(stop) the line exactly at the start(end) point (Since 1.0)
  756.  * @CAIRO_LINE_CAP_ROUND: use a round ending, the center of the circle is the end point (Since 1.0)
  757.  * @CAIRO_LINE_CAP_SQUARE: use squared ending, the center of the square is the end point (Since 1.0)
  758.  *
  759.  * Specifies how to render the endpoints of the path when stroking.
  760.  *
  761.  * The default line cap style is %CAIRO_LINE_CAP_BUTT.
  762.  *
  763.  * Since: 1.0
  764.  **/
  765. typedef enum _cairo_line_cap {
  766.     CAIRO_LINE_CAP_BUTT,
  767.     CAIRO_LINE_CAP_ROUND,
  768.     CAIRO_LINE_CAP_SQUARE
  769. } cairo_line_cap_t;
  770.  
  771. cairo_public void
  772. cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap);
  773.  
  774. /**
  775.  * cairo_line_join_t:
  776.  * @CAIRO_LINE_JOIN_MITER: use a sharp (angled) corner, see
  777.  * cairo_set_miter_limit() (Since 1.0)
  778.  * @CAIRO_LINE_JOIN_ROUND: use a rounded join, the center of the circle is the
  779.  * joint point (Since 1.0)
  780.  * @CAIRO_LINE_JOIN_BEVEL: use a cut-off join, the join is cut off at half
  781.  * the line width from the joint point (Since 1.0)
  782.  *
  783.  * Specifies how to render the junction of two lines when stroking.
  784.  *
  785.  * The default line join style is %CAIRO_LINE_JOIN_MITER.
  786.  *
  787.  * Since: 1.0
  788.  **/
  789. typedef enum _cairo_line_join {
  790.     CAIRO_LINE_JOIN_MITER,
  791.     CAIRO_LINE_JOIN_ROUND,
  792.     CAIRO_LINE_JOIN_BEVEL
  793. } cairo_line_join_t;
  794.  
  795. cairo_public void
  796. cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join);
  797.  
  798. cairo_public void
  799. cairo_set_dash (cairo_t      *cr,
  800.                 const double *dashes,
  801.                 int           num_dashes,
  802.                 double        offset);
  803.  
  804. cairo_public void
  805. cairo_set_miter_limit (cairo_t *cr, double limit);
  806.  
  807. cairo_public void
  808. cairo_translate (cairo_t *cr, double tx, double ty);
  809.  
  810. cairo_public void
  811. cairo_scale (cairo_t *cr, double sx, double sy);
  812.  
  813. cairo_public void
  814. cairo_rotate (cairo_t *cr, double angle);
  815.  
  816. cairo_public void
  817. cairo_transform (cairo_t              *cr,
  818.                  const cairo_matrix_t *matrix);
  819.  
  820. cairo_public void
  821. cairo_set_matrix (cairo_t              *cr,
  822.                   const cairo_matrix_t *matrix);
  823.  
  824. cairo_public void
  825. cairo_identity_matrix (cairo_t *cr);
  826.  
  827. cairo_public void
  828. cairo_user_to_device (cairo_t *cr, double *x, double *y);
  829.  
  830. cairo_public void
  831. cairo_user_to_device_distance (cairo_t *cr, double *dx, double *dy);
  832.  
  833. cairo_public void
  834. cairo_device_to_user (cairo_t *cr, double *x, double *y);
  835.  
  836. cairo_public void
  837. cairo_device_to_user_distance (cairo_t *cr, double *dx, double *dy);
  838.  
  839. /* Path creation functions */
  840. cairo_public void
  841. cairo_new_path (cairo_t *cr);
  842.  
  843. cairo_public void
  844. cairo_move_to (cairo_t *cr, double x, double y);
  845.  
  846. cairo_public void
  847. cairo_new_sub_path (cairo_t *cr);
  848.  
  849. cairo_public void
  850. cairo_line_to (cairo_t *cr, double x, double y);
  851.  
  852. cairo_public void
  853. cairo_curve_to (cairo_t *cr,
  854.                 double x1, double y1,
  855.                 double x2, double y2,
  856.                 double x3, double y3);
  857.  
  858. cairo_public void
  859. cairo_arc (cairo_t *cr,
  860.            double xc, double yc,
  861.            double radius,
  862.            double angle1, double angle2);
  863.  
  864. cairo_public void
  865. cairo_arc_negative (cairo_t *cr,
  866.                     double xc, double yc,
  867.                     double radius,
  868.                     double angle1, double angle2);
  869.  
  870. /* XXX: NYI
  871. cairo_public void
  872. cairo_arc_to (cairo_t *cr,
  873.               double x1, double y1,
  874.               double x2, double y2,
  875.               double radius);
  876. */
  877.  
  878. cairo_public void
  879. cairo_rel_move_to (cairo_t *cr, double dx, double dy);
  880.  
  881. cairo_public void
  882. cairo_rel_line_to (cairo_t *cr, double dx, double dy);
  883.  
  884. cairo_public void
  885. cairo_rel_curve_to (cairo_t *cr,
  886.                     double dx1, double dy1,
  887.                     double dx2, double dy2,
  888.                     double dx3, double dy3);
  889.  
  890. cairo_public void
  891. cairo_rectangle (cairo_t *cr,
  892.                  double x, double y,
  893.                  double width, double height);
  894.  
  895. /* XXX: NYI
  896. cairo_public void
  897. cairo_stroke_to_path (cairo_t *cr);
  898. */
  899.  
  900. cairo_public void
  901. cairo_close_path (cairo_t *cr);
  902.  
  903. cairo_public void
  904. cairo_path_extents (cairo_t *cr,
  905.                     double *x1, double *y1,
  906.                     double *x2, double *y2);
  907.  
  908. /* Painting functions */
  909. cairo_public void
  910. cairo_paint (cairo_t *cr);
  911.  
  912. cairo_public void
  913. cairo_paint_with_alpha (cairo_t *cr,
  914.                         double   alpha);
  915.  
  916. cairo_public void
  917. cairo_mask (cairo_t         *cr,
  918.             cairo_pattern_t *pattern);
  919.  
  920. cairo_public void
  921. cairo_mask_surface (cairo_t         *cr,
  922.                     cairo_surface_t *surface,
  923.                     double           surface_x,
  924.                     double           surface_y);
  925.  
  926. cairo_public void
  927. cairo_stroke (cairo_t *cr);
  928.  
  929. cairo_public void
  930. cairo_stroke_preserve (cairo_t *cr);
  931.  
  932. cairo_public void
  933. cairo_fill (cairo_t *cr);
  934.  
  935. cairo_public void
  936. cairo_fill_preserve (cairo_t *cr);
  937.  
  938. cairo_public void
  939. cairo_copy_page (cairo_t *cr);
  940.  
  941. cairo_public void
  942. cairo_show_page (cairo_t *cr);
  943.  
  944. /* Insideness testing */
  945. cairo_public cairo_bool_t
  946. cairo_in_stroke (cairo_t *cr, double x, double y);
  947.  
  948. cairo_public cairo_bool_t
  949. cairo_in_fill (cairo_t *cr, double x, double y);
  950.  
  951. cairo_public cairo_bool_t
  952. cairo_in_clip (cairo_t *cr, double x, double y);
  953.  
  954. /* Rectangular extents */
  955. cairo_public void
  956. cairo_stroke_extents (cairo_t *cr,
  957.                       double *x1, double *y1,
  958.                       double *x2, double *y2);
  959.  
  960. cairo_public void
  961. cairo_fill_extents (cairo_t *cr,
  962.                     double *x1, double *y1,
  963.                     double *x2, double *y2);
  964.  
  965. /* Clipping */
  966. cairo_public void
  967. cairo_reset_clip (cairo_t *cr);
  968.  
  969. cairo_public void
  970. cairo_clip (cairo_t *cr);
  971.  
  972. cairo_public void
  973. cairo_clip_preserve (cairo_t *cr);
  974.  
  975. cairo_public void
  976. cairo_clip_extents (cairo_t *cr,
  977.                     double *x1, double *y1,
  978.                     double *x2, double *y2);
  979.  
  980. /**
  981.  * cairo_rectangle_t:
  982.  * @x: X coordinate of the left side of the rectangle
  983.  * @y: Y coordinate of the the top side of the rectangle
  984.  * @width: width of the rectangle
  985.  * @height: height of the rectangle
  986.  *
  987.  * A data structure for holding a rectangle.
  988.  *
  989.  * Since: 1.4
  990.  **/
  991. typedef struct _cairo_rectangle {
  992.     double x, y, width, height;
  993. } cairo_rectangle_t;
  994.  
  995. /**
  996.  * cairo_rectangle_list_t:
  997.  * @status: Error status of the rectangle list
  998.  * @rectangles: Array containing the rectangles
  999.  * @num_rectangles: Number of rectangles in this list
  1000.  *
  1001.  * A data structure for holding a dynamically allocated
  1002.  * array of rectangles.
  1003.  *
  1004.  * Since: 1.4
  1005.  **/
  1006. typedef struct _cairo_rectangle_list {
  1007.     cairo_status_t     status;
  1008.     cairo_rectangle_t *rectangles;
  1009.     int                num_rectangles;
  1010. } cairo_rectangle_list_t;
  1011.  
  1012. cairo_public cairo_rectangle_list_t *
  1013. cairo_copy_clip_rectangle_list (cairo_t *cr);
  1014.  
  1015. cairo_public void
  1016. cairo_rectangle_list_destroy (cairo_rectangle_list_t *rectangle_list);
  1017.  
  1018. /* Font/Text functions */
  1019.  
  1020. /**
  1021.  * cairo_scaled_font_t:
  1022.  *
  1023.  * A #cairo_scaled_font_t is a font scaled to a particular size and device
  1024.  * resolution. A #cairo_scaled_font_t is most useful for low-level font
  1025.  * usage where a library or application wants to cache a reference
  1026.  * to a scaled font to speed up the computation of metrics.
  1027.  *
  1028.  * There are various types of scaled fonts, depending on the
  1029.  * <firstterm>font backend</firstterm> they use. The type of a
  1030.  * scaled font can be queried using cairo_scaled_font_get_type().
  1031.  *
  1032.  * Memory management of #cairo_scaled_font_t is done with
  1033.  * cairo_scaled_font_reference() and cairo_scaled_font_destroy().
  1034.  *
  1035.  * Since: 1.0
  1036.  **/
  1037. typedef struct _cairo_scaled_font cairo_scaled_font_t;
  1038.  
  1039. /**
  1040.  * cairo_font_face_t:
  1041.  *
  1042.  * A #cairo_font_face_t specifies all aspects of a font other
  1043.  * than the size or font matrix (a font matrix is used to distort
  1044.  * a font by sheering it or scaling it unequally in the two
  1045.  * directions) . A font face can be set on a #cairo_t by using
  1046.  * cairo_set_font_face(); the size and font matrix are set with
  1047.  * cairo_set_font_size() and cairo_set_font_matrix().
  1048.  *
  1049.  * There are various types of font faces, depending on the
  1050.  * <firstterm>font backend</firstterm> they use. The type of a
  1051.  * font face can be queried using cairo_font_face_get_type().
  1052.  *
  1053.  * Memory management of #cairo_font_face_t is done with
  1054.  * cairo_font_face_reference() and cairo_font_face_destroy().
  1055.  *
  1056.  * Since: 1.0
  1057.  **/
  1058. typedef struct _cairo_font_face cairo_font_face_t;
  1059.  
  1060. /**
  1061.  * cairo_glyph_t:
  1062.  * @index: glyph index in the font. The exact interpretation of the
  1063.  *      glyph index depends on the font technology being used.
  1064.  * @x: the offset in the X direction between the origin used for
  1065.  *     drawing or measuring the string and the origin of this glyph.
  1066.  * @y: the offset in the Y direction between the origin used for
  1067.  *     drawing or measuring the string and the origin of this glyph.
  1068.  *
  1069.  * The #cairo_glyph_t structure holds information about a single glyph
  1070.  * when drawing or measuring text. A font is (in simple terms) a
  1071.  * collection of shapes used to draw text. A glyph is one of these
  1072.  * shapes. There can be multiple glyphs for a single character
  1073.  * (alternates to be used in different contexts, for example), or a
  1074.  * glyph can be a <firstterm>ligature</firstterm> of multiple
  1075.  * characters. Cairo doesn't expose any way of converting input text
  1076.  * into glyphs, so in order to use the Cairo interfaces that take
  1077.  * arrays of glyphs, you must directly access the appropriate
  1078.  * underlying font system.
  1079.  *
  1080.  * Note that the offsets given by @x and @y are not cumulative. When
  1081.  * drawing or measuring text, each glyph is individually positioned
  1082.  * with respect to the overall origin
  1083.  *
  1084.  * Since: 1.0
  1085.  **/
  1086. typedef struct {
  1087.     unsigned long        index;
  1088.     double               x;
  1089.     double               y;
  1090. } cairo_glyph_t;
  1091.  
  1092. cairo_public cairo_glyph_t *
  1093. cairo_glyph_allocate (int num_glyphs);
  1094.  
  1095. cairo_public void
  1096. cairo_glyph_free (cairo_glyph_t *glyphs);
  1097.  
  1098. /**
  1099.  * cairo_text_cluster_t:
  1100.  * @num_bytes: the number of bytes of UTF-8 text covered by cluster
  1101.  * @num_glyphs: the number of glyphs covered by cluster
  1102.  *
  1103.  * The #cairo_text_cluster_t structure holds information about a single
  1104.  * <firstterm>text cluster</firstterm>.  A text cluster is a minimal
  1105.  * mapping of some glyphs corresponding to some UTF-8 text.
  1106.  *
  1107.  * For a cluster to be valid, both @num_bytes and @num_glyphs should
  1108.  * be non-negative, and at least one should be non-zero.
  1109.  * Note that clusters with zero glyphs are not as well supported as
  1110.  * normal clusters.  For example, PDF rendering applications typically
  1111.  * ignore those clusters when PDF text is being selected.
  1112.  *
  1113.  * See cairo_show_text_glyphs() for how clusters are used in advanced
  1114.  * text operations.
  1115.  *
  1116.  * Since: 1.8
  1117.  **/
  1118. typedef struct {
  1119.     int        num_bytes;
  1120.     int        num_glyphs;
  1121. } cairo_text_cluster_t;
  1122.  
  1123. cairo_public cairo_text_cluster_t *
  1124. cairo_text_cluster_allocate (int num_clusters);
  1125.  
  1126. cairo_public void
  1127. cairo_text_cluster_free (cairo_text_cluster_t *clusters);
  1128.  
  1129. /**
  1130.  * cairo_text_cluster_flags_t:
  1131.  * @CAIRO_TEXT_CLUSTER_FLAG_BACKWARD: The clusters in the cluster array
  1132.  * map to glyphs in the glyph array from end to start. (Since 1.8)
  1133.  *
  1134.  * Specifies properties of a text cluster mapping.
  1135.  *
  1136.  * Since: 1.8
  1137.  **/
  1138. typedef enum _cairo_text_cluster_flags {
  1139.     CAIRO_TEXT_CLUSTER_FLAG_BACKWARD = 0x00000001
  1140. } cairo_text_cluster_flags_t;
  1141.  
  1142. /**
  1143.  * cairo_text_extents_t:
  1144.  * @x_bearing: the horizontal distance from the origin to the
  1145.  *   leftmost part of the glyphs as drawn. Positive if the
  1146.  *   glyphs lie entirely to the right of the origin.
  1147.  * @y_bearing: the vertical distance from the origin to the
  1148.  *   topmost part of the glyphs as drawn. Positive only if the
  1149.  *   glyphs lie completely below the origin; will usually be
  1150.  *   negative.
  1151.  * @width: width of the glyphs as drawn
  1152.  * @height: height of the glyphs as drawn
  1153.  * @x_advance:distance to advance in the X direction
  1154.  *    after drawing these glyphs
  1155.  * @y_advance: distance to advance in the Y direction
  1156.  *   after drawing these glyphs. Will typically be zero except
  1157.  *   for vertical text layout as found in East-Asian languages.
  1158.  *
  1159.  * The #cairo_text_extents_t structure stores the extents of a single
  1160.  * glyph or a string of glyphs in user-space coordinates. Because text
  1161.  * extents are in user-space coordinates, they are mostly, but not
  1162.  * entirely, independent of the current transformation matrix. If you call
  1163.  * <literal>cairo_scale(cr, 2.0, 2.0)</literal>, text will
  1164.  * be drawn twice as big, but the reported text extents will not be
  1165.  * doubled. They will change slightly due to hinting (so you can't
  1166.  * assume that metrics are independent of the transformation matrix),
  1167.  * but otherwise will remain unchanged.
  1168.  *
  1169.  * Since: 1.0
  1170.  **/
  1171. typedef struct {
  1172.     double x_bearing;
  1173.     double y_bearing;
  1174.     double width;
  1175.     double height;
  1176.     double x_advance;
  1177.     double y_advance;
  1178. } cairo_text_extents_t;
  1179.  
  1180. /**
  1181.  * cairo_font_extents_t:
  1182.  * @ascent: the distance that the font extends above the baseline.
  1183.  *          Note that this is not always exactly equal to the maximum
  1184.  *          of the extents of all the glyphs in the font, but rather
  1185.  *          is picked to express the font designer's intent as to
  1186.  *          how the font should align with elements above it.
  1187.  * @descent: the distance that the font extends below the baseline.
  1188.  *           This value is positive for typical fonts that include
  1189.  *           portions below the baseline. Note that this is not always
  1190.  *           exactly equal to the maximum of the extents of all the
  1191.  *           glyphs in the font, but rather is picked to express the
  1192.  *           font designer's intent as to how the font should
  1193.  *           align with elements below it.
  1194.  * @height: the recommended vertical distance between baselines when
  1195.  *          setting consecutive lines of text with the font. This
  1196.  *          is greater than @ascent+@descent by a
  1197.  *          quantity known as the <firstterm>line spacing</firstterm>
  1198.  *          or <firstterm>external leading</firstterm>. When space
  1199.  *          is at a premium, most fonts can be set with only
  1200.  *          a distance of @ascent+@descent between lines.
  1201.  * @max_x_advance: the maximum distance in the X direction that
  1202.  *         the origin is advanced for any glyph in the font.
  1203.  * @max_y_advance: the maximum distance in the Y direction that
  1204.  *         the origin is advanced for any glyph in the font.
  1205.  *         This will be zero for normal fonts used for horizontal
  1206.  *         writing. (The scripts of East Asia are sometimes written
  1207.  *         vertically.)
  1208.  *
  1209.  * The #cairo_font_extents_t structure stores metric information for
  1210.  * a font. Values are given in the current user-space coordinate
  1211.  * system.
  1212.  *
  1213.  * Because font metrics are in user-space coordinates, they are
  1214.  * mostly, but not entirely, independent of the current transformation
  1215.  * matrix. If you call <literal>cairo_scale(cr, 2.0, 2.0)</literal>,
  1216.  * text will be drawn twice as big, but the reported text extents will
  1217.  * not be doubled. They will change slightly due to hinting (so you
  1218.  * can't assume that metrics are independent of the transformation
  1219.  * matrix), but otherwise will remain unchanged.
  1220.  *
  1221.  * Since: 1.0
  1222.  **/
  1223. typedef struct {
  1224.     double ascent;
  1225.     double descent;
  1226.     double height;
  1227.     double max_x_advance;
  1228.     double max_y_advance;
  1229. } cairo_font_extents_t;
  1230.  
  1231. /**
  1232.  * cairo_font_slant_t:
  1233.  * @CAIRO_FONT_SLANT_NORMAL: Upright font style, since 1.0
  1234.  * @CAIRO_FONT_SLANT_ITALIC: Italic font style, since 1.0
  1235.  * @CAIRO_FONT_SLANT_OBLIQUE: Oblique font style, since 1.0
  1236.  *
  1237.  * Specifies variants of a font face based on their slant.
  1238.  *
  1239.  * Since: 1.0
  1240.  **/
  1241. typedef enum _cairo_font_slant {
  1242.     CAIRO_FONT_SLANT_NORMAL,
  1243.     CAIRO_FONT_SLANT_ITALIC,
  1244.     CAIRO_FONT_SLANT_OBLIQUE
  1245. } cairo_font_slant_t;
  1246.  
  1247. /**
  1248.  * cairo_font_weight_t:
  1249.  * @CAIRO_FONT_WEIGHT_NORMAL: Normal font weight, since 1.0
  1250.  * @CAIRO_FONT_WEIGHT_BOLD: Bold font weight, since 1.0
  1251.  *
  1252.  * Specifies variants of a font face based on their weight.
  1253.  *
  1254.  * Since: 1.0
  1255.  **/
  1256. typedef enum _cairo_font_weight {
  1257.     CAIRO_FONT_WEIGHT_NORMAL,
  1258.     CAIRO_FONT_WEIGHT_BOLD
  1259. } cairo_font_weight_t;
  1260.  
  1261. /**
  1262.  * cairo_subpixel_order_t:
  1263.  * @CAIRO_SUBPIXEL_ORDER_DEFAULT: Use the default subpixel order for
  1264.  *   for the target device, since 1.0
  1265.  * @CAIRO_SUBPIXEL_ORDER_RGB: Subpixel elements are arranged horizontally
  1266.  *   with red at the left, since 1.0
  1267.  * @CAIRO_SUBPIXEL_ORDER_BGR:  Subpixel elements are arranged horizontally
  1268.  *   with blue at the left, since 1.0
  1269.  * @CAIRO_SUBPIXEL_ORDER_VRGB: Subpixel elements are arranged vertically
  1270.  *   with red at the top, since 1.0
  1271.  * @CAIRO_SUBPIXEL_ORDER_VBGR: Subpixel elements are arranged vertically
  1272.  *   with blue at the top, since 1.0
  1273.  *
  1274.  * The subpixel order specifies the order of color elements within
  1275.  * each pixel on the display device when rendering with an
  1276.  * antialiasing mode of %CAIRO_ANTIALIAS_SUBPIXEL.
  1277.  *
  1278.  * Since: 1.0
  1279.  **/
  1280. typedef enum _cairo_subpixel_order {
  1281.     CAIRO_SUBPIXEL_ORDER_DEFAULT,
  1282.     CAIRO_SUBPIXEL_ORDER_RGB,
  1283.     CAIRO_SUBPIXEL_ORDER_BGR,
  1284.     CAIRO_SUBPIXEL_ORDER_VRGB,
  1285.     CAIRO_SUBPIXEL_ORDER_VBGR
  1286. } cairo_subpixel_order_t;
  1287.  
  1288. /**
  1289.  * cairo_hint_style_t:
  1290.  * @CAIRO_HINT_STYLE_DEFAULT: Use the default hint style for
  1291.  *   font backend and target device, since 1.0
  1292.  * @CAIRO_HINT_STYLE_NONE: Do not hint outlines, since 1.0
  1293.  * @CAIRO_HINT_STYLE_SLIGHT: Hint outlines slightly to improve
  1294.  *   contrast while retaining good fidelity to the original
  1295.  *   shapes, since 1.0
  1296.  * @CAIRO_HINT_STYLE_MEDIUM: Hint outlines with medium strength
  1297.  *   giving a compromise between fidelity to the original shapes
  1298.  *   and contrast, since 1.0
  1299.  * @CAIRO_HINT_STYLE_FULL: Hint outlines to maximize contrast, since 1.0
  1300.  *
  1301.  * Specifies the type of hinting to do on font outlines. Hinting
  1302.  * is the process of fitting outlines to the pixel grid in order
  1303.  * to improve the appearance of the result. Since hinting outlines
  1304.  * involves distorting them, it also reduces the faithfulness
  1305.  * to the original outline shapes. Not all of the outline hinting
  1306.  * styles are supported by all font backends.
  1307.  *
  1308.  * New entries may be added in future versions.
  1309.  *
  1310.  * Since: 1.0
  1311.  **/
  1312. typedef enum _cairo_hint_style {
  1313.     CAIRO_HINT_STYLE_DEFAULT,
  1314.     CAIRO_HINT_STYLE_NONE,
  1315.     CAIRO_HINT_STYLE_SLIGHT,
  1316.     CAIRO_HINT_STYLE_MEDIUM,
  1317.     CAIRO_HINT_STYLE_FULL
  1318. } cairo_hint_style_t;
  1319.  
  1320. /**
  1321.  * cairo_hint_metrics_t:
  1322.  * @CAIRO_HINT_METRICS_DEFAULT: Hint metrics in the default
  1323.  *  manner for the font backend and target device, since 1.0
  1324.  * @CAIRO_HINT_METRICS_OFF: Do not hint font metrics, since 1.0
  1325.  * @CAIRO_HINT_METRICS_ON: Hint font metrics, since 1.0
  1326.  *
  1327.  * Specifies whether to hint font metrics; hinting font metrics
  1328.  * means quantizing them so that they are integer values in
  1329.  * device space. Doing this improves the consistency of
  1330.  * letter and line spacing, however it also means that text
  1331.  * will be laid out differently at different zoom factors.
  1332.  *
  1333.  * Since: 1.0
  1334.  **/
  1335. typedef enum _cairo_hint_metrics {
  1336.     CAIRO_HINT_METRICS_DEFAULT,
  1337.     CAIRO_HINT_METRICS_OFF,
  1338.     CAIRO_HINT_METRICS_ON
  1339. } cairo_hint_metrics_t;
  1340.  
  1341. /**
  1342.  * cairo_font_options_t:
  1343.  *
  1344.  * An opaque structure holding all options that are used when
  1345.  * rendering fonts.
  1346.  *
  1347.  * Individual features of a #cairo_font_options_t can be set or
  1348.  * accessed using functions named
  1349.  * <function>cairo_font_options_set_<emphasis>feature_name</emphasis>()</function> and
  1350.  * <function>cairo_font_options_get_<emphasis>feature_name</emphasis>()</function>, like
  1351.  * cairo_font_options_set_antialias() and
  1352.  * cairo_font_options_get_antialias().
  1353.  *
  1354.  * New features may be added to a #cairo_font_options_t in the
  1355.  * future.  For this reason, cairo_font_options_copy(),
  1356.  * cairo_font_options_equal(), cairo_font_options_merge(), and
  1357.  * cairo_font_options_hash() should be used to copy, check
  1358.  * for equality, merge, or compute a hash value of
  1359.  * #cairo_font_options_t objects.
  1360.  *
  1361.  * Since: 1.0
  1362.  **/
  1363. typedef struct _cairo_font_options cairo_font_options_t;
  1364.  
  1365. cairo_public cairo_font_options_t *
  1366. cairo_font_options_create (void);
  1367.  
  1368. cairo_public cairo_font_options_t *
  1369. cairo_font_options_copy (const cairo_font_options_t *original);
  1370.  
  1371. cairo_public void
  1372. cairo_font_options_destroy (cairo_font_options_t *options);
  1373.  
  1374. cairo_public cairo_status_t
  1375. cairo_font_options_status (cairo_font_options_t *options);
  1376.  
  1377. cairo_public void
  1378. cairo_font_options_merge (cairo_font_options_t       *options,
  1379.                           const cairo_font_options_t *other);
  1380. cairo_public cairo_bool_t
  1381. cairo_font_options_equal (const cairo_font_options_t *options,
  1382.                           const cairo_font_options_t *other);
  1383.  
  1384. cairo_public unsigned long
  1385. cairo_font_options_hash (const cairo_font_options_t *options);
  1386.  
  1387. cairo_public void
  1388. cairo_font_options_set_antialias (cairo_font_options_t *options,
  1389.                                   cairo_antialias_t     antialias);
  1390. cairo_public cairo_antialias_t
  1391. cairo_font_options_get_antialias (const cairo_font_options_t *options);
  1392.  
  1393. cairo_public void
  1394. cairo_font_options_set_subpixel_order (cairo_font_options_t   *options,
  1395.                                        cairo_subpixel_order_t  subpixel_order);
  1396. cairo_public cairo_subpixel_order_t
  1397. cairo_font_options_get_subpixel_order (const cairo_font_options_t *options);
  1398.  
  1399. cairo_public void
  1400. cairo_font_options_set_hint_style (cairo_font_options_t *options,
  1401.                                    cairo_hint_style_t     hint_style);
  1402. cairo_public cairo_hint_style_t
  1403. cairo_font_options_get_hint_style (const cairo_font_options_t *options);
  1404.  
  1405. cairo_public void
  1406. cairo_font_options_set_hint_metrics (cairo_font_options_t *options,
  1407.                                      cairo_hint_metrics_t  hint_metrics);
  1408. cairo_public cairo_hint_metrics_t
  1409. cairo_font_options_get_hint_metrics (const cairo_font_options_t *options);
  1410.  
  1411. /* This interface is for dealing with text as text, not caring about the
  1412.    font object inside the the cairo_t. */
  1413.  
  1414. cairo_public void
  1415. cairo_select_font_face (cairo_t              *cr,
  1416.                         const char           *family,
  1417.                         cairo_font_slant_t   slant,
  1418.                         cairo_font_weight_t  weight);
  1419.  
  1420. cairo_public void
  1421. cairo_set_font_size (cairo_t *cr, double size);
  1422.  
  1423. cairo_public void
  1424. cairo_set_font_matrix (cairo_t              *cr,
  1425.                        const cairo_matrix_t *matrix);
  1426.  
  1427. cairo_public void
  1428. cairo_get_font_matrix (cairo_t *cr,
  1429.                        cairo_matrix_t *matrix);
  1430.  
  1431. cairo_public void
  1432. cairo_set_font_options (cairo_t                    *cr,
  1433.                         const cairo_font_options_t *options);
  1434.  
  1435. cairo_public void
  1436. cairo_get_font_options (cairo_t              *cr,
  1437.                         cairo_font_options_t *options);
  1438.  
  1439. cairo_public void
  1440. cairo_set_font_face (cairo_t *cr, cairo_font_face_t *font_face);
  1441.  
  1442. cairo_public cairo_font_face_t *
  1443. cairo_get_font_face (cairo_t *cr);
  1444.  
  1445. cairo_public void
  1446. cairo_set_scaled_font (cairo_t                   *cr,
  1447.                        const cairo_scaled_font_t *scaled_font);
  1448.  
  1449. cairo_public cairo_scaled_font_t *
  1450. cairo_get_scaled_font (cairo_t *cr);
  1451.  
  1452. cairo_public void
  1453. cairo_show_text (cairo_t *cr, const char *utf8);
  1454.  
  1455. cairo_public void
  1456. cairo_show_glyphs (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs);
  1457.  
  1458. cairo_public void
  1459. cairo_show_text_glyphs (cairo_t                    *cr,
  1460.                         const char                 *utf8,
  1461.                         int                         utf8_len,
  1462.                         const cairo_glyph_t        *glyphs,
  1463.                         int                         num_glyphs,
  1464.                         const cairo_text_cluster_t *clusters,
  1465.                         int                         num_clusters,
  1466.                         cairo_text_cluster_flags_t  cluster_flags);
  1467.  
  1468. cairo_public void
  1469. cairo_text_path  (cairo_t *cr, const char *utf8);
  1470.  
  1471. cairo_public void
  1472. cairo_glyph_path (cairo_t *cr, const cairo_glyph_t *glyphs, int num_glyphs);
  1473.  
  1474. cairo_public void
  1475. cairo_text_extents (cairo_t              *cr,
  1476.                     const char           *utf8,
  1477.                     cairo_text_extents_t *extents);
  1478.  
  1479. cairo_public void
  1480. cairo_glyph_extents (cairo_t               *cr,
  1481.                      const cairo_glyph_t   *glyphs,
  1482.                      int                   num_glyphs,
  1483.                      cairo_text_extents_t  *extents);
  1484.  
  1485. cairo_public void
  1486. cairo_font_extents (cairo_t              *cr,
  1487.                     cairo_font_extents_t *extents);
  1488.  
  1489. /* Generic identifier for a font style */
  1490.  
  1491. cairo_public cairo_font_face_t *
  1492. cairo_font_face_reference (cairo_font_face_t *font_face);
  1493.  
  1494. cairo_public void
  1495. cairo_font_face_destroy (cairo_font_face_t *font_face);
  1496.  
  1497. cairo_public unsigned int
  1498. cairo_font_face_get_reference_count (cairo_font_face_t *font_face);
  1499.  
  1500. cairo_public cairo_status_t
  1501. cairo_font_face_status (cairo_font_face_t *font_face);
  1502.  
  1503.  
  1504. /**
  1505.  * cairo_font_type_t:
  1506.  * @CAIRO_FONT_TYPE_TOY: The font was created using cairo's toy font api (Since: 1.2)
  1507.  * @CAIRO_FONT_TYPE_FT: The font is of type FreeType (Since: 1.2)
  1508.  * @CAIRO_FONT_TYPE_WIN32: The font is of type Win32 (Since: 1.2)
  1509.  * @CAIRO_FONT_TYPE_QUARTZ: The font is of type Quartz (Since: 1.6, in 1.2 and
  1510.  * 1.4 it was named CAIRO_FONT_TYPE_ATSUI)
  1511.  * @CAIRO_FONT_TYPE_USER: The font was create using cairo's user font api (Since: 1.8)
  1512.  *
  1513.  * #cairo_font_type_t is used to describe the type of a given font
  1514.  * face or scaled font. The font types are also known as "font
  1515.  * backends" within cairo.
  1516.  *
  1517.  * The type of a font face is determined by the function used to
  1518.  * create it, which will generally be of the form
  1519.  * <function>cairo_<emphasis>type</emphasis>_font_face_create(<!-- -->)</function>.
  1520.  * The font face type can be queried with cairo_font_face_get_type()
  1521.  *
  1522.  * The various #cairo_font_face_t functions can be used with a font face
  1523.  * of any type.
  1524.  *
  1525.  * The type of a scaled font is determined by the type of the font
  1526.  * face passed to cairo_scaled_font_create(). The scaled font type can
  1527.  * be queried with cairo_scaled_font_get_type()
  1528.  *
  1529.  * The various #cairo_scaled_font_t functions can be used with scaled
  1530.  * fonts of any type, but some font backends also provide
  1531.  * type-specific functions that must only be called with a scaled font
  1532.  * of the appropriate type. These functions have names that begin with
  1533.  * <function>cairo_<emphasis>type</emphasis>_scaled_font(<!-- -->)</function>
  1534.  * such as cairo_ft_scaled_font_lock_face().
  1535.  *
  1536.  * The behavior of calling a type-specific function with a scaled font
  1537.  * of the wrong type is undefined.
  1538.  *
  1539.  * New entries may be added in future versions.
  1540.  *
  1541.  * Since: 1.2
  1542.  **/
  1543. typedef enum _cairo_font_type {
  1544.     CAIRO_FONT_TYPE_TOY,
  1545.     CAIRO_FONT_TYPE_FT,
  1546.     CAIRO_FONT_TYPE_WIN32,
  1547.     CAIRO_FONT_TYPE_QUARTZ,
  1548.     CAIRO_FONT_TYPE_USER
  1549. } cairo_font_type_t;
  1550.  
  1551. cairo_public cairo_font_type_t
  1552. cairo_font_face_get_type (cairo_font_face_t *font_face);
  1553.  
  1554. cairo_public void *
  1555. cairo_font_face_get_user_data (cairo_font_face_t           *font_face,
  1556.                                const cairo_user_data_key_t *key);
  1557.  
  1558. cairo_public cairo_status_t
  1559. cairo_font_face_set_user_data (cairo_font_face_t           *font_face,
  1560.                                const cairo_user_data_key_t *key,
  1561.                                void                        *user_data,
  1562.                                cairo_destroy_func_t         destroy);
  1563.  
  1564. /* Portable interface to general font features. */
  1565.  
  1566. cairo_public cairo_scaled_font_t *
  1567. cairo_scaled_font_create (cairo_font_face_t          *font_face,
  1568.                           const cairo_matrix_t       *font_matrix,
  1569.                           const cairo_matrix_t       *ctm,
  1570.                           const cairo_font_options_t *options);
  1571.  
  1572. cairo_public cairo_scaled_font_t *
  1573. cairo_scaled_font_reference (cairo_scaled_font_t *scaled_font);
  1574.  
  1575. cairo_public void
  1576. cairo_scaled_font_destroy (cairo_scaled_font_t *scaled_font);
  1577.  
  1578. cairo_public unsigned int
  1579. cairo_scaled_font_get_reference_count (cairo_scaled_font_t *scaled_font);
  1580.  
  1581. cairo_public cairo_status_t
  1582. cairo_scaled_font_status (cairo_scaled_font_t *scaled_font);
  1583.  
  1584. cairo_public cairo_font_type_t
  1585. cairo_scaled_font_get_type (cairo_scaled_font_t *scaled_font);
  1586.  
  1587. cairo_public void *
  1588. cairo_scaled_font_get_user_data (cairo_scaled_font_t         *scaled_font,
  1589.                                  const cairo_user_data_key_t *key);
  1590.  
  1591. cairo_public cairo_status_t
  1592. cairo_scaled_font_set_user_data (cairo_scaled_font_t         *scaled_font,
  1593.                                  const cairo_user_data_key_t *key,
  1594.                                  void                        *user_data,
  1595.                                  cairo_destroy_func_t         destroy);
  1596.  
  1597. cairo_public void
  1598. cairo_scaled_font_extents (cairo_scaled_font_t  *scaled_font,
  1599.                            cairo_font_extents_t *extents);
  1600.  
  1601. cairo_public void
  1602. cairo_scaled_font_text_extents (cairo_scaled_font_t  *scaled_font,
  1603.                                 const char           *utf8,
  1604.                                 cairo_text_extents_t *extents);
  1605.  
  1606. cairo_public void
  1607. cairo_scaled_font_glyph_extents (cairo_scaled_font_t   *scaled_font,
  1608.                                  const cairo_glyph_t   *glyphs,
  1609.                                  int                   num_glyphs,
  1610.                                  cairo_text_extents_t  *extents);
  1611.  
  1612. cairo_public cairo_status_t
  1613. cairo_scaled_font_text_to_glyphs (cairo_scaled_font_t        *scaled_font,
  1614.                                   double                      x,
  1615.                                   double                      y,
  1616.                                   const char                 *utf8,
  1617.                                   int                         utf8_len,
  1618.                                   cairo_glyph_t             **glyphs,
  1619.                                   int                        *num_glyphs,
  1620.                                   cairo_text_cluster_t      **clusters,
  1621.                                   int                        *num_clusters,
  1622.                                   cairo_text_cluster_flags_t *cluster_flags);
  1623.  
  1624. cairo_public cairo_font_face_t *
  1625. cairo_scaled_font_get_font_face (cairo_scaled_font_t *scaled_font);
  1626.  
  1627. cairo_public void
  1628. cairo_scaled_font_get_font_matrix (cairo_scaled_font_t  *scaled_font,
  1629.                                    cairo_matrix_t       *font_matrix);
  1630.  
  1631. cairo_public void
  1632. cairo_scaled_font_get_ctm (cairo_scaled_font_t  *scaled_font,
  1633.                            cairo_matrix_t       *ctm);
  1634.  
  1635. cairo_public void
  1636. cairo_scaled_font_get_scale_matrix (cairo_scaled_font_t *scaled_font,
  1637.                                     cairo_matrix_t      *scale_matrix);
  1638.  
  1639. cairo_public void
  1640. cairo_scaled_font_get_font_options (cairo_scaled_font_t         *scaled_font,
  1641.                                     cairo_font_options_t        *options);
  1642.  
  1643.  
  1644. /* Toy fonts */
  1645.  
  1646. cairo_public cairo_font_face_t *
  1647. cairo_toy_font_face_create (const char           *family,
  1648.                             cairo_font_slant_t    slant,
  1649.                             cairo_font_weight_t   weight);
  1650.  
  1651. cairo_public const char *
  1652. cairo_toy_font_face_get_family (cairo_font_face_t *font_face);
  1653.  
  1654. cairo_public cairo_font_slant_t
  1655. cairo_toy_font_face_get_slant (cairo_font_face_t *font_face);
  1656.  
  1657. cairo_public cairo_font_weight_t
  1658. cairo_toy_font_face_get_weight (cairo_font_face_t *font_face);
  1659.  
  1660.  
  1661. /* User fonts */
  1662.  
  1663. cairo_public cairo_font_face_t *
  1664. cairo_user_font_face_create (void);
  1665.  
  1666. /* User-font method signatures */
  1667.  
  1668. /**
  1669.  * cairo_user_scaled_font_init_func_t:
  1670.  * @scaled_font: the scaled-font being created
  1671.  * @cr: a cairo context, in font space
  1672.  * @extents: font extents to fill in, in font space
  1673.  *
  1674.  * #cairo_user_scaled_font_init_func_t is the type of function which is
  1675.  * called when a scaled-font needs to be created for a user font-face.
  1676.  *
  1677.  * The cairo context @cr is not used by the caller, but is prepared in font
  1678.  * space, similar to what the cairo contexts passed to the render_glyph
  1679.  * method will look like.  The callback can use this context for extents
  1680.  * computation for example.  After the callback is called, @cr is checked
  1681.  * for any error status.
  1682.  *
  1683.  * The @extents argument is where the user font sets the font extents for
  1684.  * @scaled_font.  It is in font space, which means that for most cases its
  1685.  * ascent and descent members should add to 1.0.  @extents is preset to
  1686.  * hold a value of 1.0 for ascent, height, and max_x_advance, and 0.0 for
  1687.  * descent and max_y_advance members.
  1688.  *
  1689.  * The callback is optional.  If not set, default font extents as described
  1690.  * in the previous paragraph will be used.
  1691.  *
  1692.  * Note that @scaled_font is not fully initialized at this
  1693.  * point and trying to use it for text operations in the callback will result
  1694.  * in deadlock.
  1695.  *
  1696.  * Returns: %CAIRO_STATUS_SUCCESS upon success, or an error status on error.
  1697.  *
  1698.  * Since: 1.8
  1699.  **/
  1700. typedef cairo_status_t (*cairo_user_scaled_font_init_func_t) (cairo_scaled_font_t  *scaled_font,
  1701.                                                               cairo_t              *cr,
  1702.                                                               cairo_font_extents_t *extents);
  1703.  
  1704. /**
  1705.  * cairo_user_scaled_font_render_glyph_func_t:
  1706.  * @scaled_font: user scaled-font
  1707.  * @glyph: glyph code to render
  1708.  * @cr: cairo context to draw to, in font space
  1709.  * @extents: glyph extents to fill in, in font space
  1710.  *
  1711.  * #cairo_user_scaled_font_render_glyph_func_t is the type of function which
  1712.  * is called when a user scaled-font needs to render a glyph.
  1713.  *
  1714.  * The callback is mandatory, and expected to draw the glyph with code @glyph to
  1715.  * the cairo context @cr.  @cr is prepared such that the glyph drawing is done in
  1716.  * font space.  That is, the matrix set on @cr is the scale matrix of @scaled_font,
  1717.  * The @extents argument is where the user font sets the font extents for
  1718.  * @scaled_font.  However, if user prefers to draw in user space, they can
  1719.  * achieve that by changing the matrix on @cr.  All cairo rendering operations
  1720.  * to @cr are permitted, however, the result is undefined if any source other
  1721.  * than the default source on @cr is used.  That means, glyph bitmaps should
  1722.  * be rendered using cairo_mask() instead of cairo_paint().
  1723.  *
  1724.  * Other non-default settings on @cr include a font size of 1.0 (given that
  1725.  * it is set up to be in font space), and font options corresponding to
  1726.  * @scaled_font.
  1727.  *
  1728.  * The @extents argument is preset to have <literal>x_bearing</literal>,
  1729.  * <literal>width</literal>, and <literal>y_advance</literal> of zero,
  1730.  * <literal>y_bearing</literal> set to <literal>-font_extents.ascent</literal>,
  1731.  * <literal>height</literal> to <literal>font_extents.ascent+font_extents.descent</literal>,
  1732.  * and <literal>x_advance</literal> to <literal>font_extents.max_x_advance</literal>.
  1733.  * The only field user needs to set in majority of cases is
  1734.  * <literal>x_advance</literal>.
  1735.  * If the <literal>width</literal> field is zero upon the callback returning
  1736.  * (which is its preset value), the glyph extents are automatically computed
  1737.  * based on the drawings done to @cr.  This is in most cases exactly what the
  1738.  * desired behavior is.  However, if for any reason the callback sets the
  1739.  * extents, it must be ink extents, and include the extents of all drawing
  1740.  * done to @cr in the callback.
  1741.  *
  1742.  * Returns: %CAIRO_STATUS_SUCCESS upon success, or
  1743.  * %CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
  1744.  *
  1745.  * Since: 1.8
  1746.  **/
  1747. typedef cairo_status_t (*cairo_user_scaled_font_render_glyph_func_t) (cairo_scaled_font_t  *scaled_font,
  1748.                                                                       unsigned long         glyph,
  1749.                                                                       cairo_t              *cr,
  1750.                                                                       cairo_text_extents_t *extents);
  1751.  
  1752. /**
  1753.  * cairo_user_scaled_font_text_to_glyphs_func_t:
  1754.  * @scaled_font: the scaled-font being created
  1755.  * @utf8: a string of text encoded in UTF-8
  1756.  * @utf8_len: length of @utf8 in bytes
  1757.  * @glyphs: pointer to array of glyphs to fill, in font space
  1758.  * @num_glyphs: pointer to number of glyphs
  1759.  * @clusters: pointer to array of cluster mapping information to fill, or %NULL
  1760.  * @num_clusters: pointer to number of clusters
  1761.  * @cluster_flags: pointer to location to store cluster flags corresponding to the
  1762.  *                 output @clusters
  1763.  *
  1764.  * #cairo_user_scaled_font_text_to_glyphs_func_t is the type of function which
  1765.  * is called to convert input text to an array of glyphs.  This is used by the
  1766.  * cairo_show_text() operation.
  1767.  *
  1768.  * Using this callback the user-font has full control on glyphs and their
  1769.  * positions.  That means, it allows for features like ligatures and kerning,
  1770.  * as well as complex <firstterm>shaping</firstterm> required for scripts like
  1771.  * Arabic and Indic.
  1772.  *
  1773.  * The @num_glyphs argument is preset to the number of glyph entries available
  1774.  * in the @glyphs buffer. If the @glyphs buffer is %NULL, the value of
  1775.  * @num_glyphs will be zero.  If the provided glyph array is too short for
  1776.  * the conversion (or for convenience), a new glyph array may be allocated
  1777.  * using cairo_glyph_allocate() and placed in @glyphs.  Upon return,
  1778.  * @num_glyphs should contain the number of generated glyphs.  If the value
  1779.  * @glyphs points at has changed after the call, the caller will free the
  1780.  * allocated glyph array using cairo_glyph_free().  The caller will also free
  1781.  * the original value of @glyphs, so the callback shouldn't do so.
  1782.  * The callback should populate the glyph indices and positions (in font space)
  1783.  * assuming that the text is to be shown at the origin.
  1784.  *
  1785.  * If @clusters is not %NULL, @num_clusters and @cluster_flags are also
  1786.  * non-%NULL, and cluster mapping should be computed. The semantics of how
  1787.  * cluster array allocation works is similar to the glyph array.  That is,
  1788.  * if @clusters initially points to a non-%NULL value, that array may be used
  1789.  * as a cluster buffer, and @num_clusters points to the number of cluster
  1790.  * entries available there.  If the provided cluster array is too short for
  1791.  * the conversion (or for convenience), a new cluster array may be allocated
  1792.  * using cairo_text_cluster_allocate() and placed in @clusters.  In this case,
  1793.  * the original value of @clusters will still be freed by the caller.  Upon
  1794.  * return, @num_clusters should contain the number of generated clusters.
  1795.  * If the value @clusters points at has changed after the call, the caller
  1796.  * will free the allocated cluster array using cairo_text_cluster_free().
  1797.  *
  1798.  * The callback is optional.  If @num_glyphs is negative upon
  1799.  * the callback returning or if the return value
  1800.  * is %CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED, the unicode_to_glyph callback
  1801.  * is tried.  See #cairo_user_scaled_font_unicode_to_glyph_func_t.
  1802.  *
  1803.  * Note: While cairo does not impose any limitation on glyph indices,
  1804.  * some applications may assume that a glyph index fits in a 16-bit
  1805.  * unsigned integer.  As such, it is advised that user-fonts keep their
  1806.  * glyphs in the 0 to 65535 range.  Furthermore, some applications may
  1807.  * assume that glyph 0 is a special glyph-not-found glyph.  User-fonts
  1808.  * are advised to use glyph 0 for such purposes and do not use that
  1809.  * glyph value for other purposes.
  1810.  *
  1811.  * Returns: %CAIRO_STATUS_SUCCESS upon success,
  1812.  * %CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED if fallback options should be tried,
  1813.  * or %CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
  1814.  *
  1815.  * Since: 1.8
  1816.  **/
  1817. typedef cairo_status_t (*cairo_user_scaled_font_text_to_glyphs_func_t) (cairo_scaled_font_t        *scaled_font,
  1818.                                                                         const char                 *utf8,
  1819.                                                                         int                         utf8_len,
  1820.                                                                         cairo_glyph_t             **glyphs,
  1821.                                                                         int                        *num_glyphs,
  1822.                                                                         cairo_text_cluster_t      **clusters,
  1823.                                                                         int                        *num_clusters,
  1824.                                                                         cairo_text_cluster_flags_t *cluster_flags);
  1825.  
  1826. /**
  1827.  * cairo_user_scaled_font_unicode_to_glyph_func_t:
  1828.  * @scaled_font: the scaled-font being created
  1829.  * @unicode: input unicode character code-point
  1830.  * @glyph_index: output glyph index
  1831.  *
  1832.  * #cairo_user_scaled_font_unicode_to_glyph_func_t is the type of function which
  1833.  * is called to convert an input Unicode character to a single glyph.
  1834.  * This is used by the cairo_show_text() operation.
  1835.  *
  1836.  * This callback is used to provide the same functionality as the
  1837.  * text_to_glyphs callback does (see #cairo_user_scaled_font_text_to_glyphs_func_t)
  1838.  * but has much less control on the output,
  1839.  * in exchange for increased ease of use.  The inherent assumption to using
  1840.  * this callback is that each character maps to one glyph, and that the
  1841.  * mapping is context independent.  It also assumes that glyphs are positioned
  1842.  * according to their advance width.  These mean no ligatures, kerning, or
  1843.  * complex scripts can be implemented using this callback.
  1844.  *
  1845.  * The callback is optional, and only used if text_to_glyphs callback is not
  1846.  * set or fails to return glyphs.  If this callback is not set or if it returns
  1847.  * %CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED, an identity mapping from Unicode
  1848.  * code-points to glyph indices is assumed.
  1849.  *
  1850.  * Note: While cairo does not impose any limitation on glyph indices,
  1851.  * some applications may assume that a glyph index fits in a 16-bit
  1852.  * unsigned integer.  As such, it is advised that user-fonts keep their
  1853.  * glyphs in the 0 to 65535 range.  Furthermore, some applications may
  1854.  * assume that glyph 0 is a special glyph-not-found glyph.  User-fonts
  1855.  * are advised to use glyph 0 for such purposes and do not use that
  1856.  * glyph value for other purposes.
  1857.  *
  1858.  * Returns: %CAIRO_STATUS_SUCCESS upon success,
  1859.  * %CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED if fallback options should be tried,
  1860.  * or %CAIRO_STATUS_USER_FONT_ERROR or any other error status on error.
  1861.  *
  1862.  * Since: 1.8
  1863.  **/
  1864. typedef cairo_status_t (*cairo_user_scaled_font_unicode_to_glyph_func_t) (cairo_scaled_font_t *scaled_font,
  1865.                                                                           unsigned long        unicode,
  1866.                                                                           unsigned long       *glyph_index);
  1867.  
  1868. /* User-font method setters */
  1869.  
  1870. cairo_public void
  1871. cairo_user_font_face_set_init_func (cairo_font_face_t                  *font_face,
  1872.                                     cairo_user_scaled_font_init_func_t  init_func);
  1873.  
  1874. cairo_public void
  1875. cairo_user_font_face_set_render_glyph_func (cairo_font_face_t                          *font_face,
  1876.                                             cairo_user_scaled_font_render_glyph_func_t  render_glyph_func);
  1877.  
  1878. cairo_public void
  1879. cairo_user_font_face_set_text_to_glyphs_func (cairo_font_face_t                            *font_face,
  1880.                                               cairo_user_scaled_font_text_to_glyphs_func_t  text_to_glyphs_func);
  1881.  
  1882. cairo_public void
  1883. cairo_user_font_face_set_unicode_to_glyph_func (cairo_font_face_t                              *font_face,
  1884.                                                 cairo_user_scaled_font_unicode_to_glyph_func_t  unicode_to_glyph_func);
  1885.  
  1886. /* User-font method getters */
  1887.  
  1888. cairo_public cairo_user_scaled_font_init_func_t
  1889. cairo_user_font_face_get_init_func (cairo_font_face_t *font_face);
  1890.  
  1891. cairo_public cairo_user_scaled_font_render_glyph_func_t
  1892. cairo_user_font_face_get_render_glyph_func (cairo_font_face_t *font_face);
  1893.  
  1894. cairo_public cairo_user_scaled_font_text_to_glyphs_func_t
  1895. cairo_user_font_face_get_text_to_glyphs_func (cairo_font_face_t *font_face);
  1896.  
  1897. cairo_public cairo_user_scaled_font_unicode_to_glyph_func_t
  1898. cairo_user_font_face_get_unicode_to_glyph_func (cairo_font_face_t *font_face);
  1899.  
  1900.  
  1901. /* Query functions */
  1902.  
  1903. cairo_public cairo_operator_t
  1904. cairo_get_operator (cairo_t *cr);
  1905.  
  1906. cairo_public cairo_pattern_t *
  1907. cairo_get_source (cairo_t *cr);
  1908.  
  1909. cairo_public double
  1910. cairo_get_tolerance (cairo_t *cr);
  1911.  
  1912. cairo_public cairo_antialias_t
  1913. cairo_get_antialias (cairo_t *cr);
  1914.  
  1915. cairo_public cairo_bool_t
  1916. cairo_has_current_point (cairo_t *cr);
  1917.  
  1918. cairo_public void
  1919. cairo_get_current_point (cairo_t *cr, double *x, double *y);
  1920.  
  1921. cairo_public cairo_fill_rule_t
  1922. cairo_get_fill_rule (cairo_t *cr);
  1923.  
  1924. cairo_public double
  1925. cairo_get_line_width (cairo_t *cr);
  1926.  
  1927. cairo_public cairo_line_cap_t
  1928. cairo_get_line_cap (cairo_t *cr);
  1929.  
  1930. cairo_public cairo_line_join_t
  1931. cairo_get_line_join (cairo_t *cr);
  1932.  
  1933. cairo_public double
  1934. cairo_get_miter_limit (cairo_t *cr);
  1935.  
  1936. cairo_public int
  1937. cairo_get_dash_count (cairo_t *cr);
  1938.  
  1939. cairo_public void
  1940. cairo_get_dash (cairo_t *cr, double *dashes, double *offset);
  1941.  
  1942. cairo_public void
  1943. cairo_get_matrix (cairo_t *cr, cairo_matrix_t *matrix);
  1944.  
  1945. cairo_public cairo_surface_t *
  1946. cairo_get_target (cairo_t *cr);
  1947.  
  1948. cairo_public cairo_surface_t *
  1949. cairo_get_group_target (cairo_t *cr);
  1950.  
  1951. /**
  1952.  * cairo_path_data_type_t:
  1953.  * @CAIRO_PATH_MOVE_TO: A move-to operation, since 1.0
  1954.  * @CAIRO_PATH_LINE_TO: A line-to operation, since 1.0
  1955.  * @CAIRO_PATH_CURVE_TO: A curve-to operation, since 1.0
  1956.  * @CAIRO_PATH_CLOSE_PATH: A close-path operation, since 1.0
  1957.  *
  1958.  * #cairo_path_data_t is used to describe the type of one portion
  1959.  * of a path when represented as a #cairo_path_t.
  1960.  * See #cairo_path_data_t for details.
  1961.  *
  1962.  * Since: 1.0
  1963.  **/
  1964. typedef enum _cairo_path_data_type {
  1965.     CAIRO_PATH_MOVE_TO,
  1966.     CAIRO_PATH_LINE_TO,
  1967.     CAIRO_PATH_CURVE_TO,
  1968.     CAIRO_PATH_CLOSE_PATH
  1969. } cairo_path_data_type_t;
  1970.  
  1971. /**
  1972.  * cairo_path_data_t:
  1973.  *
  1974.  * #cairo_path_data_t is used to represent the path data inside a
  1975.  * #cairo_path_t.
  1976.  *
  1977.  * The data structure is designed to try to balance the demands of
  1978.  * efficiency and ease-of-use. A path is represented as an array of
  1979.  * #cairo_path_data_t, which is a union of headers and points.
  1980.  *
  1981.  * Each portion of the path is represented by one or more elements in
  1982.  * the array, (one header followed by 0 or more points). The length
  1983.  * value of the header is the number of array elements for the current
  1984.  * portion including the header, (ie. length == 1 + # of points), and
  1985.  * where the number of points for each element type is as follows:
  1986.  *
  1987.  * <programlisting>
  1988.  *     %CAIRO_PATH_MOVE_TO:     1 point
  1989.  *     %CAIRO_PATH_LINE_TO:     1 point
  1990.  *     %CAIRO_PATH_CURVE_TO:    3 points
  1991.  *     %CAIRO_PATH_CLOSE_PATH:  0 points
  1992.  * </programlisting>
  1993.  *
  1994.  * The semantics and ordering of the coordinate values are consistent
  1995.  * with cairo_move_to(), cairo_line_to(), cairo_curve_to(), and
  1996.  * cairo_close_path().
  1997.  *
  1998.  * Here is sample code for iterating through a #cairo_path_t:
  1999.  *
  2000.  * <informalexample><programlisting>
  2001.  *      int i;
  2002.  *      cairo_path_t *path;
  2003.  *      cairo_path_data_t *data;
  2004.  * &nbsp;
  2005.  *      path = cairo_copy_path (cr);
  2006.  * &nbsp;
  2007.  *      for (i=0; i < path->num_data; i += path->data[i].header.length) {
  2008.  *          data = &amp;path->data[i];
  2009.  *          switch (data->header.type) {
  2010.  *          case CAIRO_PATH_MOVE_TO:
  2011.  *              do_move_to_things (data[1].point.x, data[1].point.y);
  2012.  *              break;
  2013.  *          case CAIRO_PATH_LINE_TO:
  2014.  *              do_line_to_things (data[1].point.x, data[1].point.y);
  2015.  *              break;
  2016.  *          case CAIRO_PATH_CURVE_TO:
  2017.  *              do_curve_to_things (data[1].point.x, data[1].point.y,
  2018.  *                                  data[2].point.x, data[2].point.y,
  2019.  *                                  data[3].point.x, data[3].point.y);
  2020.  *              break;
  2021.  *          case CAIRO_PATH_CLOSE_PATH:
  2022.  *              do_close_path_things ();
  2023.  *              break;
  2024.  *          }
  2025.  *      }
  2026.  *      cairo_path_destroy (path);
  2027.  * </programlisting></informalexample>
  2028.  *
  2029.  * As of cairo 1.4, cairo does not mind if there are more elements in
  2030.  * a portion of the path than needed.  Such elements can be used by
  2031.  * users of the cairo API to hold extra values in the path data
  2032.  * structure.  For this reason, it is recommended that applications
  2033.  * always use <literal>data->header.length</literal> to
  2034.  * iterate over the path data, instead of hardcoding the number of
  2035.  * elements for each element type.
  2036.  *
  2037.  * Since: 1.0
  2038.  **/
  2039. typedef union _cairo_path_data_t cairo_path_data_t;
  2040. union _cairo_path_data_t {
  2041.     struct {
  2042.         cairo_path_data_type_t type;
  2043.         int length;
  2044.     } header;
  2045.     struct {
  2046.         double x, y;
  2047.     } point;
  2048. };
  2049.  
  2050. /**
  2051.  * cairo_path_t:
  2052.  * @status: the current error status
  2053.  * @data: the elements in the path
  2054.  * @num_data: the number of elements in the data array
  2055.  *
  2056.  * A data structure for holding a path. This data structure serves as
  2057.  * the return value for cairo_copy_path() and
  2058.  * cairo_copy_path_flat() as well the input value for
  2059.  * cairo_append_path().
  2060.  *
  2061.  * See #cairo_path_data_t for hints on how to iterate over the
  2062.  * actual data within the path.
  2063.  *
  2064.  * The num_data member gives the number of elements in the data
  2065.  * array. This number is larger than the number of independent path
  2066.  * portions (defined in #cairo_path_data_type_t), since the data
  2067.  * includes both headers and coordinates for each portion.
  2068.  *
  2069.  * Since: 1.0
  2070.  **/
  2071. typedef struct cairo_path {
  2072.     cairo_status_t status;
  2073.     cairo_path_data_t *data;
  2074.     int num_data;
  2075. } cairo_path_t;
  2076.  
  2077. cairo_public cairo_path_t *
  2078. cairo_copy_path (cairo_t *cr);
  2079.  
  2080. cairo_public cairo_path_t *
  2081. cairo_copy_path_flat (cairo_t *cr);
  2082.  
  2083. cairo_public void
  2084. cairo_append_path (cairo_t              *cr,
  2085.                    const cairo_path_t   *path);
  2086.  
  2087. cairo_public void
  2088. cairo_path_destroy (cairo_path_t *path);
  2089.  
  2090. /* Error status queries */
  2091.  
  2092. cairo_public cairo_status_t
  2093. cairo_status (cairo_t *cr);
  2094.  
  2095. cairo_public const char *
  2096. cairo_status_to_string (cairo_status_t status);
  2097.  
  2098. /* Backend device manipulation */
  2099.  
  2100. cairo_public cairo_device_t *
  2101. cairo_device_reference (cairo_device_t *device);
  2102.  
  2103. /**
  2104.  * cairo_device_type_t:
  2105.  * @CAIRO_DEVICE_TYPE_DRM: The device is of type Direct Render Manager, since 1.10
  2106.  * @CAIRO_DEVICE_TYPE_GL: The device is of type OpenGL, since 1.10
  2107.  * @CAIRO_DEVICE_TYPE_SCRIPT: The device is of type script, since 1.10
  2108.  * @CAIRO_DEVICE_TYPE_XCB: The device is of type xcb, since 1.10
  2109.  * @CAIRO_DEVICE_TYPE_XLIB: The device is of type xlib, since 1.10
  2110.  * @CAIRO_DEVICE_TYPE_XML: The device is of type XML, since 1.10
  2111.  * @CAIRO_DEVICE_TYPE_COGL: The device is of type cogl, since 1.12
  2112.  * @CAIRO_DEVICE_TYPE_WIN32: The device is of type win32, since 1.12
  2113.  * @CAIRO_DEVICE_TYPE_INVALID: The device is invalid, since 1.10
  2114.  *
  2115.  * #cairo_device_type_t is used to describe the type of a given
  2116.  * device. The devices types are also known as "backends" within cairo.
  2117.  *
  2118.  * The device type can be queried with cairo_device_get_type()
  2119.  *
  2120.  * The various #cairo_device_t functions can be used with devices of
  2121.  * any type, but some backends also provide type-specific functions
  2122.  * that must only be called with a device of the appropriate
  2123.  * type. These functions have names that begin with
  2124.  * <literal>cairo_<emphasis>type</emphasis>_device</literal> such as
  2125.  * cairo_xcb_device_debug_cap_xrender_version().
  2126.  *
  2127.  * The behavior of calling a type-specific function with a device of
  2128.  * the wrong type is undefined.
  2129.  *
  2130.  * New entries may be added in future versions.
  2131.  *
  2132.  * Since: 1.10
  2133.  **/
  2134. typedef enum _cairo_device_type {
  2135.     CAIRO_DEVICE_TYPE_DRM,
  2136.     CAIRO_DEVICE_TYPE_GL,
  2137.     CAIRO_DEVICE_TYPE_SCRIPT,
  2138.     CAIRO_DEVICE_TYPE_XCB,
  2139.     CAIRO_DEVICE_TYPE_XLIB,
  2140.     CAIRO_DEVICE_TYPE_XML,
  2141.     CAIRO_DEVICE_TYPE_COGL,
  2142.     CAIRO_DEVICE_TYPE_WIN32,
  2143.  
  2144.     CAIRO_DEVICE_TYPE_INVALID = -1
  2145. } cairo_device_type_t;
  2146.  
  2147. cairo_public cairo_device_type_t
  2148. cairo_device_get_type (cairo_device_t *device);
  2149.  
  2150. cairo_public cairo_status_t
  2151. cairo_device_status (cairo_device_t *device);
  2152.  
  2153. cairo_public cairo_status_t
  2154. cairo_device_acquire (cairo_device_t *device);
  2155.  
  2156. cairo_public void
  2157. cairo_device_release (cairo_device_t *device);
  2158.  
  2159. cairo_public void
  2160. cairo_device_flush (cairo_device_t *device);
  2161.  
  2162. cairo_public void
  2163. cairo_device_finish (cairo_device_t *device);
  2164.  
  2165. cairo_public void
  2166. cairo_device_destroy (cairo_device_t *device);
  2167.  
  2168. cairo_public unsigned int
  2169. cairo_device_get_reference_count (cairo_device_t *device);
  2170.  
  2171. cairo_public void *
  2172. cairo_device_get_user_data (cairo_device_t               *device,
  2173.                             const cairo_user_data_key_t *key);
  2174.  
  2175. cairo_public cairo_status_t
  2176. cairo_device_set_user_data (cairo_device_t               *device,
  2177.                             const cairo_user_data_key_t *key,
  2178.                             void                         *user_data,
  2179.                             cairo_destroy_func_t          destroy);
  2180.  
  2181.  
  2182. /* Surface manipulation */
  2183.  
  2184. cairo_public cairo_surface_t *
  2185. cairo_surface_create_similar (cairo_surface_t  *other,
  2186.                               cairo_content_t   content,
  2187.                               int               width,
  2188.                               int               height);
  2189.  
  2190. cairo_public cairo_surface_t *
  2191. cairo_surface_create_similar_image (cairo_surface_t  *other,
  2192.                                     cairo_format_t    format,
  2193.                                     int         width,
  2194.                                     int         height);
  2195.  
  2196. cairo_public cairo_surface_t *
  2197. cairo_surface_map_to_image (cairo_surface_t  *surface,
  2198.                             const cairo_rectangle_int_t *extents);
  2199.  
  2200. cairo_public void
  2201. cairo_surface_unmap_image (cairo_surface_t *surface,
  2202.                            cairo_surface_t *image);
  2203.  
  2204. cairo_public cairo_surface_t *
  2205. cairo_surface_create_for_rectangle (cairo_surface_t     *target,
  2206.                                     double               x,
  2207.                                     double               y,
  2208.                                     double               width,
  2209.                                     double               height);
  2210.  
  2211. typedef enum {
  2212.         CAIRO_SURFACE_OBSERVER_NORMAL = 0,
  2213.         CAIRO_SURFACE_OBSERVER_RECORD_OPERATIONS = 0x1
  2214. } cairo_surface_observer_mode_t;
  2215.  
  2216. cairo_public cairo_surface_t *
  2217. cairo_surface_create_observer (cairo_surface_t *target,
  2218.                                cairo_surface_observer_mode_t mode);
  2219.  
  2220. typedef void (*cairo_surface_observer_callback_t) (cairo_surface_t *observer,
  2221.                                                    cairo_surface_t *target,
  2222.                                                    void *data);
  2223.  
  2224. cairo_public cairo_status_t
  2225. cairo_surface_observer_add_paint_callback (cairo_surface_t *abstract_surface,
  2226.                                            cairo_surface_observer_callback_t func,
  2227.                                            void *data);
  2228.  
  2229. cairo_public cairo_status_t
  2230. cairo_surface_observer_add_mask_callback (cairo_surface_t *abstract_surface,
  2231.                                           cairo_surface_observer_callback_t func,
  2232.                                           void *data);
  2233.  
  2234. cairo_public cairo_status_t
  2235. cairo_surface_observer_add_fill_callback (cairo_surface_t *abstract_surface,
  2236.                                           cairo_surface_observer_callback_t func,
  2237.                                           void *data);
  2238.  
  2239. cairo_public cairo_status_t
  2240. cairo_surface_observer_add_stroke_callback (cairo_surface_t *abstract_surface,
  2241.                                             cairo_surface_observer_callback_t func,
  2242.                                             void *data);
  2243.  
  2244. cairo_public cairo_status_t
  2245. cairo_surface_observer_add_glyphs_callback (cairo_surface_t *abstract_surface,
  2246.                                             cairo_surface_observer_callback_t func,
  2247.                                             void *data);
  2248.  
  2249. cairo_public cairo_status_t
  2250. cairo_surface_observer_add_flush_callback (cairo_surface_t *abstract_surface,
  2251.                                            cairo_surface_observer_callback_t func,
  2252.                                            void *data);
  2253.  
  2254. cairo_public cairo_status_t
  2255. cairo_surface_observer_add_finish_callback (cairo_surface_t *abstract_surface,
  2256.                                             cairo_surface_observer_callback_t func,
  2257.                                             void *data);
  2258.  
  2259. cairo_public cairo_status_t
  2260. cairo_surface_observer_print (cairo_surface_t *surface,
  2261.                               cairo_write_func_t write_func,
  2262.                               void *closure);
  2263. cairo_public double
  2264. cairo_surface_observer_elapsed (cairo_surface_t *surface);
  2265.  
  2266. cairo_public cairo_status_t
  2267. cairo_device_observer_print (cairo_device_t *device,
  2268.                              cairo_write_func_t write_func,
  2269.                              void *closure);
  2270.  
  2271. cairo_public double
  2272. cairo_device_observer_elapsed (cairo_device_t *device);
  2273.  
  2274. cairo_public double
  2275. cairo_device_observer_paint_elapsed (cairo_device_t *device);
  2276.  
  2277. cairo_public double
  2278. cairo_device_observer_mask_elapsed (cairo_device_t *device);
  2279.  
  2280. cairo_public double
  2281. cairo_device_observer_fill_elapsed (cairo_device_t *device);
  2282.  
  2283. cairo_public double
  2284. cairo_device_observer_stroke_elapsed (cairo_device_t *device);
  2285.  
  2286. cairo_public double
  2287. cairo_device_observer_glyphs_elapsed (cairo_device_t *device);
  2288.  
  2289. cairo_public cairo_surface_t *
  2290. cairo_surface_reference (cairo_surface_t *surface);
  2291.  
  2292. cairo_public void
  2293. cairo_surface_finish (cairo_surface_t *surface);
  2294.  
  2295. cairo_public void
  2296. cairo_surface_destroy (cairo_surface_t *surface);
  2297.  
  2298. cairo_public cairo_device_t *
  2299. cairo_surface_get_device (cairo_surface_t *surface);
  2300.  
  2301. cairo_public unsigned int
  2302. cairo_surface_get_reference_count (cairo_surface_t *surface);
  2303.  
  2304. cairo_public cairo_status_t
  2305. cairo_surface_status (cairo_surface_t *surface);
  2306.  
  2307. /**
  2308.  * cairo_surface_type_t:
  2309.  * @CAIRO_SURFACE_TYPE_IMAGE: The surface is of type image, since 1.2
  2310.  * @CAIRO_SURFACE_TYPE_PDF: The surface is of type pdf, since 1.2
  2311.  * @CAIRO_SURFACE_TYPE_PS: The surface is of type ps, since 1.2
  2312.  * @CAIRO_SURFACE_TYPE_XLIB: The surface is of type xlib, since 1.2
  2313.  * @CAIRO_SURFACE_TYPE_XCB: The surface is of type xcb, since 1.2
  2314.  * @CAIRO_SURFACE_TYPE_GLITZ: The surface is of type glitz, since 1.2
  2315.  * @CAIRO_SURFACE_TYPE_QUARTZ: The surface is of type quartz, since 1.2
  2316.  * @CAIRO_SURFACE_TYPE_WIN32: The surface is of type win32, since 1.2
  2317.  * @CAIRO_SURFACE_TYPE_BEOS: The surface is of type beos, since 1.2
  2318.  * @CAIRO_SURFACE_TYPE_DIRECTFB: The surface is of type directfb, since 1.2
  2319.  * @CAIRO_SURFACE_TYPE_SVG: The surface is of type svg, since 1.2
  2320.  * @CAIRO_SURFACE_TYPE_OS2: The surface is of type os2, since 1.4
  2321.  * @CAIRO_SURFACE_TYPE_WIN32_PRINTING: The surface is a win32 printing surface, since 1.6
  2322.  * @CAIRO_SURFACE_TYPE_QUARTZ_IMAGE: The surface is of type quartz_image, since 1.6
  2323.  * @CAIRO_SURFACE_TYPE_SCRIPT: The surface is of type script, since 1.10
  2324.  * @CAIRO_SURFACE_TYPE_QT: The surface is of type Qt, since 1.10
  2325.  * @CAIRO_SURFACE_TYPE_RECORDING: The surface is of type recording, since 1.10
  2326.  * @CAIRO_SURFACE_TYPE_VG: The surface is a OpenVG surface, since 1.10
  2327.  * @CAIRO_SURFACE_TYPE_GL: The surface is of type OpenGL, since 1.10
  2328.  * @CAIRO_SURFACE_TYPE_DRM: The surface is of type Direct Render Manager, since 1.10
  2329.  * @CAIRO_SURFACE_TYPE_TEE: The surface is of type 'tee' (a multiplexing surface), since 1.10
  2330.  * @CAIRO_SURFACE_TYPE_XML: The surface is of type XML (for debugging), since 1.10
  2331.  * @CAIRO_SURFACE_TYPE_SKIA: The surface is of type Skia, since 1.10
  2332.  * @CAIRO_SURFACE_TYPE_SUBSURFACE: The surface is a subsurface created with
  2333.  *   cairo_surface_create_for_rectangle(), since 1.10
  2334.  * @CAIRO_SURFACE_TYPE_COGL: This surface is of type Cogl, since 1.12
  2335.  *
  2336.  * #cairo_surface_type_t is used to describe the type of a given
  2337.  * surface. The surface types are also known as "backends" or "surface
  2338.  * backends" within cairo.
  2339.  *
  2340.  * The type of a surface is determined by the function used to create
  2341.  * it, which will generally be of the form
  2342.  * <function>cairo_<emphasis>type</emphasis>_surface_create(<!-- -->)</function>,
  2343.  * (though see cairo_surface_create_similar() as well).
  2344.  *
  2345.  * The surface type can be queried with cairo_surface_get_type()
  2346.  *
  2347.  * The various #cairo_surface_t functions can be used with surfaces of
  2348.  * any type, but some backends also provide type-specific functions
  2349.  * that must only be called with a surface of the appropriate
  2350.  * type. These functions have names that begin with
  2351.  * <literal>cairo_<emphasis>type</emphasis>_surface</literal> such as cairo_image_surface_get_width().
  2352.  *
  2353.  * The behavior of calling a type-specific function with a surface of
  2354.  * the wrong type is undefined.
  2355.  *
  2356.  * New entries may be added in future versions.
  2357.  *
  2358.  * Since: 1.2
  2359.  **/
  2360. typedef enum _cairo_surface_type {
  2361.     CAIRO_SURFACE_TYPE_IMAGE,
  2362.     CAIRO_SURFACE_TYPE_PDF,
  2363.     CAIRO_SURFACE_TYPE_PS,
  2364.     CAIRO_SURFACE_TYPE_XLIB,
  2365.     CAIRO_SURFACE_TYPE_XCB,
  2366.     CAIRO_SURFACE_TYPE_GLITZ,
  2367.     CAIRO_SURFACE_TYPE_QUARTZ,
  2368.     CAIRO_SURFACE_TYPE_WIN32,
  2369.     CAIRO_SURFACE_TYPE_BEOS,
  2370.     CAIRO_SURFACE_TYPE_DIRECTFB,
  2371.     CAIRO_SURFACE_TYPE_SVG,
  2372.     CAIRO_SURFACE_TYPE_OS2,
  2373.     CAIRO_SURFACE_TYPE_WIN32_PRINTING,
  2374.     CAIRO_SURFACE_TYPE_QUARTZ_IMAGE,
  2375.     CAIRO_SURFACE_TYPE_SCRIPT,
  2376.     CAIRO_SURFACE_TYPE_QT,
  2377.     CAIRO_SURFACE_TYPE_RECORDING,
  2378.     CAIRO_SURFACE_TYPE_VG,
  2379.     CAIRO_SURFACE_TYPE_GL,
  2380.     CAIRO_SURFACE_TYPE_DRM,
  2381.     CAIRO_SURFACE_TYPE_TEE,
  2382.     CAIRO_SURFACE_TYPE_XML,
  2383.     CAIRO_SURFACE_TYPE_SKIA,
  2384.     CAIRO_SURFACE_TYPE_SUBSURFACE,
  2385.     CAIRO_SURFACE_TYPE_COGL
  2386. } cairo_surface_type_t;
  2387.  
  2388. cairo_public cairo_surface_type_t
  2389. cairo_surface_get_type (cairo_surface_t *surface);
  2390.  
  2391. cairo_public cairo_content_t
  2392. cairo_surface_get_content (cairo_surface_t *surface);
  2393.  
  2394. #if CAIRO_HAS_PNG_FUNCTIONS
  2395.  
  2396. cairo_public cairo_status_t
  2397. cairo_surface_write_to_png (cairo_surface_t     *surface,
  2398.                             const char          *filename);
  2399.  
  2400. cairo_public cairo_status_t
  2401. cairo_surface_write_to_png_stream (cairo_surface_t      *surface,
  2402.                                    cairo_write_func_t   write_func,
  2403.                                    void                 *closure);
  2404.  
  2405. #endif
  2406.  
  2407. cairo_public void *
  2408. cairo_surface_get_user_data (cairo_surface_t             *surface,
  2409.                              const cairo_user_data_key_t *key);
  2410.  
  2411. cairo_public cairo_status_t
  2412. cairo_surface_set_user_data (cairo_surface_t             *surface,
  2413.                              const cairo_user_data_key_t *key,
  2414.                              void                        *user_data,
  2415.                              cairo_destroy_func_t        destroy);
  2416.  
  2417. #define CAIRO_MIME_TYPE_JPEG "image/jpeg"
  2418. #define CAIRO_MIME_TYPE_PNG "image/png"
  2419. #define CAIRO_MIME_TYPE_JP2 "image/jp2"
  2420. #define CAIRO_MIME_TYPE_URI "text/x-uri"
  2421. #define CAIRO_MIME_TYPE_UNIQUE_ID "application/x-cairo.uuid"
  2422.  
  2423. cairo_public void
  2424. cairo_surface_get_mime_data (cairo_surface_t            *surface,
  2425.                              const char                 *mime_type,
  2426.                              const unsigned char       **data,
  2427.                              unsigned long              *length);
  2428.  
  2429. cairo_public cairo_status_t
  2430. cairo_surface_set_mime_data (cairo_surface_t            *surface,
  2431.                              const char                 *mime_type,
  2432.                              const unsigned char        *data,
  2433.                              unsigned long               length,
  2434.                              cairo_destroy_func_t        destroy,
  2435.                              void                       *closure);
  2436.  
  2437. cairo_public cairo_bool_t
  2438. cairo_surface_supports_mime_type (cairo_surface_t               *surface,
  2439.                                   const char                    *mime_type);
  2440.  
  2441. cairo_public void
  2442. cairo_surface_get_font_options (cairo_surface_t      *surface,
  2443.                                 cairo_font_options_t *options);
  2444.  
  2445. cairo_public void
  2446. cairo_surface_flush (cairo_surface_t *surface);
  2447.  
  2448. cairo_public void
  2449. cairo_surface_mark_dirty (cairo_surface_t *surface);
  2450.  
  2451. cairo_public void
  2452. cairo_surface_mark_dirty_rectangle (cairo_surface_t *surface,
  2453.                                     int              x,
  2454.                                     int              y,
  2455.                                     int              width,
  2456.                                     int              height);
  2457.  
  2458. cairo_public void
  2459. cairo_surface_set_device_offset (cairo_surface_t *surface,
  2460.                                  double           x_offset,
  2461.                                  double           y_offset);
  2462.  
  2463. cairo_public void
  2464. cairo_surface_get_device_offset (cairo_surface_t *surface,
  2465.                                  double          *x_offset,
  2466.                                  double          *y_offset);
  2467.  
  2468. cairo_public void
  2469. cairo_surface_set_fallback_resolution (cairo_surface_t  *surface,
  2470.                                        double            x_pixels_per_inch,
  2471.                                        double            y_pixels_per_inch);
  2472.  
  2473. cairo_public void
  2474. cairo_surface_get_fallback_resolution (cairo_surface_t  *surface,
  2475.                                        double           *x_pixels_per_inch,
  2476.                                        double           *y_pixels_per_inch);
  2477.  
  2478. cairo_public void
  2479. cairo_surface_copy_page (cairo_surface_t *surface);
  2480.  
  2481. cairo_public void
  2482. cairo_surface_show_page (cairo_surface_t *surface);
  2483.  
  2484. cairo_public cairo_bool_t
  2485. cairo_surface_has_show_text_glyphs (cairo_surface_t *surface);
  2486.  
  2487. /* Image-surface functions */
  2488.  
  2489. cairo_public cairo_surface_t *
  2490. cairo_image_surface_create (cairo_format_t      format,
  2491.                             int                 width,
  2492.                             int                 height);
  2493.  
  2494. cairo_public int
  2495. cairo_format_stride_for_width (cairo_format_t   format,
  2496.                                int              width);
  2497.  
  2498. cairo_public cairo_surface_t *
  2499. cairo_image_surface_create_for_data (unsigned char             *data,
  2500.                                      cairo_format_t             format,
  2501.                                      int                        width,
  2502.                                      int                        height,
  2503.                                      int                        stride);
  2504.  
  2505. cairo_public unsigned char *
  2506. cairo_image_surface_get_data (cairo_surface_t *surface);
  2507.  
  2508. cairo_public cairo_format_t
  2509. cairo_image_surface_get_format (cairo_surface_t *surface);
  2510.  
  2511. cairo_public int
  2512. cairo_image_surface_get_width (cairo_surface_t *surface);
  2513.  
  2514. cairo_public int
  2515. cairo_image_surface_get_height (cairo_surface_t *surface);
  2516.  
  2517. cairo_public int
  2518. cairo_image_surface_get_stride (cairo_surface_t *surface);
  2519.  
  2520. #if CAIRO_HAS_PNG_FUNCTIONS
  2521.  
  2522. cairo_public cairo_surface_t *
  2523. cairo_image_surface_create_from_png (const char *filename);
  2524.  
  2525. cairo_public cairo_surface_t *
  2526. cairo_image_surface_create_from_png_stream (cairo_read_func_t   read_func,
  2527.                                             void                *closure);
  2528.  
  2529. #endif
  2530.  
  2531. /* Recording-surface functions */
  2532.  
  2533. cairo_public cairo_surface_t *
  2534. cairo_recording_surface_create (cairo_content_t          content,
  2535.                                 const cairo_rectangle_t *extents);
  2536.  
  2537. cairo_public void
  2538. cairo_recording_surface_ink_extents (cairo_surface_t *surface,
  2539.                                      double *x0,
  2540.                                      double *y0,
  2541.                                      double *width,
  2542.                                      double *height);
  2543.  
  2544. cairo_public cairo_bool_t
  2545. cairo_recording_surface_get_extents (cairo_surface_t *surface,
  2546.                                      cairo_rectangle_t *extents);
  2547.  
  2548. /* raster-source pattern (callback) functions */
  2549.  
  2550. /**
  2551.  * cairo_raster_source_acquire_func_t:
  2552.  * @pattern: the pattern being rendered from
  2553.  * @callback_data: the user data supplied during creation
  2554.  * @target: the rendering target surface
  2555.  * @extents: rectangular region of interest in pixels in sample space
  2556.  *
  2557.  * #cairo_raster_source_acquire_func_t is the type of function which is
  2558.  * called when a pattern is being rendered from. It should create a surface
  2559.  * that provides the pixel data for the region of interest as defined by
  2560.  * extents, though the surface itself does not have to be limited to that
  2561.  * area. For convenience the surface should probably be of image type,
  2562.  * created with cairo_surface_create_similar_image() for the target (which
  2563.  * enables the number of copies to be reduced during transfer to the
  2564.  * device). Another option, might be to return a similar surface to the
  2565.  * target for explicit handling by the application of a set of cached sources
  2566.  * on the device. The region of sample data provided should be defined using
  2567.  * cairo_surface_set_device_offset() to specify the top-left corner of the
  2568.  * sample data (along with width and height of the surface).
  2569.  *
  2570.  * Returns: a #cairo_surface_t
  2571.  *
  2572.  * Since: 1.12
  2573.  **/
  2574. typedef cairo_surface_t *
  2575. (*cairo_raster_source_acquire_func_t) (cairo_pattern_t *pattern,
  2576.                                        void *callback_data,
  2577.                                        cairo_surface_t *target,
  2578.                                        const cairo_rectangle_int_t *extents);
  2579.  
  2580. /**
  2581.  * cairo_raster_source_release_func_t:
  2582.  * @pattern: the pattern being rendered from
  2583.  * @callback_data: the user data supplied during creation
  2584.  * @surface: the surface created during acquire
  2585.  *
  2586.  * #cairo_raster_source_release_func_t is the type of function which is
  2587.  * called when the pixel data is no longer being access by the pattern
  2588.  * for the rendering operation. Typically this function will simply
  2589.  * destroy the surface created during acquire.
  2590.  *
  2591.  * Since: 1.12
  2592.  **/
  2593. typedef void
  2594. (*cairo_raster_source_release_func_t) (cairo_pattern_t *pattern,
  2595.                                        void *callback_data,
  2596.                                        cairo_surface_t *surface);
  2597.  
  2598. /**
  2599.  * cairo_raster_source_snapshot_func_t:
  2600.  * @pattern: the pattern being rendered from
  2601.  * @callback_data: the user data supplied during creation
  2602.  *
  2603.  * #cairo_raster_source_snapshot_func_t is the type of function which is
  2604.  * called when the pixel data needs to be preserved for later use
  2605.  * during printing. This pattern will be accessed again later, and it
  2606.  * is expected to provide the pixel data that was current at the time
  2607.  * of snapshotting.
  2608.  *
  2609.  * Return value: CAIRO_STATUS_SUCCESS on success, or one of the
  2610.  * #cairo_status_t error codes for failure.
  2611.  *
  2612.  * Since: 1.12
  2613.  **/
  2614. typedef cairo_status_t
  2615. (*cairo_raster_source_snapshot_func_t) (cairo_pattern_t *pattern,
  2616.                                         void *callback_data);
  2617.  
  2618. /**
  2619.  * cairo_raster_source_copy_func_t:
  2620.  * @pattern: the #cairo_pattern_t that was copied to
  2621.  * @callback_data: the user data supplied during creation
  2622.  * @other: the #cairo_pattern_t being used as the source for the copy
  2623.  *
  2624.  * #cairo_raster_source_copy_func_t is the type of function which is
  2625.  * called when the pattern gets copied as a normal part of rendering.
  2626.  *
  2627.  * Return value: CAIRO_STATUS_SUCCESS on success, or one of the
  2628.  * #cairo_status_t error codes for failure.
  2629.  *
  2630.  * Since: 1.12
  2631.  **/
  2632. typedef cairo_status_t
  2633. (*cairo_raster_source_copy_func_t) (cairo_pattern_t *pattern,
  2634.                                     void *callback_data,
  2635.                                     const cairo_pattern_t *other);
  2636.  
  2637. /**
  2638.  * cairo_raster_source_finish_func_t:
  2639.  * @pattern: the pattern being rendered from
  2640.  * @callback_data: the user data supplied during creation
  2641.  *
  2642.  * #cairo_raster_source_finish_func_t is the type of function which is
  2643.  * called when the pattern (or a copy thereof) is no longer required.
  2644.  *
  2645.  * Since: 1.12
  2646.  **/
  2647. typedef void
  2648. (*cairo_raster_source_finish_func_t) (cairo_pattern_t *pattern,
  2649.                                       void *callback_data);
  2650.  
  2651. cairo_public cairo_pattern_t *
  2652. cairo_pattern_create_raster_source (void *user_data,
  2653.                                     cairo_content_t content,
  2654.                                     int width, int height);
  2655.  
  2656. cairo_public void
  2657. cairo_raster_source_pattern_set_callback_data (cairo_pattern_t *pattern,
  2658.                                                void *data);
  2659.  
  2660. cairo_public void *
  2661. cairo_raster_source_pattern_get_callback_data (cairo_pattern_t *pattern);
  2662.  
  2663. cairo_public void
  2664. cairo_raster_source_pattern_set_acquire (cairo_pattern_t *pattern,
  2665.                                          cairo_raster_source_acquire_func_t acquire,
  2666.                                          cairo_raster_source_release_func_t release);
  2667.  
  2668. cairo_public void
  2669. cairo_raster_source_pattern_get_acquire (cairo_pattern_t *pattern,
  2670.                                          cairo_raster_source_acquire_func_t *acquire,
  2671.                                          cairo_raster_source_release_func_t *release);
  2672. cairo_public void
  2673. cairo_raster_source_pattern_set_snapshot (cairo_pattern_t *pattern,
  2674.                                           cairo_raster_source_snapshot_func_t snapshot);
  2675.  
  2676. cairo_public cairo_raster_source_snapshot_func_t
  2677. cairo_raster_source_pattern_get_snapshot (cairo_pattern_t *pattern);
  2678.  
  2679. cairo_public void
  2680. cairo_raster_source_pattern_set_copy (cairo_pattern_t *pattern,
  2681.                                       cairo_raster_source_copy_func_t copy);
  2682.  
  2683. cairo_public cairo_raster_source_copy_func_t
  2684. cairo_raster_source_pattern_get_copy (cairo_pattern_t *pattern);
  2685.  
  2686. cairo_public void
  2687. cairo_raster_source_pattern_set_finish (cairo_pattern_t *pattern,
  2688.                                         cairo_raster_source_finish_func_t finish);
  2689.  
  2690. cairo_public cairo_raster_source_finish_func_t
  2691. cairo_raster_source_pattern_get_finish (cairo_pattern_t *pattern);
  2692.  
  2693. /* Pattern creation functions */
  2694.  
  2695. cairo_public cairo_pattern_t *
  2696. cairo_pattern_create_rgb (double red, double green, double blue);
  2697.  
  2698. cairo_public cairo_pattern_t *
  2699. cairo_pattern_create_rgba (double red, double green, double blue,
  2700.                            double alpha);
  2701.  
  2702. cairo_public cairo_pattern_t *
  2703. cairo_pattern_create_for_surface (cairo_surface_t *surface);
  2704.  
  2705. cairo_public cairo_pattern_t *
  2706. cairo_pattern_create_linear (double x0, double y0,
  2707.                              double x1, double y1);
  2708.  
  2709. cairo_public cairo_pattern_t *
  2710. cairo_pattern_create_radial (double cx0, double cy0, double radius0,
  2711.                              double cx1, double cy1, double radius1);
  2712.  
  2713. cairo_public cairo_pattern_t *
  2714. cairo_pattern_create_mesh (void);
  2715.  
  2716. cairo_public cairo_pattern_t *
  2717. cairo_pattern_reference (cairo_pattern_t *pattern);
  2718.  
  2719. cairo_public void
  2720. cairo_pattern_destroy (cairo_pattern_t *pattern);
  2721.  
  2722. cairo_public unsigned int
  2723. cairo_pattern_get_reference_count (cairo_pattern_t *pattern);
  2724.  
  2725. cairo_public cairo_status_t
  2726. cairo_pattern_status (cairo_pattern_t *pattern);
  2727.  
  2728. cairo_public void *
  2729. cairo_pattern_get_user_data (cairo_pattern_t             *pattern,
  2730.                              const cairo_user_data_key_t *key);
  2731.  
  2732. cairo_public cairo_status_t
  2733. cairo_pattern_set_user_data (cairo_pattern_t             *pattern,
  2734.                              const cairo_user_data_key_t *key,
  2735.                              void                        *user_data,
  2736.                              cairo_destroy_func_t         destroy);
  2737.  
  2738. /**
  2739.  * cairo_pattern_type_t:
  2740.  * @CAIRO_PATTERN_TYPE_SOLID: The pattern is a solid (uniform)
  2741.  * color. It may be opaque or translucent, since 1.2.
  2742.  * @CAIRO_PATTERN_TYPE_SURFACE: The pattern is a based on a surface (an image), since 1.2.
  2743.  * @CAIRO_PATTERN_TYPE_LINEAR: The pattern is a linear gradient, since 1.2.
  2744.  * @CAIRO_PATTERN_TYPE_RADIAL: The pattern is a radial gradient, since 1.2.
  2745.  * @CAIRO_PATTERN_TYPE_MESH: The pattern is a mesh, since 1.12.
  2746.  * @CAIRO_PATTERN_TYPE_RASTER_SOURCE: The pattern is a user pattern providing raster data, since 1.12.
  2747.  *
  2748.  * #cairo_pattern_type_t is used to describe the type of a given pattern.
  2749.  *
  2750.  * The type of a pattern is determined by the function used to create
  2751.  * it. The cairo_pattern_create_rgb() and cairo_pattern_create_rgba()
  2752.  * functions create SOLID patterns. The remaining
  2753.  * cairo_pattern_create<!-- --> functions map to pattern types in obvious
  2754.  * ways.
  2755.  *
  2756.  * The pattern type can be queried with cairo_pattern_get_type()
  2757.  *
  2758.  * Most #cairo_pattern_t functions can be called with a pattern of any
  2759.  * type, (though trying to change the extend or filter for a solid
  2760.  * pattern will have no effect). A notable exception is
  2761.  * cairo_pattern_add_color_stop_rgb() and
  2762.  * cairo_pattern_add_color_stop_rgba() which must only be called with
  2763.  * gradient patterns (either LINEAR or RADIAL). Otherwise the pattern
  2764.  * will be shutdown and put into an error state.
  2765.  *
  2766.  * New entries may be added in future versions.
  2767.  *
  2768.  * Since: 1.2
  2769.  **/
  2770. typedef enum _cairo_pattern_type {
  2771.     CAIRO_PATTERN_TYPE_SOLID,
  2772.     CAIRO_PATTERN_TYPE_SURFACE,
  2773.     CAIRO_PATTERN_TYPE_LINEAR,
  2774.     CAIRO_PATTERN_TYPE_RADIAL,
  2775.     CAIRO_PATTERN_TYPE_MESH,
  2776.     CAIRO_PATTERN_TYPE_RASTER_SOURCE
  2777. } cairo_pattern_type_t;
  2778.  
  2779. cairo_public cairo_pattern_type_t
  2780. cairo_pattern_get_type (cairo_pattern_t *pattern);
  2781.  
  2782. cairo_public void
  2783. cairo_pattern_add_color_stop_rgb (cairo_pattern_t *pattern,
  2784.                                   double offset,
  2785.                                   double red, double green, double blue);
  2786.  
  2787. cairo_public void
  2788. cairo_pattern_add_color_stop_rgba (cairo_pattern_t *pattern,
  2789.                                    double offset,
  2790.                                    double red, double green, double blue,
  2791.                                    double alpha);
  2792.  
  2793. cairo_public void
  2794. cairo_mesh_pattern_begin_patch (cairo_pattern_t *pattern);
  2795.  
  2796. cairo_public void
  2797. cairo_mesh_pattern_end_patch (cairo_pattern_t *pattern);
  2798.  
  2799. cairo_public void
  2800. cairo_mesh_pattern_curve_to (cairo_pattern_t *pattern,
  2801.                              double x1, double y1,
  2802.                              double x2, double y2,
  2803.                              double x3, double y3);
  2804.  
  2805. cairo_public void
  2806. cairo_mesh_pattern_line_to (cairo_pattern_t *pattern,
  2807.                             double x, double y);
  2808.  
  2809. cairo_public void
  2810. cairo_mesh_pattern_move_to (cairo_pattern_t *pattern,
  2811.                             double x, double y);
  2812.  
  2813. cairo_public void
  2814. cairo_mesh_pattern_set_control_point (cairo_pattern_t *pattern,
  2815.                                       unsigned int point_num,
  2816.                                       double x, double y);
  2817.  
  2818. cairo_public void
  2819. cairo_mesh_pattern_set_corner_color_rgb (cairo_pattern_t *pattern,
  2820.                                          unsigned int corner_num,
  2821.                                          double red, double green, double blue);
  2822.  
  2823. cairo_public void
  2824. cairo_mesh_pattern_set_corner_color_rgba (cairo_pattern_t *pattern,
  2825.                                           unsigned int corner_num,
  2826.                                           double red, double green, double blue,
  2827.                                           double alpha);
  2828.  
  2829. cairo_public void
  2830. cairo_pattern_set_matrix (cairo_pattern_t      *pattern,
  2831.                           const cairo_matrix_t *matrix);
  2832.  
  2833. cairo_public void
  2834. cairo_pattern_get_matrix (cairo_pattern_t *pattern,
  2835.                           cairo_matrix_t  *matrix);
  2836.  
  2837. /**
  2838.  * cairo_extend_t:
  2839.  * @CAIRO_EXTEND_NONE: pixels outside of the source pattern
  2840.  *   are fully transparent (Since 1.0)
  2841.  * @CAIRO_EXTEND_REPEAT: the pattern is tiled by repeating (Since 1.0)
  2842.  * @CAIRO_EXTEND_REFLECT: the pattern is tiled by reflecting
  2843.  *   at the edges (Since 1.0; but only implemented for surface patterns since 1.6)
  2844.  * @CAIRO_EXTEND_PAD: pixels outside of the pattern copy
  2845.  *   the closest pixel from the source (Since 1.2; but only
  2846.  *   implemented for surface patterns since 1.6)
  2847.  *
  2848.  * #cairo_extend_t is used to describe how pattern color/alpha will be
  2849.  * determined for areas "outside" the pattern's natural area, (for
  2850.  * example, outside the surface bounds or outside the gradient
  2851.  * geometry).
  2852.  *
  2853.  * Mesh patterns are not affected by the extend mode.
  2854.  *
  2855.  * The default extend mode is %CAIRO_EXTEND_NONE for surface patterns
  2856.  * and %CAIRO_EXTEND_PAD for gradient patterns.
  2857.  *
  2858.  * New entries may be added in future versions.
  2859.  *
  2860.  * Since: 1.0
  2861.  **/
  2862. typedef enum _cairo_extend {
  2863.     CAIRO_EXTEND_NONE,
  2864.     CAIRO_EXTEND_REPEAT,
  2865.     CAIRO_EXTEND_REFLECT,
  2866.     CAIRO_EXTEND_PAD
  2867. } cairo_extend_t;
  2868.  
  2869. cairo_public void
  2870. cairo_pattern_set_extend (cairo_pattern_t *pattern, cairo_extend_t extend);
  2871.  
  2872. cairo_public cairo_extend_t
  2873. cairo_pattern_get_extend (cairo_pattern_t *pattern);
  2874.  
  2875. /**
  2876.  * cairo_filter_t:
  2877.  * @CAIRO_FILTER_FAST: A high-performance filter, with quality similar
  2878.  *     to %CAIRO_FILTER_NEAREST (Since 1.0)
  2879.  * @CAIRO_FILTER_GOOD: A reasonable-performance filter, with quality
  2880.  *     similar to %CAIRO_FILTER_BILINEAR (Since 1.0)
  2881.  * @CAIRO_FILTER_BEST: The highest-quality available, performance may
  2882.  *     not be suitable for interactive use. (Since 1.0)
  2883.  * @CAIRO_FILTER_NEAREST: Nearest-neighbor filtering (Since 1.0)
  2884.  * @CAIRO_FILTER_BILINEAR: Linear interpolation in two dimensions (Since 1.0)
  2885.  * @CAIRO_FILTER_GAUSSIAN: This filter value is currently
  2886.  *     unimplemented, and should not be used in current code. (Since 1.0)
  2887.  *
  2888.  * #cairo_filter_t is used to indicate what filtering should be
  2889.  * applied when reading pixel values from patterns. See
  2890.  * cairo_pattern_set_filter() for indicating the desired filter to be
  2891.  * used with a particular pattern.
  2892.  *
  2893.  * Since: 1.0
  2894.  **/
  2895. typedef enum _cairo_filter {
  2896.     CAIRO_FILTER_FAST,
  2897.     CAIRO_FILTER_GOOD,
  2898.     CAIRO_FILTER_BEST,
  2899.     CAIRO_FILTER_NEAREST,
  2900.     CAIRO_FILTER_BILINEAR,
  2901.     CAIRO_FILTER_GAUSSIAN
  2902. } cairo_filter_t;
  2903.  
  2904. cairo_public void
  2905. cairo_pattern_set_filter (cairo_pattern_t *pattern, cairo_filter_t filter);
  2906.  
  2907. cairo_public cairo_filter_t
  2908. cairo_pattern_get_filter (cairo_pattern_t *pattern);
  2909.  
  2910. cairo_public cairo_status_t
  2911. cairo_pattern_get_rgba (cairo_pattern_t *pattern,
  2912.                         double *red, double *green,
  2913.                         double *blue, double *alpha);
  2914.  
  2915. cairo_public cairo_status_t
  2916. cairo_pattern_get_surface (cairo_pattern_t *pattern,
  2917.                            cairo_surface_t **surface);
  2918.  
  2919.  
  2920. cairo_public cairo_status_t
  2921. cairo_pattern_get_color_stop_rgba (cairo_pattern_t *pattern,
  2922.                                    int index, double *offset,
  2923.                                    double *red, double *green,
  2924.                                    double *blue, double *alpha);
  2925.  
  2926. cairo_public cairo_status_t
  2927. cairo_pattern_get_color_stop_count (cairo_pattern_t *pattern,
  2928.                                     int *count);
  2929.  
  2930. cairo_public cairo_status_t
  2931. cairo_pattern_get_linear_points (cairo_pattern_t *pattern,
  2932.                                  double *x0, double *y0,
  2933.                                  double *x1, double *y1);
  2934.  
  2935. cairo_public cairo_status_t
  2936. cairo_pattern_get_radial_circles (cairo_pattern_t *pattern,
  2937.                                   double *x0, double *y0, double *r0,
  2938.                                   double *x1, double *y1, double *r1);
  2939.  
  2940. cairo_public cairo_status_t
  2941. cairo_mesh_pattern_get_patch_count (cairo_pattern_t *pattern,
  2942.                                     unsigned int *count);
  2943.  
  2944. cairo_public cairo_path_t *
  2945. cairo_mesh_pattern_get_path (cairo_pattern_t *pattern,
  2946.                              unsigned int patch_num);
  2947.  
  2948. cairo_public cairo_status_t
  2949. cairo_mesh_pattern_get_corner_color_rgba (cairo_pattern_t *pattern,
  2950.                                           unsigned int patch_num,
  2951.                                           unsigned int corner_num,
  2952.                                           double *red, double *green,
  2953.                                           double *blue, double *alpha);
  2954.  
  2955. cairo_public cairo_status_t
  2956. cairo_mesh_pattern_get_control_point (cairo_pattern_t *pattern,
  2957.                                       unsigned int patch_num,
  2958.                                       unsigned int point_num,
  2959.                                       double *x, double *y);
  2960.  
  2961. /* Matrix functions */
  2962.  
  2963. cairo_public void
  2964. cairo_matrix_init (cairo_matrix_t *matrix,
  2965.                    double  xx, double  yx,
  2966.                    double  xy, double  yy,
  2967.                    double  x0, double  y0);
  2968.  
  2969. cairo_public void
  2970. cairo_matrix_init_identity (cairo_matrix_t *matrix);
  2971.  
  2972. cairo_public void
  2973. cairo_matrix_init_translate (cairo_matrix_t *matrix,
  2974.                              double tx, double ty);
  2975.  
  2976. cairo_public void
  2977. cairo_matrix_init_scale (cairo_matrix_t *matrix,
  2978.                          double sx, double sy);
  2979.  
  2980. cairo_public void
  2981. cairo_matrix_init_rotate (cairo_matrix_t *matrix,
  2982.                           double radians);
  2983.  
  2984. cairo_public void
  2985. cairo_matrix_translate (cairo_matrix_t *matrix, double tx, double ty);
  2986.  
  2987. cairo_public void
  2988. cairo_matrix_scale (cairo_matrix_t *matrix, double sx, double sy);
  2989.  
  2990. cairo_public void
  2991. cairo_matrix_rotate (cairo_matrix_t *matrix, double radians);
  2992.  
  2993. cairo_public cairo_status_t
  2994. cairo_matrix_invert (cairo_matrix_t *matrix);
  2995.  
  2996. cairo_public void
  2997. cairo_matrix_multiply (cairo_matrix_t       *result,
  2998.                        const cairo_matrix_t *a,
  2999.                        const cairo_matrix_t *b);
  3000.  
  3001. cairo_public void
  3002. cairo_matrix_transform_distance (const cairo_matrix_t *matrix,
  3003.                                  double *dx, double *dy);
  3004.  
  3005. cairo_public void
  3006. cairo_matrix_transform_point (const cairo_matrix_t *matrix,
  3007.                               double *x, double *y);
  3008.  
  3009. /* Region functions */
  3010.  
  3011. /**
  3012.  * cairo_region_t:
  3013.  *
  3014.  * A #cairo_region_t represents a set of integer-aligned rectangles.
  3015.  *
  3016.  * It allows set-theoretical operations like cairo_region_union() and
  3017.  * cairo_region_intersect() to be performed on them.
  3018.  *
  3019.  * Memory management of #cairo_region_t is done with
  3020.  * cairo_region_reference() and cairo_region_destroy().
  3021.  *
  3022.  * Since: 1.10
  3023.  **/
  3024. typedef struct _cairo_region cairo_region_t;
  3025.  
  3026. typedef enum _cairo_region_overlap {
  3027.     CAIRO_REGION_OVERLAP_IN,            /* completely inside region */
  3028.     CAIRO_REGION_OVERLAP_OUT,           /* completely outside region */
  3029.     CAIRO_REGION_OVERLAP_PART           /* partly inside region */
  3030. } cairo_region_overlap_t;
  3031.  
  3032. cairo_public cairo_region_t *
  3033. cairo_region_create (void);
  3034.  
  3035. cairo_public cairo_region_t *
  3036. cairo_region_create_rectangle (const cairo_rectangle_int_t *rectangle);
  3037.  
  3038. cairo_public cairo_region_t *
  3039. cairo_region_create_rectangles (const cairo_rectangle_int_t *rects,
  3040.                                 int count);
  3041.  
  3042. cairo_public cairo_region_t *
  3043. cairo_region_copy (const cairo_region_t *original);
  3044.  
  3045. cairo_public cairo_region_t *
  3046. cairo_region_reference (cairo_region_t *region);
  3047.  
  3048. cairo_public void
  3049. cairo_region_destroy (cairo_region_t *region);
  3050.  
  3051. cairo_public cairo_bool_t
  3052. cairo_region_equal (const cairo_region_t *a, const cairo_region_t *b);
  3053.  
  3054. cairo_public cairo_status_t
  3055. cairo_region_status (const cairo_region_t *region);
  3056.  
  3057. cairo_public void
  3058. cairo_region_get_extents (const cairo_region_t        *region,
  3059.                           cairo_rectangle_int_t *extents);
  3060.  
  3061. cairo_public int
  3062. cairo_region_num_rectangles (const cairo_region_t *region);
  3063.  
  3064. cairo_public void
  3065. cairo_region_get_rectangle (const cairo_region_t  *region,
  3066.                             int                    nth,
  3067.                             cairo_rectangle_int_t *rectangle);
  3068.  
  3069. cairo_public cairo_bool_t
  3070. cairo_region_is_empty (const cairo_region_t *region);
  3071.  
  3072. cairo_public cairo_region_overlap_t
  3073. cairo_region_contains_rectangle (const cairo_region_t *region,
  3074.                                  const cairo_rectangle_int_t *rectangle);
  3075.  
  3076. cairo_public cairo_bool_t
  3077. cairo_region_contains_point (const cairo_region_t *region, int x, int y);
  3078.  
  3079. cairo_public void
  3080. cairo_region_translate (cairo_region_t *region, int dx, int dy);
  3081.  
  3082. cairo_public cairo_status_t
  3083. cairo_region_subtract (cairo_region_t *dst, const cairo_region_t *other);
  3084.  
  3085. cairo_public cairo_status_t
  3086. cairo_region_subtract_rectangle (cairo_region_t *dst,
  3087.                                  const cairo_rectangle_int_t *rectangle);
  3088.  
  3089. cairo_public cairo_status_t
  3090. cairo_region_intersect (cairo_region_t *dst, const cairo_region_t *other);
  3091.  
  3092. cairo_public cairo_status_t
  3093. cairo_region_intersect_rectangle (cairo_region_t *dst,
  3094.                                   const cairo_rectangle_int_t *rectangle);
  3095.  
  3096. cairo_public cairo_status_t
  3097. cairo_region_union (cairo_region_t *dst, const cairo_region_t *other);
  3098.  
  3099. cairo_public cairo_status_t
  3100. cairo_region_union_rectangle (cairo_region_t *dst,
  3101.                               const cairo_rectangle_int_t *rectangle);
  3102.  
  3103. cairo_public cairo_status_t
  3104. cairo_region_xor (cairo_region_t *dst, const cairo_region_t *other);
  3105.  
  3106. cairo_public cairo_status_t
  3107. cairo_region_xor_rectangle (cairo_region_t *dst,
  3108.                             const cairo_rectangle_int_t *rectangle);
  3109.  
  3110. /* Functions to be used while debugging (not intended for use in production code) */
  3111. cairo_public void
  3112. cairo_debug_reset_static_data (void);
  3113.  
  3114.  
  3115. CAIRO_END_DECLS
  3116.  
  3117. #endif /* CAIRO_H */
  3118.