Subversion Repositories Kolibri OS

/* cairo - a vector graphics library with display and print output

 *

 * Copyright © 2002 University of Southern California

 * Copyright © 2005 Red Hat, Inc.

 *

 * This library is free software; you can redistribute it and/or

 * modify it either under the terms of the GNU Lesser General Public

 * License version 2.1 as published by the Free Software Foundation

 * (the "LGPL") or, at your option, under the terms of the Mozilla

 * Public License Version 1.1 (the "MPL"). If you do not alter this

 * notice, a recipient may use your version of this file under either

 * the MPL or the LGPL.

 *

 * You should have received a copy of the LGPL along with this library

 * in the file COPYING-LGPL-2.1; if not, write to the Free Software

 * Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA

 * You should have received a copy of the MPL along with this library

 * in the file COPYING-MPL-1.1

 *

 * The contents of this file are subject to the Mozilla Public License

 * Version 1.1 (the "License"); you may not use this file except in

 * compliance with the License. You may obtain a copy of the License at

 * http://www.mozilla.org/MPL/

 *

 * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY

 * OF ANY KIND, either express or implied. See the LGPL or the MPL for

 * the specific language governing rights and limitations.

 *

 * The Original Code is the cairo graphics library.

 *

 * The Initial Developer of the Original Code is University of Southern

 * California.

 *

 * Contributor(s):

 *	Carl D. Worth 

 */

#ifndef CAIRO_H

#define CAIRO_H

#include "cairo-version.h"

#include "cairo-features.h"

#include "cairo-deprecated.h"

#ifdef  __cplusplus

# define CAIRO_BEGIN_DECLS  extern "C" {

# define CAIRO_END_DECLS    }

#else

# define CAIRO_BEGIN_DECLS

# define CAIRO_END_DECLS

#endif

#ifndef cairo_public

# if defined (_MSC_VER) && ! defined (CAIRO_WIN32_STATIC_BUILD)

#  define cairo_public __declspec(dllimport)

# else

#  define cairo_public

# endif

#endif

CAIRO_BEGIN_DECLS

#define CAIRO_VERSION_ENCODE(major, minor, micro) (	\

	  ((major) * 10000)				\

	+ ((minor) *   100)				\

	+ ((micro) *     1))

#define CAIRO_VERSION CAIRO_VERSION_ENCODE(	\

	CAIRO_VERSION_MAJOR,			\

	CAIRO_VERSION_MINOR,			\

	CAIRO_VERSION_MICRO)

#define CAIRO_VERSION_STRINGIZE_(major, minor, micro)	\

	#major"."#minor"."#micro

#define CAIRO_VERSION_STRINGIZE(major, minor, micro)	\

	CAIRO_VERSION_STRINGIZE_(major, minor, micro)

#define CAIRO_VERSION_STRING CAIRO_VERSION_STRINGIZE(	\

	CAIRO_VERSION_MAJOR,				\

	CAIRO_VERSION_MINOR,				\

	CAIRO_VERSION_MICRO)

cairo_public int

cairo_version (void);

cairo_public const char*

cairo_version_string (void);

/**

 * cairo_bool_t:

 *

 * #cairo_bool_t is used for boolean values. Returns of type

 * #cairo_bool_t will always be either 0 or 1, but testing against

 * these values explicitly is not encouraged; just use the

 * value as a boolean condition.

 *

 * 

 *  if (cairo_in_stroke (cr, x, y)) {

 *      /* do something */

 *  }

 * 

 *

 * Since: 1.0

 **/

typedef int cairo_bool_t;

/**

 * cairo_t:

 *

 * A #cairo_t contains the current state of the rendering device,

 * including coordinates of yet to be drawn shapes.

 *

 * Cairo contexts, as #cairo_t objects are named, are central to

 * cairo and all drawing with cairo is always done to a #cairo_t

 * object.

 *

 * Memory management of #cairo_t is done with

 * cairo_reference() and cairo_destroy().

 *

 * Since: 1.0

 **/

typedef struct _cairo cairo_t;

/**

 * cairo_surface_t:

 *

 * A #cairo_surface_t represents an image, either as the destination

 * of a drawing operation or as source when drawing onto another

 * surface.  To draw to a #cairo_surface_t, create a cairo context

 * with the surface as the target, using cairo_create().

 *

 * There are different subtypes of #cairo_surface_t for

 * different drawing backends; for example, cairo_image_surface_create()

 * creates a bitmap image in memory.

 * The type of a surface can be queried with cairo_surface_get_type().

 *

 * The initial contents of a surface after creation depend upon the manner

 * of its creation. If cairo creates the surface and backing storage for

 * the user, it will be initially cleared; for example,

 * cairo_image_surface_create() and cairo_surface_create_similar().

 * Alternatively, if the user passes in a reference to some backing storage

 * and asks cairo to wrap that in a #cairo_surface_t, then the contents are

 * not modified; for example, cairo_image_surface_create_for_data() and

 * cairo_xlib_surface_create().

 *

 * Memory management of #cairo_surface_t is done with

 * cairo_surface_reference() and cairo_surface_destroy().

 *

 * Since: 1.0

 **/

typedef struct _cairo_surface cairo_surface_t;

/**

 * cairo_device_t:

 *

 * A #cairo_device_t represents the driver interface for drawing

 * operations to a #cairo_surface_t.  There are different subtypes of

 * #cairo_device_t for different drawing backends; for example,

 * cairo_egl_device_create() creates a device that wraps an EGL display and

 * context.

 *

 * The type of a device can be queried with cairo_device_get_type().

 *

 * Memory management of #cairo_device_t is done with

 * cairo_device_reference() and cairo_device_destroy().

 *

 * Since: 1.10

 **/

typedef struct _cairo_device cairo_device_t;

/**

 * cairo_matrix_t:

 * @xx: xx component of the affine transformation

 * @yx: yx component of the affine transformation

 * @xy: xy component of the affine transformation

 * @yy: yy component of the affine transformation

 * @x0: X translation component of the affine transformation

 * @y0: Y translation component of the affine transformation

 *

 * A #cairo_matrix_t holds an affine transformation, such as a scale,

 * rotation, shear, or a combination of those. The transformation of

 * a point (x, y) is given by:

 * 

 *     x_new = xx * x + xy * y + x0;

 *     y_new = yx * x + yy * y + y0;

 * 

 *

 * Since: 1.0

 **/

typedef struct _cairo_matrix {

    double xx; double yx;

    double xy; double yy;

    double x0; double y0;

} cairo_matrix_t;

/**

 * cairo_pattern_t:

 *

 * A #cairo_pattern_t represents a source when drawing onto a

 * surface. There are different subtypes of #cairo_pattern_t,

 * for different types of sources; for example,

 * cairo_pattern_create_rgb() creates a pattern for a solid

 * opaque color.

 *

 * Other than various

 * cairo_pattern_create_type()

 * functions, some of the pattern types can be implicitly created using various

 * cairo_set_source_type() functions;

 * for example cairo_set_source_rgb().

 *

 * The type of a pattern can be queried with cairo_pattern_get_type().

 *

 * Memory management of #cairo_pattern_t is done with

 * cairo_pattern_reference() and cairo_pattern_destroy().

 *

 * Since: 1.0

 **/

typedef struct _cairo_pattern cairo_pattern_t;

/**

 * cairo_destroy_func_t:

 * @data: The data element being destroyed.

 *

 * #cairo_destroy_func_t the type of function which is called when a

 * data element is destroyed. It is passed the pointer to the data

 * element and should free any memory and resources allocated for it.

 *

 * Since: 1.0

 **/

typedef void (*cairo_destroy_func_t) (void *data);

/**

 * cairo_user_data_key_t:

 * @unused: not used; ignore.

 *

 * #cairo_user_data_key_t is used for attaching user data to cairo

 * data structures.  The actual contents of the struct is never used,

 * and there is no need to initialize the object; only the unique

 * address of a #cairo_data_key_t object is used.  Typically, you

 * would just use the address of a static #cairo_data_key_t object.

 *

 * Since: 1.0

 **/

typedef struct _cairo_user_data_key {

    int unused;

} cairo_user_data_key_t;

/**

 * cairo_status_t:

 * @CAIRO_STATUS_SUCCESS: no error has occurred (Since 1.0)

 * @CAIRO_STATUS_NO_MEMORY: out of memory (Since 1.0)

 * @CAIRO_STATUS_INVALID_RESTORE: cairo_restore() called without matching cairo_save() (Since 1.0)

 * @CAIRO_STATUS_INVALID_POP_GROUP: no saved group to pop, i.e. cairo_pop_group() without matching cairo_push_group() (Since 1.0)

 * @CAIRO_STATUS_NO_CURRENT_POINT: no current point defined (Since 1.0)

 * @CAIRO_STATUS_INVALID_MATRIX: invalid matrix (not invertible) (Since 1.0)

 * @CAIRO_STATUS_INVALID_STATUS: invalid value for an input #cairo_status_t (Since 1.0)

 * @CAIRO_STATUS_NULL_POINTER: %NULL pointer (Since 1.0)

 * @CAIRO_STATUS_INVALID_STRING: input string not valid UTF-8 (Since 1.0)

 * @CAIRO_STATUS_INVALID_PATH_DATA: input path data not valid (Since 1.0)

 * @CAIRO_STATUS_READ_ERROR: error while reading from input stream (Since 1.0)

 * @CAIRO_STATUS_WRITE_ERROR: error while writing to output stream (Since 1.0)

 * @CAIRO_STATUS_SURFACE_FINISHED: target surface has been finished (Since 1.0)

 * @CAIRO_STATUS_SURFACE_TYPE_MISMATCH: the surface type is not appropriate for the operation (Since 1.0)

 * @CAIRO_STATUS_PATTERN_TYPE_MISMATCH: the pattern type is not appropriate for the operation (Since 1.0)

 * @CAIRO_STATUS_INVALID_CONTENT: invalid value for an input #cairo_content_t (Since 1.0)

 * @CAIRO_STATUS_INVALID_FORMAT: invalid value for an input #cairo_format_t (Since 1.0)

 * @CAIRO_STATUS_INVALID_VISUAL: invalid value for an input Visual* (Since 1.0)

 * @CAIRO_STATUS_FILE_NOT_FOUND: file not found (Since 1.0)

 * @CAIRO_STATUS_INVALID_DASH: invalid value for a dash setting (Since 1.0)

 * @CAIRO_STATUS_INVALID_DSC_COMMENT: invalid value for a DSC comment (Since 1.2)

 * @CAIRO_STATUS_INVALID_INDEX: invalid index passed to getter (Since 1.4)

 * @CAIRO_STATUS_CLIP_NOT_REPRESENTABLE: clip region not representable in desired format (Since 1.4)

 * @CAIRO_STATUS_TEMP_FILE_ERROR: error creating or writing to a temporary file (Since 1.6)

 * @CAIRO_STATUS_INVALID_STRIDE: invalid value for stride (Since 1.6)

 * @CAIRO_STATUS_FONT_TYPE_MISMATCH: the font type is not appropriate for the operation (Since 1.8)

 * @CAIRO_STATUS_USER_FONT_IMMUTABLE: the user-font is immutable (Since 1.8)

 * @CAIRO_STATUS_USER_FONT_ERROR: error occurred in a user-font callback function (Since 1.8)

 * @CAIRO_STATUS_NEGATIVE_COUNT: negative number used where it is not allowed (Since 1.8)

 * @CAIRO_STATUS_INVALID_CLUSTERS: input clusters do not represent the accompanying text and glyph array (Since 1.8)

 * @CAIRO_STATUS_INVALID_SLANT: invalid value for an input #cairo_font_slant_t (Since 1.8)

 * @CAIRO_STATUS_INVALID_WEIGHT: invalid value for an input #cairo_font_weight_t (Since 1.8)

 * @CAIRO_STATUS_INVALID_SIZE: invalid value (typically too big) for the size of the input (surface, pattern, etc.) (Since 1.10)

 * @CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED: user-font method not implemented (Since 1.10)

 * @CAIRO_STATUS_DEVICE_TYPE_MISMATCH: the device type is not appropriate for the operation (Since 1.10)

 * @CAIRO_STATUS_DEVICE_ERROR: an operation to the device caused an unspecified error (Since 1.10)

 * @CAIRO_STATUS_INVALID_MESH_CONSTRUCTION: a mesh pattern

 *   construction operation was used outside of a

 *   cairo_mesh_pattern_begin_patch()/cairo_mesh_pattern_end_patch()

 *   pair (Since 1.12)

 * @CAIRO_STATUS_DEVICE_FINISHED: target device has been finished (Since 1.12)

 * @CAIRO_STATUS_LAST_STATUS: this is a special value indicating the number of

 *   status values defined in this enumeration.  When using this value, note

 *   that the version of cairo at run-time may have additional status values

 *   defined than the value of this symbol at compile-time. (Since 1.10)

 *

 * #cairo_status_t is used to indicate errors that can occur when

 * using Cairo. In some cases it is returned directly by functions.

 * but when using #cairo_t, the last error, if any, is stored in

 * the context and can be retrieved with cairo_status().

 *

 * New entries may be added in future versions.  Use cairo_status_to_string()

 * to get a human-readable representation of an error message.

 *

 * Since: 1.0

 **/

typedef enum _cairo_status {

    CAIRO_STATUS_SUCCESS = 0,

    CAIRO_STATUS_NO_MEMORY,

    CAIRO_STATUS_INVALID_RESTORE,

    CAIRO_STATUS_INVALID_POP_GROUP,

    CAIRO_STATUS_NO_CURRENT_POINT,

    CAIRO_STATUS_INVALID_MATRIX,

    CAIRO_STATUS_INVALID_STATUS,

    CAIRO_STATUS_NULL_POINTER,

    CAIRO_STATUS_INVALID_STRING,

    CAIRO_STATUS_INVALID_PATH_DATA,

    CAIRO_STATUS_READ_ERROR,

    CAIRO_STATUS_WRITE_ERROR,

    CAIRO_STATUS_SURFACE_FINISHED,

    CAIRO_STATUS_SURFACE_TYPE_MISMATCH,

    CAIRO_STATUS_PATTERN_TYPE_MISMATCH,

    CAIRO_STATUS_INVALID_CONTENT,

    CAIRO_STATUS_INVALID_FORMAT,

    CAIRO_STATUS_INVALID_VISUAL,

    CAIRO_STATUS_FILE_NOT_FOUND,

    CAIRO_STATUS_INVALID_DASH,

    CAIRO_STATUS_INVALID_DSC_COMMENT,

    CAIRO_STATUS_INVALID_INDEX,

    CAIRO_STATUS_CLIP_NOT_REPRESENTABLE,

    CAIRO_STATUS_TEMP_FILE_ERROR,

    CAIRO_STATUS_INVALID_STRIDE,

    CAIRO_STATUS_FONT_TYPE_MISMATCH,

    CAIRO_STATUS_USER_FONT_IMMUTABLE,

    CAIRO_STATUS_USER_FONT_ERROR,

    CAIRO_STATUS_NEGATIVE_COUNT,

    CAIRO_STATUS_INVALID_CLUSTERS,

    CAIRO_STATUS_INVALID_SLANT,

    CAIRO_STATUS_INVALID_WEIGHT,

    CAIRO_STATUS_INVALID_SIZE,

    CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED,

    CAIRO_STATUS_DEVICE_TYPE_MISMATCH,

    CAIRO_STATUS_DEVICE_ERROR,

    CAIRO_STATUS_INVALID_MESH_CONSTRUCTION,

    CAIRO_STATUS_DEVICE_FINISHED,

    CAIRO_STATUS_LAST_STATUS

} cairo_status_t;

/**

 * cairo_content_t:

 * @CAIRO_CONTENT_COLOR: The surface will hold color content only. (Since 1.0)

 * @CAIRO_CONTENT_ALPHA: The surface will hold alpha content only. (Since 1.0)

 * @CAIRO_CONTENT_COLOR_ALPHA: The surface will hold color and alpha content. (Since 1.0)

 *

 * #cairo_content_t is used to describe the content that a surface will

 * contain, whether color information, alpha information (translucence

 * vs. opacity), or both.

 *

 * Note: The large values here are designed to keep #cairo_content_t

 * values distinct from #cairo_format_t values so that the

 * implementation can detect the error if users confuse the two types.

 *

 * Since: 1.0

 **/

typedef enum _cairo_content {

    CAIRO_CONTENT_COLOR		= 0x1000,

    CAIRO_CONTENT_ALPHA		= 0x2000,

    CAIRO_CONTENT_COLOR_ALPHA	= 0x3000

} cairo_content_t;

/**

 * cairo_format_t:

 * @CAIRO_FORMAT_INVALID: no such format exists or is supported.

 * @CAIRO_FORMAT_ARGB32: each pixel is a 32-bit quantity, with

 *   alpha in the upper 8 bits, then red, then green, then blue.

 *   The 32-bit quantities are stored native-endian. Pre-multiplied

 *   alpha is used. (That is, 50% transparent red is 0x80800000,

 *   not 0x80ff0000.) (Since 1.0)

 * @CAIRO_FORMAT_RGB24: each pixel is a 32-bit quantity, with

 *   the upper 8 bits unused. Red, Green, and Blue are stored

 *   in the remaining 24 bits in that order. (Since 1.0)

 * @CAIRO_FORMAT_A8: each pixel is a 8-bit quantity holding

 *   an alpha value. (Since 1.0)

 * @CAIRO_FORMAT_A1: each pixel is a 1-bit quantity holding

 *   an alpha value. Pixels are packed together into 32-bit

 *   quantities. The ordering of the bits matches the

 *   endianess of the platform. On a big-endian machine, the

 *   first pixel is in the uppermost bit, on a little-endian

 *   machine the first pixel is in the least-significant bit. (Since 1.0)

 * @CAIRO_FORMAT_RGB16_565: each pixel is a 16-bit quantity

 *   with red in the upper 5 bits, then green in the middle

 *   6 bits, and blue in the lower 5 bits. (Since 1.2)

 * @CAIRO_FORMAT_RGB30: like RGB24 but with 10bpc. (Since 1.12)

 *

 * #cairo_format_t is used to identify the memory format of

 * image data.

 *

 * New entries may be added in future versions.

 *

 * Since: 1.0

 **/

typedef enum _cairo_format {

    CAIRO_FORMAT_INVALID   = -1,

    CAIRO_FORMAT_ARGB32    = 0,

    CAIRO_FORMAT_RGB24     = 1,

    CAIRO_FORMAT_A8        = 2,

    CAIRO_FORMAT_A1        = 3,

    CAIRO_FORMAT_RGB16_565 = 4,

    CAIRO_FORMAT_RGB30     = 5

} cairo_format_t;

/**

 * cairo_write_func_t:

 * @closure: the output closure

 * @data: the buffer containing the data to write

 * @length: the amount of data to write

 *

 * #cairo_write_func_t is the type of function which is called when a

 * backend needs to write data to an output stream.  It is passed the

 * closure which was specified by the user at the time the write

 * function was registered, the data to write and the length of the

 * data in bytes.  The write function should return

 * %CAIRO_STATUS_SUCCESS if all the data was successfully written,

 * %CAIRO_STATUS_WRITE_ERROR otherwise.

 *

 * Returns: the status code of the write operation

 *

 * Since: 1.0

 **/

typedef cairo_status_t (*cairo_write_func_t) (void		  *closure,

					      const unsigned char *data,

					      unsigned int	   length);

/**

 * cairo_read_func_t:

 * @closure: the input closure

 * @data: the buffer into which to read the data

 * @length: the amount of data to read

 *

 * #cairo_read_func_t is the type of function which is called when a

 * backend needs to read data from an input stream.  It is passed the

 * closure which was specified by the user at the time the read

 * function was registered, the buffer to read the data into and the

 * length of the data in bytes.  The read function should return

 * %CAIRO_STATUS_SUCCESS if all the data was successfully read,

 * %CAIRO_STATUS_READ_ERROR otherwise.

 *

 * Returns: the status code of the read operation

 *

 * Since: 1.0

 **/

typedef cairo_status_t (*cairo_read_func_t) (void		*closure,

					     unsigned char	*data,

					     unsigned int	length);

/**

 * cairo_rectangle_int_t:

 * @x: X coordinate of the left side of the rectangle

 * @y: Y coordinate of the the top side of the rectangle

 * @width: width of the rectangle

 * @height: height of the rectangle

 *

 * A data structure for holding a rectangle with integer coordinates.

 *

 * Since: 1.10

 **/

typedef struct _cairo_rectangle_int {

    int x, y;

    int width, height;

} cairo_rectangle_int_t;

/* Functions for manipulating state objects */

cairo_public cairo_t *

cairo_create (cairo_surface_t *target);

cairo_public cairo_t *

cairo_reference (cairo_t *cr);

cairo_public void

cairo_destroy (cairo_t *cr);

cairo_public unsigned int

cairo_get_reference_count (cairo_t *cr);

cairo_public void *

cairo_get_user_data (cairo_t			 *cr,

		     const cairo_user_data_key_t *key);

cairo_public cairo_status_t

cairo_set_user_data (cairo_t			 *cr,

		     const cairo_user_data_key_t *key,

		     void			 *user_data,

		     cairo_destroy_func_t	  destroy);

cairo_public void

cairo_save (cairo_t *cr);

cairo_public void

cairo_restore (cairo_t *cr);

cairo_public void

cairo_push_group (cairo_t *cr);

cairo_public void

cairo_push_group_with_content (cairo_t *cr, cairo_content_t content);

cairo_public cairo_pattern_t *

cairo_pop_group (cairo_t *cr);

cairo_public void

cairo_pop_group_to_source (cairo_t *cr);

/* Modify state */

/**

 * cairo_operator_t:

 * @CAIRO_OPERATOR_CLEAR: clear destination layer (bounded) (Since 1.0)

 * @CAIRO_OPERATOR_SOURCE: replace destination layer (bounded) (Since 1.0)

 * @CAIRO_OPERATOR_OVER: draw source layer on top of destination layer

 * (bounded) (Since 1.0)

 * @CAIRO_OPERATOR_IN: draw source where there was destination content

 * (unbounded) (Since 1.0)

 * @CAIRO_OPERATOR_OUT: draw source where there was no destination

 * content (unbounded) (Since 1.0)

 * @CAIRO_OPERATOR_ATOP: draw source on top of destination content and

 * only there (Since 1.0)

 * @CAIRO_OPERATOR_DEST: ignore the source (Since 1.0)

 * @CAIRO_OPERATOR_DEST_OVER: draw destination on top of source (Since 1.0)

 * @CAIRO_OPERATOR_DEST_IN: leave destination only where there was

 * source content (unbounded) (Since 1.0)

 * @CAIRO_OPERATOR_DEST_OUT: leave destination only where there was no

 * source content (Since 1.0)

 * @CAIRO_OPERATOR_DEST_ATOP: leave destination on top of source content

 * and only there (unbounded) (Since 1.0)

 * @CAIRO_OPERATOR_XOR: source and destination are shown where there is only

 * one of them (Since 1.0)

 * @CAIRO_OPERATOR_ADD: source and destination layers are accumulated (Since 1.0)

 * @CAIRO_OPERATOR_SATURATE: like over, but assuming source and dest are

 * disjoint geometries (Since 1.0)

 * @CAIRO_OPERATOR_MULTIPLY: source and destination layers are multiplied.

 * This causes the result to be at least as dark as the darker inputs. (Since 1.10)

 * @CAIRO_OPERATOR_SCREEN: source and destination are complemented and

 * multiplied. This causes the result to be at least as light as the lighter

 * inputs. (Since 1.10)

 * @CAIRO_OPERATOR_OVERLAY: multiplies or screens, depending on the

 * lightness of the destination color. (Since 1.10)

 * @CAIRO_OPERATOR_DARKEN: replaces the destination with the source if it

 * is darker, otherwise keeps the source. (Since 1.10)

 * @CAIRO_OPERATOR_LIGHTEN: replaces the destination with the source if it

 * is lighter, otherwise keeps the source. (Since 1.10)

 * @CAIRO_OPERATOR_COLOR_DODGE: brightens the destination color to reflect

 * the source color. (Since 1.10)

 * @CAIRO_OPERATOR_COLOR_BURN: darkens the destination color to reflect

 * the source color. (Since 1.10)

 * @CAIRO_OPERATOR_HARD_LIGHT: Multiplies or screens, dependent on source

 * color. (Since 1.10)

 * @CAIRO_OPERATOR_SOFT_LIGHT: Darkens or lightens, dependent on source

 * color. (Since 1.10)

 * @CAIRO_OPERATOR_DIFFERENCE: Takes the difference of the source and

 * destination color. (Since 1.10)

 * @CAIRO_OPERATOR_EXCLUSION: Produces an effect similar to difference, but

 * with lower contrast. (Since 1.10)

 * @CAIRO_OPERATOR_HSL_HUE: Creates a color with the hue of the source

 * and the saturation and luminosity of the target. (Since 1.10)

 * @CAIRO_OPERATOR_HSL_SATURATION: Creates a color with the saturation

 * of the source and the hue and luminosity of the target. Painting with

 * this mode onto a gray area produces no change. (Since 1.10)

 * @CAIRO_OPERATOR_HSL_COLOR: Creates a color with the hue and saturation

 * of the source and the luminosity of the target. This preserves the gray

 * levels of the target and is useful for coloring monochrome images or

 * tinting color images. (Since 1.10)

 * @CAIRO_OPERATOR_HSL_LUMINOSITY: Creates a color with the luminosity of

 * the source and the hue and saturation of the target. This produces an

 * inverse effect to @CAIRO_OPERATOR_HSL_COLOR. (Since 1.10)

 *

 * #cairo_operator_t is used to set the compositing operator for all cairo

 * drawing operations.

 *

 * The default operator is %CAIRO_OPERATOR_OVER.

 *

 * The operators marked as unbounded modify their

 * destination even outside of the mask layer (that is, their effect is not

 * bound by the mask layer).  However, their effect can still be limited by

 * way of clipping.

 *

 * To keep things simple, the operator descriptions here

 * document the behavior for when both source and destination are either fully

 * transparent or fully opaque.  The actual implementation works for

 * translucent layers too.

 * For a more detailed explanation of the effects of each operator, including

 * the mathematical definitions, see

 * http://cairographics.org/operators/.

 *

 * Since: 1.0

 **/

typedef enum _cairo_operator {

    CAIRO_OPERATOR_CLEAR,

    CAIRO_OPERATOR_SOURCE,

    CAIRO_OPERATOR_OVER,

    CAIRO_OPERATOR_IN,

    CAIRO_OPERATOR_OUT,

    CAIRO_OPERATOR_ATOP,

    CAIRO_OPERATOR_DEST,

    CAIRO_OPERATOR_DEST_OVER,

    CAIRO_OPERATOR_DEST_IN,

    CAIRO_OPERATOR_DEST_OUT,

    CAIRO_OPERATOR_DEST_ATOP,

    CAIRO_OPERATOR_XOR,

    CAIRO_OPERATOR_ADD,

    CAIRO_OPERATOR_SATURATE,

    CAIRO_OPERATOR_MULTIPLY,

    CAIRO_OPERATOR_SCREEN,

    CAIRO_OPERATOR_OVERLAY,

    CAIRO_OPERATOR_DARKEN,

    CAIRO_OPERATOR_LIGHTEN,

    CAIRO_OPERATOR_COLOR_DODGE,

    CAIRO_OPERATOR_COLOR_BURN,

    CAIRO_OPERATOR_HARD_LIGHT,

    CAIRO_OPERATOR_SOFT_LIGHT,

    CAIRO_OPERATOR_DIFFERENCE,

    CAIRO_OPERATOR_EXCLUSION,

    CAIRO_OPERATOR_HSL_HUE,

    CAIRO_OPERATOR_HSL_SATURATION,

    CAIRO_OPERATOR_HSL_COLOR,

    CAIRO_OPERATOR_HSL_LUMINOSITY

} cairo_operator_t;

cairo_public void

cairo_set_operator (cairo_t *cr, cairo_operator_t op);

cairo_public void

cairo_set_source (cairo_t *cr, cairo_pattern_t *source);

cairo_public void

cairo_set_source_rgb (cairo_t *cr, double red, double green, double blue);

cairo_public void

cairo_set_source_rgba (cairo_t *cr,

		       double red, double green, double blue,

		       double alpha);

cairo_public void

cairo_set_source_surface (cairo_t	  *cr,

			  cairo_surface_t *surface,

			  double	   x,

			  double	   y);

cairo_public void

cairo_set_tolerance (cairo_t *cr, double tolerance);

/**

 * cairo_antialias_t:

 * @CAIRO_ANTIALIAS_DEFAULT: Use the default antialiasing for

 *   the subsystem and target device, since 1.0

 * @CAIRO_ANTIALIAS_NONE: Use a bilevel alpha mask, since 1.0

 * @CAIRO_ANTIALIAS_GRAY: Perform single-color antialiasing (using

 *  shades of gray for black text on a white background, for example), since 1.0

 * @CAIRO_ANTIALIAS_SUBPIXEL: Perform antialiasing by taking

 *  advantage of the order of subpixel elements on devices

 *  such as LCD panels, since 1.0

 * @CAIRO_ANTIALIAS_FAST: Hint that the backend should perform some

 * antialiasing but prefer speed over quality, since 1.12

 * @CAIRO_ANTIALIAS_GOOD: The backend should balance quality against

 * performance, since 1.12

 * @CAIRO_ANTIALIAS_BEST: Hint that the backend should render at the highest

 * quality, sacrificing speed if necessary, since 1.12

 *

 * Specifies the type of antialiasing to do when rendering text or shapes.

 *

 * As it is not necessarily clear from the above what advantages a particular

 * antialias method provides, since 1.12, there is also a set of hints:

 * @CAIRO_ANTIALIAS_FAST: Allow the backend to degrade raster quality for speed

 * @CAIRO_ANTIALIAS_GOOD: A balance between speed and quality

 * @CAIRO_ANTIALIAS_BEST: A high-fidelity, but potentially slow, raster mode

 *

 * These make no guarantee on how the backend will perform its rasterisation

 * (if it even rasterises!), nor that they have any differing effect other

 * than to enable some form of antialiasing. In the case of glyph rendering,

 * @CAIRO_ANTIALIAS_FAST and @CAIRO_ANTIALIAS_GOOD will be mapped to

 * @CAIRO_ANTIALIAS_GRAY, with @CAIRO_ANTALIAS_BEST being equivalent to

 * @CAIRO_ANTIALIAS_SUBPIXEL.

 *

 * The interpretation of @CAIRO_ANTIALIAS_DEFAULT is left entirely up to

 * the backend, typically this will be similar to @CAIRO_ANTIALIAS_GOOD.

 *

 * Since: 1.0

 **/

typedef enum _cairo_antialias {

    CAIRO_ANTIALIAS_DEFAULT,

    /* method */

    CAIRO_ANTIALIAS_NONE,

    CAIRO_ANTIALIAS_GRAY,

    CAIRO_ANTIALIAS_SUBPIXEL,

    /* hints */

    CAIRO_ANTIALIAS_FAST,

    CAIRO_ANTIALIAS_GOOD,

    CAIRO_ANTIALIAS_BEST

} cairo_antialias_t;

cairo_public void

cairo_set_antialias (cairo_t *cr, cairo_antialias_t antialias);

/**

 * cairo_fill_rule_t:

 * @CAIRO_FILL_RULE_WINDING: If the path crosses the ray from

 * left-to-right, counts +1. If the path crosses the ray

 * from right to left, counts -1. (Left and right are determined

 * from the perspective of looking along the ray from the starting

 * point.) If the total count is non-zero, the point will be filled. (Since 1.0)

 * @CAIRO_FILL_RULE_EVEN_ODD: Counts the total number of

 * intersections, without regard to the orientation of the contour. If

 * the total number of intersections is odd, the point will be

 * filled. (Since 1.0)

 *

 * #cairo_fill_rule_t is used to select how paths are filled. For both

 * fill rules, whether or not a point is included in the fill is

 * determined by taking a ray from that point to infinity and looking

 * at intersections with the path. The ray can be in any direction,

 * as long as it doesn't pass through the end point of a segment

 * or have a tricky intersection such as intersecting tangent to the path.

 * (Note that filling is not actually implemented in this way. This

 * is just a description of the rule that is applied.)

 *

 * The default fill rule is %CAIRO_FILL_RULE_WINDING.

 *

 * New entries may be added in future versions.

 *

 * Since: 1.0

 **/

typedef enum _cairo_fill_rule {

    CAIRO_FILL_RULE_WINDING,

    CAIRO_FILL_RULE_EVEN_ODD

} cairo_fill_rule_t;

cairo_public void

cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule);

cairo_public void

cairo_set_line_width (cairo_t *cr, double width);

/**

 * cairo_line_cap_t:

 * @CAIRO_LINE_CAP_BUTT: start(stop) the line exactly at the start(end) point (Since 1.0)

 * @CAIRO_LINE_CAP_ROUND: use a round ending, the center of the circle is the end point (Since 1.0)

 * @CAIRO_LINE_CAP_SQUARE: use squared ending, the center of the square is the end point (Since 1.0)

 *

 * Specifies how to render the endpoints of the path when stroking.

 *

 * The default line cap style is %CAIRO_LINE_CAP_BUTT.

 *

 * Since: 1.0

 **/

typedef enum _cairo_line_cap {

    CAIRO_LINE_CAP_BUTT,

    CAIRO_LINE_CAP_ROUND,

    CAIRO_LINE_CAP_SQUARE

} cairo_line_cap_t;

cairo_public void

cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap);

/**

 * cairo_line_join_t:

 * @CAIRO_LINE_JOIN_MITER: use a sharp (angled) corner, see

 * cairo_set_miter_limit() (Since 1.0)

 * @CAIRO_LINE_JOIN_ROUND: use a rounded join, the center of the circle is the

 * joint point (Since 1.0)

 * @CAIRO_LINE_JOIN_BEVEL: use a cut-off join, the join is cut off at half

 * the line width from the joint point (Since 1.0)

 *

 * Specifies how to render the junction of two lines when stroking.

 *

 * The default line join style is %CAIRO_LINE_JOIN_MITER.

 *

 * Since: 1.0

 **/

typedef enum _cairo_line_join {

    CAIRO_LINE_JOIN_MITER,

    CAIRO_LINE_JOIN_ROUND,

    CAIRO_LINE_JOIN_BEVEL

} cairo_line_join_t;

cairo_public void

cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join);

cairo_public void

cairo_set_dash (cairo_t      *cr,

		const double *dashes,

		int	      num_dashes,

		double	      offset);

cairo_public void

cairo_set_miter_limit (cairo_t *cr, double limit);

cairo_public void

cairo_translate (cairo_t *cr, double tx, double ty);

cairo_public void

cairo_scale (cairo_t *cr, double sx, double sy);

cairo_public void

cairo_rotate (cairo_t *cr, double angle);

cairo_public void

cairo_transform (cairo_t	      *cr,

		 const cairo_matrix_t *matrix);

cairo_public void

cairo_set_matrix (cairo_t	       *cr,

		  const cairo_matrix_t *matrix);

cairo_public void

cairo_identity_matrix (cairo_t *cr);

cairo_public void

cairo_user_to_device (cairo_t *cr, double *x, double *y);

cairo_public void

cairo_user_to_device_distance (cairo_t *cr, double *dx, double *dy);

cairo_public void

cairo_device_to_user (cairo_t *cr, double *x, double *y);

cairo_public void

cairo_device_to_user_distance (cairo_t *cr, double *dx, double *dy);

/* Path creation functions */

cairo_public void

cairo_new_path (cairo_t *cr);

cairo_public void

cairo_move_to (cairo_t *cr, double x, double y);

cairo_public void

cairo_new_sub_path (cairo_t *cr);

cairo_public void

cairo_line_to (cairo_t *cr, double x, double y);

cairo_public void

cairo_curve_to (cairo_t *cr,

		double x1, double y1,

		double x2, double y2,

		double x3, double y3);

cairo_public void

cairo_arc (cairo_t *cr,

	   double xc, double yc,

	   double radius,

	   double angle1, double angle2);

cairo_public void

cairo_arc_negative (cairo_t *cr,

		    double xc, double yc,

		    double radius,

		    double angle1, double angle2);

/* XXX: NYI

cairo_public void

cairo_arc_to (cairo_t *cr,

	      double x1, double y1,

	      double x2, double y2,

	      double radius);

*/

cairo_public void

cairo_rel_move_to (cairo_t *cr, double dx, double dy);

cairo_public void

cairo_rel_line_to (cairo_t *cr, double dx, double dy);

cairo_public void

cairo_rel_curve_to (cairo_t *cr,

		    double dx1, double dy1,

		    double dx2, double dy2,

		    double dx3, double dy3);

cairo_public void

cairo_rectangle (cairo_t *cr,

		 double x, double y,

		 double width, double height);

/* XXX: NYI

cairo_public void

cairo_stroke_to_path (cairo_t *cr);

*/

cairo_public void

cairo_close_path (cairo_t *cr);

cairo_public void

cairo_path_extents (cairo_t *cr,

		    double *x1, double *y1,

		    double *x2, double *y2);

/* Painting functions */

cairo_public void

cairo_paint (cairo_t *cr);

cairo_public void

cairo_paint_with_alpha (cairo_t *cr,

			double   alpha);

cairo_public void

cairo_mask (cairo_t         *cr,

	    cairo_pattern_t *pattern);

cairo_public void

cairo_mask_surface (cairo_t         *cr,

		    cairo_surface_t *surface,

		    double           surface_x,

		    double           surface_y);

cairo_public void

cairo_stroke (cairo_t *cr);

cairo_public void

cairo_stroke_preserve (cairo_t *cr);

cairo_public void

cairo_fill (cairo_t *cr);

cairo_public void

cairo_fill_preserve (cairo_t *cr);

cairo_public void

cairo_copy_page (cairo_t *cr);

cairo_public void

cairo_show_page (cairo_t *cr);

/* Insideness testing */

cairo_public cairo_bool_t

cairo_in_stroke (cairo_t *cr, double x, double y);

cairo_public cairo_bool_t

cairo_in_fill (cairo_t *cr, double x, double y);

cairo_public cairo_bool_t

cairo_in_clip (cairo_t *cr, double x, double y);

/* Rectangular extents */

cairo_public void

cairo_stroke_extents (cairo_t *cr,

		      double *x1, double *y1,

		      double *x2, double *y2);

cairo_public void

cairo_fill_extents (cairo_t *cr,

		    double *x1, double *y1,

		    double *x2, double *y2);

/* Clipping */

cairo_public void

cairo_reset_clip (cairo_t *cr);

cairo_public void

cairo_clip (cairo_t *cr);

cairo_public void

cairo_clip_preserve (cairo_t *cr);

cairo_public void

cairo_clip_extents (cairo_t *cr,

		    double *x1, double *y1,

		    double *x2, double *y2);

/**

 * cairo_rectangle_t:

 * @x: X coordinate of the left side of the rectangle

 * @y: Y coordinate of the the top side of the rectangle

 * @width: width of the rectangle

 * @height: height of the rectangle

 *

 * A data structure for holding a rectangle.

 *

 * Since: 1.4

 **/

typedef struct _cairo_rectangle {

    double x, y, width, height;

} cairo_rectangle_t;

/**

 * cairo_rectangle_list_t:

 * @status: Error status of the rectangle list

 * @rectangles: Array containing the rectangles

 * @num_rectangles: Number of rectangles in this list

 *

 * A data structure for holding a dynamically allocated

 * array of rectangles.

 *

 * Since: 1.4

 **/

typedef struct _cairo_rectangle_list {

    cairo_status_t     status;

    cairo_rectangle_t *rectangles;

    int                num_rectangles;

} cairo_rectangle_list_t;

cairo_public cairo_rectangle_list_t *

cairo_copy_clip_rectangle_list (cairo_t *cr);

cairo_public void

cairo_rectangle_list_destroy (cairo_rectangle_list_t *rectangle_list);

/* Font/Text functions */

/**

 * cairo_scaled_font_t:

 *

 * A #cairo_scaled_font_t is a font scaled to a particular size and device

 * resolution. A #cairo_scaled_font_t is most useful for low-level font

 * usage where a library or application wants to cache a reference

 * to a scaled font to speed up the computation of metrics.

 *

 * There are various types of scaled fonts, depending on the

 * font backend they use. The type of a

 * scaled font can be queried using cairo_scaled_font_get_type().

 *

 * Memory management of #cairo_scaled_font_t is done with

 * cairo_scaled_font_reference() and cairo_scaled_font_destroy().

 *

 * Since: 1.0

 **/

typedef struct _cairo_scaled_font cairo_scaled_font_t;

/**

 * cairo_font_face_t:

 *

 * A #cairo_font_face_t specifies all aspects of a font other

 * than the size or font matrix (a font matrix is used to distort

 * a font by sheering it or scaling it unequally in the two

 * directions) . A font face can be set on a #cairo_t by using

 * cairo_set_font_face(); the size and font matrix are set with

 * cairo_set_font_size() and cairo_set_font_matrix().

 *

 * There are various types of font faces, depending on the

 * font backend they use. The type of a

 * font face can be queried using cairo_font_face_get_type().

 *

 * Memory management of #cairo_font_face_t is done with

 * cairo_font_face_reference() and cairo_font_face_destroy().

 *

 * Since: 1.0

 **/

typedef struct _cairo_font_face cairo_font_face_t;

/**

 * cairo_glyph_t:

 * @index: glyph index in the font. The exact interpretation of the

 *      glyph index depends on the font technology being used.

 * @x: the offset in the X direction between the origin used for

 *     drawing or measuring the string and the origin of this glyph.

 * @y: the offset in the Y direction between the origin used for

 *     drawing or measuring the string and the origin of this glyph.

 *

 * The #cairo_glyph_t structure holds information about a single glyph

 * when drawing or measuring text. A font is (in simple terms) a

 * collection of shapes used to draw text. A glyph is one of these

 * shapes. There can be multiple glyphs for a single character

 * (alternates to be used in different contexts, for example), or a

 * glyph can be a ligature of multiple

 * characters. Cairo doesn't expose any way of converting input text

 * into glyphs, so in order to use the Cairo interfaces that take

 * arrays of glyphs, you must directly access the appropriate

 * underlying font system.

 *

 * Note that the offsets given by @x and @y are not cumulative. When

 * drawing or measuring text, each glyph is individually positioned

 * with respect to the overall origin

 *

 * Since: 1.0

 **/

typedef struct {

    unsigned long        index;

    double               x;

    double               y;

} cairo_glyph_t;

cairo_public cairo_glyph_t *

cairo_glyph_allocate (int num_glyphs);

cairo_public void

cairo_glyph_free (cairo_glyph_t *glyphs);

/**

 * cairo_text_cluster_t:

 * @num_bytes: the number of bytes of UTF-8 text covered by cluster

 * @num_glyphs: the number of glyphs covered by cluster

 *

 * The #cairo_text_cluster_t structure holds information about a single

 * text cluster.  A text cluster is a minimal

 * mapping of some glyphs corresponding to some UTF-8 text.

 *

 * For a cluster to be valid, both @num_bytes and @num_glyphs should

 * be non-negative, and at least one should be non-zero.

 * Note that clusters with zero glyphs are not as well supported as