WebSVN – Kolibri OS – Blame – /programs/develop/libraries/cairo/src/cairo.c

Rev	Author	Line No.	Line
1892	serge	1	/* -- Mode: c; c-basic-offset: 4; indent-tabs-mode: t; tab-width: 8; -- */
		2	/* cairo - a vector graphics library with display and print output
		3	*
		4	* Copyright © 2002 University of Southern California
		5	* Copyright © 2005 Red Hat, Inc.
3959	Serge	6	* Copyright © 2011 Intel Corporation
1892	serge	7	*
		8	* This library is free software; you can redistribute it and/or
		9	* modify it either under the terms of the GNU Lesser General Public
		10	* License version 2.1 as published by the Free Software Foundation
		11	* (the "LGPL") or, at your option, under the terms of the Mozilla
		12	* Public License Version 1.1 (the "MPL"). If you do not alter this
		13	* notice, a recipient may use your version of this file under either
		14	* the MPL or the LGPL.
		15	*
		16	* You should have received a copy of the LGPL along with this library
		17	* in the file COPYING-LGPL-2.1; if not, write to the Free Software
		18	* Foundation, Inc., 51 Franklin Street, Suite 500, Boston, MA 02110-1335, USA
		19	* You should have received a copy of the MPL along with this library
		20	* in the file COPYING-MPL-1.1
		21	*
		22	* The contents of this file are subject to the Mozilla Public License
		23	* Version 1.1 (the "License"); you may not use this file except in
		24	* compliance with the License. You may obtain a copy of the License at
		25	* http://www.mozilla.org/MPL/
		26	*
		27	* This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
		28	* OF ANY KIND, either express or implied. See the LGPL or the MPL for
		29	* the specific language governing rights and limitations.
		30	*
		31	* The Original Code is the cairo graphics library.
		32	*
		33	* The Initial Developer of the Original Code is University of Southern
		34	* California.
		35	*
		36	* Contributor(s):
		37	* Carl D. Worth
3959	Serge	38	* Chris Wilson
1892	serge	39	*/
		40
		41	#include "cairoint.h"
		42	#include "cairo-private.h"
		43
3959	Serge	44	#include "cairo-backend-private.h"
1892	serge	45	#include "cairo-error-private.h"
		46	#include "cairo-path-private.h"
3959	Serge	47	#include "cairo-pattern-private.h"
		48	#include "cairo-surface-private.h"
		49	#include "cairo-surface-backend-private.h"
1892	serge	50
3959	Serge	51	#include
		52
1892	serge	53	/**
		54	* SECTION:cairo
		55	* @Title: cairo_t
		56	* @Short_Description: The cairo drawing context
		57	* @See_Also: #cairo_surface_t
		58	*
		59	* #cairo_t is the main object used when drawing with cairo. To
		60	* draw with cairo, you create a #cairo_t, set the target surface,
		61	* and drawing options for the #cairo_t, create shapes with
		62	* functions like cairo_move_to() and cairo_line_to(), and then
		63	* draw shapes with cairo_stroke() or cairo_fill().
		64	*
		65	* #cairo_t's can be pushed to a stack via cairo_save().
3959	Serge	66	* They may then safely be changed, without losing the current state.
1892	serge	67	* Use cairo_restore() to restore to the saved state.
3959	Serge	68	**/
1892	serge	69
		70	/**
		71	* SECTION:cairo-text
		72	* @Title: text
		73	* @Short_Description: Rendering text and glyphs
		74	* @See_Also: #cairo_font_face_t, #cairo_scaled_font_t, cairo_text_path(),
		75	* cairo_glyph_path()
		76	*
		77	* The functions with text in their name form cairo's
		78	* toy text API. The toy API takes UTF-8 encoded
		79	* text and is limited in its functionality to rendering simple
		80	* left-to-right text with no advanced features. That means for example
		81	* that most complex scripts like Hebrew, Arabic, and Indic scripts are
		82	* out of question. No kerning or correct positioning of diacritical marks
		83	* either. The font selection is pretty limited too and doesn't handle the
		84	* case that the selected font does not cover the characters in the text.
		85	* This set of functions are really that, a toy text API, for testing and
		86	* demonstration purposes. Any serious application should avoid them.
		87	*
		88	* The functions with glyphs in their name form cairo's
		89	* low-level text API. The low-level API relies on
		90	* the user to convert text to a set of glyph indexes and positions. This
		91	* is a very hard problem and is best handled by external libraries, like
		92	* the pangocairo that is part of the Pango text layout and rendering library.
		93	* Pango is available from
		94	* url="http://www.pango.org/">http://www.pango.org/.
3959	Serge	95	**/
1892	serge	96
		97	/**
		98	* SECTION:cairo-transforms
		99	* @Title: Transformations
		100	* @Short_Description: Manipulating the current transformation matrix
		101	* @See_Also: #cairo_matrix_t
		102	*
		103	* The current transformation matrix, ctm, is a
		104	* two-dimensional affine transformation that maps all coordinates and other
		105	* drawing instruments from the user space into the
		106	* surface's canonical coordinate system, also known as the device
		107	* space.
3959	Serge	108	**/
1892	serge	109
3959	Serge	110	#define DEFINE_NIL_CONTEXT(status) \
		111	{ \
		112	CAIRO_REFERENCE_COUNT_INVALID, /* ref_count */ \
		113	status, /* status */ \
		114	{ 0, 0, 0, NULL }, /* user_data */ \
		115	NULL \
		116	}
1892	serge	117
3959	Serge	118	static const cairo_t _cairo_nil[] = {
		119	DEFINE_NIL_CONTEXT (CAIRO_STATUS_NO_MEMORY),
		120	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_RESTORE),
		121	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_POP_GROUP),
		122	DEFINE_NIL_CONTEXT (CAIRO_STATUS_NO_CURRENT_POINT),
		123	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_MATRIX),
		124	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_STATUS),
		125	DEFINE_NIL_CONTEXT (CAIRO_STATUS_NULL_POINTER),
		126	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_STRING),
		127	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_PATH_DATA),
		128	DEFINE_NIL_CONTEXT (CAIRO_STATUS_READ_ERROR),
		129	DEFINE_NIL_CONTEXT (CAIRO_STATUS_WRITE_ERROR),
		130	DEFINE_NIL_CONTEXT (CAIRO_STATUS_SURFACE_FINISHED),
		131	DEFINE_NIL_CONTEXT (CAIRO_STATUS_SURFACE_TYPE_MISMATCH),
		132	DEFINE_NIL_CONTEXT (CAIRO_STATUS_PATTERN_TYPE_MISMATCH),
		133	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_CONTENT),
		134	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_FORMAT),
		135	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_VISUAL),
		136	DEFINE_NIL_CONTEXT (CAIRO_STATUS_FILE_NOT_FOUND),
		137	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_DASH),
		138	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_DSC_COMMENT),
		139	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_INDEX),
		140	DEFINE_NIL_CONTEXT (CAIRO_STATUS_CLIP_NOT_REPRESENTABLE),
		141	DEFINE_NIL_CONTEXT (CAIRO_STATUS_TEMP_FILE_ERROR),
		142	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_STRIDE),
		143	DEFINE_NIL_CONTEXT (CAIRO_STATUS_FONT_TYPE_MISMATCH),
		144	DEFINE_NIL_CONTEXT (CAIRO_STATUS_USER_FONT_IMMUTABLE),
		145	DEFINE_NIL_CONTEXT (CAIRO_STATUS_USER_FONT_ERROR),
		146	DEFINE_NIL_CONTEXT (CAIRO_STATUS_NEGATIVE_COUNT),
		147	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_CLUSTERS),
		148	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_SLANT),
		149	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_WEIGHT),
		150	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_SIZE),
		151	DEFINE_NIL_CONTEXT (CAIRO_STATUS_USER_FONT_NOT_IMPLEMENTED),
		152	DEFINE_NIL_CONTEXT (CAIRO_STATUS_DEVICE_TYPE_MISMATCH),
		153	DEFINE_NIL_CONTEXT (CAIRO_STATUS_DEVICE_ERROR),
		154	DEFINE_NIL_CONTEXT (CAIRO_STATUS_INVALID_MESH_CONSTRUCTION),
		155	DEFINE_NIL_CONTEXT (CAIRO_STATUS_DEVICE_FINISHED)
1892	serge	156	};
3959	Serge	157	COMPILE_TIME_ASSERT (ARRAY_LENGTH (_cairo_nil) == CAIRO_STATUS_LAST_STATUS - 1);
1892	serge	158
		159	/**
		160	* _cairo_set_error:
		161	* @cr: a cairo context
		162	* @status: a status value indicating an error
		163	*
		164	* Atomically sets cr->status to @status and calls _cairo_error;
		165	* Does nothing if status is %CAIRO_STATUS_SUCCESS.
		166	*
		167	* All assignments of an error status to cr->status should happen
		168	* through _cairo_set_error(). Note that due to the nature of the atomic
		169	* operation, it is not safe to call this function on the nil objects.
		170	*
		171	* The purpose of this function is to allow the user to set a
		172	* breakpoint in _cairo_error() to generate a stack trace for when the
		173	* user causes cairo to detect an error.
		174	**/
		175	static void
		176	_cairo_set_error (cairo_t *cr, cairo_status_t status)
		177	{
		178	/* Don't overwrite an existing error. This preserves the first
		179	* error, which is the most significant. */
		180	_cairo_status_set_error (&cr->status, _cairo_error (status));
		181	}
		182
3959	Serge	183	cairo_t *
1892	serge	184	_cairo_create_in_error (cairo_status_t status)
		185	{
		186	cairo_t *cr;
		187
		188	assert (status != CAIRO_STATUS_SUCCESS);
		189
3959	Serge	190	cr = (cairo_t *) &_cairo_nil[status - CAIRO_STATUS_NO_MEMORY];
		191	assert (status == cr->status);
1892	serge	192
		193	return cr;
		194	}
		195
		196	/**
		197	* cairo_create:
		198	* @target: target surface for the context
		199	*
		200	* Creates a new #cairo_t with all graphics state parameters set to
		201	* default values and with @target as a target surface. The target
		202	* surface should be constructed with a backend-specific function such
		203	* as cairo_image_surface_create() (or any other
3959	Serge	204	* cairo_backend_surface_create()
		205	* variant).
1892	serge	206	*
		207	* This function references @target, so you can immediately
		208	* call cairo_surface_destroy() on it if you don't need to
		209	* maintain a separate reference to it.
		210	*
		211	* Return value: a newly allocated #cairo_t with a reference
		212	* count of 1. The initial reference count should be released
		213	* with cairo_destroy() when you are done using the #cairo_t.
		214	* This function never returns %NULL. If memory cannot be
		215	* allocated, a special #cairo_t object will be returned on
3959	Serge	216	* which cairo_status() returns %CAIRO_STATUS_NO_MEMORY. If
		217	* you attempt to target a surface which does not support
		218	* writing (such as #cairo_mime_surface_t) then a
		219	* %CAIRO_STATUS_WRITE_ERROR will be raised. You can use this
		220	* object normally, but no drawing will be done.
		221	*
		222	* Since: 1.0
1892	serge	223	**/
		224	cairo_t *
		225	cairo_create (cairo_surface_t *target)
		226	{
		227	if (unlikely (target == NULL))
		228	return _cairo_create_in_error (_cairo_error (CAIRO_STATUS_NULL_POINTER));
		229	if (unlikely (target->status))
		230	return _cairo_create_in_error (target->status);
		231
3959	Serge	232	if (target->backend->create_context == NULL)
		233	return _cairo_create_in_error (_cairo_error (CAIRO_STATUS_WRITE_ERROR));
1892	serge	234
3959	Serge	235	return target->backend->create_context (target);
		236
		237	}
		238	slim_hidden_def (cairo_create);
		239
		240	void
		241	_cairo_init (cairo_t *cr,
		242	const cairo_backend_t *backend)
		243	{
1892	serge	244	CAIRO_REFERENCE_COUNT_INIT (&cr->ref_count, 1);
		245	cr->status = CAIRO_STATUS_SUCCESS;
		246	_cairo_user_data_array_init (&cr->user_data);
		247
3959	Serge	248	cr->backend = backend;
1892	serge	249	}
		250
		251	/**
		252	* cairo_reference:
		253	* @cr: a #cairo_t
		254	*
		255	* Increases the reference count on @cr by one. This prevents
		256	* @cr from being destroyed until a matching call to cairo_destroy()
		257	* is made.
		258	*
		259	* The number of references to a #cairo_t can be get using
		260	* cairo_get_reference_count().
		261	*
		262	* Return value: the referenced #cairo_t.
3959	Serge	263	*
		264	* Since: 1.0
1892	serge	265	**/
		266	cairo_t *
		267	cairo_reference (cairo_t *cr)
		268	{
		269	if (cr == NULL \|\| CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
		270	return cr;
		271
		272	assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&cr->ref_count));
		273
		274	_cairo_reference_count_inc (&cr->ref_count);
		275
		276	return cr;
		277	}
		278
3959	Serge	279	void
		280	_cairo_fini (cairo_t *cr)
		281	{
		282	_cairo_user_data_array_fini (&cr->user_data);
		283	}
		284
1892	serge	285	/**
		286	* cairo_destroy:
		287	* @cr: a #cairo_t
		288	*
		289	* Decreases the reference count on @cr by one. If the result
		290	* is zero, then @cr and all associated resources are freed.
		291	* See cairo_reference().
3959	Serge	292	*
		293	* Since: 1.0
1892	serge	294	**/
		295	void
		296	cairo_destroy (cairo_t *cr)
		297	{
		298	if (cr == NULL \|\| CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
		299	return;
		300
		301	assert (CAIRO_REFERENCE_COUNT_HAS_REFERENCE (&cr->ref_count));
		302
		303	if (! _cairo_reference_count_dec_and_test (&cr->ref_count))
		304	return;
		305
3959	Serge	306	cr->backend->destroy (cr);
1892	serge	307	}
		308	slim_hidden_def (cairo_destroy);
		309
		310	/**
		311	* cairo_get_user_data:
		312	* @cr: a #cairo_t
		313	* @key: the address of the #cairo_user_data_key_t the user data was
		314	* attached to
		315	*
		316	* Return user data previously attached to @cr using the specified
		317	* key. If no user data has been attached with the given key this
		318	* function returns %NULL.
		319	*
		320	* Return value: the user data previously attached or %NULL.
		321	*
		322	* Since: 1.4
		323	**/
		324	void *
		325	cairo_get_user_data (cairo_t *cr,
		326	const cairo_user_data_key_t *key)
		327	{
3959	Serge	328	return _cairo_user_data_array_get_data (&cr->user_data, key);
1892	serge	329	}
		330
		331	/**
		332	* cairo_set_user_data:
		333	* @cr: a #cairo_t
		334	* @key: the address of a #cairo_user_data_key_t to attach the user data to
		335	* @user_data: the user data to attach to the #cairo_t
		336	* @destroy: a #cairo_destroy_func_t which will be called when the
		337	* #cairo_t is destroyed or when new user data is attached using the
		338	* same key.
		339	*
		340	* Attach user data to @cr. To remove user data from a surface,
		341	* call this function with the key that was used to set it and %NULL
		342	* for @data.
		343	*
		344	* Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY if a
		345	* slot could not be allocated for the user data.
		346	*
		347	* Since: 1.4
		348	**/
		349	cairo_status_t
		350	cairo_set_user_data (cairo_t *cr,
		351	const cairo_user_data_key_t *key,
		352	void *user_data,
		353	cairo_destroy_func_t destroy)
		354	{
		355	if (CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
		356	return cr->status;
		357
		358	return _cairo_user_data_array_set_data (&cr->user_data,
		359	key, user_data, destroy);
		360	}
		361
		362	/**
		363	* cairo_get_reference_count:
		364	* @cr: a #cairo_t
		365	*
		366	* Returns the current reference count of @cr.
		367	*
		368	* Return value: the current reference count of @cr. If the
		369	* object is a nil object, 0 will be returned.
		370	*
		371	* Since: 1.4
		372	**/
		373	unsigned int
		374	cairo_get_reference_count (cairo_t *cr)
		375	{
		376	if (cr == NULL \|\| CAIRO_REFERENCE_COUNT_IS_INVALID (&cr->ref_count))
		377	return 0;
		378
		379	return CAIRO_REFERENCE_COUNT_GET_VALUE (&cr->ref_count);
		380	}
		381
		382	/**
		383	* cairo_save:
		384	* @cr: a #cairo_t
		385	*
		386	* Makes a copy of the current state of @cr and saves it
		387	* on an internal stack of saved states for @cr. When
		388	* cairo_restore() is called, @cr will be restored to
		389	* the saved state. Multiple calls to cairo_save() and
		390	* cairo_restore() can be nested; each call to cairo_restore()
		391	* restores the state from the matching paired cairo_save().
		392	*
		393	* It isn't necessary to clear all saved states before
		394	* a #cairo_t is freed. If the reference count of a #cairo_t
		395	* drops to zero in response to a call to cairo_destroy(),
		396	* any saved states will be freed along with the #cairo_t.
3959	Serge	397	*
		398	* Since: 1.0
1892	serge	399	**/
		400	void
		401	cairo_save (cairo_t *cr)
		402	{
		403	cairo_status_t status;
		404
		405	if (unlikely (cr->status))
		406	return;
		407
3959	Serge	408	status = cr->backend->save (cr);
1892	serge	409	if (unlikely (status))
		410	_cairo_set_error (cr, status);
		411	}
		412	slim_hidden_def(cairo_save);
		413
		414	/**
		415	* cairo_restore:
		416	* @cr: a #cairo_t
		417	*
		418	* Restores @cr to the state saved by a preceding call to
		419	* cairo_save() and removes that state from the stack of
		420	* saved states.
3959	Serge	421	*
		422	* Since: 1.0
1892	serge	423	**/
		424	void
		425	cairo_restore (cairo_t *cr)
		426	{
		427	cairo_status_t status;
		428
		429	if (unlikely (cr->status))
		430	return;
		431
3959	Serge	432	status = cr->backend->restore (cr);
1892	serge	433	if (unlikely (status))
		434	_cairo_set_error (cr, status);
		435	}
		436	slim_hidden_def(cairo_restore);
		437
		438	/**
		439	* cairo_push_group:
		440	* @cr: a cairo context
		441	*
		442	* Temporarily redirects drawing to an intermediate surface known as a
		443	* group. The redirection lasts until the group is completed by a call
		444	* to cairo_pop_group() or cairo_pop_group_to_source(). These calls
		445	* provide the result of any drawing to the group as a pattern,
		446	* (either as an explicit object, or set as the source pattern).
		447	*
		448	* This group functionality can be convenient for performing
		449	* intermediate compositing. One common use of a group is to render
		450	* objects as opaque within the group, (so that they occlude each
		451	* other), and then blend the result with translucence onto the
		452	* destination.
		453	*
		454	* Groups can be nested arbitrarily deep by making balanced calls to
		455	* cairo_push_group()/cairo_pop_group(). Each call pushes/pops the new
		456	* target group onto/from a stack.
		457	*
		458	* The cairo_push_group() function calls cairo_save() so that any
		459	* changes to the graphics state will not be visible outside the
		460	* group, (the pop_group functions call cairo_restore()).
		461	*
		462	* By default the intermediate group will have a content type of
		463	* %CAIRO_CONTENT_COLOR_ALPHA. Other content types can be chosen for
		464	* the group by using cairo_push_group_with_content() instead.
		465	*
		466	* As an example, here is how one might fill and stroke a path with
		467	* translucence, but without any portion of the fill being visible
		468	* under the stroke:
		469	*
		470	*
		471	* cairo_push_group (cr);
		472	* cairo_set_source (cr, fill_pattern);
		473	* cairo_fill_preserve (cr);
		474	* cairo_set_source (cr, stroke_pattern);
		475	* cairo_stroke (cr);
		476	* cairo_pop_group_to_source (cr);
		477	* cairo_paint_with_alpha (cr, alpha);
		478	*
		479	*
		480	* Since: 1.2
3959	Serge	481	**/
1892	serge	482	void
		483	cairo_push_group (cairo_t *cr)
		484	{
		485	cairo_push_group_with_content (cr, CAIRO_CONTENT_COLOR_ALPHA);
		486	}
		487
		488	/**
		489	* cairo_push_group_with_content:
		490	* @cr: a cairo context
		491	* @content: a #cairo_content_t indicating the type of group that
		492	* will be created
		493	*
		494	* Temporarily redirects drawing to an intermediate surface known as a
		495	* group. The redirection lasts until the group is completed by a call
		496	* to cairo_pop_group() or cairo_pop_group_to_source(). These calls
		497	* provide the result of any drawing to the group as a pattern,
		498	* (either as an explicit object, or set as the source pattern).
		499	*
		500	* The group will have a content type of @content. The ability to
		501	* control this content type is the only distinction between this
		502	* function and cairo_push_group() which you should see for a more
		503	* detailed description of group rendering.
		504	*
		505	* Since: 1.2
3959	Serge	506	**/
1892	serge	507	void
		508	cairo_push_group_with_content (cairo_t *cr, cairo_content_t content)
		509	{
		510	cairo_status_t status;
		511
		512	if (unlikely (cr->status))
		513	return;
		514
3959	Serge	515	status = cr->backend->push_group (cr, content);
1892	serge	516	if (unlikely (status))
		517	_cairo_set_error (cr, status);
		518	}
		519	slim_hidden_def(cairo_push_group_with_content);
		520
		521	/**
		522	* cairo_pop_group:
		523	* @cr: a cairo context
		524	*
		525	* Terminates the redirection begun by a call to cairo_push_group() or
		526	* cairo_push_group_with_content() and returns a new pattern
		527	* containing the results of all drawing operations performed to the
		528	* group.
		529	*
		530	* The cairo_pop_group() function calls cairo_restore(), (balancing a
		531	* call to cairo_save() by the push_group function), so that any
		532	* changes to the graphics state will not be visible outside the
		533	* group.
		534	*
		535	* Return value: a newly created (surface) pattern containing the
		536	* results of all drawing operations performed to the group. The
		537	* caller owns the returned object and should call
		538	* cairo_pattern_destroy() when finished with it.
		539	*
		540	* Since: 1.2
		541	**/
		542	cairo_pattern_t *
		543	cairo_pop_group (cairo_t *cr)
		544	{
		545	cairo_pattern_t *group_pattern;
		546
		547	if (unlikely (cr->status))
		548	return _cairo_pattern_create_in_error (cr->status);
		549
3959	Serge	550	group_pattern = cr->backend->pop_group (cr);
		551	if (unlikely (group_pattern->status))
		552	_cairo_set_error (cr, group_pattern->status);
1892	serge	553
		554	return group_pattern;
		555	}
		556	slim_hidden_def(cairo_pop_group);
		557
		558	/**
		559	* cairo_pop_group_to_source:
		560	* @cr: a cairo context
		561	*
		562	* Terminates the redirection begun by a call to cairo_push_group() or
		563	* cairo_push_group_with_content() and installs the resulting pattern
		564	* as the source pattern in the given cairo context.
		565	*
		566	* The behavior of this function is equivalent to the sequence of
		567	* operations:
		568	*
		569	*
3959	Serge	570	* cairo_pattern_t *group = cairo_pop_group (cr);
1892	serge	571	* cairo_set_source (cr, group);
		572	* cairo_pattern_destroy (group);
		573	*
		574	*
		575	* but is more convenient as their is no need for a variable to store
		576	* the short-lived pointer to the pattern.
		577	*
		578	* The cairo_pop_group() function calls cairo_restore(), (balancing a
		579	* call to cairo_save() by the push_group function), so that any
		580	* changes to the graphics state will not be visible outside the
		581	* group.
		582	*
		583	* Since: 1.2
		584	**/
		585	void
		586	cairo_pop_group_to_source (cairo_t *cr)
		587	{
		588	cairo_pattern_t *group_pattern;
		589
		590	group_pattern = cairo_pop_group (cr);
		591	cairo_set_source (cr, group_pattern);
		592	cairo_pattern_destroy (group_pattern);
		593	}
		594
		595	/**
		596	* cairo_set_operator:
		597	* @cr: a #cairo_t
		598	* @op: a compositing operator, specified as a #cairo_operator_t
		599	*
		600	* Sets the compositing operator to be used for all drawing
		601	* operations. See #cairo_operator_t for details on the semantics of
		602	* each available compositing operator.
		603	*
		604	* The default operator is %CAIRO_OPERATOR_OVER.
3959	Serge	605	*
		606	* Since: 1.0
1892	serge	607	**/
		608	void
		609	cairo_set_operator (cairo_t *cr, cairo_operator_t op)
		610	{
		611	cairo_status_t status;
		612
		613	if (unlikely (cr->status))
		614	return;
		615
3959	Serge	616	status = cr->backend->set_operator (cr, op);
1892	serge	617	if (unlikely (status))
		618	_cairo_set_error (cr, status);
		619	}
		620	slim_hidden_def (cairo_set_operator);
		621
		622
3959	Serge	623	#if 0
		624	/**
		625	* cairo_set_opacity:
		626	* @cr: a #cairo_t
		627	* @opacity: the level of opacity to use when compositing
		628	*
		629	* Sets the compositing opacity to be used for all drawing
		630	* operations. The effect is to fade out the operations
		631	* using the alpha value.
		632	*
		633	* The default opacity is 1.
		634	*
		635	* Since: TBD
		636	**/
		637	void
		638	cairo_set_opacity (cairo_t *cr, double opacity)
1892	serge	639	{
3959	Serge	640	cairo_status_t status;
1892	serge	641
3959	Serge	642	if (unlikely (cr->status))
		643	return;
1892	serge	644
3959	Serge	645	status = cr->backend->set_opacity (cr, opacity);
		646	if (unlikely (status))
		647	_cairo_set_error (cr, status);
		648	}
		649	#endif
1892	serge	650
		651	/**
3959	Serge	652	* cairo_set_source_rgb:
1892	serge	653	* @cr: a cairo context
		654	* @red: red component of color
		655	* @green: green component of color
		656	* @blue: blue component of color
		657	*
		658	* Sets the source pattern within @cr to an opaque color. This opaque
		659	* color will then be used for any subsequent drawing operation until
		660	* a new source pattern is set.
		661	*
		662	* The color components are floating point numbers in the range 0 to
		663	* 1. If the values passed in are outside that range, they will be
		664	* clamped.
		665	*
		666	* The default source pattern is opaque black, (that is, it is
		667	* equivalent to cairo_set_source_rgb(cr, 0.0, 0.0, 0.0)).
3959	Serge	668	*
		669	* Since: 1.0
1892	serge	670	**/
		671	void
		672	cairo_set_source_rgb (cairo_t *cr, double red, double green, double blue)
		673	{
3959	Serge	674	cairo_status_t status;
1892	serge	675
		676	if (unlikely (cr->status))
		677	return;
		678
3959	Serge	679	status = cr->backend->set_source_rgba (cr, red, green, blue, 1.);
		680	if (unlikely (status))
		681	_cairo_set_error (cr, status);
1892	serge	682	}
		683	slim_hidden_def (cairo_set_source_rgb);
		684
		685	/**
		686	* cairo_set_source_rgba:
		687	* @cr: a cairo context
		688	* @red: red component of color
		689	* @green: green component of color
		690	* @blue: blue component of color
		691	* @alpha: alpha component of color
		692	*
		693	* Sets the source pattern within @cr to a translucent color. This
		694	* color will then be used for any subsequent drawing operation until
		695	* a new source pattern is set.
		696	*
		697	* The color and alpha components are floating point numbers in the
		698	* range 0 to 1. If the values passed in are outside that range, they
		699	* will be clamped.
		700	*
		701	* The default source pattern is opaque black, (that is, it is
		702	* equivalent to cairo_set_source_rgba(cr, 0.0, 0.0, 0.0, 1.0)).
3959	Serge	703	*
		704	* Since: 1.0
1892	serge	705	**/
		706	void
		707	cairo_set_source_rgba (cairo_t *cr,
		708	double red, double green, double blue,
		709	double alpha)
		710	{
3959	Serge	711	cairo_status_t status;
1892	serge	712
		713	if (unlikely (cr->status))
		714	return;
		715
3959	Serge	716	status = cr->backend->set_source_rgba (cr, red, green, blue, alpha);
		717	if (unlikely (status))
		718	_cairo_set_error (cr, status);
1892	serge	719	}
		720
		721	/**
		722	* cairo_set_source_surface:
		723	* @cr: a cairo context
		724	* @surface: a surface to be used to set the source pattern
		725	* @x: User-space X coordinate for surface origin
		726	* @y: User-space Y coordinate for surface origin
		727	*
		728	* This is a convenience function for creating a pattern from @surface
		729	* and setting it as the source in @cr with cairo_set_source().
		730	*
		731	* The @x and @y parameters give the user-space coordinate at which
		732	* the surface origin should appear. (The surface origin is its
		733	* upper-left corner before any transformation has been applied.) The
		734	* @x and @y parameters are negated and then set as translation values
		735	* in the pattern matrix.
		736	*
		737	* Other than the initial translation pattern matrix, as described
		738	* above, all other pattern attributes, (such as its extend mode), are
		739	* set to the default values as in cairo_pattern_create_for_surface().
		740	* The resulting pattern can be queried with cairo_get_source() so
		741	* that these attributes can be modified if desired, (eg. to create a
		742	* repeating pattern with cairo_pattern_set_extend()).
3959	Serge	743	*
		744	* Since: 1.0
1892	serge	745	**/
		746	void
		747	cairo_set_source_surface (cairo_t *cr,
		748	cairo_surface_t *surface,
		749	double x,
		750	double y)
		751	{
3959	Serge	752	cairo_status_t status;
1892	serge	753
		754	if (unlikely (cr->status))
		755	return;
		756
3959	Serge	757	if (unlikely (surface == NULL)) {
		758	_cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
		759	return;
		760	}
1892	serge	761
3959	Serge	762	status = cr->backend->set_source_surface (cr, surface, x, y);
		763	if (unlikely (status))
		764	_cairo_set_error (cr, status);
1892	serge	765	}
		766	slim_hidden_def (cairo_set_source_surface);
		767
		768	/**
3959	Serge	769	* cairo_set_source:
1892	serge	770	* @cr: a cairo context
		771	* @source: a #cairo_pattern_t to be used as the source for
		772	* subsequent drawing operations.
		773	*
		774	* Sets the source pattern within @cr to @source. This pattern
		775	* will then be used for any subsequent drawing operation until a new
		776	* source pattern is set.
		777	*
		778	* Note: The pattern's transformation matrix will be locked to the
		779	* user space in effect at the time of cairo_set_source(). This means
		780	* that further modifications of the current transformation matrix
		781	* will not affect the source pattern. See cairo_pattern_set_matrix().
		782	*
		783	* The default source pattern is a solid pattern that is opaque black,
		784	* (that is, it is equivalent to cairo_set_source_rgb(cr, 0.0, 0.0,
		785	* 0.0)).
3959	Serge	786	*
		787	* Since: 1.0
1892	serge	788	**/
		789	void
		790	cairo_set_source (cairo_t cr, cairo_pattern_t source)
		791	{
		792	cairo_status_t status;
		793
		794	if (unlikely (cr->status))
		795	return;
		796
3959	Serge	797	if (unlikely (source == NULL)) {
1892	serge	798	_cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
		799	return;
		800	}
		801
3959	Serge	802	if (unlikely (source->status)) {
1892	serge	803	_cairo_set_error (cr, source->status);
		804	return;
		805	}
		806
3959	Serge	807	status = cr->backend->set_source (cr, source);
1892	serge	808	if (unlikely (status))
		809	_cairo_set_error (cr, status);
		810	}
		811	slim_hidden_def (cairo_set_source);
		812
		813	/**
		814	* cairo_get_source:
		815	* @cr: a cairo context
		816	*
		817	* Gets the current source pattern for @cr.
		818	*
		819	* Return value: the current source pattern. This object is owned by
		820	* cairo. To keep a reference to it, you must call
		821	* cairo_pattern_reference().
3959	Serge	822	*
		823	* Since: 1.0
1892	serge	824	**/
		825	cairo_pattern_t *
		826	cairo_get_source (cairo_t *cr)
		827	{
		828	if (unlikely (cr->status))
		829	return _cairo_pattern_create_in_error (cr->status);
		830
3959	Serge	831	return cr->backend->get_source (cr);
1892	serge	832	}
		833
		834	/**
		835	* cairo_set_tolerance:
		836	* @cr: a #cairo_t
		837	* @tolerance: the tolerance, in device units (typically pixels)
		838	*
		839	* Sets the tolerance used when converting paths into trapezoids.
		840	* Curved segments of the path will be subdivided until the maximum
		841	* deviation between the original path and the polygonal approximation
		842	* is less than @tolerance. The default value is 0.1. A larger
		843	* value will give better performance, a smaller value, better
		844	* appearance. (Reducing the value from the default value of 0.1
		845	* is unlikely to improve appearance significantly.) The accuracy of paths
		846	* within Cairo is limited by the precision of its internal arithmetic, and
		847	* the prescribed @tolerance is restricted to the smallest
		848	* representable internal value.
3959	Serge	849	*
		850	* Since: 1.0
1892	serge	851	**/
		852	void
		853	cairo_set_tolerance (cairo_t *cr, double tolerance)
		854	{
		855	cairo_status_t status;
		856
		857	if (unlikely (cr->status))
		858	return;
		859
3959	Serge	860	status = cr->backend->set_tolerance (cr, tolerance);
1892	serge	861	if (unlikely (status))
		862	_cairo_set_error (cr, status);
		863	}
		864	slim_hidden_def (cairo_set_tolerance);
		865
		866	/**
		867	* cairo_set_antialias:
		868	* @cr: a #cairo_t
		869	* @antialias: the new antialiasing mode
		870	*
		871	* Set the antialiasing mode of the rasterizer used for drawing shapes.
		872	* This value is a hint, and a particular backend may or may not support
		873	* a particular value. At the current time, no backend supports
		874	* %CAIRO_ANTIALIAS_SUBPIXEL when drawing shapes.
		875	*
		876	* Note that this option does not affect text rendering, instead see
		877	* cairo_font_options_set_antialias().
3959	Serge	878	*
		879	* Since: 1.0
1892	serge	880	**/
		881	void
		882	cairo_set_antialias (cairo_t *cr, cairo_antialias_t antialias)
		883	{
		884	cairo_status_t status;
		885
		886	if (unlikely (cr->status))
		887	return;
		888
3959	Serge	889	status = cr->backend->set_antialias (cr, antialias);
1892	serge	890	if (unlikely (status))
		891	_cairo_set_error (cr, status);
		892	}
		893
		894	/**
		895	* cairo_set_fill_rule:
		896	* @cr: a #cairo_t
		897	* @fill_rule: a fill rule, specified as a #cairo_fill_rule_t
		898	*
		899	* Set the current fill rule within the cairo context. The fill rule
		900	* is used to determine which regions are inside or outside a complex
		901	* (potentially self-intersecting) path. The current fill rule affects
		902	* both cairo_fill() and cairo_clip(). See #cairo_fill_rule_t for details
		903	* on the semantics of each available fill rule.
		904	*
		905	* The default fill rule is %CAIRO_FILL_RULE_WINDING.
3959	Serge	906	*
		907	* Since: 1.0
1892	serge	908	**/
		909	void
		910	cairo_set_fill_rule (cairo_t *cr, cairo_fill_rule_t fill_rule)
		911	{
		912	cairo_status_t status;
		913
		914	if (unlikely (cr->status))
		915	return;
		916
3959	Serge	917	status = cr->backend->set_fill_rule (cr, fill_rule);
1892	serge	918	if (unlikely (status))
		919	_cairo_set_error (cr, status);
		920	}
		921
		922	/**
		923	* cairo_set_line_width:
		924	* @cr: a #cairo_t
		925	* @width: a line width
		926	*
		927	* Sets the current line width within the cairo context. The line
		928	* width value specifies the diameter of a pen that is circular in
		929	* user space, (though device-space pen may be an ellipse in general
		930	* due to scaling/shear/rotation of the CTM).
		931	*
		932	* Note: When the description above refers to user space and CTM it
		933	* refers to the user space and CTM in effect at the time of the
		934	* stroking operation, not the user space and CTM in effect at the
		935	* time of the call to cairo_set_line_width(). The simplest usage
		936	* makes both of these spaces identical. That is, if there is no
		937	* change to the CTM between a call to cairo_set_line_width() and the
		938	* stroking operation, then one can just pass user-space values to
		939	* cairo_set_line_width() and ignore this note.
		940	*
		941	* As with the other stroke parameters, the current line width is
		942	* examined by cairo_stroke(), cairo_stroke_extents(), and
		943	* cairo_stroke_to_path(), but does not have any effect during path
		944	* construction.
		945	*
		946	* The default line width value is 2.0.
3959	Serge	947	*
		948	* Since: 1.0
1892	serge	949	**/
		950	void
		951	cairo_set_line_width (cairo_t *cr, double width)
		952	{
		953	cairo_status_t status;
		954
		955	if (unlikely (cr->status))
		956	return;
		957
		958	if (width < 0.)
		959	width = 0.;
		960
3959	Serge	961	status = cr->backend->set_line_width (cr, width);
1892	serge	962	if (unlikely (status))
		963	_cairo_set_error (cr, status);
		964	}
		965	slim_hidden_def (cairo_set_line_width);
		966
		967	/**
		968	* cairo_set_line_cap:
		969	* @cr: a cairo context
		970	* @line_cap: a line cap style
		971	*
		972	* Sets the current line cap style within the cairo context. See
		973	* #cairo_line_cap_t for details about how the available line cap
		974	* styles are drawn.
		975	*
		976	* As with the other stroke parameters, the current line cap style is
		977	* examined by cairo_stroke(), cairo_stroke_extents(), and
		978	* cairo_stroke_to_path(), but does not have any effect during path
		979	* construction.
		980	*
		981	* The default line cap style is %CAIRO_LINE_CAP_BUTT.
3959	Serge	982	*
		983	* Since: 1.0
1892	serge	984	**/
		985	void
		986	cairo_set_line_cap (cairo_t *cr, cairo_line_cap_t line_cap)
		987	{
		988	cairo_status_t status;
		989
		990	if (unlikely (cr->status))
		991	return;
		992
3959	Serge	993	status = cr->backend->set_line_cap (cr, line_cap);
1892	serge	994	if (unlikely (status))
		995	_cairo_set_error (cr, status);
		996	}
		997	slim_hidden_def (cairo_set_line_cap);
		998
		999	/**
		1000	* cairo_set_line_join:
		1001	* @cr: a cairo context
		1002	* @line_join: a line join style
		1003	*
		1004	* Sets the current line join style within the cairo context. See
		1005	* #cairo_line_join_t for details about how the available line join
		1006	* styles are drawn.
		1007	*
		1008	* As with the other stroke parameters, the current line join style is
		1009	* examined by cairo_stroke(), cairo_stroke_extents(), and
		1010	* cairo_stroke_to_path(), but does not have any effect during path
		1011	* construction.
		1012	*
		1013	* The default line join style is %CAIRO_LINE_JOIN_MITER.
3959	Serge	1014	*
		1015	* Since: 1.0
1892	serge	1016	**/
		1017	void
		1018	cairo_set_line_join (cairo_t *cr, cairo_line_join_t line_join)
		1019	{
		1020	cairo_status_t status;
		1021
		1022	if (unlikely (cr->status))
		1023	return;
		1024
3959	Serge	1025	status = cr->backend->set_line_join (cr, line_join);
1892	serge	1026	if (unlikely (status))
		1027	_cairo_set_error (cr, status);
		1028	}
		1029	slim_hidden_def (cairo_set_line_join);
		1030
		1031	/**
		1032	* cairo_set_dash:
		1033	* @cr: a cairo context
		1034	* @dashes: an array specifying alternate lengths of on and off stroke portions
		1035	* @num_dashes: the length of the dashes array
		1036	* @offset: an offset into the dash pattern at which the stroke should start
		1037	*
		1038	* Sets the dash pattern to be used by cairo_stroke(). A dash pattern
		1039	* is specified by @dashes, an array of positive values. Each value
		1040	* provides the length of alternate "on" and "off" portions of the
		1041	* stroke. The @offset specifies an offset into the pattern at which
		1042	* the stroke begins.
		1043	*
		1044	* Each "on" segment will have caps applied as if the segment were a
		1045	* separate sub-path. In particular, it is valid to use an "on" length
		1046	* of 0.0 with %CAIRO_LINE_CAP_ROUND or %CAIRO_LINE_CAP_SQUARE in order
		1047	* to distributed dots or squares along a path.
		1048	*
		1049	* Note: The length values are in user-space units as evaluated at the
		1050	* time of stroking. This is not necessarily the same as the user
		1051	* space at the time of cairo_set_dash().
		1052	*
		1053	* If @num_dashes is 0 dashing is disabled.
		1054	*
		1055	* If @num_dashes is 1 a symmetric pattern is assumed with alternating
		1056	* on and off portions of the size specified by the single value in
		1057	* @dashes.
		1058	*
		1059	* If any value in @dashes is negative, or if all values are 0, then
		1060	* @cr will be put into an error state with a status of
		1061	* %CAIRO_STATUS_INVALID_DASH.
3959	Serge	1062	*
		1063	* Since: 1.0
1892	serge	1064	**/
		1065	void
		1066	cairo_set_dash (cairo_t *cr,
		1067	const double *dashes,
		1068	int num_dashes,
		1069	double offset)
		1070	{
		1071	cairo_status_t status;
		1072
		1073	if (unlikely (cr->status))
		1074	return;
		1075
3959	Serge	1076	status = cr->backend->set_dash (cr, dashes, num_dashes, offset);
1892	serge	1077	if (unlikely (status))
		1078	_cairo_set_error (cr, status);
		1079	}
		1080
		1081	/**
		1082	* cairo_get_dash_count:
		1083	* @cr: a #cairo_t
		1084	*
		1085	* This function returns the length of the dash array in @cr (0 if dashing
		1086	* is not currently in effect).
		1087	*
		1088	* See also cairo_set_dash() and cairo_get_dash().
		1089	*
		1090	* Return value: the length of the dash array, or 0 if no dash array set.
		1091	*
		1092	* Since: 1.4
3959	Serge	1093	**/
1892	serge	1094	int
		1095	cairo_get_dash_count (cairo_t *cr)
		1096	{
		1097	int num_dashes;
		1098
		1099	if (unlikely (cr->status))
		1100	return 0;
		1101
3959	Serge	1102	cr->backend->get_dash (cr, NULL, &num_dashes, NULL);
1892	serge	1103
		1104	return num_dashes;
		1105	}
		1106
		1107	/**
		1108	* cairo_get_dash:
		1109	* @cr: a #cairo_t
		1110	* @dashes: return value for the dash array, or %NULL
		1111	* @offset: return value for the current dash offset, or %NULL
		1112	*
		1113	* Gets the current dash array. If not %NULL, @dashes should be big
		1114	* enough to hold at least the number of values returned by
		1115	* cairo_get_dash_count().
		1116	*
		1117	* Since: 1.4
		1118	**/
		1119	void
		1120	cairo_get_dash (cairo_t *cr,
		1121	double *dashes,
		1122	double *offset)
		1123	{
		1124	if (unlikely (cr->status))
		1125	return;
		1126
3959	Serge	1127	cr->backend->get_dash (cr, dashes, NULL, offset);
1892	serge	1128	}
		1129
		1130	/**
		1131	* cairo_set_miter_limit:
		1132	* @cr: a cairo context
		1133	* @limit: miter limit to set
		1134	*
		1135	* Sets the current miter limit within the cairo context.
		1136	*
		1137	* If the current line join style is set to %CAIRO_LINE_JOIN_MITER
		1138	* (see cairo_set_line_join()), the miter limit is used to determine
		1139	* whether the lines should be joined with a bevel instead of a miter.
		1140	* Cairo divides the length of the miter by the line width.
		1141	* If the result is greater than the miter limit, the style is
		1142	* converted to a bevel.
		1143	*
		1144	* As with the other stroke parameters, the current line miter limit is
		1145	* examined by cairo_stroke(), cairo_stroke_extents(), and
		1146	* cairo_stroke_to_path(), but does not have any effect during path
		1147	* construction.
		1148	*
		1149	* The default miter limit value is 10.0, which will convert joins
		1150	* with interior angles less than 11 degrees to bevels instead of
		1151	* miters. For reference, a miter limit of 2.0 makes the miter cutoff
		1152	* at 60 degrees, and a miter limit of 1.414 makes the cutoff at 90
		1153	* degrees.
		1154	*
		1155	* A miter limit for a desired angle can be computed as: miter limit =
		1156	* 1/sin(angle/2)
3959	Serge	1157	*
		1158	* Since: 1.0
1892	serge	1159	**/
		1160	void
		1161	cairo_set_miter_limit (cairo_t *cr, double limit)
		1162	{
		1163	cairo_status_t status;
		1164
		1165	if (unlikely (cr->status))
		1166	return;
		1167
3959	Serge	1168	status = cr->backend->set_miter_limit (cr, limit);
1892	serge	1169	if (unlikely (status))
		1170	_cairo_set_error (cr, status);
		1171	}
		1172
		1173	/**
		1174	* cairo_translate:
		1175	* @cr: a cairo context
		1176	* @tx: amount to translate in the X direction
		1177	* @ty: amount to translate in the Y direction
		1178	*
		1179	* Modifies the current transformation matrix (CTM) by translating the
		1180	* user-space origin by (@tx, @ty). This offset is interpreted as a
		1181	* user-space coordinate according to the CTM in place before the new
		1182	* call to cairo_translate(). In other words, the translation of the
		1183	* user-space origin takes place after any existing transformation.
3959	Serge	1184	*
		1185	* Since: 1.0
1892	serge	1186	**/
		1187	void
		1188	cairo_translate (cairo_t *cr, double tx, double ty)
		1189	{
		1190	cairo_status_t status;
		1191
		1192	if (unlikely (cr->status))
		1193	return;
		1194
3959	Serge	1195	status = cr->backend->translate (cr, tx, ty);
1892	serge	1196	if (unlikely (status))
		1197	_cairo_set_error (cr, status);
		1198	}
		1199	slim_hidden_def (cairo_translate);
		1200
		1201	/**
		1202	* cairo_scale:
		1203	* @cr: a cairo context
		1204	* @sx: scale factor for the X dimension
		1205	* @sy: scale factor for the Y dimension
		1206	*
		1207	* Modifies the current transformation matrix (CTM) by scaling the X
		1208	* and Y user-space axes by @sx and @sy respectively. The scaling of
		1209	* the axes takes place after any existing transformation of user
		1210	* space.
3959	Serge	1211	*
		1212	* Since: 1.0
1892	serge	1213	**/
		1214	void
		1215	cairo_scale (cairo_t *cr, double sx, double sy)
		1216	{
		1217	cairo_status_t status;
		1218
		1219	if (unlikely (cr->status))
		1220	return;
		1221
3959	Serge	1222	status = cr->backend->scale (cr, sx, sy);
1892	serge	1223	if (unlikely (status))
		1224	_cairo_set_error (cr, status);
		1225	}
		1226	slim_hidden_def (cairo_scale);
		1227
		1228	/**
		1229	* cairo_rotate:
		1230	* @cr: a cairo context
		1231	* @angle: angle (in radians) by which the user-space axes will be
		1232	* rotated
		1233	*
		1234	* Modifies the current transformation matrix (CTM) by rotating the
		1235	* user-space axes by @angle radians. The rotation of the axes takes
		1236	* places after any existing transformation of user space. The
		1237	* rotation direction for positive angles is from the positive X axis
		1238	* toward the positive Y axis.
3959	Serge	1239	*
		1240	* Since: 1.0
1892	serge	1241	**/
		1242	void
		1243	cairo_rotate (cairo_t *cr, double angle)
		1244	{
		1245	cairo_status_t status;
		1246
		1247	if (unlikely (cr->status))
		1248	return;
		1249
3959	Serge	1250	status = cr->backend->rotate (cr, angle);
1892	serge	1251	if (unlikely (status))
		1252	_cairo_set_error (cr, status);
		1253	}
		1254
		1255	/**
		1256	* cairo_transform:
		1257	* @cr: a cairo context
		1258	* @matrix: a transformation to be applied to the user-space axes
		1259	*
		1260	* Modifies the current transformation matrix (CTM) by applying
		1261	* @matrix as an additional transformation. The new transformation of
		1262	* user space takes place after any existing transformation.
3959	Serge	1263	*
		1264	* Since: 1.0
1892	serge	1265	**/
		1266	void
		1267	cairo_transform (cairo_t *cr,
		1268	const cairo_matrix_t *matrix)
		1269	{
		1270	cairo_status_t status;
		1271
		1272	if (unlikely (cr->status))
		1273	return;
		1274
3959	Serge	1275	status = cr->backend->transform (cr, matrix);
1892	serge	1276	if (unlikely (status))
		1277	_cairo_set_error (cr, status);
		1278	}
		1279	slim_hidden_def (cairo_transform);
		1280
		1281	/**
		1282	* cairo_set_matrix:
		1283	* @cr: a cairo context
		1284	* @matrix: a transformation matrix from user space to device space
		1285	*
		1286	* Modifies the current transformation matrix (CTM) by setting it
		1287	* equal to @matrix.
3959	Serge	1288	*
		1289	* Since: 1.0
1892	serge	1290	**/
		1291	void
		1292	cairo_set_matrix (cairo_t *cr,
		1293	const cairo_matrix_t *matrix)
		1294	{
		1295	cairo_status_t status;
		1296
		1297	if (unlikely (cr->status))
		1298	return;
		1299
3959	Serge	1300	status = cr->backend->set_matrix (cr, matrix);
1892	serge	1301	if (unlikely (status))
		1302	_cairo_set_error (cr, status);
		1303	}
		1304	slim_hidden_def (cairo_set_matrix);
		1305
		1306	/**
		1307	* cairo_identity_matrix:
		1308	* @cr: a cairo context
		1309	*
		1310	* Resets the current transformation matrix (CTM) by setting it equal
		1311	* to the identity matrix. That is, the user-space and device-space
		1312	* axes will be aligned and one user-space unit will transform to one
		1313	* device-space unit.
3959	Serge	1314	*
		1315	* Since: 1.0
1892	serge	1316	**/
		1317	void
		1318	cairo_identity_matrix (cairo_t *cr)
		1319	{
3959	Serge	1320	cairo_status_t status;
		1321
1892	serge	1322	if (unlikely (cr->status))
		1323	return;
		1324
3959	Serge	1325	status = cr->backend->set_identity_matrix (cr);
		1326	if (unlikely (status))
		1327	_cairo_set_error (cr, status);
1892	serge	1328	}
		1329
		1330	/**
		1331	* cairo_user_to_device:
		1332	* @cr: a cairo context
		1333	* @x: X value of coordinate (in/out parameter)
		1334	* @y: Y value of coordinate (in/out parameter)
		1335	*
		1336	* Transform a coordinate from user space to device space by
		1337	* multiplying the given point by the current transformation matrix
		1338	* (CTM).
3959	Serge	1339	*
		1340	* Since: 1.0
1892	serge	1341	**/
		1342	void
		1343	cairo_user_to_device (cairo_t cr, double x, double *y)
		1344	{
		1345	if (unlikely (cr->status))
		1346	return;
		1347
3959	Serge	1348	cr->backend->user_to_device (cr, x, y);
1892	serge	1349	}
		1350	slim_hidden_def (cairo_user_to_device);
		1351
		1352	/**
		1353	* cairo_user_to_device_distance:
		1354	* @cr: a cairo context
		1355	* @dx: X component of a distance vector (in/out parameter)
		1356	* @dy: Y component of a distance vector (in/out parameter)
		1357	*
		1358	* Transform a distance vector from user space to device space. This
		1359	* function is similar to cairo_user_to_device() except that the
		1360	* translation components of the CTM will be ignored when transforming
		1361	* (@dx,@dy).
3959	Serge	1362	*
		1363	* Since: 1.0
1892	serge	1364	**/
		1365	void
		1366	cairo_user_to_device_distance (cairo_t cr, double dx, double *dy)
		1367	{
		1368	if (unlikely (cr->status))
		1369	return;
		1370
3959	Serge	1371	cr->backend->user_to_device_distance (cr, dx, dy);
1892	serge	1372	}
		1373	slim_hidden_def (cairo_user_to_device_distance);
		1374
		1375	/**
		1376	* cairo_device_to_user:
		1377	* @cr: a cairo
		1378	* @x: X value of coordinate (in/out parameter)
		1379	* @y: Y value of coordinate (in/out parameter)
		1380	*
		1381	* Transform a coordinate from device space to user space by
		1382	* multiplying the given point by the inverse of the current
		1383	* transformation matrix (CTM).
3959	Serge	1384	*
		1385	* Since: 1.0
1892	serge	1386	**/
		1387	void
		1388	cairo_device_to_user (cairo_t cr, double x, double *y)
		1389	{
		1390	if (unlikely (cr->status))
		1391	return;
		1392
3959	Serge	1393	cr->backend->device_to_user (cr, x, y);
1892	serge	1394	}
3959	Serge	1395	slim_hidden_def (cairo_device_to_user);
1892	serge	1396
		1397	/**
		1398	* cairo_device_to_user_distance:
		1399	* @cr: a cairo context
		1400	* @dx: X component of a distance vector (in/out parameter)
		1401	* @dy: Y component of a distance vector (in/out parameter)
		1402	*
		1403	* Transform a distance vector from device space to user space. This
		1404	* function is similar to cairo_device_to_user() except that the
		1405	* translation components of the inverse CTM will be ignored when
		1406	* transforming (@dx,@dy).
3959	Serge	1407	*
		1408	* Since: 1.0
1892	serge	1409	**/
		1410	void
		1411	cairo_device_to_user_distance (cairo_t cr, double dx, double *dy)
		1412	{
		1413	if (unlikely (cr->status))
		1414	return;
		1415
3959	Serge	1416	cr->backend->device_to_user_distance (cr, dx, dy);
1892	serge	1417	}
		1418
		1419	/**
		1420	* cairo_new_path:
		1421	* @cr: a cairo context
		1422	*
		1423	* Clears the current path. After this call there will be no path and
		1424	* no current point.
3959	Serge	1425	*
		1426	* Since: 1.0
1892	serge	1427	**/
		1428	void
		1429	cairo_new_path (cairo_t *cr)
		1430	{
		1431	cairo_status_t status;
		1432
		1433	if (unlikely (cr->status))
		1434	return;
		1435
3959	Serge	1436	status = cr->backend->new_path (cr);
1892	serge	1437	if (unlikely (status))
		1438	_cairo_set_error (cr, status);
		1439	}
3959	Serge	1440	slim_hidden_def(cairo_new_path);
1892	serge	1441
		1442	/**
		1443	* cairo_new_sub_path:
		1444	* @cr: a cairo context
		1445	*
		1446	* Begin a new sub-path. Note that the existing path is not
		1447	* affected. After this call there will be no current point.
		1448	*
		1449	* In many cases, this call is not needed since new sub-paths are
		1450	* frequently started with cairo_move_to().
		1451	*
		1452	* A call to cairo_new_sub_path() is particularly useful when
		1453	* beginning a new sub-path with one of the cairo_arc() calls. This
		1454	* makes things easier as it is no longer necessary to manually
		1455	* compute the arc's initial coordinates for a call to
		1456	* cairo_move_to().
		1457	*
		1458	* Since: 1.2
		1459	**/
		1460	void
		1461	cairo_new_sub_path (cairo_t *cr)
		1462	{
3959	Serge	1463	cairo_status_t status;
		1464
1892	serge	1465	if (unlikely (cr->status))
		1466	return;
		1467
3959	Serge	1468	status = cr->backend->new_sub_path (cr);
		1469	if (unlikely (status))
		1470	_cairo_set_error (cr, status);
1892	serge	1471	}
		1472
		1473	/**
3959	Serge	1474	* cairo_move_to:
		1475	* @cr: a cairo context
		1476	* @x: the X coordinate of the new position
		1477	* @y: the Y coordinate of the new position
		1478	*
		1479	* Begin a new sub-path. After this call the current point will be (@x,
		1480	* @y).
		1481	*
		1482	* Since: 1.0
		1483	**/
		1484	void
		1485	cairo_move_to (cairo_t *cr, double x, double y)
		1486	{
		1487	cairo_status_t status;
		1488
		1489	if (unlikely (cr->status))
		1490	return;
		1491
		1492	status = cr->backend->move_to (cr, x, y);
		1493	if (unlikely (status))
		1494	_cairo_set_error (cr, status);
		1495	}
		1496	slim_hidden_def(cairo_move_to);
		1497
		1498
		1499	/**
1892	serge	1500	* cairo_line_to:
		1501	* @cr: a cairo context
		1502	* @x: the X coordinate of the end of the new line
		1503	* @y: the Y coordinate of the end of the new line
		1504	*
		1505	* Adds a line to the path from the current point to position (@x, @y)
		1506	* in user-space coordinates. After this call the current point
		1507	* will be (@x, @y).
		1508	*
		1509	* If there is no current point before the call to cairo_line_to()
		1510	* this function will behave as cairo_move_to(@cr, @x, @y).
3959	Serge	1511	*
		1512	* Since: 1.0
1892	serge	1513	**/
		1514	void
		1515	cairo_line_to (cairo_t *cr, double x, double y)
		1516	{
		1517	cairo_status_t status;
		1518
		1519	if (unlikely (cr->status))
		1520	return;
		1521
3959	Serge	1522	status = cr->backend->line_to (cr, x, y);
1892	serge	1523	if (unlikely (status))
		1524	_cairo_set_error (cr, status);
		1525	}
		1526	slim_hidden_def (cairo_line_to);
		1527
		1528	/**
		1529	* cairo_curve_to:
		1530	* @cr: a cairo context
		1531	* @x1: the X coordinate of the first control point
		1532	* @y1: the Y coordinate of the first control point
		1533	* @x2: the X coordinate of the second control point
		1534	* @y2: the Y coordinate of the second control point
		1535	* @x3: the X coordinate of the end of the curve
		1536	* @y3: the Y coordinate of the end of the curve
		1537	*
		1538	* Adds a cubic Bézier spline to the path from the current point to
		1539	* position (@x3, @y3) in user-space coordinates, using (@x1, @y1) and
		1540	* (@x2, @y2) as the control points. After this call the current point
		1541	* will be (@x3, @y3).
		1542	*
		1543	* If there is no current point before the call to cairo_curve_to()
		1544	* this function will behave as if preceded by a call to
		1545	* cairo_move_to(@cr, @x1, @y1).
3959	Serge	1546	*
		1547	* Since: 1.0
1892	serge	1548	**/
		1549	void
		1550	cairo_curve_to (cairo_t *cr,
		1551	double x1, double y1,
		1552	double x2, double y2,
		1553	double x3, double y3)
		1554	{
		1555	cairo_status_t status;
		1556
		1557	if (unlikely (cr->status))
		1558	return;
		1559
3959	Serge	1560	status = cr->backend->curve_to (cr,
		1561	x1, y1,
		1562	x2, y2,
		1563	x3, y3);
1892	serge	1564	if (unlikely (status))
		1565	_cairo_set_error (cr, status);
		1566	}
		1567	slim_hidden_def (cairo_curve_to);
		1568
		1569	/**
		1570	* cairo_arc:
		1571	* @cr: a cairo context
		1572	* @xc: X position of the center of the arc
		1573	* @yc: Y position of the center of the arc
		1574	* @radius: the radius of the arc
		1575	* @angle1: the start angle, in radians
		1576	* @angle2: the end angle, in radians
		1577	*
		1578	* Adds a circular arc of the given @radius to the current path. The
		1579	* arc is centered at (@xc, @yc), begins at @angle1 and proceeds in
		1580	* the direction of increasing angles to end at @angle2. If @angle2 is
3959	Serge	1581	* less than @angle1 it will be progressively increased by
		1582	* 2*M_PI until it is greater than @angle1.
1892	serge	1583	*
		1584	* If there is a current point, an initial line segment will be added
		1585	* to the path to connect the current point to the beginning of the
		1586	* arc. If this initial line is undesired, it can be avoided by
		1587	* calling cairo_new_sub_path() before calling cairo_arc().
		1588	*
		1589	* Angles are measured in radians. An angle of 0.0 is in the direction
3959	Serge	1590	* of the positive X axis (in user space). An angle of
		1591	* M_PI/2.0 radians (90 degrees) is in the
		1592	* direction of the positive Y axis (in user space). Angles increase
		1593	* in the direction from the positive X axis toward the positive Y
		1594	* axis. So with the default transformation matrix, angles increase in
		1595	* a clockwise direction.
1892	serge	1596	*
		1597	* (To convert from degrees to radians, use degrees * (M_PI /
		1598	* 180.).)
		1599	*
		1600	* This function gives the arc in the direction of increasing angles;
		1601	* see cairo_arc_negative() to get the arc in the direction of
		1602	* decreasing angles.
		1603	*
		1604	* The arc is circular in user space. To achieve an elliptical arc,
		1605	* you can scale the current transformation matrix by different
		1606	* amounts in the X and Y directions. For example, to draw an ellipse
		1607	* in the box given by @x, @y, @width, @height:
		1608	*
		1609	*
		1610	* cairo_save (cr);
		1611	* cairo_translate (cr, x + width / 2., y + height / 2.);
		1612	* cairo_scale (cr, width / 2., height / 2.);
		1613	* cairo_arc (cr, 0., 0., 1., 0., 2 * M_PI);
		1614	* cairo_restore (cr);
		1615	*
3959	Serge	1616	*
		1617	* Since: 1.0
1892	serge	1618	**/
		1619	void
		1620	cairo_arc (cairo_t *cr,
		1621	double xc, double yc,
		1622	double radius,
		1623	double angle1, double angle2)
		1624	{
3959	Serge	1625	cairo_status_t status;
		1626
1892	serge	1627	if (unlikely (cr->status))
		1628	return;
		1629
3959	Serge	1630	if (angle2 < angle1) {
		1631	/* increase angle2 by multiples of full circle until it
		1632	* satisfies angle2 >= angle1 */
		1633	angle2 = fmod (angle2 - angle1, 2 * M_PI);
		1634	if (angle2 < 0)
		1635	angle2 += 2 * M_PI;
		1636	angle2 += angle1;
1892	serge	1637	}
		1638
3959	Serge	1639	status = cr->backend->arc (cr, xc, yc, radius, angle1, angle2, TRUE);
		1640	if (unlikely (status))
		1641	_cairo_set_error (cr, status);
1892	serge	1642	}
		1643
		1644	/**
		1645	* cairo_arc_negative:
		1646	* @cr: a cairo context
		1647	* @xc: X position of the center of the arc
		1648	* @yc: Y position of the center of the arc
		1649	* @radius: the radius of the arc
		1650	* @angle1: the start angle, in radians
		1651	* @angle2: the end angle, in radians
		1652	*
		1653	* Adds a circular arc of the given @radius to the current path. The
		1654	* arc is centered at (@xc, @yc), begins at @angle1 and proceeds in
		1655	* the direction of decreasing angles to end at @angle2. If @angle2 is
3959	Serge	1656	* greater than @angle1 it will be progressively decreased by
		1657	* 2*M_PI until it is less than @angle1.
1892	serge	1658	*
		1659	* See cairo_arc() for more details. This function differs only in the
		1660	* direction of the arc between the two angles.
3959	Serge	1661	*
		1662	* Since: 1.0
1892	serge	1663	**/
		1664	void
		1665	cairo_arc_negative (cairo_t *cr,
		1666	double xc, double yc,
		1667	double radius,
		1668	double angle1, double angle2)
		1669	{
3959	Serge	1670	cairo_status_t status;
		1671
1892	serge	1672	if (unlikely (cr->status))
		1673	return;
		1674
3959	Serge	1675	if (angle2 > angle1) {
		1676	/* decrease angle2 by multiples of full circle until it
		1677	* satisfies angle2 <= angle1 */
		1678	angle2 = fmod (angle2 - angle1, 2 * M_PI);
		1679	if (angle2 > 0)
		1680	angle2 -= 2 * M_PI;
		1681	angle2 += angle1;
		1682	}
1892	serge	1683
3959	Serge	1684	status = cr->backend->arc (cr, xc, yc, radius, angle1, angle2, FALSE);
		1685	if (unlikely (status))
		1686	_cairo_set_error (cr, status);
1892	serge	1687	}
		1688
		1689	/* XXX: NYI
		1690	void
		1691	cairo_arc_to (cairo_t *cr,
		1692	double x1, double y1,
		1693	double x2, double y2,
		1694	double radius)
		1695	{
		1696	cairo_status_t status;
		1697
		1698	if (unlikely (cr->status))
		1699	return;
		1700
3959	Serge	1701	status = cr->backend->arc_to (cr, x1, y1, x2, y2, radius);
1892	serge	1702	if (unlikely (status))
		1703	_cairo_set_error (cr, status);
		1704	}
3959	Serge	1705
		1706	void
		1707	cairo_rel_arc_to (cairo_t *cr,
		1708	double dx1, double dy1,
		1709	double dx2, double dy2,
		1710	double radius)
		1711	{
		1712	cairo_status_t status;
		1713
		1714	if (unlikely (cr->status))
		1715	return;
		1716
		1717	status = cr->backend->rel_arc_to (cr, dx1, dy1, dx2, dy2, radius);
		1718	if (unlikely (status))
		1719	_cairo_set_error (cr, status);
		1720	}
1892	serge	1721	*/
		1722
		1723	/**
		1724	* cairo_rel_move_to:
		1725	* @cr: a cairo context
		1726	* @dx: the X offset
		1727	* @dy: the Y offset
		1728	*
		1729	* Begin a new sub-path. After this call the current point will offset
		1730	* by (@x, @y).
		1731	*
		1732	* Given a current point of (x, y), cairo_rel_move_to(@cr, @dx, @dy)
		1733	* is logically equivalent to cairo_move_to(@cr, x + @dx, y + @dy).
		1734	*
		1735	* It is an error to call this function with no current point. Doing
		1736	* so will cause @cr to shutdown with a status of
		1737	* %CAIRO_STATUS_NO_CURRENT_POINT.
3959	Serge	1738	*
		1739	* Since: 1.0
1892	serge	1740	**/
		1741	void
		1742	cairo_rel_move_to (cairo_t *cr, double dx, double dy)
		1743	{
		1744	cairo_status_t status;
		1745
		1746	if (unlikely (cr->status))
		1747	return;
		1748
3959	Serge	1749	status = cr->backend->rel_move_to (cr, dx, dy);
1892	serge	1750	if (unlikely (status))
		1751	_cairo_set_error (cr, status);
		1752	}
		1753
		1754	/**
		1755	* cairo_rel_line_to:
		1756	* @cr: a cairo context
		1757	* @dx: the X offset to the end of the new line
		1758	* @dy: the Y offset to the end of the new line
		1759	*
		1760	* Relative-coordinate version of cairo_line_to(). Adds a line to the
		1761	* path from the current point to a point that is offset from the
		1762	* current point by (@dx, @dy) in user space. After this call the
		1763	* current point will be offset by (@dx, @dy).
		1764	*
		1765	* Given a current point of (x, y), cairo_rel_line_to(@cr, @dx, @dy)
		1766	* is logically equivalent to cairo_line_to(@cr, x + @dx, y + @dy).
		1767	*
		1768	* It is an error to call this function with no current point. Doing
		1769	* so will cause @cr to shutdown with a status of
		1770	* %CAIRO_STATUS_NO_CURRENT_POINT.
3959	Serge	1771	*
		1772	* Since: 1.0
1892	serge	1773	**/
		1774	void
		1775	cairo_rel_line_to (cairo_t *cr, double dx, double dy)
		1776	{
		1777	cairo_status_t status;
		1778
		1779	if (unlikely (cr->status))
		1780	return;
		1781
3959	Serge	1782	status = cr->backend->rel_line_to (cr, dx, dy);
1892	serge	1783	if (unlikely (status))
		1784	_cairo_set_error (cr, status);
		1785	}
		1786	slim_hidden_def(cairo_rel_line_to);
		1787
		1788	/**
		1789	* cairo_rel_curve_to:
		1790	* @cr: a cairo context
		1791	* @dx1: the X offset to the first control point
		1792	* @dy1: the Y offset to the first control point
		1793	* @dx2: the X offset to the second control point
		1794	* @dy2: the Y offset to the second control point
		1795	* @dx3: the X offset to the end of the curve
		1796	* @dy3: the Y offset to the end of the curve
		1797	*
		1798	* Relative-coordinate version of cairo_curve_to(). All offsets are
		1799	* relative to the current point. Adds a cubic Bézier spline to the
		1800	* path from the current point to a point offset from the current
		1801	* point by (@dx3, @dy3), using points offset by (@dx1, @dy1) and
		1802	* (@dx2, @dy2) as the control points. After this call the current
		1803	* point will be offset by (@dx3, @dy3).
		1804	*
		1805	* Given a current point of (x, y), cairo_rel_curve_to(@cr, @dx1,
		1806	* @dy1, @dx2, @dy2, @dx3, @dy3) is logically equivalent to
		1807	* cairo_curve_to(@cr, x+@dx1, y+@dy1, x+@dx2, y+@dy2, x+@dx3, y+@dy3).
		1808	*
		1809	* It is an error to call this function with no current point. Doing
		1810	* so will cause @cr to shutdown with a status of
		1811	* %CAIRO_STATUS_NO_CURRENT_POINT.
3959	Serge	1812	*
		1813	* Since: 1.0
1892	serge	1814	**/
		1815	void
		1816	cairo_rel_curve_to (cairo_t *cr,
		1817	double dx1, double dy1,
		1818	double dx2, double dy2,
		1819	double dx3, double dy3)
		1820	{
		1821	cairo_status_t status;
		1822
		1823	if (unlikely (cr->status))
		1824	return;
		1825
3959	Serge	1826	status = cr->backend->rel_curve_to (cr,
		1827	dx1, dy1,
		1828	dx2, dy2,
		1829	dx3, dy3);
1892	serge	1830	if (unlikely (status))
		1831	_cairo_set_error (cr, status);
		1832	}
		1833
		1834	/**
		1835	* cairo_rectangle:
		1836	* @cr: a cairo context
		1837	* @x: the X coordinate of the top left corner of the rectangle
		1838	* @y: the Y coordinate to the top left corner of the rectangle
		1839	* @width: the width of the rectangle
		1840	* @height: the height of the rectangle
		1841	*
		1842	* Adds a closed sub-path rectangle of the given size to the current
		1843	* path at position (@x, @y) in user-space coordinates.
		1844	*
		1845	* This function is logically equivalent to:
		1846	*
		1847	* cairo_move_to (cr, x, y);
		1848	* cairo_rel_line_to (cr, width, 0);
		1849	* cairo_rel_line_to (cr, 0, height);
		1850	* cairo_rel_line_to (cr, -width, 0);
		1851	* cairo_close_path (cr);
		1852	*
3959	Serge	1853	*
		1854	* Since: 1.0
1892	serge	1855	**/
		1856	void
		1857	cairo_rectangle (cairo_t *cr,
		1858	double x, double y,
		1859	double width, double height)
		1860	{
3959	Serge	1861	cairo_status_t status;
		1862
1892	serge	1863	if (unlikely (cr->status))
		1864	return;
		1865
3959	Serge	1866	status = cr->backend->rectangle (cr, x, y, width, height);
		1867	if (unlikely (status))
		1868	_cairo_set_error (cr, status);
1892	serge	1869	}
		1870
		1871	#if 0
		1872	/* XXX: NYI */
		1873	void
		1874	cairo_stroke_to_path (cairo_t *cr)
		1875	{
		1876	cairo_status_t status;
		1877
		1878	if (unlikely (cr->status))
		1879	return;
		1880
		1881	/* The code in _cairo_recording_surface_get_path has a poorman's stroke_to_path */
		1882
		1883	status = _cairo_gstate_stroke_path (cr->gstate);
		1884	if (unlikely (status))
		1885	_cairo_set_error (cr, status);
		1886	}
		1887	#endif
		1888
		1889	/**
		1890	* cairo_close_path:
		1891	* @cr: a cairo context
		1892	*
		1893	* Adds a line segment to the path from the current point to the
		1894	* beginning of the current sub-path, (the most recent point passed to
		1895	* cairo_move_to()), and closes this sub-path. After this call the
		1896	* current point will be at the joined endpoint of the sub-path.
		1897	*
		1898	* The behavior of cairo_close_path() is distinct from simply calling
		1899	* cairo_line_to() with the equivalent coordinate in the case of
		1900	* stroking. When a closed sub-path is stroked, there are no caps on
		1901	* the ends of the sub-path. Instead, there is a line join connecting
		1902	* the final and initial segments of the sub-path.
		1903	*
		1904	* If there is no current point before the call to cairo_close_path(),
		1905	* this function will have no effect.
		1906	*
		1907	* Note: As of cairo version 1.2.4 any call to cairo_close_path() will
		1908	* place an explicit MOVE_TO element into the path immediately after
		1909	* the CLOSE_PATH element, (which can be seen in cairo_copy_path() for
		1910	* example). This can simplify path processing in some cases as it may
		1911	* not be necessary to save the "last move_to point" during processing
		1912	* as the MOVE_TO immediately after the CLOSE_PATH will provide that
		1913	* point.
3959	Serge	1914	*
		1915	* Since: 1.0
1892	serge	1916	**/
		1917	void
		1918	cairo_close_path (cairo_t *cr)
		1919	{
		1920	cairo_status_t status;
		1921
		1922	if (unlikely (cr->status))
		1923	return;
		1924
3959	Serge	1925	status = cr->backend->close_path (cr);
1892	serge	1926	if (unlikely (status))
		1927	_cairo_set_error (cr, status);
		1928	}
		1929	slim_hidden_def(cairo_close_path);
		1930
		1931	/**
		1932	* cairo_path_extents:
		1933	* @cr: a cairo context
		1934	* @x1: left of the resulting extents
		1935	* @y1: top of the resulting extents
		1936	* @x2: right of the resulting extents
		1937	* @y2: bottom of the resulting extents
		1938	*
		1939	* Computes a bounding box in user-space coordinates covering the
		1940	* points on the current path. If the current path is empty, returns
		1941	* an empty rectangle ((0,0), (0,0)). Stroke parameters, fill rule,
		1942	* surface dimensions and clipping are not taken into account.
		1943	*
		1944	* Contrast with cairo_fill_extents() and cairo_stroke_extents() which
		1945	* return the extents of only the area that would be "inked" by
		1946	* the corresponding drawing operations.
		1947	*
		1948	* The result of cairo_path_extents() is defined as equivalent to the
		1949	* limit of cairo_stroke_extents() with %CAIRO_LINE_CAP_ROUND as the
		1950	* line width approaches 0.0, (but never reaching the empty-rectangle
		1951	* returned by cairo_stroke_extents() for a line width of 0.0).
		1952	*
		1953	* Specifically, this means that zero-area sub-paths such as
		1954	* cairo_move_to();cairo_line_to() segments, (even degenerate cases
		1955	* where the coordinates to both calls are identical), will be
		1956	* considered as contributing to the extents. However, a lone
		1957	* cairo_move_to() will not contribute to the results of
		1958	* cairo_path_extents().
		1959	*
		1960	* Since: 1.6
		1961	**/
		1962	void
		1963	cairo_path_extents (cairo_t *cr,
		1964	double x1, double y1, double x2, double y2)
		1965	{
		1966	if (unlikely (cr->status)) {
		1967	if (x1)
		1968	*x1 = 0.0;
		1969	if (y1)
		1970	*y1 = 0.0;
		1971	if (x2)
		1972	*x2 = 0.0;
		1973	if (y2)
		1974	*y2 = 0.0;
		1975
		1976	return;
		1977	}
		1978
3959	Serge	1979	cr->backend->path_extents (cr, x1, y1, x2, y2);
1892	serge	1980	}
		1981
		1982	/**
		1983	* cairo_paint:
		1984	* @cr: a cairo context
		1985	*
		1986	* A drawing operator that paints the current source everywhere within
		1987	* the current clip region.
3959	Serge	1988	*
		1989	* Since: 1.0
1892	serge	1990	**/
		1991	void
		1992	cairo_paint (cairo_t *cr)
		1993	{
		1994	cairo_status_t status;
		1995
		1996	if (unlikely (cr->status))
		1997	return;
		1998
3959	Serge	1999	status = cr->backend->paint (cr);
1892	serge	2000	if (unlikely (status))
		2001	_cairo_set_error (cr, status);
		2002	}
		2003	slim_hidden_def (cairo_paint);
		2004
		2005	/**
		2006	* cairo_paint_with_alpha:
		2007	* @cr: a cairo context
		2008	* @alpha: alpha value, between 0 (transparent) and 1 (opaque)
		2009	*
		2010	* A drawing operator that paints the current source everywhere within
		2011	* the current clip region using a mask of constant alpha value
		2012	* @alpha. The effect is similar to cairo_paint(), but the drawing
		2013	* is faded out using the alpha value.
3959	Serge	2014	*
		2015	* Since: 1.0
1892	serge	2016	**/
		2017	void
		2018	cairo_paint_with_alpha (cairo_t *cr,
		2019	double alpha)
		2020	{
		2021	cairo_status_t status;
		2022
		2023	if (unlikely (cr->status))
		2024	return;
		2025
3959	Serge	2026	status = cr->backend->paint_with_alpha (cr, alpha);
1892	serge	2027	if (unlikely (status))
		2028	_cairo_set_error (cr, status);
		2029	}
		2030
		2031	/**
		2032	* cairo_mask:
		2033	* @cr: a cairo context
		2034	* @pattern: a #cairo_pattern_t
		2035	*
		2036	* A drawing operator that paints the current source
		2037	* using the alpha channel of @pattern as a mask. (Opaque
		2038	* areas of @pattern are painted with the source, transparent
		2039	* areas are not painted.)
3959	Serge	2040	*
		2041	* Since: 1.0
		2042	**/
1892	serge	2043	void
		2044	cairo_mask (cairo_t *cr,
		2045	cairo_pattern_t *pattern)
		2046	{
		2047	cairo_status_t status;
		2048
		2049	if (unlikely (cr->status))
		2050	return;
		2051
3959	Serge	2052	if (unlikely (pattern == NULL)) {
1892	serge	2053	_cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
		2054	return;
		2055	}
		2056
3959	Serge	2057	if (unlikely (pattern->status)) {
1892	serge	2058	_cairo_set_error (cr, pattern->status);
		2059	return;
		2060	}
		2061
3959	Serge	2062	status = cr->backend->mask (cr, pattern);
1892	serge	2063	if (unlikely (status))
		2064	_cairo_set_error (cr, status);
		2065	}
		2066	slim_hidden_def (cairo_mask);
		2067
		2068	/**
		2069	* cairo_mask_surface:
		2070	* @cr: a cairo context
		2071	* @surface: a #cairo_surface_t
		2072	* @surface_x: X coordinate at which to place the origin of @surface
		2073	* @surface_y: Y coordinate at which to place the origin of @surface
		2074	*
		2075	* A drawing operator that paints the current source
		2076	* using the alpha channel of @surface as a mask. (Opaque
		2077	* areas of @surface are painted with the source, transparent
		2078	* areas are not painted.)
3959	Serge	2079	*
		2080	* Since: 1.0
		2081	**/
1892	serge	2082	void
		2083	cairo_mask_surface (cairo_t *cr,
		2084	cairo_surface_t *surface,
		2085	double surface_x,
		2086	double surface_y)
		2087	{
		2088	cairo_pattern_t *pattern;
		2089	cairo_matrix_t matrix;
		2090
		2091	if (unlikely (cr->status))
		2092	return;
		2093
		2094	pattern = cairo_pattern_create_for_surface (surface);
		2095
		2096	cairo_matrix_init_translate (&matrix, - surface_x, - surface_y);
		2097	cairo_pattern_set_matrix (pattern, &matrix);
		2098
		2099	cairo_mask (cr, pattern);
		2100
		2101	cairo_pattern_destroy (pattern);
		2102	}
		2103
		2104	/**
		2105	* cairo_stroke:
		2106	* @cr: a cairo context
		2107	*
		2108	* A drawing operator that strokes the current path according to the
		2109	* current line width, line join, line cap, and dash settings. After
		2110	* cairo_stroke(), the current path will be cleared from the cairo
		2111	* context. See cairo_set_line_width(), cairo_set_line_join(),
		2112	* cairo_set_line_cap(), cairo_set_dash(), and
		2113	* cairo_stroke_preserve().
		2114	*
		2115	* Note: Degenerate segments and sub-paths are treated specially and
		2116	* provide a useful result. These can result in two different
		2117	* situations:
		2118	*
		2119	* 1. Zero-length "on" segments set in cairo_set_dash(). If the cap
		2120	* style is %CAIRO_LINE_CAP_ROUND or %CAIRO_LINE_CAP_SQUARE then these
		2121	* segments will be drawn as circular dots or squares respectively. In
		2122	* the case of %CAIRO_LINE_CAP_SQUARE, the orientation of the squares
		2123	* is determined by the direction of the underlying path.
		2124	*
		2125	* 2. A sub-path created by cairo_move_to() followed by either a
		2126	* cairo_close_path() or one or more calls to cairo_line_to() to the
		2127	* same coordinate as the cairo_move_to(). If the cap style is
		2128	* %CAIRO_LINE_CAP_ROUND then these sub-paths will be drawn as circular
		2129	* dots. Note that in the case of %CAIRO_LINE_CAP_SQUARE a degenerate
		2130	* sub-path will not be drawn at all, (since the correct orientation
		2131	* is indeterminate).
		2132	*
		2133	* In no case will a cap style of %CAIRO_LINE_CAP_BUTT cause anything
		2134	* to be drawn in the case of either degenerate segments or sub-paths.
3959	Serge	2135	*
		2136	* Since: 1.0
1892	serge	2137	**/
		2138	void
		2139	cairo_stroke (cairo_t *cr)
		2140	{
3959	Serge	2141	cairo_status_t status;
1892	serge	2142
3959	Serge	2143	if (unlikely (cr->status))
		2144	return;
		2145
		2146	status = cr->backend->stroke (cr);
		2147	if (unlikely (status))
		2148	_cairo_set_error (cr, status);
1892	serge	2149	}
		2150	slim_hidden_def(cairo_stroke);
		2151
		2152	/**
		2153	* cairo_stroke_preserve:
		2154	* @cr: a cairo context
		2155	*
		2156	* A drawing operator that strokes the current path according to the
		2157	* current line width, line join, line cap, and dash settings. Unlike
		2158	* cairo_stroke(), cairo_stroke_preserve() preserves the path within the
		2159	* cairo context.
		2160	*
		2161	* See cairo_set_line_width(), cairo_set_line_join(),
		2162	* cairo_set_line_cap(), cairo_set_dash(), and
		2163	* cairo_stroke_preserve().
3959	Serge	2164	*
		2165	* Since: 1.0
1892	serge	2166	**/
		2167	void
		2168	cairo_stroke_preserve (cairo_t *cr)
		2169	{
		2170	cairo_status_t status;
		2171
		2172	if (unlikely (cr->status))
		2173	return;
		2174
3959	Serge	2175	status = cr->backend->stroke_preserve (cr);
1892	serge	2176	if (unlikely (status))
		2177	_cairo_set_error (cr, status);
		2178	}
		2179	slim_hidden_def(cairo_stroke_preserve);
		2180
		2181	/**
		2182	* cairo_fill:
		2183	* @cr: a cairo context
		2184	*
		2185	* A drawing operator that fills the current path according to the
		2186	* current fill rule, (each sub-path is implicitly closed before being
		2187	* filled). After cairo_fill(), the current path will be cleared from
		2188	* the cairo context. See cairo_set_fill_rule() and
		2189	* cairo_fill_preserve().
3959	Serge	2190	*
		2191	* Since: 1.0
1892	serge	2192	**/
		2193	void
		2194	cairo_fill (cairo_t *cr)
		2195	{
3959	Serge	2196	cairo_status_t status;
1892	serge	2197
3959	Serge	2198	if (unlikely (cr->status))
		2199	return;
		2200
		2201	status = cr->backend->fill (cr);
		2202	if (unlikely (status))
		2203	_cairo_set_error (cr, status);
1892	serge	2204	}
		2205
		2206	/**
		2207	* cairo_fill_preserve:
		2208	* @cr: a cairo context
		2209	*
		2210	* A drawing operator that fills the current path according to the
		2211	* current fill rule, (each sub-path is implicitly closed before being
		2212	* filled). Unlike cairo_fill(), cairo_fill_preserve() preserves the
		2213	* path within the cairo context.
		2214	*
		2215	* See cairo_set_fill_rule() and cairo_fill().
3959	Serge	2216	*
		2217	* Since: 1.0
1892	serge	2218	**/
		2219	void
		2220	cairo_fill_preserve (cairo_t *cr)
		2221	{
		2222	cairo_status_t status;
		2223
		2224	if (unlikely (cr->status))
		2225	return;
		2226
3959	Serge	2227	status = cr->backend->fill_preserve (cr);
1892	serge	2228	if (unlikely (status))
		2229	_cairo_set_error (cr, status);
		2230	}
		2231	slim_hidden_def(cairo_fill_preserve);
		2232
		2233	/**
		2234	* cairo_copy_page:
		2235	* @cr: a cairo context
		2236	*
		2237	* Emits the current page for backends that support multiple pages, but
		2238	* doesn't clear it, so, the contents of the current page will be retained
		2239	* for the next page too. Use cairo_show_page() if you want to get an
		2240	* empty page after the emission.
		2241	*
		2242	* This is a convenience function that simply calls
		2243	* cairo_surface_copy_page() on @cr's target.
3959	Serge	2244	*
		2245	* Since: 1.0
1892	serge	2246	**/
		2247	void
		2248	cairo_copy_page (cairo_t *cr)
		2249	{
		2250	cairo_status_t status;
		2251
		2252	if (unlikely (cr->status))
		2253	return;
		2254
3959	Serge	2255	status = cr->backend->copy_page (cr);
1892	serge	2256	if (unlikely (status))
		2257	_cairo_set_error (cr, status);
		2258	}
		2259
		2260	/**
		2261	* cairo_show_page:
		2262	* @cr: a cairo context
		2263	*
		2264	* Emits and clears the current page for backends that support multiple
		2265	* pages. Use cairo_copy_page() if you don't want to clear the page.
		2266	*
		2267	* This is a convenience function that simply calls
		2268	* cairo_surface_show_page() on @cr's target.
3959	Serge	2269	*
		2270	* Since: 1.0
1892	serge	2271	**/
		2272	void
		2273	cairo_show_page (cairo_t *cr)
		2274	{
		2275	cairo_status_t status;
		2276
		2277	if (unlikely (cr->status))
		2278	return;
		2279
3959	Serge	2280	status = cr->backend->show_page (cr);
1892	serge	2281	if (unlikely (status))
		2282	_cairo_set_error (cr, status);
		2283	}
		2284
		2285	/**
		2286	* cairo_in_stroke:
		2287	* @cr: a cairo context
		2288	* @x: X coordinate of the point to test
		2289	* @y: Y coordinate of the point to test
		2290	*
		2291	* Tests whether the given point is inside the area that would be
		2292	* affected by a cairo_stroke() operation given the current path and
		2293	* stroking parameters. Surface dimensions and clipping are not taken
		2294	* into account.
		2295	*
		2296	* See cairo_stroke(), cairo_set_line_width(), cairo_set_line_join(),
		2297	* cairo_set_line_cap(), cairo_set_dash(), and
		2298	* cairo_stroke_preserve().
		2299	*
		2300	* Return value: A non-zero value if the point is inside, or zero if
		2301	* outside.
3959	Serge	2302	*
		2303	* Since: 1.0
1892	serge	2304	**/
		2305	cairo_bool_t
		2306	cairo_in_stroke (cairo_t *cr, double x, double y)
		2307	{
		2308	cairo_status_t status;
		2309	cairo_bool_t inside = FALSE;
		2310
		2311	if (unlikely (cr->status))
		2312	return FALSE;
		2313
3959	Serge	2314	status = cr->backend->in_stroke (cr, x, y, &inside);
1892	serge	2315	if (unlikely (status))
		2316	_cairo_set_error (cr, status);
		2317
		2318	return inside;
		2319	}
		2320
		2321	/**
		2322	* cairo_in_fill:
		2323	* @cr: a cairo context
		2324	* @x: X coordinate of the point to test
		2325	* @y: Y coordinate of the point to test
		2326	*
		2327	* Tests whether the given point is inside the area that would be
		2328	* affected by a cairo_fill() operation given the current path and
		2329	* filling parameters. Surface dimensions and clipping are not taken
		2330	* into account.
		2331	*
		2332	* See cairo_fill(), cairo_set_fill_rule() and cairo_fill_preserve().
		2333	*
		2334	* Return value: A non-zero value if the point is inside, or zero if
		2335	* outside.
3959	Serge	2336	*
		2337	* Since: 1.0
1892	serge	2338	**/
		2339	cairo_bool_t
		2340	cairo_in_fill (cairo_t *cr, double x, double y)
		2341	{
3959	Serge	2342	cairo_status_t status;
		2343	cairo_bool_t inside = FALSE;
		2344
1892	serge	2345	if (unlikely (cr->status))
		2346	return FALSE;
		2347
3959	Serge	2348	status = cr->backend->in_fill (cr, x, y, &inside);
		2349	if (unlikely (status))
		2350	_cairo_set_error (cr, status);
		2351
		2352	return inside;
1892	serge	2353	}
		2354
		2355	/**
		2356	* cairo_stroke_extents:
		2357	* @cr: a cairo context
		2358	* @x1: left of the resulting extents
		2359	* @y1: top of the resulting extents
		2360	* @x2: right of the resulting extents
		2361	* @y2: bottom of the resulting extents
		2362	*
		2363	* Computes a bounding box in user coordinates covering the area that
		2364	* would be affected, (the "inked" area), by a cairo_stroke()
		2365	* operation given the current path and stroke parameters.
		2366	* If the current path is empty, returns an empty rectangle ((0,0), (0,0)).
		2367	* Surface dimensions and clipping are not taken into account.
		2368	*
		2369	* Note that if the line width is set to exactly zero, then
		2370	* cairo_stroke_extents() will return an empty rectangle. Contrast with
		2371	* cairo_path_extents() which can be used to compute the non-empty
		2372	* bounds as the line width approaches zero.
		2373	*
		2374	* Note that cairo_stroke_extents() must necessarily do more work to
		2375	* compute the precise inked areas in light of the stroke parameters,
		2376	* so cairo_path_extents() may be more desirable for sake of
		2377	* performance if non-inked path extents are desired.
		2378	*
		2379	* See cairo_stroke(), cairo_set_line_width(), cairo_set_line_join(),
		2380	* cairo_set_line_cap(), cairo_set_dash(), and
		2381	* cairo_stroke_preserve().
3959	Serge	2382	*
		2383	* Since: 1.0
1892	serge	2384	**/
		2385	void
		2386	cairo_stroke_extents (cairo_t *cr,
		2387	double x1, double y1, double x2, double y2)
		2388	{
		2389	cairo_status_t status;
		2390
		2391	if (unlikely (cr->status)) {
		2392	if (x1)
		2393	*x1 = 0.0;
		2394	if (y1)
		2395	*y1 = 0.0;
		2396	if (x2)
		2397	*x2 = 0.0;
		2398	if (y2)
		2399	*y2 = 0.0;
		2400
		2401	return;
		2402	}
		2403
3959	Serge	2404	status = cr->backend->stroke_extents (cr, x1, y1, x2, y2);
1892	serge	2405	if (unlikely (status))
		2406	_cairo_set_error (cr, status);
		2407	}
		2408
		2409	/**
		2410	* cairo_fill_extents:
		2411	* @cr: a cairo context
		2412	* @x1: left of the resulting extents
		2413	* @y1: top of the resulting extents
		2414	* @x2: right of the resulting extents
		2415	* @y2: bottom of the resulting extents
		2416	*
		2417	* Computes a bounding box in user coordinates covering the area that
		2418	* would be affected, (the "inked" area), by a cairo_fill() operation
		2419	* given the current path and fill parameters. If the current path is
		2420	* empty, returns an empty rectangle ((0,0), (0,0)). Surface
		2421	* dimensions and clipping are not taken into account.
		2422	*
		2423	* Contrast with cairo_path_extents(), which is similar, but returns
		2424	* non-zero extents for some paths with no inked area, (such as a
		2425	* simple line segment).
		2426	*
		2427	* Note that cairo_fill_extents() must necessarily do more work to
		2428	* compute the precise inked areas in light of the fill rule, so
		2429	* cairo_path_extents() may be more desirable for sake of performance
		2430	* if the non-inked path extents are desired.
		2431	*
		2432	* See cairo_fill(), cairo_set_fill_rule() and cairo_fill_preserve().
3959	Serge	2433	*
		2434	* Since: 1.0
1892	serge	2435	**/
		2436	void
		2437	cairo_fill_extents (cairo_t *cr,
		2438	double x1, double y1, double x2, double y2)
		2439	{
		2440	cairo_status_t status;
		2441
		2442	if (unlikely (cr->status)) {
		2443	if (x1)
		2444	*x1 = 0.0;
		2445	if (y1)
		2446	*y1 = 0.0;
		2447	if (x2)
		2448	*x2 = 0.0;
		2449	if (y2)
		2450	*y2 = 0.0;
		2451
		2452	return;
		2453	}
		2454
3959	Serge	2455	status = cr->backend->fill_extents (cr, x1, y1, x2, y2);
1892	serge	2456	if (unlikely (status))
		2457	_cairo_set_error (cr, status);
		2458	}
		2459
		2460	/**
		2461	* cairo_clip:
		2462	* @cr: a cairo context
		2463	*
		2464	* Establishes a new clip region by intersecting the current clip
		2465	* region with the current path as it would be filled by cairo_fill()
		2466	* and according to the current fill rule (see cairo_set_fill_rule()).
		2467	*
		2468	* After cairo_clip(), the current path will be cleared from the cairo
		2469	* context.
		2470	*
		2471	* The current clip region affects all drawing operations by
		2472	* effectively masking out any changes to the surface that are outside
		2473	* the current clip region.
		2474	*
		2475	* Calling cairo_clip() can only make the clip region smaller, never
		2476	* larger. But the current clip is part of the graphics state, so a
		2477	* temporary restriction of the clip region can be achieved by
		2478	* calling cairo_clip() within a cairo_save()/cairo_restore()
		2479	* pair. The only other means of increasing the size of the clip
		2480	* region is cairo_reset_clip().
3959	Serge	2481	*
		2482	* Since: 1.0
1892	serge	2483	**/
		2484	void
		2485	cairo_clip (cairo_t *cr)
		2486	{
3959	Serge	2487	cairo_status_t status;
1892	serge	2488
3959	Serge	2489	if (unlikely (cr->status))
		2490	return;
		2491
		2492	status = cr->backend->clip (cr);
		2493	if (unlikely (status))
		2494	_cairo_set_error (cr, status);
1892	serge	2495	}
		2496
		2497	/**
		2498	* cairo_clip_preserve:
		2499	* @cr: a cairo context
		2500	*
		2501	* Establishes a new clip region by intersecting the current clip
		2502	* region with the current path as it would be filled by cairo_fill()
		2503	* and according to the current fill rule (see cairo_set_fill_rule()).
		2504	*
		2505	* Unlike cairo_clip(), cairo_clip_preserve() preserves the path within
		2506	* the cairo context.
		2507	*
		2508	* The current clip region affects all drawing operations by
		2509	* effectively masking out any changes to the surface that are outside
		2510	* the current clip region.
		2511	*
		2512	* Calling cairo_clip_preserve() can only make the clip region smaller, never
		2513	* larger. But the current clip is part of the graphics state, so a
		2514	* temporary restriction of the clip region can be achieved by
		2515	* calling cairo_clip_preserve() within a cairo_save()/cairo_restore()
		2516	* pair. The only other means of increasing the size of the clip
		2517	* region is cairo_reset_clip().
3959	Serge	2518	*
		2519	* Since: 1.0
1892	serge	2520	**/
		2521	void
		2522	cairo_clip_preserve (cairo_t *cr)
		2523	{
		2524	cairo_status_t status;
		2525
		2526	if (unlikely (cr->status))
		2527	return;
		2528
3959	Serge	2529	status = cr->backend->clip_preserve (cr);
1892	serge	2530	if (unlikely (status))
		2531	_cairo_set_error (cr, status);
		2532	}
		2533	slim_hidden_def(cairo_clip_preserve);
		2534
		2535	/**
		2536	* cairo_reset_clip:
		2537	* @cr: a cairo context
		2538	*
		2539	* Reset the current clip region to its original, unrestricted
		2540	* state. That is, set the clip region to an infinitely large shape
		2541	* containing the target surface. Equivalently, if infinity is too
		2542	* hard to grasp, one can imagine the clip region being reset to the
		2543	* exact bounds of the target surface.
		2544	*
		2545	* Note that code meant to be reusable should not call
		2546	* cairo_reset_clip() as it will cause results unexpected by
		2547	* higher-level code which calls cairo_clip(). Consider using
		2548	* cairo_save() and cairo_restore() around cairo_clip() as a more
		2549	* robust means of temporarily restricting the clip region.
3959	Serge	2550	*
		2551	* Since: 1.0
1892	serge	2552	**/
		2553	void
		2554	cairo_reset_clip (cairo_t *cr)
		2555	{
		2556	cairo_status_t status;
		2557
		2558	if (unlikely (cr->status))
		2559	return;
		2560
3959	Serge	2561	status = cr->backend->reset_clip (cr);
1892	serge	2562	if (unlikely (status))
		2563	_cairo_set_error (cr, status);
		2564	}
		2565
		2566	/**
		2567	* cairo_clip_extents:
		2568	* @cr: a cairo context
		2569	* @x1: left of the resulting extents
		2570	* @y1: top of the resulting extents
		2571	* @x2: right of the resulting extents
		2572	* @y2: bottom of the resulting extents
		2573	*
		2574	* Computes a bounding box in user coordinates covering the area inside the
		2575	* current clip.
		2576	*
		2577	* Since: 1.4
		2578	**/
		2579	void
		2580	cairo_clip_extents (cairo_t *cr,
		2581	double x1, double y1,
		2582	double x2, double y2)
		2583	{
3959	Serge	2584	cairo_status_t status;
1892	serge	2585
3959	Serge	2586	if (x1)
		2587	*x1 = 0.0;
		2588	if (y1)
		2589	*y1 = 0.0;
		2590	if (x2)
		2591	*x2 = 0.0;
		2592	if (y2)
		2593	*y2 = 0.0;
		2594
		2595	if (unlikely (cr->status))
1892	serge	2596	return;
		2597
3959	Serge	2598	status = cr->backend->clip_extents (cr, x1, y1, x2, y2);
		2599	if (unlikely (status))
		2600	_cairo_set_error (cr, status);
1892	serge	2601	}
		2602
		2603	/**
		2604	* cairo_in_clip:
		2605	* @cr: a cairo context
		2606	* @x: X coordinate of the point to test
		2607	* @y: Y coordinate of the point to test
		2608	*
		2609	* Tests whether the given point is inside the area that would be
		2610	* visible through the current clip, i.e. the area that would be filled by
		2611	* a cairo_paint() operation.
		2612	*
		2613	* See cairo_clip(), and cairo_clip_preserve().
		2614	*
		2615	* Return value: A non-zero value if the point is inside, or zero if
		2616	* outside.
		2617	*
		2618	* Since: 1.10
		2619	**/
		2620	cairo_bool_t
		2621	cairo_in_clip (cairo_t *cr, double x, double y)
		2622	{
3959	Serge	2623	cairo_status_t status;
		2624	cairo_bool_t inside = FALSE;
		2625
1892	serge	2626	if (unlikely (cr->status))
		2627	return FALSE;
		2628
3959	Serge	2629	status = cr->backend->in_clip (cr, x, y, &inside);
		2630	if (unlikely (status))
		2631	_cairo_set_error (cr, status);
1892	serge	2632
3959	Serge	2633	return inside;
1892	serge	2634	}
		2635
		2636	/**
		2637	* cairo_copy_clip_rectangle_list:
		2638	* @cr: a cairo context
		2639	*
		2640	* Gets the current clip region as a list of rectangles in user coordinates.
		2641	* Never returns %NULL.
		2642	*
		2643	* The status in the list may be %CAIRO_STATUS_CLIP_NOT_REPRESENTABLE to
		2644	* indicate that the clip region cannot be represented as a list of
		2645	* user-space rectangles. The status may have other values to indicate
		2646	* other errors.
		2647	*
		2648	* Returns: the current clip region as a list of rectangles in user coordinates,
		2649	* which should be destroyed using cairo_rectangle_list_destroy().
		2650	*
		2651	* Since: 1.4
		2652	**/
		2653	cairo_rectangle_list_t *
		2654	cairo_copy_clip_rectangle_list (cairo_t *cr)
		2655	{
		2656	if (unlikely (cr->status))
		2657	return _cairo_rectangle_list_create_in_error (cr->status);
		2658
3959	Serge	2659	return cr->backend->clip_copy_rectangle_list (cr);
1892	serge	2660	}
		2661
		2662	/**
		2663	* cairo_select_font_face:
		2664	* @cr: a #cairo_t
		2665	* @family: a font family name, encoded in UTF-8
		2666	* @slant: the slant for the font
		2667	* @weight: the weight for the font
		2668	*
		2669	* Note: The cairo_select_font_face() function call is part of what
		2670	* the cairo designers call the "toy" text API. It is convenient for
		2671	* short demos and simple programs, but it is not expected to be
		2672	* adequate for serious text-using applications.
		2673	*
		2674	* Selects a family and style of font from a simplified description as
		2675	* a family name, slant and weight. Cairo provides no operation to
		2676	* list available family names on the system (this is a "toy",
		2677	* remember), but the standard CSS2 generic family names, ("serif",
		2678	* "sans-serif", "cursive", "fantasy", "monospace"), are likely to
		2679	* work as expected.
		2680	*
		2681	* If @family starts with the string "@cairo:", or if no native font
		2682	* backends are compiled in, cairo will use an internal font family.
		2683	* The internal font family recognizes many modifiers in the @family
		2684	* string, most notably, it recognizes the string "monospace". That is,
		2685	* the family name "@cairo:monospace" will use the monospace version of
		2686	* the internal font family.
		2687	*
		2688	* For "real" font selection, see the font-backend-specific
		2689	* font_face_create functions for the font backend you are using. (For
		2690	* example, if you are using the freetype-based cairo-ft font backend,
		2691	* see cairo_ft_font_face_create_for_ft_face() or
		2692	* cairo_ft_font_face_create_for_pattern().) The resulting font face
		2693	* could then be used with cairo_scaled_font_create() and
		2694	* cairo_set_scaled_font().
		2695	*
		2696	* Similarly, when using the "real" font support, you can call
		2697	* directly into the underlying font system, (such as fontconfig or
		2698	* freetype), for operations such as listing available fonts, etc.
		2699	*
		2700	* It is expected that most applications will need to use a more
		2701	* comprehensive font handling and text layout library, (for example,
		2702	* pango), in conjunction with cairo.
		2703	*
		2704	* If text is drawn without a call to cairo_select_font_face(), (nor
		2705	* cairo_set_font_face() nor cairo_set_scaled_font()), the default
		2706	* family is platform-specific, but is essentially "sans-serif".
		2707	* Default slant is %CAIRO_FONT_SLANT_NORMAL, and default weight is
		2708	* %CAIRO_FONT_WEIGHT_NORMAL.
		2709	*
		2710	* This function is equivalent to a call to cairo_toy_font_face_create()
		2711	* followed by cairo_set_font_face().
3959	Serge	2712	*
		2713	* Since: 1.0
1892	serge	2714	**/
		2715	void
		2716	cairo_select_font_face (cairo_t *cr,
		2717	const char *family,
		2718	cairo_font_slant_t slant,
		2719	cairo_font_weight_t weight)
		2720	{
3959	Serge	2721	cairo_font_face_t *font_face;
1892	serge	2722	cairo_status_t status;
		2723
		2724	if (unlikely (cr->status))
		2725	return;
		2726
3959	Serge	2727	font_face = cairo_toy_font_face_create (family, slant, weight);
		2728	if (unlikely (font_face->status)) {
		2729	_cairo_set_error (cr, font_face->status);
		2730	return;
		2731	}
		2732
		2733	status = cr->backend->set_font_face (cr, font_face);
		2734	cairo_font_face_destroy (font_face);
		2735
1892	serge	2736	if (unlikely (status))
		2737	_cairo_set_error (cr, status);
		2738	}
		2739
		2740	/**
		2741	* cairo_font_extents:
		2742	* @cr: a #cairo_t
		2743	* @extents: a #cairo_font_extents_t object into which the results
		2744	* will be stored.
		2745	*
		2746	* Gets the font extents for the currently selected font.
3959	Serge	2747	*
		2748	* Since: 1.0
1892	serge	2749	**/
		2750	void
		2751	cairo_font_extents (cairo_t *cr,
		2752	cairo_font_extents_t *extents)
		2753	{
		2754	cairo_status_t status;
		2755
		2756	extents->ascent = 0.0;
		2757	extents->descent = 0.0;
		2758	extents->height = 0.0;
		2759	extents->max_x_advance = 0.0;
		2760	extents->max_y_advance = 0.0;
		2761
		2762	if (unlikely (cr->status))
		2763	return;
		2764
3959	Serge	2765	status = cr->backend->font_extents (cr, extents);
1892	serge	2766	if (unlikely (status))
		2767	_cairo_set_error (cr, status);
		2768	}
		2769
		2770	/**
		2771	* cairo_set_font_face:
		2772	* @cr: a #cairo_t
		2773	* @font_face: a #cairo_font_face_t, or %NULL to restore to the default font
		2774	*
		2775	* Replaces the current #cairo_font_face_t object in the #cairo_t with
		2776	* @font_face. The replaced font face in the #cairo_t will be
		2777	* destroyed if there are no other references to it.
3959	Serge	2778	*
		2779	* Since: 1.0
1892	serge	2780	**/
		2781	void
		2782	cairo_set_font_face (cairo_t *cr,
		2783	cairo_font_face_t *font_face)
		2784	{
		2785	cairo_status_t status;
		2786
		2787	if (unlikely (cr->status))
		2788	return;
		2789
3959	Serge	2790	status = cr->backend->set_font_face (cr, font_face);
1892	serge	2791	if (unlikely (status))
		2792	_cairo_set_error (cr, status);
		2793	}
		2794
		2795	/**
		2796	* cairo_get_font_face:
		2797	* @cr: a #cairo_t
		2798	*
		2799	* Gets the current font face for a #cairo_t.
		2800	*
		2801	* Return value: the current font face. This object is owned by
		2802	* cairo. To keep a reference to it, you must call
		2803	* cairo_font_face_reference().
		2804	*
		2805	* This function never returns %NULL. If memory cannot be allocated, a
		2806	* special "nil" #cairo_font_face_t object will be returned on which
		2807	* cairo_font_face_status() returns %CAIRO_STATUS_NO_MEMORY. Using
		2808	* this nil object will cause its error state to propagate to other
		2809	* objects it is passed to, (for example, calling
		2810	* cairo_set_font_face() with a nil font will trigger an error that
		2811	* will shutdown the #cairo_t object).
3959	Serge	2812	*
		2813	* Since: 1.0
1892	serge	2814	**/
		2815	cairo_font_face_t *
		2816	cairo_get_font_face (cairo_t *cr)
		2817	{
		2818	if (unlikely (cr->status))
		2819	return (cairo_font_face_t*) &_cairo_font_face_nil;
		2820
3959	Serge	2821	return cr->backend->get_font_face (cr);
1892	serge	2822	}
		2823
		2824	/**
		2825	* cairo_set_font_size:
		2826	* @cr: a #cairo_t
		2827	* @size: the new font size, in user space units
		2828	*
		2829	* Sets the current font matrix to a scale by a factor of @size, replacing
		2830	* any font matrix previously set with cairo_set_font_size() or
		2831	* cairo_set_font_matrix(). This results in a font size of @size user space
		2832	* units. (More precisely, this matrix will result in the font's
		2833	* em-square being a @size by @size square in user space.)
		2834	*
		2835	* If text is drawn without a call to cairo_set_font_size(), (nor
		2836	* cairo_set_font_matrix() nor cairo_set_scaled_font()), the default
		2837	* font size is 10.0.
3959	Serge	2838	*
		2839	* Since: 1.0
1892	serge	2840	**/
		2841	void
		2842	cairo_set_font_size (cairo_t *cr, double size)
		2843	{
		2844	cairo_status_t status;
		2845
		2846	if (unlikely (cr->status))
		2847	return;
		2848
3959	Serge	2849	status = cr->backend->set_font_size (cr, size);
1892	serge	2850	if (unlikely (status))
		2851	_cairo_set_error (cr, status);
		2852	}
		2853	slim_hidden_def (cairo_set_font_size);
		2854
		2855	/**
3959	Serge	2856	* cairo_set_font_matrix:
1892	serge	2857	* @cr: a #cairo_t
		2858	* @matrix: a #cairo_matrix_t describing a transform to be applied to
		2859	* the current font.
		2860	*
		2861	* Sets the current font matrix to @matrix. The font matrix gives a
		2862	* transformation from the design space of the font (in this space,
		2863	* the em-square is 1 unit by 1 unit) to user space. Normally, a
		2864	* simple scale is used (see cairo_set_font_size()), but a more
		2865	* complex font matrix can be used to shear the font
		2866	* or stretch it unequally along the two axes
3959	Serge	2867	*
		2868	* Since: 1.0
1892	serge	2869	**/
		2870	void
		2871	cairo_set_font_matrix (cairo_t *cr,
		2872	const cairo_matrix_t *matrix)
		2873	{
		2874	cairo_status_t status;
		2875
		2876	if (unlikely (cr->status))
		2877	return;
		2878
3959	Serge	2879	status = cr->backend->set_font_matrix (cr, matrix);
1892	serge	2880	if (unlikely (status))
		2881	_cairo_set_error (cr, status);
		2882	}
3959	Serge	2883	slim_hidden_def (cairo_set_font_matrix);
1892	serge	2884
		2885	/**
3959	Serge	2886	* cairo_get_font_matrix:
1892	serge	2887	* @cr: a #cairo_t
		2888	* @matrix: return value for the matrix
		2889	*
		2890	* Stores the current font matrix into @matrix. See
		2891	* cairo_set_font_matrix().
3959	Serge	2892	*
		2893	* Since: 1.0
1892	serge	2894	**/
		2895	void
		2896	cairo_get_font_matrix (cairo_t cr, cairo_matrix_t matrix)
		2897	{
		2898	if (unlikely (cr->status)) {
		2899	cairo_matrix_init_identity (matrix);
		2900	return;
		2901	}
		2902
3959	Serge	2903	cr->backend->get_font_matrix (cr, matrix);
1892	serge	2904	}
		2905
		2906	/**
		2907	* cairo_set_font_options:
		2908	* @cr: a #cairo_t
		2909	* @options: font options to use
		2910	*
		2911	* Sets a set of custom font rendering options for the #cairo_t.
		2912	* Rendering options are derived by merging these options with the
		2913	* options derived from underlying surface; if the value in @options
		2914	* has a default value (like %CAIRO_ANTIALIAS_DEFAULT), then the value
		2915	* from the surface is used.
3959	Serge	2916	*
		2917	* Since: 1.0
1892	serge	2918	**/
		2919	void
		2920	cairo_set_font_options (cairo_t *cr,
		2921	const cairo_font_options_t *options)
		2922	{
		2923	cairo_status_t status;
		2924
		2925	if (unlikely (cr->status))
		2926	return;
		2927
		2928	status = cairo_font_options_status ((cairo_font_options_t *) options);
		2929	if (unlikely (status)) {
		2930	_cairo_set_error (cr, status);
		2931	return;
		2932	}
		2933
3959	Serge	2934	status = cr->backend->set_font_options (cr, options);
		2935	if (unlikely (status))
		2936	_cairo_set_error (cr, status);
1892	serge	2937	}
		2938	slim_hidden_def (cairo_set_font_options);
		2939
		2940	/**
		2941	* cairo_get_font_options:
		2942	* @cr: a #cairo_t
		2943	* @options: a #cairo_font_options_t object into which to store
		2944	* the retrieved options. All existing values are overwritten
		2945	*
		2946	* Retrieves font rendering options set via #cairo_set_font_options.
		2947	* Note that the returned options do not include any options derived
		2948	* from the underlying surface; they are literally the options
		2949	* passed to cairo_set_font_options().
3959	Serge	2950	*
		2951	* Since: 1.0
1892	serge	2952	**/
		2953	void
		2954	cairo_get_font_options (cairo_t *cr,
		2955	cairo_font_options_t *options)
		2956	{
		2957	/* check that we aren't trying to overwrite the nil object */
		2958	if (cairo_font_options_status (options))
		2959	return;
		2960
		2961	if (unlikely (cr->status)) {
		2962	_cairo_font_options_init_default (options);
		2963	return;
		2964	}
		2965
3959	Serge	2966	cr->backend->get_font_options (cr, options);
1892	serge	2967	}
		2968
		2969	/**
		2970	* cairo_set_scaled_font:
		2971	* @cr: a #cairo_t
		2972	* @scaled_font: a #cairo_scaled_font_t
		2973	*
		2974	* Replaces the current font face, font matrix, and font options in
		2975	* the #cairo_t with those of the #cairo_scaled_font_t. Except for
		2976	* some translation, the current CTM of the #cairo_t should be the
		2977	* same as that of the #cairo_scaled_font_t, which can be accessed
		2978	* using cairo_scaled_font_get_ctm().
		2979	*
		2980	* Since: 1.2
		2981	**/
		2982	void
		2983	cairo_set_scaled_font (cairo_t *cr,
		2984	const cairo_scaled_font_t *scaled_font)
		2985	{
		2986	cairo_status_t status;
		2987
		2988	if (unlikely (cr->status))
		2989	return;
		2990
3959	Serge	2991	if ((scaled_font == NULL)) {
		2992	_cairo_set_error (cr, _cairo_error (CAIRO_STATUS_NULL_POINTER));
		2993	return;
1892	serge	2994	}
		2995
		2996	status = scaled_font->status;
3959	Serge	2997	if (unlikely (status)) {
		2998	_cairo_set_error (cr, status);
1892	serge	2999	return;
3959	Serge	3000	}
1892	serge	3001
3959	Serge	3002	status = cr->backend->set_scaled_font (cr, (cairo_scaled_font_t *) scaled_font);
1892	serge	3003	if (unlikely (status))
3959	Serge	3004	_cairo_set_error (cr, status);
1892	serge	3005	}
		3006
		3007	/**
		3008	* cairo_get_scaled_font:
		3009	* @cr: a #cairo_t
		3010	*
		3011	* Gets the current scaled font for a #cairo_t.
		3012	*
		3013	* Return value: the current scaled font. This object is owned by
		3014	* cairo. To keep a reference to it, you must call
		3015	* cairo_scaled_font_reference().
		3016	*
		3017	* This function never returns %NULL. If memory cannot be allocated, a
		3018	* special "nil" #cairo_scaled_font_t object will be returned on which
		3019	* cairo_scaled_font_status() returns %CAIRO_STATUS_NO_MEMORY. Using
		3020	* this nil object will cause its error state to propagate to other
		3021	* objects it is passed to, (for example, calling
		3022	* cairo_set_scaled_font() with a nil font will trigger an error that
		3023	* will shutdown the #cairo_t object).
		3024	*
		3025	* Since: 1.4
		3026	**/
		3027	cairo_scaled_font_t *
		3028	cairo_get_scaled_font (cairo_t *cr)
		3029	{
		3030	if (unlikely (cr->status))
		3031	return _cairo_scaled_font_create_in_error (cr->status);
		3032
3959	Serge	3033	return cr->backend->get_scaled_font (cr);
1892	serge	3034	}
3959	Serge	3035	slim_hidden_def (cairo_get_scaled_font);
1892	serge	3036
		3037	/**
		3038	* cairo_text_extents:
		3039	* @cr: a #cairo_t
		3040	* @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
		3041	* @extents: a #cairo_text_extents_t object into which the results
		3042	* will be stored
		3043	*
		3044	* Gets the extents for a string of text. The extents describe a
		3045	* user-space rectangle that encloses the "inked" portion of the text,
		3046	* (as it would be drawn by cairo_show_text()). Additionally, the
		3047	* x_advance and y_advance values indicate the amount by which the
		3048	* current point would be advanced by cairo_show_text().
		3049	*
		3050	* Note that whitespace characters do not directly contribute to the
		3051	* size of the rectangle (extents.width and extents.height). They do
		3052	* contribute indirectly by changing the position of non-whitespace
		3053	* characters. In particular, trailing whitespace characters are
		3054	* likely to not affect the size of the rectangle, though they will
		3055	* affect the x_advance and y_advance values.
3959	Serge	3056	*
		3057	* Since: 1.0
1892	serge	3058	**/
		3059	void
		3060	cairo_text_extents (cairo_t *cr,
		3061	const char *utf8,
		3062	cairo_text_extents_t *extents)
		3063	{
		3064	cairo_status_t status;
3959	Serge	3065	cairo_scaled_font_t *scaled_font;
1892	serge	3066	cairo_glyph_t *glyphs = NULL;
3959	Serge	3067	int num_glyphs = 0;
1892	serge	3068	double x, y;
		3069
		3070	extents->x_bearing = 0.0;
		3071	extents->y_bearing = 0.0;
		3072	extents->width = 0.0;
		3073	extents->height = 0.0;
		3074	extents->x_advance = 0.0;
		3075	extents->y_advance = 0.0;
		3076
		3077	if (unlikely (cr->status))
		3078	return;
		3079
		3080	if (utf8 == NULL)
		3081	return;
		3082
3959	Serge	3083	scaled_font = cairo_get_scaled_font (cr);
		3084	if (unlikely (scaled_font->status)) {
		3085	_cairo_set_error (cr, scaled_font->status);
		3086	return;
		3087	}
		3088
1892	serge	3089	cairo_get_current_point (cr, &x, &y);
3959	Serge	3090	status = cairo_scaled_font_text_to_glyphs (scaled_font,
		3091	x, y,
		3092	utf8, -1,
		3093	&glyphs, &num_glyphs,
		3094	NULL, NULL, NULL);
1892	serge	3095
3959	Serge	3096	if (likely (status == CAIRO_STATUS_SUCCESS)) {
		3097	status = cr->backend->glyph_extents (cr,
		3098	glyphs, num_glyphs,
		3099	extents);
		3100	}
1892	serge	3101	cairo_glyph_free (glyphs);
		3102
		3103	if (unlikely (status))
		3104	_cairo_set_error (cr, status);
		3105	}
		3106
		3107	/**
		3108	* cairo_glyph_extents:
		3109	* @cr: a #cairo_t
		3110	* @glyphs: an array of #cairo_glyph_t objects
		3111	* @num_glyphs: the number of elements in @glyphs
		3112	* @extents: a #cairo_text_extents_t object into which the results
		3113	* will be stored
		3114	*
		3115	* Gets the extents for an array of glyphs. The extents describe a
		3116	* user-space rectangle that encloses the "inked" portion of the
		3117	* glyphs, (as they would be drawn by cairo_show_glyphs()).
		3118	* Additionally, the x_advance and y_advance values indicate the
		3119	* amount by which the current point would be advanced by
		3120	* cairo_show_glyphs().
		3121	*
		3122	* Note that whitespace glyphs do not contribute to the size of the
		3123	* rectangle (extents.width and extents.height).
3959	Serge	3124	*
		3125	* Since: 1.0
1892	serge	3126	**/
		3127	void
		3128	cairo_glyph_extents (cairo_t *cr,
		3129	const cairo_glyph_t *glyphs,
		3130	int num_glyphs,
		3131	cairo_text_extents_t *extents)
		3132	{
		3133	cairo_status_t status;
		3134
		3135	extents->x_bearing = 0.0;
		3136	extents->y_bearing = 0.0;
		3137	extents->width = 0.0;
		3138	extents->height = 0.0;
		3139	extents->x_advance = 0.0;
		3140	extents->y_advance = 0.0;
		3141
		3142	if (unlikely (cr->status))
		3143	return;
		3144
		3145	if (num_glyphs == 0)
		3146	return;
		3147
3959	Serge	3148	if (unlikely (num_glyphs < 0)) {
1892	serge	3149	_cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
		3150	return;
		3151	}
		3152
3959	Serge	3153	if (unlikely (glyphs == NULL)) {
1892	serge	3154	_cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
		3155	return;
		3156	}
		3157
3959	Serge	3158	status = cr->backend->glyph_extents (cr, glyphs, num_glyphs, extents);
1892	serge	3159	if (unlikely (status))
		3160	_cairo_set_error (cr, status);
		3161	}
		3162
		3163	/**
		3164	* cairo_show_text:
		3165	* @cr: a cairo context
		3166	* @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
		3167	*
		3168	* A drawing operator that generates the shape from a string of UTF-8
		3169	* characters, rendered according to the current font_face, font_size
		3170	* (font_matrix), and font_options.
		3171	*
		3172	* This function first computes a set of glyphs for the string of
		3173	* text. The first glyph is placed so that its origin is at the
		3174	* current point. The origin of each subsequent glyph is offset from
		3175	* that of the previous glyph by the advance values of the previous
		3176	* glyph.
		3177	*
		3178	* After this call the current point is moved to the origin of where
		3179	* the next glyph would be placed in this same progression. That is,
		3180	* the current point will be at the origin of the final glyph offset
		3181	* by its advance values. This allows for easy display of a single
		3182	* logical string with multiple calls to cairo_show_text().
		3183	*
		3184	* Note: The cairo_show_text() function call is part of what the cairo
		3185	* designers call the "toy" text API. It is convenient for short demos
		3186	* and simple programs, but it is not expected to be adequate for
		3187	* serious text-using applications. See cairo_show_glyphs() for the
		3188	* "real" text display API in cairo.
3959	Serge	3189	*
		3190	* Since: 1.0
1892	serge	3191	**/
		3192	void
		3193	cairo_show_text (cairo_t cr, const char utf8)
		3194	{
		3195	cairo_text_extents_t extents;
		3196	cairo_status_t status;
		3197	cairo_glyph_t glyphs, last_glyph;
		3198	cairo_text_cluster_t *clusters;
		3199	int utf8_len, num_glyphs, num_clusters;
		3200	cairo_text_cluster_flags_t cluster_flags;
		3201	double x, y;
		3202	cairo_bool_t has_show_text_glyphs;
		3203	cairo_glyph_t stack_glyphs[CAIRO_STACK_ARRAY_LENGTH (cairo_glyph_t)];
		3204	cairo_text_cluster_t stack_clusters[CAIRO_STACK_ARRAY_LENGTH (cairo_text_cluster_t)];
3959	Serge	3205	cairo_scaled_font_t *scaled_font;
		3206	cairo_glyph_text_info_t info, *i;
1892	serge	3207
		3208	if (unlikely (cr->status))
		3209	return;
		3210
		3211	if (utf8 == NULL)
		3212	return;
		3213
3959	Serge	3214	scaled_font = cairo_get_scaled_font (cr);
		3215	if (unlikely (scaled_font->status)) {
		3216	_cairo_set_error (cr, scaled_font->status);
		3217	return;
		3218	}
1892	serge	3219
		3220	utf8_len = strlen (utf8);
		3221
		3222	has_show_text_glyphs =
		3223	cairo_surface_has_show_text_glyphs (cairo_get_target (cr));
		3224
		3225	glyphs = stack_glyphs;
		3226	num_glyphs = ARRAY_LENGTH (stack_glyphs);
		3227
		3228	if (has_show_text_glyphs) {
		3229	clusters = stack_clusters;
		3230	num_clusters = ARRAY_LENGTH (stack_clusters);
		3231	} else {
		3232	clusters = NULL;
		3233	num_clusters = 0;
		3234	}
		3235
3959	Serge	3236	cairo_get_current_point (cr, &x, &y);
		3237	status = cairo_scaled_font_text_to_glyphs (scaled_font,
		3238	x, y,
		3239	utf8, utf8_len,
		3240	&glyphs, &num_glyphs,
		3241	has_show_text_glyphs ? &clusters : NULL, &num_clusters,
		3242	&cluster_flags);
1892	serge	3243	if (unlikely (status))
		3244	goto BAIL;
		3245
		3246	if (num_glyphs == 0)
		3247	return;
		3248
3959	Serge	3249	i = NULL;
		3250	if (has_show_text_glyphs) {
		3251	info.utf8 = utf8;
		3252	info.utf8_len = utf8_len;
		3253	info.clusters = clusters;
		3254	info.num_clusters = num_clusters;
		3255	info.cluster_flags = cluster_flags;
		3256	i = &info;
		3257	}
		3258
		3259	status = cr->backend->glyphs (cr, glyphs, num_glyphs, i);
1892	serge	3260	if (unlikely (status))
		3261	goto BAIL;
		3262
		3263	last_glyph = &glyphs[num_glyphs - 1];
3959	Serge	3264	status = cr->backend->glyph_extents (cr, last_glyph, 1, &extents);
1892	serge	3265	if (unlikely (status))
		3266	goto BAIL;
		3267
		3268	x = last_glyph->x + extents.x_advance;
		3269	y = last_glyph->y + extents.y_advance;
3959	Serge	3270	cr->backend->move_to (cr, x, y);
1892	serge	3271
		3272	BAIL:
		3273	if (glyphs != stack_glyphs)
		3274	cairo_glyph_free (glyphs);
		3275	if (clusters != stack_clusters)
		3276	cairo_text_cluster_free (clusters);
		3277
		3278	if (unlikely (status))
		3279	_cairo_set_error (cr, status);
		3280	}
		3281
		3282	/**
		3283	* cairo_show_glyphs:
		3284	* @cr: a cairo context
		3285	* @glyphs: array of glyphs to show
		3286	* @num_glyphs: number of glyphs to show
		3287	*
		3288	* A drawing operator that generates the shape from an array of glyphs,
		3289	* rendered according to the current font face, font size
		3290	* (font matrix), and font options.
3959	Serge	3291	*
		3292	* Since: 1.0
1892	serge	3293	**/
		3294	void
		3295	cairo_show_glyphs (cairo_t cr, const cairo_glyph_t glyphs, int num_glyphs)
		3296	{
		3297	cairo_status_t status;
		3298
		3299	if (unlikely (cr->status))
		3300	return;
		3301
		3302	if (num_glyphs == 0)
		3303	return;
		3304
		3305	if (num_glyphs < 0) {
		3306	_cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
		3307	return;
		3308	}
		3309
		3310	if (glyphs == NULL) {
		3311	_cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
		3312	return;
		3313	}
		3314
3959	Serge	3315	status = cr->backend->glyphs (cr, glyphs, num_glyphs, NULL);
1892	serge	3316	if (unlikely (status))
		3317	_cairo_set_error (cr, status);
		3318	}
		3319
		3320	/**
		3321	* cairo_show_text_glyphs:
		3322	* @cr: a cairo context
		3323	* @utf8: a string of text encoded in UTF-8
		3324	* @utf8_len: length of @utf8 in bytes, or -1 if it is NUL-terminated
		3325	* @glyphs: array of glyphs to show
		3326	* @num_glyphs: number of glyphs to show
		3327	* @clusters: array of cluster mapping information
		3328	* @num_clusters: number of clusters in the mapping
		3329	* @cluster_flags: cluster mapping flags
		3330	*
		3331	* This operation has rendering effects similar to cairo_show_glyphs()
		3332	* but, if the target surface supports it, uses the provided text and
		3333	* cluster mapping to embed the text for the glyphs shown in the output.
		3334	* If the target does not support the extended attributes, this function
		3335	* acts like the basic cairo_show_glyphs() as if it had been passed
		3336	* @glyphs and @num_glyphs.
		3337	*
		3338	* The mapping between @utf8 and @glyphs is provided by an array of
		3339	* clusters. Each cluster covers a number of
		3340	* text bytes and glyphs, and neighboring clusters cover neighboring
		3341	* areas of @utf8 and @glyphs. The clusters should collectively cover @utf8
		3342	* and @glyphs in entirety.
		3343	*
		3344	* The first cluster always covers bytes from the beginning of @utf8.
		3345	* If @cluster_flags do not have the %CAIRO_TEXT_CLUSTER_FLAG_BACKWARD
		3346	* set, the first cluster also covers the beginning
		3347	* of @glyphs, otherwise it covers the end of the @glyphs array and
		3348	* following clusters move backward.
		3349	*
		3350	* See #cairo_text_cluster_t for constraints on valid clusters.
		3351	*
		3352	* Since: 1.8
		3353	**/
		3354	void
		3355	cairo_show_text_glyphs (cairo_t *cr,
		3356	const char *utf8,
		3357	int utf8_len,
		3358	const cairo_glyph_t *glyphs,
		3359	int num_glyphs,
		3360	const cairo_text_cluster_t *clusters,
		3361	int num_clusters,
		3362	cairo_text_cluster_flags_t cluster_flags)
		3363	{
		3364	cairo_status_t status;
		3365
		3366	if (unlikely (cr->status))
		3367	return;
		3368
		3369	/* A slew of sanity checks */
		3370
		3371	/* Special case for NULL and -1 */
		3372	if (utf8 == NULL && utf8_len == -1)
		3373	utf8_len = 0;
		3374
		3375	/* No NULLs for non-zeros */
		3376	if ((num_glyphs && glyphs == NULL) \|\|
		3377	(utf8_len && utf8 == NULL) \|\|
		3378	(num_clusters && clusters == NULL)) {
		3379	_cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
		3380	return;
		3381	}
		3382
		3383	/* A -1 for utf8_len means NUL-terminated */
		3384	if (utf8_len == -1)
		3385	utf8_len = strlen (utf8);
		3386
		3387	/* Apart from that, no negatives */
		3388	if (num_glyphs < 0 \|\| utf8_len < 0 \|\| num_clusters < 0) {
		3389	_cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
		3390	return;
		3391	}
		3392
3959	Serge	3393	if (num_glyphs == 0 && utf8_len == 0)
		3394	return;
1892	serge	3395
3959	Serge	3396	if (utf8) {
		3397	/* Make sure clusters cover the entire glyphs and utf8 arrays,
		3398	* and that cluster boundaries are UTF-8 boundaries. */
		3399	status = _cairo_validate_text_clusters (utf8, utf8_len,
		3400	glyphs, num_glyphs,
		3401	clusters, num_clusters, cluster_flags);
		3402	if (status == CAIRO_STATUS_INVALID_CLUSTERS) {
		3403	/* Either got invalid UTF-8 text, or cluster mapping is bad.
		3404	* Differentiate those. */
1892	serge	3405
3959	Serge	3406	cairo_status_t status2;
1892	serge	3407
3959	Serge	3408	status2 = _cairo_utf8_to_ucs4 (utf8, utf8_len, NULL, NULL);
		3409	if (status2)
		3410	status = status2;
		3411	} else {
		3412	cairo_glyph_text_info_t info;
1892	serge	3413
3959	Serge	3414	info.utf8 = utf8;
		3415	info.utf8_len = utf8_len;
		3416	info.clusters = clusters;
		3417	info.num_clusters = num_clusters;
		3418	info.cluster_flags = cluster_flags;
1892	serge	3419
3959	Serge	3420	status = cr->backend->glyphs (cr, glyphs, num_glyphs, &info);
		3421	}
		3422	} else {
		3423	status = cr->backend->glyphs (cr, glyphs, num_glyphs, NULL);
		3424	}
1892	serge	3425	if (unlikely (status))
		3426	_cairo_set_error (cr, status);
		3427	}
		3428
		3429	/**
		3430	* cairo_text_path:
		3431	* @cr: a cairo context
		3432	* @utf8: a NUL-terminated string of text encoded in UTF-8, or %NULL
		3433	*
		3434	* Adds closed paths for text to the current path. The generated
		3435	* path if filled, achieves an effect similar to that of
		3436	* cairo_show_text().
		3437	*
		3438	* Text conversion and positioning is done similar to cairo_show_text().
		3439	*
		3440	* Like cairo_show_text(), After this call the current point is
		3441	* moved to the origin of where the next glyph would be placed in
		3442	* this same progression. That is, the current point will be at
		3443	* the origin of the final glyph offset by its advance values.
		3444	* This allows for chaining multiple calls to to cairo_text_path()
		3445	* without having to set current point in between.
		3446	*
		3447	* Note: The cairo_text_path() function call is part of what the cairo
		3448	* designers call the "toy" text API. It is convenient for short demos
		3449	* and simple programs, but it is not expected to be adequate for
		3450	* serious text-using applications. See cairo_glyph_path() for the
		3451	* "real" text path API in cairo.
3959	Serge	3452	*
		3453	* Since: 1.0
1892	serge	3454	**/
		3455	void
3959	Serge	3456	cairo_text_path (cairo_t cr, const char utf8)
1892	serge	3457	{
		3458	cairo_status_t status;
		3459	cairo_text_extents_t extents;
		3460	cairo_glyph_t stack_glyphs[CAIRO_STACK_ARRAY_LENGTH (cairo_glyph_t)];
		3461	cairo_glyph_t glyphs, last_glyph;
3959	Serge	3462	cairo_scaled_font_t *scaled_font;
1892	serge	3463	int num_glyphs;
		3464	double x, y;
		3465
		3466	if (unlikely (cr->status))
		3467	return;
		3468
		3469	if (utf8 == NULL)
		3470	return;
		3471
		3472
		3473	glyphs = stack_glyphs;
		3474	num_glyphs = ARRAY_LENGTH (stack_glyphs);
		3475
3959	Serge	3476	scaled_font = cairo_get_scaled_font (cr);
		3477	if (unlikely (scaled_font->status)) {
		3478	_cairo_set_error (cr, scaled_font->status);
		3479	return;
		3480	}
1892	serge	3481
3959	Serge	3482	cairo_get_current_point (cr, &x, &y);
		3483	status = cairo_scaled_font_text_to_glyphs (scaled_font,
		3484	x, y,
		3485	utf8, -1,
		3486	&glyphs, &num_glyphs,
		3487	NULL, NULL, NULL);
1892	serge	3488
		3489	if (num_glyphs == 0)
		3490	return;
		3491
3959	Serge	3492	status = cr->backend->glyph_path (cr, glyphs, num_glyphs);
1892	serge	3493
		3494	if (unlikely (status))
		3495	goto BAIL;
		3496
		3497	last_glyph = &glyphs[num_glyphs - 1];
3959	Serge	3498	status = cr->backend->glyph_extents (cr, last_glyph, 1, &extents);
1892	serge	3499
		3500	if (unlikely (status))
		3501	goto BAIL;
		3502
		3503	x = last_glyph->x + extents.x_advance;
		3504	y = last_glyph->y + extents.y_advance;
3959	Serge	3505	cr->backend->move_to (cr, x, y);
1892	serge	3506
		3507	BAIL:
		3508	if (glyphs != stack_glyphs)
		3509	cairo_glyph_free (glyphs);
		3510
		3511	if (unlikely (status))
		3512	_cairo_set_error (cr, status);
		3513	}
		3514
		3515	/**
		3516	* cairo_glyph_path:
		3517	* @cr: a cairo context
		3518	* @glyphs: array of glyphs to show
		3519	* @num_glyphs: number of glyphs to show
		3520	*
		3521	* Adds closed paths for the glyphs to the current path. The generated
		3522	* path if filled, achieves an effect similar to that of
		3523	* cairo_show_glyphs().
3959	Serge	3524	*
		3525	* Since: 1.0
1892	serge	3526	**/
		3527	void
		3528	cairo_glyph_path (cairo_t cr, const cairo_glyph_t glyphs, int num_glyphs)
		3529	{
		3530	cairo_status_t status;
		3531
		3532	if (unlikely (cr->status))
		3533	return;
		3534
		3535	if (num_glyphs == 0)
		3536	return;
		3537
3959	Serge	3538	if (unlikely (num_glyphs < 0)) {
1892	serge	3539	_cairo_set_error (cr, CAIRO_STATUS_NEGATIVE_COUNT);
		3540	return;
		3541	}
		3542
3959	Serge	3543	if (unlikely (glyphs == NULL)) {
1892	serge	3544	_cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
		3545	return;
		3546	}
		3547
3959	Serge	3548	status = cr->backend->glyph_path (cr, glyphs, num_glyphs);
1892	serge	3549	if (unlikely (status))
		3550	_cairo_set_error (cr, status);
		3551	}
		3552
		3553	/**
		3554	* cairo_get_operator:
		3555	* @cr: a cairo context
		3556	*
		3557	* Gets the current compositing operator for a cairo context.
		3558	*
		3559	* Return value: the current compositing operator.
3959	Serge	3560	*
		3561	* Since: 1.0
1892	serge	3562	**/
		3563	cairo_operator_t
		3564	cairo_get_operator (cairo_t *cr)
		3565	{
		3566	if (unlikely (cr->status))
		3567	return CAIRO_GSTATE_OPERATOR_DEFAULT;
		3568
3959	Serge	3569	return cr->backend->get_operator (cr);
1892	serge	3570	}
		3571
3959	Serge	3572	#if 0
1892	serge	3573	/**
3959	Serge	3574	* cairo_get_opacity:
		3575	* @cr: a cairo context
		3576	*
		3577	* Gets the current compositing opacity for a cairo context.
		3578	*
		3579	* Return value: the current compositing opacity.
		3580	*
		3581	* Since: TBD
		3582	**/
		3583	double
		3584	cairo_get_opacity (cairo_t *cr)
		3585	{
		3586	if (unlikely (cr->status))
		3587	return 1.;
		3588
		3589	return cr->backend->get_opacity (cr);
		3590	}
		3591	#endif
		3592
		3593	/**
1892	serge	3594	* cairo_get_tolerance:
		3595	* @cr: a cairo context
		3596	*
		3597	* Gets the current tolerance value, as set by cairo_set_tolerance().
		3598	*
		3599	* Return value: the current tolerance value.
3959	Serge	3600	*
		3601	* Since: 1.0
1892	serge	3602	**/
		3603	double
		3604	cairo_get_tolerance (cairo_t *cr)
		3605	{
		3606	if (unlikely (cr->status))
		3607	return CAIRO_GSTATE_TOLERANCE_DEFAULT;
		3608
3959	Serge	3609	return cr->backend->get_tolerance (cr);
1892	serge	3610	}
		3611	slim_hidden_def (cairo_get_tolerance);
		3612
		3613	/**
		3614	* cairo_get_antialias:
		3615	* @cr: a cairo context
		3616	*
3959	Serge	3617	* Gets the current shape antialiasing mode, as set by
		3618	* cairo_set_antialias().
1892	serge	3619	*
		3620	* Return value: the current shape antialiasing mode.
3959	Serge	3621	*
		3622	* Since: 1.0
1892	serge	3623	**/
		3624	cairo_antialias_t
		3625	cairo_get_antialias (cairo_t *cr)
		3626	{
		3627	if (unlikely (cr->status))
		3628	return CAIRO_ANTIALIAS_DEFAULT;
		3629
3959	Serge	3630	return cr->backend->get_antialias (cr);
1892	serge	3631	}
		3632
		3633	/**
		3634	* cairo_has_current_point:
		3635	* @cr: a cairo context
		3636	*
		3637	* Returns whether a current point is defined on the current path.
		3638	* See cairo_get_current_point() for details on the current point.
		3639	*
		3640	* Return value: whether a current point is defined.
		3641	*
		3642	* Since: 1.6
		3643	**/
		3644	cairo_bool_t
		3645	cairo_has_current_point (cairo_t *cr)
		3646	{
		3647	if (unlikely (cr->status))
3959	Serge	3648	return FALSE;
1892	serge	3649
3959	Serge	3650	return cr->backend->has_current_point (cr);
1892	serge	3651	}
		3652
		3653	/**
		3654	* cairo_get_current_point:
		3655	* @cr: a cairo context
		3656	* @x: return value for X coordinate of the current point
		3657	* @y: return value for Y coordinate of the current point
		3658	*
		3659	* Gets the current point of the current path, which is
		3660	* conceptually the final point reached by the path so far.
		3661	*
		3662	* The current point is returned in the user-space coordinate
		3663	* system. If there is no defined current point or if @cr is in an
		3664	* error status, @x and @y will both be set to 0.0. It is possible to
		3665	* check this in advance with cairo_has_current_point().
		3666	*
		3667	* Most path construction functions alter the current point. See the
		3668	* following for details on how they affect the current point:
		3669	* cairo_new_path(), cairo_new_sub_path(),
		3670	* cairo_append_path(), cairo_close_path(),
		3671	* cairo_move_to(), cairo_line_to(), cairo_curve_to(),
		3672	* cairo_rel_move_to(), cairo_rel_line_to(), cairo_rel_curve_to(),
		3673	* cairo_arc(), cairo_arc_negative(), cairo_rectangle(),
		3674	* cairo_text_path(), cairo_glyph_path(), cairo_stroke_to_path().
		3675	*
		3676	* Some functions use and alter the current point but do not
		3677	* otherwise change current path:
		3678	* cairo_show_text().
		3679	*
		3680	* Some functions unset the current path and as a result, current point:
		3681	* cairo_fill(), cairo_stroke().
3959	Serge	3682	*
		3683	* Since: 1.0
1892	serge	3684	**/
		3685	void
		3686	cairo_get_current_point (cairo_t cr, double x_ret, double *y_ret)
		3687	{
		3688	double x, y;
		3689
3959	Serge	3690	x = y = 0;
1892	serge	3691	if (cr->status == CAIRO_STATUS_SUCCESS &&
3959	Serge	3692	cr->backend->has_current_point (cr))
1892	serge	3693	{
3959	Serge	3694	cr->backend->get_current_point (cr, &x, &y);
1892	serge	3695	}
		3696
		3697	if (x_ret)
		3698	*x_ret = x;
		3699	if (y_ret)
		3700	*y_ret = y;
		3701	}
		3702	slim_hidden_def(cairo_get_current_point);
		3703
		3704	/**
		3705	* cairo_get_fill_rule:
		3706	* @cr: a cairo context
		3707	*
		3708	* Gets the current fill rule, as set by cairo_set_fill_rule().
		3709	*
		3710	* Return value: the current fill rule.
3959	Serge	3711	*
		3712	* Since: 1.0
1892	serge	3713	**/
		3714	cairo_fill_rule_t
		3715	cairo_get_fill_rule (cairo_t *cr)
		3716	{
		3717	if (unlikely (cr->status))
		3718	return CAIRO_GSTATE_FILL_RULE_DEFAULT;
		3719
3959	Serge	3720	return cr->backend->get_fill_rule (cr);
1892	serge	3721	}
		3722
		3723	/**
		3724	* cairo_get_line_width:
		3725	* @cr: a cairo context
		3726	*
		3727	* This function returns the current line width value exactly as set by
		3728	* cairo_set_line_width(). Note that the value is unchanged even if
		3729	* the CTM has changed between the calls to cairo_set_line_width() and
		3730	* cairo_get_line_width().
		3731	*
		3732	* Return value: the current line width.
3959	Serge	3733	*
		3734	* Since: 1.0
1892	serge	3735	**/
		3736	double
		3737	cairo_get_line_width (cairo_t *cr)
		3738	{
		3739	if (unlikely (cr->status))
		3740	return CAIRO_GSTATE_LINE_WIDTH_DEFAULT;
		3741
3959	Serge	3742	return cr->backend->get_line_width (cr);
1892	serge	3743	}
		3744	slim_hidden_def (cairo_get_line_width);
		3745
		3746	/**
		3747	* cairo_get_line_cap:
		3748	* @cr: a cairo context
		3749	*
		3750	* Gets the current line cap style, as set by cairo_set_line_cap().
		3751	*
		3752	* Return value: the current line cap style.
3959	Serge	3753	*
		3754	* Since: 1.0
1892	serge	3755	**/
		3756	cairo_line_cap_t
		3757	cairo_get_line_cap (cairo_t *cr)
		3758	{
		3759	if (unlikely (cr->status))
		3760	return CAIRO_GSTATE_LINE_CAP_DEFAULT;
		3761
3959	Serge	3762	return cr->backend->get_line_cap (cr);
1892	serge	3763	}
		3764
		3765	/**
		3766	* cairo_get_line_join:
		3767	* @cr: a cairo context
		3768	*
		3769	* Gets the current line join style, as set by cairo_set_line_join().
		3770	*
		3771	* Return value: the current line join style.
3959	Serge	3772	*
		3773	* Since: 1.0
1892	serge	3774	**/
		3775	cairo_line_join_t
		3776	cairo_get_line_join (cairo_t *cr)
		3777	{
		3778	if (unlikely (cr->status))
		3779	return CAIRO_GSTATE_LINE_JOIN_DEFAULT;
		3780
3959	Serge	3781	return cr->backend->get_line_join (cr);
1892	serge	3782	}
		3783
		3784	/**
		3785	* cairo_get_miter_limit:
		3786	* @cr: a cairo context
		3787	*
		3788	* Gets the current miter limit, as set by cairo_set_miter_limit().
		3789	*
		3790	* Return value: the current miter limit.
3959	Serge	3791	*
		3792	* Since: 1.0
1892	serge	3793	**/
		3794	double
		3795	cairo_get_miter_limit (cairo_t *cr)
		3796	{
		3797	if (unlikely (cr->status))
		3798	return CAIRO_GSTATE_MITER_LIMIT_DEFAULT;
		3799
3959	Serge	3800	return cr->backend->get_miter_limit (cr);
1892	serge	3801	}
		3802
		3803	/**
		3804	* cairo_get_matrix:
		3805	* @cr: a cairo context
		3806	* @matrix: return value for the matrix
		3807	*
		3808	* Stores the current transformation matrix (CTM) into @matrix.
3959	Serge	3809	*
		3810	* Since: 1.0
1892	serge	3811	**/
		3812	void
		3813	cairo_get_matrix (cairo_t cr, cairo_matrix_t matrix)
		3814	{
		3815	if (unlikely (cr->status)) {
		3816	cairo_matrix_init_identity (matrix);
		3817	return;
		3818	}
		3819
3959	Serge	3820	cr->backend->get_matrix (cr, matrix);
1892	serge	3821	}
		3822	slim_hidden_def (cairo_get_matrix);
		3823
		3824	/**
		3825	* cairo_get_target:
		3826	* @cr: a cairo context
		3827	*
		3828	* Gets the target surface for the cairo context as passed to
		3829	* cairo_create().
		3830	*
		3831	* This function will always return a valid pointer, but the result
		3832	* can be a "nil" surface if @cr is already in an error state,
		3833	* (ie. cairo_status() != %CAIRO_STATUS_SUCCESS).
		3834	* A nil surface is indicated by cairo_surface_status()
		3835	* != %CAIRO_STATUS_SUCCESS.
		3836	*
		3837	* Return value: the target surface. This object is owned by cairo. To
		3838	* keep a reference to it, you must call cairo_surface_reference().
3959	Serge	3839	*
		3840	* Since: 1.0
1892	serge	3841	**/
		3842	cairo_surface_t *
		3843	cairo_get_target (cairo_t *cr)
		3844	{
		3845	if (unlikely (cr->status))
		3846	return _cairo_surface_create_in_error (cr->status);
		3847
3959	Serge	3848	return cr->backend->get_original_target (cr);
1892	serge	3849	}
		3850	slim_hidden_def (cairo_get_target);
		3851
		3852	/**
		3853	* cairo_get_group_target:
		3854	* @cr: a cairo context
		3855	*
		3856	* Gets the current destination surface for the context. This is either
		3857	* the original target surface as passed to cairo_create() or the target
		3858	* surface for the current group as started by the most recent call to
		3859	* cairo_push_group() or cairo_push_group_with_content().
		3860	*
		3861	* This function will always return a valid pointer, but the result
		3862	* can be a "nil" surface if @cr is already in an error state,
		3863	* (ie. cairo_status() != %CAIRO_STATUS_SUCCESS).
		3864	* A nil surface is indicated by cairo_surface_status()
		3865	* != %CAIRO_STATUS_SUCCESS.
		3866	*
		3867	* Return value: the target surface. This object is owned by cairo. To
		3868	* keep a reference to it, you must call cairo_surface_reference().
		3869	*
		3870	* Since: 1.2
		3871	**/
		3872	cairo_surface_t *
		3873	cairo_get_group_target (cairo_t *cr)
		3874	{
		3875	if (unlikely (cr->status))
		3876	return _cairo_surface_create_in_error (cr->status);
		3877
3959	Serge	3878	return cr->backend->get_current_target (cr);
1892	serge	3879	}
		3880
		3881	/**
		3882	* cairo_copy_path:
		3883	* @cr: a cairo context
		3884	*
		3885	* Creates a copy of the current path and returns it to the user as a
		3886	* #cairo_path_t. See #cairo_path_data_t for hints on how to iterate
		3887	* over the returned data structure.
		3888	*
		3889	* This function will always return a valid pointer, but the result
		3890	* will have no data (data==%NULL and
		3891	* num_data==0), if either of the following
		3892	* conditions hold:
		3893	*
		3894	*
		3895	* If there is insufficient memory to copy the path. In this
		3896	* case path->status will be set to
		3897	* %CAIRO_STATUS_NO_MEMORY.
		3898	* If @cr is already in an error state. In this case
		3899	* path->status will contain the same status that
		3900	* would be returned by cairo_status().
		3901	*
		3902	*
		3903	* Return value: the copy of the current path. The caller owns the
		3904	* returned object and should call cairo_path_destroy() when finished
		3905	* with it.
3959	Serge	3906	*
		3907	* Since: 1.0
1892	serge	3908	**/
		3909	cairo_path_t *
		3910	cairo_copy_path (cairo_t *cr)
		3911	{
		3912	if (unlikely (cr->status))
		3913	return _cairo_path_create_in_error (cr->status);
		3914
3959	Serge	3915	return cr->backend->copy_path (cr);
1892	serge	3916	}
		3917
		3918	/**
		3919	* cairo_copy_path_flat:
		3920	* @cr: a cairo context
		3921	*
		3922	* Gets a flattened copy of the current path and returns it to the
		3923	* user as a #cairo_path_t. See #cairo_path_data_t for hints on
		3924	* how to iterate over the returned data structure.
		3925	*
		3926	* This function is like cairo_copy_path() except that any curves
		3927	* in the path will be approximated with piecewise-linear
		3928	* approximations, (accurate to within the current tolerance
		3929	* value). That is, the result is guaranteed to not have any elements
		3930	* of type %CAIRO_PATH_CURVE_TO which will instead be replaced by a
		3931	* series of %CAIRO_PATH_LINE_TO elements.
		3932	*
		3933	* This function will always return a valid pointer, but the result
		3934	* will have no data (data==%NULL and
		3935	* num_data==0), if either of the following
		3936	* conditions hold:
		3937	*
		3938	*
		3939	* If there is insufficient memory to copy the path. In this
		3940	* case path->status will be set to
		3941	* %CAIRO_STATUS_NO_MEMORY.
		3942	* If @cr is already in an error state. In this case
		3943	* path->status will contain the same status that
		3944	* would be returned by cairo_status().
		3945	*
		3946	*
		3947	* Return value: the copy of the current path. The caller owns the
		3948	* returned object and should call cairo_path_destroy() when finished
		3949	* with it.
3959	Serge	3950	*
		3951	* Since: 1.0
1892	serge	3952	**/
		3953	cairo_path_t *
		3954	cairo_copy_path_flat (cairo_t *cr)
		3955	{
		3956	if (unlikely (cr->status))
		3957	return _cairo_path_create_in_error (cr->status);
		3958
3959	Serge	3959	return cr->backend->copy_path_flat (cr);
1892	serge	3960	}
		3961
		3962	/**
		3963	* cairo_append_path:
		3964	* @cr: a cairo context
		3965	* @path: path to be appended
		3966	*
		3967	* Append the @path onto the current path. The @path may be either the
		3968	* return value from one of cairo_copy_path() or
		3969	* cairo_copy_path_flat() or it may be constructed manually. See
		3970	* #cairo_path_t for details on how the path data structure should be
		3971	* initialized, and note that path->status must be
		3972	* initialized to %CAIRO_STATUS_SUCCESS.
3959	Serge	3973	*
		3974	* Since: 1.0
1892	serge	3975	**/
		3976	void
		3977	cairo_append_path (cairo_t *cr,
		3978	const cairo_path_t *path)
		3979	{
		3980	cairo_status_t status;
		3981
		3982	if (unlikely (cr->status))
		3983	return;
		3984
3959	Serge	3985	if (unlikely (path == NULL)) {
1892	serge	3986	_cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
		3987	return;
		3988	}
		3989
3959	Serge	3990	if (unlikely (path->status)) {
1892	serge	3991	if (path->status > CAIRO_STATUS_SUCCESS &&
		3992	path->status <= CAIRO_STATUS_LAST_STATUS)
		3993	_cairo_set_error (cr, path->status);
		3994	else
		3995	_cairo_set_error (cr, CAIRO_STATUS_INVALID_STATUS);
		3996	return;
		3997	}
		3998
		3999	if (path->num_data == 0)
		4000	return;
		4001
3959	Serge	4002	if (unlikely (path->data == NULL)) {
1892	serge	4003	_cairo_set_error (cr, CAIRO_STATUS_NULL_POINTER);
		4004	return;
		4005	}
		4006
3959	Serge	4007	status = cr->backend->append_path (cr, path);
1892	serge	4008	if (unlikely (status))
		4009	_cairo_set_error (cr, status);
		4010	}
		4011
		4012	/**
		4013	* cairo_status:
		4014	* @cr: a cairo context
		4015	*
		4016	* Checks whether an error has previously occurred for this context.
		4017	*
		4018	* Returns: the current status of this context, see #cairo_status_t
3959	Serge	4019	*
		4020	* Since: 1.0
1892	serge	4021	**/
		4022	cairo_status_t
		4023	cairo_status (cairo_t *cr)
		4024	{
		4025	return cr->status;
		4026	}
		4027	slim_hidden_def (cairo_status);

Subversion Repositories Kolibri OS

(root)/programs/develop/libraries/cairo/src/cairo.c – Rev 3959