/* 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 <cworth@cworth.org>
*/
#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
#if (
defined(_WIN32) ||
defined(__CYGWIN__)) && !
defined(CAIRO_WIN32_STATIC_BUILD)
# define _cairo_export __declspec(dllexport)
# define _cairo_import __declspec(dllimport)
#elif defined(__GNUC__) && (__GNUC__ >= 4)
# define _cairo_export __attribute__((__visibility__(
"default")))
# define _cairo_import
#else
# define _cairo_export
# define _cairo_import
#endif
#ifdef CAIRO_COMPILATION
# define _cairo_api _cairo_export
#else
# define _cairo_api _cairo_import
#endif
#ifndef cairo_public
#define cairo_public _cairo_api
extern
#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.
*
* <informalexample><programlisting>
* if (cairo_in_stroke (cr, x, y)) {
* /<!-- -->* do something *<!-- -->/
* }
* </programlisting></informalexample>
*
* 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.
*
* 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:
* <programlisting>
* x_new = xx * x + xy * y + x0;
* y_new = yx * x + yy * y + y0;
* </programlisting>
*
* 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
* <function>cairo_pattern_create_<emphasis>type</emphasis>()</function>
* functions, some of the pattern types can be implicitly created using various
* <function>cairo_set_source_<emphasis>type</emphasis>()</function> 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_JBIG2_GLOBAL_MISSING: %CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID has been used on at least one image
* but no image provided %CAIRO_MIME_TYPE_JBIG2_GLOBAL (Since 1.14)
* @CAIRO_STATUS_PNG_ERROR: error occurred in libpng while reading from or writing to a PNG file (Since 1.16)
* @CAIRO_STATUS_FREETYPE_ERROR: error occurred in libfreetype (Since 1.16)
* @CAIRO_STATUS_WIN32_GDI_ERROR: error occurred in the Windows Graphics Device Interface (Since 1.16)
* @CAIRO_STATUS_TAG_ERROR: invalid tag name, attributes, or nesting (Since 1.16)
* @CAIRO_STATUS_DWRITE_ERROR: error occurred in the Windows Direct Write API (Since 1.18)
* @CAIRO_STATUS_SVG_FONT_ERROR: error occurred in OpenType-SVG font rendering (Since 1.18)
* @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_JBIG2_GLOBAL_MISSING,
CAIRO_STATUS_PNG_ERROR,
CAIRO_STATUS_FREETYPE_ERROR,
CAIRO_STATUS_WIN32_GDI_ERROR,
CAIRO_STATUS_TAG_ERROR,
CAIRO_STATUS_DWRITE_ERROR,
CAIRO_STATUS_SVG_FONT_ERROR,
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
* endianness 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_RGB96F: 3 floats, R, G, B. (Since 1.17.2)
* @CAIRO_FORMAT_RGBA128F: 4 floats, R, G, B, A. (Since 1.17.2)
*
* #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_RGB96F = 6,
CAIRO_FORMAT_RGBA128F = 7
} cairo_format_t;
/**
* cairo_dither_t:
* @CAIRO_DITHER_NONE: No dithering.
* @CAIRO_DITHER_DEFAULT: Default choice at cairo compile time. Currently NONE.
* @CAIRO_DITHER_FAST: Fastest dithering algorithm supported by the backend
* @CAIRO_DITHER_GOOD: An algorithm with smoother dithering than FAST
* @CAIRO_DITHER_BEST: Best algorithm available in the backend
*
* Dither is an intentionally applied form of noise used to randomize
* quantization error, preventing large-scale patterns such as color banding
* in images (e.g. for gradients). Ordered dithering applies a precomputed
* threshold matrix to spread the errors smoothly.
*
* #cairo_dither_t is modeled on pixman dithering algorithm choice.
* As of Pixman 0.40, FAST corresponds to a 8x8 ordered bayer noise and GOOD
* and BEST use an ordered 64x64 precomputed blue noise.
*
* Since: 1.18
**/
typedef enum _cairo_dither {
CAIRO_DITHER_NONE,
CAIRO_DITHER_DEFAULT,
CAIRO_DITHER_FAST,
CAIRO_DITHER_GOOD,
CAIRO_DITHER_BEST
} cairo_dither_t;
cairo_public
void
cairo_pattern_set_dither (cairo_pattern_t *pattern, cairo_dither_t dither);
cairo_public cairo_dither_t
cairo_pattern_get_dither (cairo_pattern_t *pattern);
/**
* 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 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 <firstterm>unbounded</firstterm> 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
* <ulink url="https://cairographics.org/operators/">https://cairographics.org/operators/</ulink>.
*
* 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_public
void
cairo_set_hairline (cairo_t *cr, cairo_bool_t set_hairline);
/**
* 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 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);
/* Logical structure tagging functions */
#define CAIRO_TAG_DEST
"cairo.dest"
#define CAIRO_TAG_LINK
"Link"
#define CAIRO_TAG_CONTENT
"cairo.content"
#define CAIRO_TAG_CONTENT_REF
"cairo.content_ref"
cairo_public
void
cairo_tag_begin (cairo_t *cr,
const char *tag_name,
const char *attributes);
cairo_public
void
cairo_tag_end (cairo_t *cr,
const char *tag_name);
/* 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
* <firstterm>font backend</firstterm> 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 shearing 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
* <firstterm>font backend</firstterm> 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 <firstterm>ligature</firstterm> 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
* <firstterm>text cluster</firstterm>. 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
* normal clusters. For example, PDF rendering applications typically
* ignore those clusters when PDF text is being selected.
*
* See cairo_show_text_glyphs() for how clusters are used in advanced
* text operations.
*
* Since: 1.8
**/
typedef struct {
int num_bytes;
int num_glyphs;
} cairo_text_cluster_t;
cairo_public cairo_text_cluster_t *
cairo_text_cluster_allocate (
int num_clusters);
cairo_public
void
cairo_text_cluster_free (cairo_text_cluster_t *clusters);
/**
* cairo_text_cluster_flags_t:
* @CAIRO_TEXT_CLUSTER_FLAG_BACKWARD: The clusters in the cluster array
* map to glyphs in the glyph array from end to start. (Since 1.8)
*
* Specifies properties of a text cluster mapping.
*
* Since: 1.8
**/
typedef enum _cairo_text_cluster_flags {
CAIRO_TEXT_CLUSTER_FLAG_BACKWARD = 0x00000001
} cairo_text_cluster_flags_t;
/**
* cairo_text_extents_t:
* @x_bearing: the horizontal distance from the origin to the
* leftmost part of the glyphs as drawn. Positive if the
* glyphs lie entirely to the right of the origin.
* @y_bearing: the vertical distance from the origin to the
* topmost part of the glyphs as drawn. Positive only if the
* glyphs lie completely below the origin; will usually be
* negative.
* @width: width of the glyphs as drawn
* @height: height of the glyphs as drawn
* @x_advance:distance to advance in the X direction
* after drawing these glyphs
* @y_advance: distance to advance in the Y direction
* after drawing these glyphs. Will typically be zero except
* for vertical text layout as found in East-Asian languages.
*
* The #cairo_text_extents_t structure stores the extents of a single
* glyph or a string of glyphs in user-space coordinates. Because text
* extents are in user-space coordinates, they are mostly, but not
* entirely, independent of the current transformation matrix. If you call
* <literal>cairo_scale(cr, 2.0, 2.0)</literal>, text will
* be drawn twice as big, but the reported text extents will not be
* doubled. They will change slightly due to hinting (so you can't
* assume that metrics are independent of the transformation matrix),
* but otherwise will remain unchanged.
*
* Since: 1.0
**/
typedef struct {
double x_bearing;
double y_bearing;
double width;
double height;
double x_advance;
double y_advance;
} cairo_text_extents_t;
/**
* cairo_font_extents_t:
* @ascent: the distance that the font extends above the baseline.
* Note that this is not always exactly equal to the maximum
* of the extents of all the glyphs in the font, but rather
* is picked to express the font designer's intent as to
* how the font should align with elements above it.
* @descent: the distance that the font extends below the baseline.
* This value is positive for typical fonts that include
* portions below the baseline. Note that this is not always
* exactly equal to the maximum of the extents of all the
* glyphs in the font, but rather is picked to express the
* font designer's intent as to how the font should
* align with elements below it.
* @height: the recommended vertical distance between baselines when
* setting consecutive lines of text with the font. This
* is greater than @ascent+@descent by a
* quantity known as the <firstterm>line spacing</firstterm>
* or <firstterm>external leading</firstterm>. When space
* is at a premium, most fonts can be set with only
* a distance of @ascent+@descent between lines.
* @max_x_advance: the maximum distance in the X direction that
* the origin is advanced for any glyph in the font.
* @max_y_advance: the maximum distance in the Y direction that
* the origin is advanced for any glyph in the font.
* This will be zero for normal fonts used for horizontal
* writing. (The scripts of East Asia are sometimes written
* vertically.)
*
* The #cairo_font_extents_t structure stores metric information for
* a font. Values are given in the current user-space coordinate
* system.
*
* Because font metrics are in user-space coordinates, they are
* mostly, but not entirely, independent of the current transformation
* matrix. If you call <literal>cairo_scale(cr, 2.0, 2.0)</literal>,
* text will be drawn twice as big, but the reported text extents will
* not be doubled. They will change slightly due to hinting (so you
* can't assume that metrics are independent of the transformation
* matrix), but otherwise will remain unchanged.
*
* Since: 1.0
**/
typedef struct {
double ascent;
double descent;
double height;
double max_x_advance;
double max_y_advance;
} cairo_font_extents_t;
/**
* cairo_font_slant_t:
* @CAIRO_FONT_SLANT_NORMAL: Upright font style, since 1.0
* @CAIRO_FONT_SLANT_ITALIC: Italic font style, since 1.0
* @CAIRO_FONT_SLANT_OBLIQUE: Oblique font style, since 1.0
*
* Specifies variants of a font face based on their slant.
*
* Since: 1.0
**/
typedef enum _cairo_font_slant {
CAIRO_FONT_SLANT_NORMAL,
CAIRO_FONT_SLANT_ITALIC,
CAIRO_FONT_SLANT_OBLIQUE
} cairo_font_slant_t;
/**
* cairo_font_weight_t:
* @CAIRO_FONT_WEIGHT_NORMAL: Normal font weight, since 1.0
* @CAIRO_FONT_WEIGHT_BOLD: Bold font weight, since 1.0
*
* Specifies variants of a font face based on their weight.
*
* Since: 1.0
**/
typedef enum _cairo_font_weight {
CAIRO_FONT_WEIGHT_NORMAL,
CAIRO_FONT_WEIGHT_BOLD
} cairo_font_weight_t;
/**
* cairo_subpixel_order_t:
* @CAIRO_SUBPIXEL_ORDER_DEFAULT: Use the default subpixel order for
* for the target device, since 1.0
* @CAIRO_SUBPIXEL_ORDER_RGB: Subpixel elements are arranged horizontally
* with red at the left, since 1.0
* @CAIRO_SUBPIXEL_ORDER_BGR: Subpixel elements are arranged horizontally
* with blue at the left, since 1.0
* @CAIRO_SUBPIXEL_ORDER_VRGB: Subpixel elements are arranged vertically
* with red at the top, since 1.0
* @CAIRO_SUBPIXEL_ORDER_VBGR: Subpixel elements are arranged vertically
* with blue at the top, since 1.0
*
* The subpixel order specifies the order of color elements within
* each pixel on the display device when rendering with an
* antialiasing mode of %CAIRO_ANTIALIAS_SUBPIXEL.
*
* Since: 1.0
**/
typedef enum _cairo_subpixel_order {
CAIRO_SUBPIXEL_ORDER_DEFAULT,
CAIRO_SUBPIXEL_ORDER_RGB,
CAIRO_SUBPIXEL_ORDER_BGR,
CAIRO_SUBPIXEL_ORDER_VRGB,
CAIRO_SUBPIXEL_ORDER_VBGR
} cairo_subpixel_order_t;
/**
* cairo_hint_style_t:
* @CAIRO_HINT_STYLE_DEFAULT: Use the default hint style for
* font backend and target device, since 1.0
* @CAIRO_HINT_STYLE_NONE: Do not hint outlines, since 1.0
* @CAIRO_HINT_STYLE_SLIGHT: Hint outlines slightly to improve
* contrast while retaining good fidelity to the original
* shapes, since 1.0
* @CAIRO_HINT_STYLE_MEDIUM: Hint outlines with medium strength
* giving a compromise between fidelity to the original shapes
* and contrast, since 1.0
* @CAIRO_HINT_STYLE_FULL: Hint outlines to maximize contrast, since 1.0
*
* Specifies the type of hinting to do on font outlines. Hinting
* is the process of fitting outlines to the pixel grid in order
* to improve the appearance of the result. Since hinting outlines
* involves distorting them, it also reduces the faithfulness
* to the original outline shapes. Not all of the outline hinting
* styles are supported by all font backends.
*
* New entries may be added in future versions.
*
* Since: 1.0
**/
typedef enum _cairo_hint_style {
CAIRO_HINT_STYLE_DEFAULT,
CAIRO_HINT_STYLE_NONE,
CAIRO_HINT_STYLE_SLIGHT,
CAIRO_HINT_STYLE_MEDIUM,
CAIRO_HINT_STYLE_FULL
} cairo_hint_style_t;
/**
* cairo_hint_metrics_t:
* @CAIRO_HINT_METRICS_DEFAULT: Hint metrics in the default
* manner for the font backend and target device, since 1.0
* @CAIRO_HINT_METRICS_OFF: Do not hint font metrics, since 1.0
* @CAIRO_HINT_METRICS_ON: Hint font metrics, since 1.0
*
* Specifies whether to hint font metrics; hinting font metrics
* means quantizing them so that they are integer values in
* device space. Doing this improves the consistency of
* letter and line spacing, however it also means that text
* will be laid out differently at different zoom factors.
*
* Since: 1.0
**/
typedef enum _cairo_hint_metrics {
CAIRO_HINT_METRICS_DEFAULT,
CAIRO_HINT_METRICS_OFF,
CAIRO_HINT_METRICS_ON
} cairo_hint_metrics_t;
/**
* cairo_color_mode_t:
* @CAIRO_COLOR_MODE_DEFAULT: Use the default color mode for
* font backend and target device, since 1.18.
* @CAIRO_COLOR_MODE_NO_COLOR: Disable rendering color glyphs. Glyphs are
* always rendered as outline glyphs, since 1.18.
* @CAIRO_COLOR_MODE_COLOR: Enable rendering color glyphs. If the font
* contains a color presentation for a glyph, and when supported by
* the font backend, the glyph will be rendered in color, since 1.18.
*
* Specifies if color fonts are to be rendered using the color
* glyphs or outline glyphs. Glyphs that do not have a color
* presentation, and non-color fonts are not affected by this font
* option.
*
* Since: 1.18
**/
typedef enum _cairo_color_mode {
CAIRO_COLOR_MODE_DEFAULT,
CAIRO_COLOR_MODE_NO_COLOR,
CAIRO_COLOR_MODE_COLOR
} cairo_color_mode_t;
/**
* _cairo_lcd_filter:
* @CAIRO_LCD_FILTER_DEFAULT: Use the default LCD filter for
* font backend and target device
* @CAIRO_LCD_FILTER_NONE: Do not perform LCD filtering
* @CAIRO_LCD_FILTER_INTRA_PIXEL: Intra-pixel filter
* @CAIRO_LCD_FILTER_FIR3: FIR filter with a 3x3 kernel
* @CAIRO_LCD_FILTER_FIR5: FIR filter with a 5x5 kernel
*
* The LCD filter specifies the low-pass filter applied to LCD-optimized
* bitmaps generated with an antialiasing mode of %CAIRO_ANTIALIAS_SUBPIXEL.
*
* Note: This API was temporarily made available in the public
* interface during the 1.7.x development series, but was made private
* before 1.8.
**/
typedef enum _cairo_lcd_filter {
CAIRO_LCD_FILTER_DEFAULT,
CAIRO_LCD_FILTER_NONE,
CAIRO_LCD_FILTER_INTRA_PIXEL,
CAIRO_LCD_FILTER_FIR3,
CAIRO_LCD_FILTER_FIR5
} cairo_lcd_filter_t;
/**
* cairo_font_options_t:
*
* An opaque structure holding all options that are used when
* rendering fonts.
*
* Individual features of a #cairo_font_options_t can be set or
* accessed using functions named
* <function>cairo_font_options_set_<emphasis>feature_name</emphasis>()</function> and
* <function>cairo_font_options_get_<emphasis>feature_name</emphasis>()</function>, like
* cairo_font_options_set_antialias() and
* cairo_font_options_get_antialias().
*
* New features may be added to a #cairo_font_options_t in the
* future. For this reason, cairo_font_options_copy(),
* cairo_font_options_equal(), cairo_font_options_merge(), and
* cairo_font_options_hash() should be used to copy, check
* for equality, merge, or compute a hash value of
* #cairo_font_options_t objects.
*
* Since: 1.0
**/
typedef struct _cairo_font_options cairo_font_options_t;
cairo_public cairo_font_options_t *
cairo_font_options_create (
void);
cairo_public cairo_font_options_t *
cairo_font_options_copy (
const cairo_font_options_t *original);
cairo_public
void
cairo_font_options_destroy (cairo_font_options_t *options);
cairo_public cairo_status_t
cairo_font_options_status (cairo_font_options_t *options);
cairo_public
void
cairo_font_options_merge (cairo_font_options_t *options,
const cairo_font_options_t *other);
cairo_public cairo_bool_t
cairo_font_options_equal (
const cairo_font_options_t *options,
const cairo_font_options_t *other);
cairo_public
unsigned long
cairo_font_options_hash (
const cairo_font_options_t *options);
cairo_public
void
cairo_font_options_set_antialias (cairo_font_options_t *options,
cairo_antialias_t antialias);
cairo_public cairo_antialias_t
cairo_font_options_get_antialias (
const cairo_font_options_t *options);
cairo_public
void
cairo_font_options_set_subpixel_order (cairo_font_options_t *options,
cairo_subpixel_order_t subpixel_order);
cairo_public cairo_subpixel_order_t
cairo_font_options_get_subpixel_order (
const cairo_font_options_t *options);
cairo_public
void
cairo_font_options_set_hint_style (cairo_font_options_t *options,
cairo_hint_style_t hint_style);
cairo_public cairo_hint_style_t
cairo_font_options_get_hint_style (
const cairo_font_options_t *options);
cairo_public
void
cairo_font_options_set_hint_metrics (cairo_font_options_t *options,
cairo_hint_metrics_t hint_metrics);
cairo_public cairo_hint_metrics_t
cairo_font_options_get_hint_metrics (
const cairo_font_options_t *options);
cairo_public
const char *
cairo_font_options_get_variations (cairo_font_options_t *options);
cairo_public
void
cairo_font_options_set_variations (cairo_font_options_t *options,
const char *variations);
#define CAIRO_COLOR_PALETTE_DEFAULT 0
cairo_public
void
cairo_font_options_set_color_mode (cairo_font_options_t *options,
cairo_color_mode_t color_mode);
cairo_public cairo_color_mode_t
cairo_font_options_get_color_mode (
const cairo_font_options_t *options);
cairo_public
unsigned int
cairo_font_options_get_color_palette (
const cairo_font_options_t *options);
cairo_public
void
cairo_font_options_set_color_palette (cairo_font_options_t *options,
unsigned int palette_index);
cairo_public
void
cairo_font_options_set_custom_palette_color (cairo_font_options_t *options,
unsigned int index,
double red,
double green,
double blue,
double alpha);
cairo_public cairo_status_t
cairo_font_options_get_custom_palette_color (cairo_font_options_t *options,
unsigned int index,
double *red,
double *green,
double *blue,
double *alpha);
/* This interface is for dealing with text as text, not caring about the
font object inside the cairo_t. */
cairo_public
void
cairo_select_font_face (cairo_t *cr,
const char *family,
cairo_font_slant_t slant,
cairo_font_weight_t weight);
cairo_public
void
cairo_set_font_size (cairo_t *cr,
double size);
cairo_public
void
cairo_set_font_matrix (cairo_t *cr,
const cairo_matrix_t *matrix);
cairo_public
void
cairo_get_font_matrix (cairo_t *cr,
cairo_matrix_t *matrix);
cairo_public
void
cairo_set_font_options (cairo_t *cr,
const cairo_font_options_t *options);
cairo_public
void
cairo_get_font_options (cairo_t *cr,
cairo_font_options_t *options);
cairo_public
void
cairo_font_options_set_lcd_filter (cairo_font_options_t *options,
cairo_lcd_filter_t lcd_filter);
cairo_public cairo_lcd_filter_t
cairo_font_options_get_lcd_filter (
const cairo_font_options_t *options);
cairo_public
void
cairo_set_font_face (cairo_t *cr, cairo_font_face_t *font_face);
cairo_public cairo_font_face_t *
cairo_get_font_face (cairo_t *cr);
cairo_public
void
cairo_set_scaled_font (cairo_t *cr,
const cairo_scaled_font_t *scaled_font);
cairo_public cairo_scaled_font_t *
cairo_get_scaled_font (cairo_t *cr);
cairo_public
void
cairo_show_text (cairo_t *cr,
const char *utf8);
cairo_public
void
cairo_show_glyphs (cairo_t *cr,
const cairo_glyph_t *glyphs,
int num_glyphs);
cairo_public
void
cairo_show_text_glyphs (cairo_t *cr,
const char *utf8,
int utf8_len,
const cairo_glyph_t *glyphs,
int num_glyphs,
const cairo_text_cluster_t *clusters,
int num_clusters,
cairo_text_cluster_flags_t cluster_flags);
cairo_public
void
cairo_text_path (cairo_t *cr,
const char *utf8);
cairo_public
void
cairo_glyph_path (cairo_t *cr,
const cairo_glyph_t *glyphs,
int num_glyphs);
cairo_public
void
cairo_text_extents (cairo_t *cr,
const char *utf8,
cairo_text_extents_t *extents);
cairo_public
void
cairo_glyph_extents (cairo_t *cr,
const cairo_glyph_t *glyphs,
int num_glyphs,
cairo_text_extents_t *extents);
cairo_public
void
cairo_font_extents (cairo_t *cr,
cairo_font_extents_t *extents);
/* Generic identifier for a font style */
cairo_public cairo_font_face_t *
cairo_font_face_reference (cairo_font_face_t *font_face);
cairo_public
void
cairo_font_face_destroy (cairo_font_face_t *font_face);
cairo_public
unsigned int
cairo_font_face_get_reference_count (cairo_font_face_t *font_face);
cairo_public cairo_status_t
cairo_font_face_status (cairo_font_face_t *font_face);
/**
* cairo_font_type_t:
* @CAIRO_FONT_TYPE_TOY: The font was created using cairo's toy font api (Since: 1.2)
* @CAIRO_FONT_TYPE_FT: The font is of type FreeType (Since: 1.2)
* @CAIRO_FONT_TYPE_WIN32: The font is of type Win32 (Since: 1.2)
* @CAIRO_FONT_TYPE_QUARTZ: The font is of type Quartz (Since: 1.6, in 1.2 and
* 1.4 it was named CAIRO_FONT_TYPE_ATSUI)
* @CAIRO_FONT_TYPE_USER: The font was create using cairo's user font api (Since: 1.8)
* @CAIRO_FONT_TYPE_DWRITE: The font is of type Win32 DWrite (Since: 1.18)
*
* #cairo_font_type_t is used to describe the type of a given font
* face or scaled font. The font types are also known as "font
* backends" within cairo.
*
* The type of a font face is determined by the function used to
* create it, which will generally be of the form
* <function>cairo_<emphasis>type</emphasis>_font_face_create(<!-- -->)</function>.
* The font face type can be queried with cairo_font_face_get_type()
*
* The various #cairo_font_face_t functions can be used with a font face
* of any type.
*
* The type of a scaled font is determined by the type of the font
* face passed to cairo_scaled_font_create(). The scaled font type can
* be queried with cairo_scaled_font_get_type()
*
* The various #cairo_scaled_font_t functions can be used with scaled
* fonts of any type, but some font backends also provide
* type-specific functions that must only be called with a scaled font
* of the appropriate type. These functions have names that begin with
* <function>cairo_<emphasis>type</emphasis>_scaled_font(<!-- -->)</function>
* such as cairo_ft_scaled_font_lock_face().
*
* The behavior of calling a type-specific function with a scaled font
* of the wrong type is undefined.
*
* New entries may be added in future versions.
*
* Since: 1.2
**/
typedef enum _cairo_font_type {
CAIRO_FONT_TYPE_TOY,
CAIRO_FONT_TYPE_FT,
CAIRO_FONT_TYPE_WIN32,
CAIRO_FONT_TYPE_QUARTZ,
CAIRO_FONT_TYPE_USER,
CAIRO_FONT_TYPE_DWRITE
} cairo_font_type_t;
cairo_public cairo_font_type_t
cairo_font_face_get_type (cairo_font_face_t *font_face);
cairo_public
void *
cairo_font_face_get_user_data (cairo_font_face_t *font_face,
const cairo_user_data_key_t *key);
cairo_public cairo_status_t
cairo_font_face_set_user_data (cairo_font_face_t *font_face,
const cairo_user_data_key_t *key,
void *user_data,
cairo_destroy_func_t destroy);
/* Portable interface to general font features. */
cairo_public cairo_scaled_font_t *
cairo_scaled_font_create (cairo_font_face_t *font_face,
const cairo_matrix_t *font_matrix,
const cairo_matrix_t *ctm,
const cairo_font_options_t *options);
cairo_public cairo_scaled_font_t *
cairo_scaled_font_reference (cairo_scaled_font_t *scaled_font);
cairo_public
void
cairo_scaled_font_destroy (cairo_scaled_font_t *scaled_font);
cairo_public
unsigned int
cairo_scaled_font_get_reference_count (cairo_scaled_font_t *scaled_font);
cairo_public cairo_status_t
cairo_scaled_font_status (cairo_scaled_font_t *scaled_font);
cairo_public cairo_font_type_t
cairo_scaled_font_get_type (cairo_scaled_font_t *scaled_font);
cairo_public
void *
cairo_scaled_font_get_user_data (cairo_scaled_font_t *scaled_font,
const cairo_user_data_key_t *key);
cairo_public cairo_status_t
cairo_scaled_font_set_user_data (cairo_scaled_font_t *scaled_font,
const cairo_user_data_key_t *key,
void *user_data,
cairo_destroy_func_t destroy);
cairo_public
void
cairo_scaled_font_extents (cairo_scaled_font_t *scaled_font,
cairo_font_extents_t *extents);
cairo_public
void
cairo_scaled_font_text_extents (cairo_scaled_font_t *scaled_font,
const char *utf8,
cairo_text_extents_t *extents);
cairo_public
void
cairo_scaled_font_glyph_extents (cairo_scaled_font_t *scaled_font,
const cairo_glyph_t *glyphs,
int num_glyphs,
cairo_text_extents_t *extents);
cairo_public cairo_status_t
cairo_scaled_font_text_to_glyphs (cairo_scaled_font_t *scaled_font,
double x,
double y,
const char *utf8,
int utf8_len,
cairo_glyph_t **glyphs,
int *num_glyphs,
cairo_text_cluster_t **clusters,
int *num_clusters,
cairo_text_cluster_flags_t *cluster_flags);
cairo_public cairo_font_face_t *
cairo_scaled_font_get_font_face (cairo_scaled_font_t *scaled_font);
cairo_public
void
cairo_scaled_font_get_font_matrix (cairo_scaled_font_t *scaled_font,
cairo_matrix_t *font_matrix);
cairo_public
void
cairo_scaled_font_get_ctm (cairo_scaled_font_t *scaled_font,
cairo_matrix_t *ctm);
cairo_public
void
cairo_scaled_font_get_scale_matrix (cairo_scaled_font_t *scaled_font,
cairo_matrix_t *scale_matrix);
cairo_public
void
cairo_scaled_font_get_font_options (cairo_scaled_font_t *scaled_font,
cairo_font_options_t *options);
/* Toy fonts */
cairo_public cairo_font_face_t *
cairo_toy_font_face_create (
const char *family,
cairo_font_slant_t slant,
cairo_font_weight_t weight);
cairo_public
const char *
cairo_toy_font_face_get_family (cairo_font_face_t *font_face);
cairo_public cairo_font_slant_t
cairo_toy_font_face_get_slant (cairo_font_face_t *font_face);
cairo_public cairo_font_weight_t
cairo_toy_font_face_get_weight (cairo_font_face_t *font_face);
/* User fonts */
cairo_public cairo_font_face_t *
cairo_user_font_face_create (
void);
/* User-font method signatures */
/**
* cairo_user_scaled_font_init_func_t:
* @scaled_font: the scaled-font being created
* @cr: a cairo context, in font space
* @extents: font extents to fill in, in font space
*
* #cairo_user_scaled_font_init_func_t is the type of function which is
* called when a scaled-font needs to be created for a user font-face.
*
* The cairo context @cr is not used by the caller, but is prepared in font
* space, similar to what the cairo contexts passed to the render_glyph
* method will look like. The callback can use this context for extents
* computation for example. After the callback is called, @cr is checked
* for any error status.
*
* The @extents argument is where the user font sets the font extents for
* @scaled_font. It is in font space, which means that for most cases its
* ascent and descent members should add to 1.0. @extents is preset to
* hold a value of 1.0 for ascent, height, and max_x_advance, and 0.0 for
* descent and max_y_advance members.
*
* The callback is optional. If not set, default font extents as described
* in the previous paragraph will be used.
*
* Note that @scaled_font is not fully initialized at this
* point and trying to use it for text operations in the callback will result
* in deadlock.
*
* Returns: %CAIRO_STATUS_SUCCESS upon success, or an error status on error.
*
* Since: 1.8
**/
typedef cairo_status_t (*cairo_user_scaled_font_init_func_t) (cairo_scaled_font_t *s
caled_font,
cairo_t *cr,
cairo_font_extents_t *extents);
/**
--> --------------------
--> maximum size reached
--> --------------------
