Subversion Repositories Kolibri OS

Rev

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