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