cairo_t: Cairo: A Vector Graphics Library

+ + +

cairo_t

cairo_t — The cairo drawing context

Functions

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+cairo_t * +	+cairo_create () +
+cairo_t * +	+cairo_reference () +
+void +	+cairo_destroy () +
+cairo_status_t +	+cairo_status () +
+void +	+cairo_save () +
+void +	+cairo_restore () +
+cairo_surface_t * +	+cairo_get_target () +
+void +	+cairo_push_group () +
+void +	+cairo_push_group_with_content () +
+cairo_pattern_t * +	+cairo_pop_group () +
+void +	+cairo_pop_group_to_source () +
+cairo_surface_t * +	+cairo_get_group_target () +
+void +	+cairo_set_source_rgb () +
+void +	+cairo_set_source_rgba () +
+void +	+cairo_set_source () +
+void +	+cairo_set_source_surface () +
+cairo_pattern_t * +	+cairo_get_source () +
+void +	+cairo_set_antialias () +
+cairo_antialias_t +	+cairo_get_antialias () +
+void +	+cairo_set_dash () +
+int +	+cairo_get_dash_count () +
+void +	+cairo_get_dash () +
+void +	+cairo_set_fill_rule () +
+cairo_fill_rule_t +	+cairo_get_fill_rule () +
+void +	+cairo_set_line_cap () +
+cairo_line_cap_t +	+cairo_get_line_cap () +
+void +	+cairo_set_line_join () +
+cairo_line_join_t +	+cairo_get_line_join () +
+void +	+cairo_set_line_width () +
+double +	+cairo_get_line_width () +
+void +	+cairo_set_miter_limit () +
+double +	+cairo_get_miter_limit () +
+void +	+cairo_set_operator () +
+cairo_operator_t +	+cairo_get_operator () +
+void +	+cairo_set_tolerance () +
+double +	+cairo_get_tolerance () +
+void +	+cairo_clip () +
+void +	+cairo_clip_preserve () +
+void +	+cairo_clip_extents () +
+cairo_bool_t +	+cairo_in_clip () +
+void +	+cairo_reset_clip () +
+void +	+cairo_rectangle_list_destroy () +
+cairo_rectangle_list_t * +	+cairo_copy_clip_rectangle_list () +
+void +	+cairo_fill () +
+void +	+cairo_fill_preserve () +
+void +	+cairo_fill_extents () +
+cairo_bool_t +	+cairo_in_fill () +
+void +	+cairo_mask () +
+void +	+cairo_mask_surface () +
+void +	+cairo_paint () +
+void +	+cairo_paint_with_alpha () +
+void +	+cairo_stroke () +
+void +	+cairo_stroke_preserve () +
+void +	+cairo_stroke_extents () +
+cairo_bool_t +	+cairo_in_stroke () +
+void +	+cairo_copy_page () +
+void +	+cairo_show_page () +
unsigned int +	+cairo_get_reference_count () +
+cairo_status_t +	+cairo_set_user_data () +
+void * +	+cairo_get_user_data () +

Types and Values

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

typedef	cairo_t
enum	cairo_antialias_t
enum	cairo_fill_rule_t
enum	cairo_line_cap_t
enum	cairo_line_join_t
enum	cairo_operator_t
	cairo_rectangle_t
	cairo_rectangle_list_t

Description

cairo_t is the main object used when drawing with cairo. To +draw with cairo, you create a cairo_t, set the target surface, +and drawing options for the cairo_t, create shapes with +functions like cairo_move_to() and cairo_line_to(), and then +draw shapes with cairo_stroke() or cairo_fill().

cairo_t's can be pushed to a stack via cairo_save(). +They may then safely be changed, without losing the current state. +Use cairo_restore() to restore to the saved state.

Functions

cairo_create ()

cairo_t *
+cairo_create (cairo_surface_t *target);

Creates a new cairo_t with all graphics state parameters set to +default values and with target + as a target surface. The target +surface should be constructed with a backend-specific function such +as cairo_image_surface_create() (or any other +cairo_backend_surface_create() +variant).

This function references target +, so you can immediately +call cairo_surface_destroy() on it if you don't need to +maintain a separate reference to it.

Parameters

+++++ + + + + + +

target

target surface for the context

Returns

a newly allocated cairo_t with a reference +count of 1. The initial reference count should be released +with cairo_destroy() when you are done using the cairo_t. +This function never returns NULL. If memory cannot be +allocated, a special cairo_t object will be returned on +which cairo_status() returns CAIRO_STATUS_NO_MEMORY. If +you attempt to target a surface which does not support +writing (such as cairo_mime_surface_t) then a +CAIRO_STATUS_WRITE_ERROR will be raised. You can use this +object normally, but no drawing will be done.

Since: 1.0

cairo_reference ()

cairo_t *
+cairo_reference (cairo_t *cr);

Increases the reference count on cr + by one. This prevents +cr + from being destroyed until a matching call to cairo_destroy() +is made.

Use cairo_get_reference_count() to get the number of references to +a cairo_t.

Parameters

+++++ + + + + + +

a cairo_t

Returns

the referenced cairo_t.

Since: 1.0

cairo_destroy ()

void
+cairo_destroy (cairo_t *cr);

Decreases the reference count on cr + by one. If the result +is zero, then cr + and all associated resources are freed. +See cairo_reference().

Parameters

+++++ + + + + + +

a cairo_t

Since: 1.0

cairo_status ()

cairo_status_t
+cairo_status (cairo_t *cr);

Checks whether an error has previously occurred for this context.

Parameters

+++++ + + + + + +

a cairo context

Returns

the current status of this context, see cairo_status_t

Since: 1.0

cairo_save ()

void
+cairo_save (cairo_t *cr);

Makes a copy of the current state of cr + and saves it +on an internal stack of saved states for cr +. When +cairo_restore() is called, cr + will be restored to +the saved state. Multiple calls to cairo_save() and +cairo_restore() can be nested; each call to cairo_restore() +restores the state from the matching paired cairo_save().

It isn't necessary to clear all saved states before +a cairo_t is freed. If the reference count of a cairo_t +drops to zero in response to a call to cairo_destroy(), +any saved states will be freed along with the cairo_t.

Parameters

+++++ + + + + + +

a cairo_t

Since: 1.0

cairo_restore ()

void
+cairo_restore (cairo_t *cr);

Restores cr + to the state saved by a preceding call to +cairo_save() and removes that state from the stack of +saved states.

Parameters

+++++ + + + + + +

a cairo_t

Since: 1.0

cairo_get_target ()

cairo_surface_t *
+cairo_get_target (cairo_t *cr);

Gets the target surface for the cairo context as passed to +cairo_create().

This function will always return a valid pointer, but the result +can be a "nil" surface if cr + is already in an error state, +(ie. cairo_status() != CAIRO_STATUS_SUCCESS). +A nil surface is indicated by cairo_surface_status() +!= CAIRO_STATUS_SUCCESS.

Parameters

+++++ + + + + + +

a cairo context

Returns

the target surface. This object is owned by cairo. To +keep a reference to it, you must call cairo_surface_reference().

Since: 1.0

cairo_push_group ()

void
+cairo_push_group (cairo_t *cr);

Temporarily redirects drawing to an intermediate surface known as a +group. The redirection lasts until the group is completed by a call +to cairo_pop_group() or cairo_pop_group_to_source(). These calls +provide the result of any drawing to the group as a pattern, +(either as an explicit object, or set as the source pattern).

This group functionality can be convenient for performing +intermediate compositing. One common use of a group is to render +objects as opaque within the group, (so that they occlude each +other), and then blend the result with translucence onto the +destination.

Groups can be nested arbitrarily deep by making balanced calls to +cairo_push_group()/cairo_pop_group(). Each call pushes/pops the new +target group onto/from a stack.

The cairo_push_group() function calls cairo_save() so that any +changes to the graphics state will not be visible outside the +group, (the pop_group functions call cairo_restore()).

By default the intermediate group will have a content type of +CAIRO_CONTENT_COLOR_ALPHA. Other content types can be chosen for +the group by using cairo_push_group_with_content() instead.

As an example, here is how one might fill and stroke a path with +translucence, but without any portion of the fill being visible +under the stroke:

+ + + + + + + +

1
+2
+3
+4
+5
+6
+7

cairo_push_group (cr);
+cairo_set_source (cr, fill_pattern);
+cairo_fill_preserve (cr);
+cairo_set_source (cr, stroke_pattern);
+cairo_stroke (cr);
+cairo_pop_group_to_source (cr);
+cairo_paint_with_alpha (cr, alpha);

+ +

Parameters

+++++ + + + + + +

a cairo context

Since: 1.2

cairo_push_group_with_content ()

void
+cairo_push_group_with_content (cairo_t *cr,
+                               cairo_content_t content);

The group will have a content type of content +. The ability to +control this content type is the only distinction between this +function and cairo_push_group() which you should see for a more +detailed description of group rendering.

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo context
content	a cairo_content_t indicating the type of group that +will be created

Since: 1.2

cairo_pop_group ()

cairo_pattern_t *
+cairo_pop_group (cairo_t *cr);

Terminates the redirection begun by a call to cairo_push_group() or +cairo_push_group_with_content() and returns a new pattern +containing the results of all drawing operations performed to the +group.

The cairo_pop_group() function calls cairo_restore(), (balancing a +call to cairo_save() by the push_group function), so that any +changes to the graphics state will not be visible outside the +group.

Parameters

+++++ + + + + + +

a cairo context

Returns

a newly created (surface) pattern containing the +results of all drawing operations performed to the group. The +caller owns the returned object and should call +cairo_pattern_destroy() when finished with it.

Since: 1.2

cairo_pop_group_to_source ()

void
+cairo_pop_group_to_source (cairo_t *cr);

Terminates the redirection begun by a call to cairo_push_group() or +cairo_push_group_with_content() and installs the resulting pattern +as the source pattern in the given cairo context.

The behavior of this function is equivalent to the sequence of +operations:

+ + + + + + + +

1
+2
+3

cairo_pattern_t *group = cairo_pop_group (cr);
+cairo_set_source (cr, group);
+cairo_pattern_destroy (group);

+ +

but is more convenient as their is no need for a variable to store +the short-lived pointer to the pattern.

Parameters

+++++ + + + + + +

a cairo context

Since: 1.2

cairo_get_group_target ()

cairo_surface_t *
+cairo_get_group_target (cairo_t *cr);

Gets the current destination surface for the context. This is either +the original target surface as passed to cairo_create() or the target +surface for the current group as started by the most recent call to +cairo_push_group() or cairo_push_group_with_content().

Parameters

+++++ + + + + + +

a cairo context

Returns

the target surface. This object is owned by cairo. To +keep a reference to it, you must call cairo_surface_reference().

Since: 1.2

cairo_set_source_rgb ()

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

Sets the source pattern within cr + to an opaque color. This opaque +color will then be used for any subsequent drawing operation until +a new source pattern is set.

The color components are floating point numbers in the range 0 to

If the values passed in are outside that range, they will be +clamped.

The default source pattern is opaque black, (that is, it is +equivalent to cairo_set_source_rgb(cr, 0.0, 0.0, 0.0)).

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

cr	a cairo context
red	red component of color
green	green component of color
blue	blue component of color

Since: 1.0

cairo_set_source_rgba ()

void
+cairo_set_source_rgba (cairo_t *cr,
+                       double red,
+                       double green,
+                       double blue,
+                       double alpha);

Sets the source pattern within cr + to a translucent color. This +color will then be used for any subsequent drawing operation until +a new source pattern is set.

The color and alpha components are floating point numbers in the +range 0 to 1. If the values passed in are outside that range, they +will be clamped.

The default source pattern is opaque black, (that is, it is +equivalent to cairo_set_source_rgba(cr, 0.0, 0.0, 0.0, 1.0)).

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

cr	a cairo context
red	red component of color
green	green component of color
blue	blue component of color
alpha	alpha component of color

Since: 1.0

cairo_set_source ()

void
+cairo_set_source (cairo_t *cr,
+                  cairo_pattern_t *source);

Sets the source pattern within cr + to source +. This pattern +will then be used for any subsequent drawing operation until a new +source pattern is set.

Note: The pattern's transformation matrix will be locked to the +user space in effect at the time of cairo_set_source(). This means +that further modifications of the current transformation matrix +will not affect the source pattern. See cairo_pattern_set_matrix().

The default source pattern is a solid pattern that is opaque black, +(that is, it is equivalent to cairo_set_source_rgb(cr, 0.0, 0.0, +0.0)).

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo context
source	a cairo_pattern_t to be used as the source for +subsequent drawing operations.

Since: 1.0

cairo_set_source_surface ()

void
+cairo_set_source_surface (cairo_t *cr,
+                          cairo_surface_t *surface,
+                          double x,
+                          double y);

This is a convenience function for creating a pattern from surface + +and setting it as the source in cr + with cairo_set_source().

The x + and y + parameters give the user-space coordinate at which +the surface origin should appear. (The surface origin is its +upper-left corner before any transformation has been applied.) The +x + and y + parameters are negated and then set as translation values +in the pattern matrix.

Other than the initial translation pattern matrix, as described +above, all other pattern attributes, (such as its extend mode), are +set to the default values as in cairo_pattern_create_for_surface(). +The resulting pattern can be queried with cairo_get_source() so +that these attributes can be modified if desired, (eg. to create a +repeating pattern with cairo_pattern_set_extend()).

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

cr	a cairo context
surface	a surface to be used to set the source pattern
x	User-space X coordinate for surface origin
y	User-space Y coordinate for surface origin

Since: 1.0

cairo_get_source ()

cairo_pattern_t *
+cairo_get_source (cairo_t *cr);

Gets the current source pattern for cr +.

Parameters

+++++ + + + + + +

a cairo context

Returns

the current source pattern. This object is owned by +cairo. To keep a reference to it, you must call +cairo_pattern_reference().

Since: 1.0

cairo_set_antialias ()

void
+cairo_set_antialias (cairo_t *cr,
+                     cairo_antialias_t antialias);

Set the antialiasing mode of the rasterizer used for drawing shapes. +This value is a hint, and a particular backend may or may not support +a particular value. At the current time, no backend supports +CAIRO_ANTIALIAS_SUBPIXEL when drawing shapes.

Note that this option does not affect text rendering, instead see +cairo_font_options_set_antialias().

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo_t
antialias	the new antialiasing mode

Since: 1.0

cairo_get_antialias ()

cairo_antialias_t
+cairo_get_antialias (cairo_t *cr);

Gets the current shape antialiasing mode, as set by +cairo_set_antialias().

Parameters

+++++ + + + + + +

a cairo context

Returns

the current shape antialiasing mode.

Since: 1.0

cairo_set_dash ()

void
+cairo_set_dash (cairo_t *cr,
+                const double *dashes,
+                int num_dashes,
+                double offset);

Sets the dash pattern to be used by cairo_stroke(). A dash pattern +is specified by dashes +, an array of positive values. Each value +provides the length of alternate "on" and "off" portions of the +stroke. The offset + specifies an offset into the pattern at which +the stroke begins.

Each "on" segment will have caps applied as if the segment were a +separate sub-path. In particular, it is valid to use an "on" length +of 0.0 with CAIRO_LINE_CAP_ROUND or CAIRO_LINE_CAP_SQUARE in order +to distributed dots or squares along a path.

Note: The length values are in user-space units as evaluated at the +time of stroking. This is not necessarily the same as the user +space at the time of cairo_set_dash().

If num_dashes + is 0 dashing is disabled.

If num_dashes + is 1 a symmetric pattern is assumed with alternating +on and off portions of the size specified by the single value in +dashes +.

If any value in dashes + is negative, or if all values are 0, then +cr + will be put into an error state with a status of +CAIRO_STATUS_INVALID_DASH.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

cr	a cairo context
dashes	an array specifying alternate lengths of on and off stroke portions
num_dashes	the length of the dashes array
offset	an offset into the dash pattern at which the stroke should start

Since: 1.0

cairo_get_dash_count ()

int
+cairo_get_dash_count (cairo_t *cr);

This function returns the length of the dash array in cr + (0 if dashing +is not currently in effect).

Parameters

+++++ + + + + + +

a cairo_t

Returns

the length of the dash array, or 0 if no dash array set.

Since: 1.4

cairo_get_dash ()

void
+cairo_get_dash (cairo_t *cr,
+                double *dashes,
+                double *offset);

Gets the current dash array. If not NULL, dashes + should be big +enough to hold at least the number of values returned by +cairo_get_dash_count().

Parameters

+++++ + + + + + + + + + + + + + + + + + +

cr	a cairo_t
dashes	return value for the dash array, or `NULL`
offset	return value for the current dash offset, or `NULL`

Since: 1.4

cairo_set_fill_rule ()

void
+cairo_set_fill_rule (cairo_t *cr,
+                     cairo_fill_rule_t fill_rule);

Set the current fill rule within the cairo context. The fill rule +is used to determine which regions are inside or outside a complex +(potentially self-intersecting) path. The current fill rule affects +both cairo_fill() and cairo_clip(). See cairo_fill_rule_t for details +on the semantics of each available fill rule.

The default fill rule is CAIRO_FILL_RULE_WINDING.

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo_t
fill_rule	a fill rule, specified as a cairo_fill_rule_t

Since: 1.0

cairo_get_fill_rule ()

cairo_fill_rule_t
+cairo_get_fill_rule (cairo_t *cr);

Gets the current fill rule, as set by cairo_set_fill_rule().

Parameters

+++++ + + + + + +

a cairo context

Returns

the current fill rule.

Since: 1.0

cairo_set_line_cap ()

void
+cairo_set_line_cap (cairo_t *cr,
+                    cairo_line_cap_t line_cap);

Sets the current line cap style within the cairo context. See +cairo_line_cap_t for details about how the available line cap +styles are drawn.

As with the other stroke parameters, the current line cap style is +examined by cairo_stroke(), cairo_stroke_extents(), and +cairo_stroke_to_path(), but does not have any effect during path +construction.

The default line cap style is CAIRO_LINE_CAP_BUTT.

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo context
line_cap	a line cap style

Since: 1.0

cairo_get_line_cap ()

cairo_line_cap_t
+cairo_get_line_cap (cairo_t *cr);

Gets the current line cap style, as set by cairo_set_line_cap().

Parameters

+++++ + + + + + +

a cairo context

Returns

the current line cap style.

Since: 1.0

cairo_set_line_join ()

void
+cairo_set_line_join (cairo_t *cr,
+                     cairo_line_join_t line_join);

Sets the current line join style within the cairo context. See +cairo_line_join_t for details about how the available line join +styles are drawn.

As with the other stroke parameters, the current line join style is +examined by cairo_stroke(), cairo_stroke_extents(), and +cairo_stroke_to_path(), but does not have any effect during path +construction.

The default line join style is CAIRO_LINE_JOIN_MITER.

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo context
line_join	a line join style

Since: 1.0

cairo_get_line_join ()

cairo_line_join_t
+cairo_get_line_join (cairo_t *cr);

Gets the current line join style, as set by cairo_set_line_join().

Parameters

+++++ + + + + + +

a cairo context

Returns

the current line join style.

Since: 1.0

cairo_set_line_width ()

void
+cairo_set_line_width (cairo_t *cr,
+                      double width);

Sets the current line width within the cairo context. The line +width value specifies the diameter of a pen that is circular in +user space, (though device-space pen may be an ellipse in general +due to scaling/shear/rotation of the CTM).

Note: When the description above refers to user space and CTM it +refers to the user space and CTM in effect at the time of the +stroking operation, not the user space and CTM in effect at the +time of the call to cairo_set_line_width(). The simplest usage +makes both of these spaces identical. That is, if there is no +change to the CTM between a call to cairo_set_line_width() and the +stroking operation, then one can just pass user-space values to +cairo_set_line_width() and ignore this note.

As with the other stroke parameters, the current line width is +examined by cairo_stroke(), cairo_stroke_extents(), and +cairo_stroke_to_path(), but does not have any effect during path +construction.

The default line width value is 2.0.

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo_t
width	a line width

Since: 1.0

cairo_get_line_width ()

double
+cairo_get_line_width (cairo_t *cr);

This function returns the current line width value exactly as set by +cairo_set_line_width(). Note that the value is unchanged even if +the CTM has changed between the calls to cairo_set_line_width() and +cairo_get_line_width().

Parameters

+++++ + + + + + +

a cairo context

Returns

the current line width.

Since: 1.0

cairo_set_miter_limit ()

void
+cairo_set_miter_limit (cairo_t *cr,
+                       double limit);

Sets the current miter limit within the cairo context.

If the current line join style is set to CAIRO_LINE_JOIN_MITER +(see cairo_set_line_join()), the miter limit is used to determine +whether the lines should be joined with a bevel instead of a miter. +Cairo divides the length of the miter by the line width. +If the result is greater than the miter limit, the style is +converted to a bevel.

As with the other stroke parameters, the current line miter limit is +examined by cairo_stroke(), cairo_stroke_extents(), and +cairo_stroke_to_path(), but does not have any effect during path +construction.

The default miter limit value is 10.0, which will convert joins +with interior angles less than 11 degrees to bevels instead of +miters. For reference, a miter limit of 2.0 makes the miter cutoff +at 60 degrees, and a miter limit of 1.414 makes the cutoff at 90 +degrees.

A miter limit for a desired angle can be computed as: miter limit = +1/sin(angle/2)

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo context
limit	miter limit to set

Since: 1.0

cairo_get_miter_limit ()

double
+cairo_get_miter_limit (cairo_t *cr);

Gets the current miter limit, as set by cairo_set_miter_limit().

Parameters

+++++ + + + + + +

a cairo context

Returns

the current miter limit.

Since: 1.0

cairo_set_operator ()

void
+cairo_set_operator (cairo_t *cr,
+                    cairo_operator_t op);

Sets the compositing operator to be used for all drawing +operations. See cairo_operator_t for details on the semantics of +each available compositing operator.

The default operator is CAIRO_OPERATOR_OVER.

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo_t
op	a compositing operator, specified as a cairo_operator_t

Since: 1.0

cairo_get_operator ()

cairo_operator_t
+cairo_get_operator (cairo_t *cr);

Gets the current compositing operator for a cairo context.

Parameters

+++++ + + + + + +

a cairo context

Returns

the current compositing operator.

Since: 1.0

cairo_set_tolerance ()

void
+cairo_set_tolerance (cairo_t *cr,
+                     double tolerance);

Sets the tolerance used when converting paths into trapezoids. +Curved segments of the path will be subdivided until the maximum +deviation between the original path and the polygonal approximation +is less than tolerance +. The default value is 0.1. A larger +value will give better performance, a smaller value, better +appearance. (Reducing the value from the default value of 0.1 +is unlikely to improve appearance significantly.) The accuracy of paths +within Cairo is limited by the precision of its internal arithmetic, and +the prescribed tolerance + is restricted to the smallest +representable internal value.

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo_t
tolerance	the tolerance, in device units (typically pixels)

Since: 1.0

cairo_get_tolerance ()

double
+cairo_get_tolerance (cairo_t *cr);

Gets the current tolerance value, as set by cairo_set_tolerance().

Parameters

+++++ + + + + + +

a cairo context

Returns

the current tolerance value.

Since: 1.0

cairo_clip ()

void
+cairo_clip (cairo_t *cr);

Establishes a new clip region by intersecting the current clip +region with the current path as it would be filled by cairo_fill() +and according to the current fill rule (see cairo_set_fill_rule()).

After cairo_clip(), the current path will be cleared from the cairo +context.

The current clip region affects all drawing operations by +effectively masking out any changes to the surface that are outside +the current clip region.

Calling cairo_clip() can only make the clip region smaller, never +larger. But the current clip is part of the graphics state, so a +temporary restriction of the clip region can be achieved by +calling cairo_clip() within a cairo_save()/cairo_restore() +pair. The only other means of increasing the size of the clip +region is cairo_reset_clip().

Parameters

+++++ + + + + + +

a cairo context

Since: 1.0

cairo_clip_preserve ()

void
+cairo_clip_preserve (cairo_t *cr);

Unlike cairo_clip(), cairo_clip_preserve() preserves the path within +the cairo context.

The current clip region affects all drawing operations by +effectively masking out any changes to the surface that are outside +the current clip region.

Calling cairo_clip_preserve() can only make the clip region smaller, never +larger. But the current clip is part of the graphics state, so a +temporary restriction of the clip region can be achieved by +calling cairo_clip_preserve() within a cairo_save()/cairo_restore() +pair. The only other means of increasing the size of the clip +region is cairo_reset_clip().

Parameters

+++++ + + + + + +

a cairo context

Since: 1.0

cairo_clip_extents ()

void
+cairo_clip_extents (cairo_t *cr,
+                    double *x1,
+                    double *y1,
+                    double *x2,
+                    double *y2);

Computes a bounding box in user coordinates covering the area inside the +current clip.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

cr	a cairo context
x1	left of the resulting extents
y1	top of the resulting extents
x2	right of the resulting extents
y2	bottom of the resulting extents

Since: 1.4

cairo_in_clip ()

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

Tests whether the given point is inside the area that would be +visible through the current clip, i.e. the area that would be filled by +a cairo_paint() operation.

See cairo_clip(), and cairo_clip_preserve().

Parameters

+++++ + + + + + + + + + + + + + + + + + +

cr	a cairo context
x	X coordinate of the point to test
y	Y coordinate of the point to test

Returns

A non-zero value if the point is inside, or zero if +outside.

Since: 1.10

cairo_reset_clip ()

void
+cairo_reset_clip (cairo_t *cr);

Reset the current clip region to its original, unrestricted +state. That is, set the clip region to an infinitely large shape +containing the target surface. Equivalently, if infinity is too +hard to grasp, one can imagine the clip region being reset to the +exact bounds of the target surface.

Note that code meant to be reusable should not call +cairo_reset_clip() as it will cause results unexpected by +higher-level code which calls cairo_clip(). Consider using +cairo_save() and cairo_restore() around cairo_clip() as a more +robust means of temporarily restricting the clip region.

Parameters

+++++ + + + + + +

a cairo context

Since: 1.0

cairo_rectangle_list_destroy ()

void
+cairo_rectangle_list_destroy (cairo_rectangle_list_t *rectangle_list);

Unconditionally frees rectangle_list + and all associated +references. After this call, the rectangle_list + pointer must not +be dereferenced.

Parameters

+++++ + + + + + +

rectangle_list

a rectangle list, as obtained from cairo_copy_clip_rectangle_list()

Since: 1.4

cairo_copy_clip_rectangle_list ()

cairo_rectangle_list_t *
+cairo_copy_clip_rectangle_list (cairo_t *cr);

Gets the current clip region as a list of rectangles in user coordinates. +Never returns NULL.

The status in the list may be CAIRO_STATUS_CLIP_NOT_REPRESENTABLE to +indicate that the clip region cannot be represented as a list of +user-space rectangles. The status may have other values to indicate +other errors.

Parameters

+++++ + + + + + +

a cairo context

Returns

the current clip region as a list of rectangles in user coordinates, +which should be destroyed using cairo_rectangle_list_destroy().

Since: 1.4

cairo_fill ()

void
+cairo_fill (cairo_t *cr);

A drawing operator that fills the current path according to the +current fill rule, (each sub-path is implicitly closed before being +filled). After cairo_fill(), the current path will be cleared from +the cairo context. See cairo_set_fill_rule() and +cairo_fill_preserve().

Parameters

+++++ + + + + + +

a cairo context

Since: 1.0

cairo_fill_preserve ()

void
+cairo_fill_preserve (cairo_t *cr);

A drawing operator that fills the current path according to the +current fill rule, (each sub-path is implicitly closed before being +filled). Unlike cairo_fill(), cairo_fill_preserve() preserves the +path within the cairo context.

See cairo_set_fill_rule() and cairo_fill().

Parameters

+++++ + + + + + +

a cairo context

Since: 1.0

cairo_fill_extents ()

void
+cairo_fill_extents (cairo_t *cr,
+                    double *x1,
+                    double *y1,
+                    double *x2,
+                    double *y2);

Computes a bounding box in user coordinates covering the area that +would be affected, (the "inked" area), by a cairo_fill() operation +given the current path and fill parameters. If the current path is +empty, returns an empty rectangle ((0,0), (0,0)). Surface +dimensions and clipping are not taken into account.

Contrast with cairo_path_extents(), which is similar, but returns +non-zero extents for some paths with no inked area, (such as a +simple line segment).

Note that cairo_fill_extents() must necessarily do more work to +compute the precise inked areas in light of the fill rule, so +cairo_path_extents() may be more desirable for sake of performance +if the non-inked path extents are desired.

See cairo_fill(), cairo_set_fill_rule() and cairo_fill_preserve().

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

cr	a cairo context
x1	left of the resulting extents
y1	top of the resulting extents
x2	right of the resulting extents
y2	bottom of the resulting extents

Since: 1.0

cairo_in_fill ()

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

Tests whether the given point is inside the area that would be +affected by a cairo_fill() operation given the current path and +filling parameters. Surface dimensions and clipping are not taken +into account.

See cairo_fill(), cairo_set_fill_rule() and cairo_fill_preserve().

Parameters

+++++ + + + + + + + + + + + + + + + + + +

cr	a cairo context
x	X coordinate of the point to test
y	Y coordinate of the point to test

Returns

A non-zero value if the point is inside, or zero if +outside.

Since: 1.0

cairo_mask ()

void
+cairo_mask (cairo_t *cr,
+            cairo_pattern_t *pattern);

A drawing operator that paints the current source +using the alpha channel of pattern + as a mask. (Opaque +areas of pattern + are painted with the source, transparent +areas are not painted.)

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo context
pattern	a cairo_pattern_t

Since: 1.0

cairo_mask_surface ()

void
+cairo_mask_surface (cairo_t *cr,
+                    cairo_surface_t *surface,
+                    double surface_x,
+                    double surface_y);

A drawing operator that paints the current source +using the alpha channel of surface + as a mask. (Opaque +areas of surface + are painted with the source, transparent +areas are not painted.)

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

cr	a cairo context
surface	a cairo_surface_t
surface_x	X coordinate at which to place the origin of `surface` +
surface_y	Y coordinate at which to place the origin of `surface` +

Since: 1.0

cairo_paint ()

void
+cairo_paint (cairo_t *cr);

A drawing operator that paints the current source everywhere within +the current clip region.

Parameters

+++++ + + + + + +

a cairo context

Since: 1.0

cairo_paint_with_alpha ()

void
+cairo_paint_with_alpha (cairo_t *cr,
+                        double alpha);

A drawing operator that paints the current source everywhere within +the current clip region using a mask of constant alpha value +alpha +. The effect is similar to cairo_paint(), but the drawing +is faded out using the alpha value.

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo context
alpha	alpha value, between 0 (transparent) and 1 (opaque)

Since: 1.0

cairo_stroke ()

void
+cairo_stroke (cairo_t *cr);

A drawing operator that strokes the current path according to the +current line width, line join, line cap, and dash settings. After +cairo_stroke(), the current path will be cleared from the cairo +context. See cairo_set_line_width(), cairo_set_line_join(), +cairo_set_line_cap(), cairo_set_dash(), and +cairo_stroke_preserve().

Note: Degenerate segments and sub-paths are treated specially and +provide a useful result. These can result in two different +situations:

Zero-length "on" segments set in cairo_set_dash(). If the cap +style is CAIRO_LINE_CAP_ROUND or CAIRO_LINE_CAP_SQUARE then these +segments will be drawn as circular dots or squares respectively. In +the case of CAIRO_LINE_CAP_SQUARE, the orientation of the squares +is determined by the direction of the underlying path.
A sub-path created by cairo_move_to() followed by either a +cairo_close_path() or one or more calls to cairo_line_to() to the +same coordinate as the cairo_move_to(). If the cap style is +CAIRO_LINE_CAP_ROUND then these sub-paths will be drawn as circular +dots. Note that in the case of CAIRO_LINE_CAP_SQUARE a degenerate +sub-path will not be drawn at all, (since the correct orientation +is indeterminate).

In no case will a cap style of CAIRO_LINE_CAP_BUTT cause anything +to be drawn in the case of either degenerate segments or sub-paths.

Parameters

+++++ + + + + + +

a cairo context

Since: 1.0

cairo_stroke_preserve ()

void
+cairo_stroke_preserve (cairo_t *cr);

A drawing operator that strokes the current path according to the +current line width, line join, line cap, and dash settings. Unlike +cairo_stroke(), cairo_stroke_preserve() preserves the path within the +cairo context.

See cairo_set_line_width(), cairo_set_line_join(), +cairo_set_line_cap(), cairo_set_dash(), and +cairo_stroke_preserve().

Parameters

+++++ + + + + + +

a cairo context

Since: 1.0

cairo_stroke_extents ()

void
+cairo_stroke_extents (cairo_t *cr,
+                      double *x1,
+                      double *y1,
+                      double *x2,
+                      double *y2);

Computes a bounding box in user coordinates covering the area that +would be affected, (the "inked" area), by a cairo_stroke() +operation given the current path and stroke parameters. +If the current path is empty, returns an empty rectangle ((0,0), (0,0)). +Surface dimensions and clipping are not taken into account.

Note that if the line width is set to exactly zero, then +cairo_stroke_extents() will return an empty rectangle. Contrast with +cairo_path_extents() which can be used to compute the non-empty +bounds as the line width approaches zero.

Note that cairo_stroke_extents() must necessarily do more work to +compute the precise inked areas in light of the stroke parameters, +so cairo_path_extents() may be more desirable for sake of +performance if non-inked path extents are desired.

See cairo_stroke(), cairo_set_line_width(), cairo_set_line_join(), +cairo_set_line_cap(), cairo_set_dash(), and +cairo_stroke_preserve().

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

cr	a cairo context
x1	left of the resulting extents
y1	top of the resulting extents
x2	right of the resulting extents
y2	bottom of the resulting extents

Since: 1.0

cairo_in_stroke ()

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

Tests whether the given point is inside the area that would be +affected by a cairo_stroke() operation given the current path and +stroking parameters. Surface dimensions and clipping are not taken +into account.

See cairo_stroke(), cairo_set_line_width(), cairo_set_line_join(), +cairo_set_line_cap(), cairo_set_dash(), and +cairo_stroke_preserve().

Parameters

+++++ + + + + + + + + + + + + + + + + + +

cr	a cairo context
x	X coordinate of the point to test
y	Y coordinate of the point to test

Returns

A non-zero value if the point is inside, or zero if +outside.

Since: 1.0

cairo_copy_page ()

void
+cairo_copy_page (cairo_t *cr);

Emits the current page for backends that support multiple pages, but +doesn't clear it, so, the contents of the current page will be retained +for the next page too. Use cairo_show_page() if you want to get an +empty page after the emission.

This is a convenience function that simply calls +cairo_surface_copy_page() on cr +'s target.

Parameters

+++++ + + + + + +

a cairo context

Since: 1.0

cairo_show_page ()

void
+cairo_show_page (cairo_t *cr);

Emits and clears the current page for backends that support multiple +pages. Use cairo_copy_page() if you don't want to clear the page.

This is a convenience function that simply calls +cairo_surface_show_page() on cr +'s target.

Parameters

+++++ + + + + + +

a cairo context

Since: 1.0

cairo_get_reference_count ()

unsigned int
+cairo_get_reference_count (cairo_t *cr);

Returns the current reference count of cr +.

Parameters

+++++ + + + + + +

a cairo_t

Returns

the current reference count of cr +. If the +object is a nil object, 0 will be returned.

Since: 1.4

cairo_set_user_data ()

cairo_status_t
+cairo_set_user_data (cairo_t *cr,
+                     const cairo_user_data_key_t *key,
+                     void *user_data,
+                     cairo_destroy_func_t destroy);

Attach user data to cr +. To remove user data from a surface, +call this function with the key that was used to set it and NULL +for data +.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

cr	a cairo_t
key	the address of a cairo_user_data_key_t to attach the user data to
user_data	the user data to attach to the cairo_t
destroy	a cairo_destroy_func_t which will be called when the +cairo_t is destroyed or when new user data is attached using the +same key.

Returns

CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY if a +slot could not be allocated for the user data.

Since: 1.4

cairo_get_user_data ()

void *
+cairo_get_user_data (cairo_t *cr,
+                     const cairo_user_data_key_t *key);

Return user data previously attached to cr + using the specified +key. If no user data has been attached with the given key this +function returns NULL.

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo_t
key	the address of the cairo_user_data_key_t the user data was +attached to

Returns

the user data previously attached or NULL.

Since: 1.4

Types and Values

cairo_t

typedef struct _cairo cairo_t;
+

A cairo_t contains the current state of the rendering device, +including coordinates of yet to be drawn shapes.

Cairo contexts, as cairo_t objects are named, are central to +cairo and all drawing with cairo is always done to a cairo_t +object.

Memory management of cairo_t is done with +cairo_reference() and cairo_destroy().

Since: 1.0

enum cairo_antialias_t

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

As it is not necessarily clear from the above what advantages a particular +antialias method provides, since 1.12, there is also a set of hints: +CAIRO_ANTIALIAS_FAST +: Allow the backend to degrade raster quality for speed +CAIRO_ANTIALIAS_GOOD +: A balance between speed and quality +CAIRO_ANTIALIAS_BEST +: A high-fidelity, but potentially slow, raster mode

These make no guarantee on how the backend will perform its rasterisation +(if it even rasterises!), nor that they have any differing effect other +than to enable some form of antialiasing. In the case of glyph rendering, +CAIRO_ANTIALIAS_FAST + and CAIRO_ANTIALIAS_GOOD + will be mapped to +CAIRO_ANTIALIAS_GRAY +, with CAIRO_ANTALIAS_BEST + being equivalent to +CAIRO_ANTIALIAS_SUBPIXEL +.

The interpretation of CAIRO_ANTIALIAS_DEFAULT + is left entirely up to +the backend, typically this will be similar to CAIRO_ANTIALIAS_GOOD +.

Members

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

CAIRO_ANTIALIAS_DEFAULT	+ Use the default antialiasing for + the subsystem and target device, since 1.0 +
CAIRO_ANTIALIAS_NONE	+ Use a bilevel alpha mask, since 1.0 +
CAIRO_ANTIALIAS_GRAY	+ Perform single-color antialiasing (using + shades of gray for black text on a white background, for example), since 1.0 +
CAIRO_ANTIALIAS_SUBPIXEL	+ Perform antialiasing by taking + advantage of the order of subpixel elements on devices + such as LCD panels, since 1.0 +
CAIRO_ANTIALIAS_FAST	+ Hint that the backend should perform some +antialiasing but prefer speed over quality, since 1.12 +
CAIRO_ANTIALIAS_GOOD	+ The backend should balance quality against +performance, since 1.12 +
CAIRO_ANTIALIAS_BEST	+ Hint that the backend should render at the highest +quality, sacrificing speed if necessary, since 1.12 +

Since: 1.0

enum cairo_fill_rule_t

cairo_fill_rule_t is used to select how paths are filled. For both +fill rules, whether or not a point is included in the fill is +determined by taking a ray from that point to infinity and looking +at intersections with the path. The ray can be in any direction, +as long as it doesn't pass through the end point of a segment +or have a tricky intersection such as intersecting tangent to the path. +(Note that filling is not actually implemented in this way. This +is just a description of the rule that is applied.)

The default fill rule is CAIRO_FILL_RULE_WINDING.

New entries may be added in future versions.

Members

+++++ + + + + + + + + + + + + +

CAIRO_FILL_RULE_WINDING	+ If the path crosses the ray from +left-to-right, counts +1. If the path crosses the ray +from right to left, counts -1. (Left and right are determined +from the perspective of looking along the ray from the starting +point.) If the total count is non-zero, the point will be filled. (Since 1.0) +
CAIRO_FILL_RULE_EVEN_ODD	+ Counts the total number of +intersections, without regard to the orientation of the contour. If +the total number of intersections is odd, the point will be +filled. (Since 1.0) +

Since: 1.0

enum cairo_line_cap_t

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

The default line cap style is CAIRO_LINE_CAP_BUTT.

Members

+++++ + + + + + + + + + + + + + + + + + +

CAIRO_LINE_CAP_BUTT	+ start(stop) the line exactly at the start(end) point (Since 1.0) +
CAIRO_LINE_CAP_ROUND	+ use a round ending, the center of the circle is the end point (Since 1.0) +
CAIRO_LINE_CAP_SQUARE	+ use squared ending, the center of the square is the end point (Since 1.0) +

Since: 1.0

enum cairo_line_join_t

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

The default line join style is CAIRO_LINE_JOIN_MITER.

Members

+++++ + + + + + + + + + + + + + + + + + +

CAIRO_LINE_JOIN_MITER	+ use a sharp (angled) corner, see +`cairo_set_miter_limit()` (Since 1.0) +
CAIRO_LINE_JOIN_ROUND	+ use a rounded join, the center of the circle is the +joint point (Since 1.0) +
CAIRO_LINE_JOIN_BEVEL	+ use a cut-off join, the join is cut off at half +the line width from the joint point (Since 1.0) +

Since: 1.0

enum cairo_operator_t

cairo_operator_t is used to set the compositing operator for all cairo +drawing operations.

The default operator is CAIRO_OPERATOR_OVER.

The operators marked as unbounded modify their +destination even outside of the mask layer (that is, their effect is not +bound by the mask layer). However, their effect can still be limited by +way of clipping.

To keep things simple, the operator descriptions here +document the behavior for when both source and destination are either fully +transparent or fully opaque. The actual implementation works for +translucent layers too. +For a more detailed explanation of the effects of each operator, including +the mathematical definitions, see

+https://cairographics.org/operators/. +

Members

CAIRO_OPERATOR_CLEAR	+ clear destination layer (bounded) (Since 1.0) +
CAIRO_OPERATOR_SOURCE	+ replace destination layer (bounded) (Since 1.0) +
CAIRO_OPERATOR_OVER	+ draw source layer on top of destination layer +(bounded) (Since 1.0) +
CAIRO_OPERATOR_IN	+ draw source where there was destination content +(unbounded) (Since 1.0) +
CAIRO_OPERATOR_OUT	+ draw source where there was no destination +content (unbounded) (Since 1.0) +
CAIRO_OPERATOR_ATOP	+ draw source on top of destination content and +only there (Since 1.0) +
CAIRO_OPERATOR_DEST	+ ignore the source (Since 1.0) +
CAIRO_OPERATOR_DEST_OVER	+ draw destination on top of source (Since 1.0) +
CAIRO_OPERATOR_DEST_IN	+ leave destination only where there was +source content (unbounded) (Since 1.0) +
CAIRO_OPERATOR_DEST_OUT	+ leave destination only where there was no +source content (Since 1.0) +
CAIRO_OPERATOR_DEST_ATOP	+ leave destination on top of source content +and only there (unbounded) (Since 1.0) +
CAIRO_OPERATOR_XOR	+ source and destination are shown where there is only +one of them (Since 1.0) +
CAIRO_OPERATOR_ADD	+ source and destination layers are accumulated (Since 1.0) +
CAIRO_OPERATOR_SATURATE	+ like over, but assuming source and dest are +disjoint geometries (Since 1.0) +
CAIRO_OPERATOR_MULTIPLY	+ source and destination layers are multiplied. +This causes the result to be at least as dark as the darker inputs. (Since 1.10) +
CAIRO_OPERATOR_SCREEN	+ source and destination are complemented and +multiplied. This causes the result to be at least as light as the lighter +inputs. (Since 1.10) +
CAIRO_OPERATOR_OVERLAY	+ multiplies or screens, depending on the +lightness of the destination color. (Since 1.10) +
CAIRO_OPERATOR_DARKEN	+ replaces the destination with the source if it +is darker, otherwise keeps the source. (Since 1.10) +
CAIRO_OPERATOR_LIGHTEN	+ replaces the destination with the source if it +is lighter, otherwise keeps the source. (Since 1.10) +
CAIRO_OPERATOR_COLOR_DODGE	+ brightens the destination color to reflect +the source color. (Since 1.10) +
CAIRO_OPERATOR_COLOR_BURN	+ darkens the destination color to reflect +the source color. (Since 1.10) +
CAIRO_OPERATOR_HARD_LIGHT	+ Multiplies or screens, dependent on source +color. (Since 1.10) +
CAIRO_OPERATOR_SOFT_LIGHT	+ Darkens or lightens, dependent on source +color. (Since 1.10) +
CAIRO_OPERATOR_DIFFERENCE	+ Takes the difference of the source and +destination color. (Since 1.10) +
CAIRO_OPERATOR_EXCLUSION	+ Produces an effect similar to difference, but +with lower contrast. (Since 1.10) +
CAIRO_OPERATOR_HSL_HUE	+ Creates a color with the hue of the source +and the saturation and luminosity of the target. (Since 1.10) +
CAIRO_OPERATOR_HSL_SATURATION	+ Creates a color with the saturation +of the source and the hue and luminosity of the target. Painting with +this mode onto a gray area produces no change. (Since 1.10) +
CAIRO_OPERATOR_HSL_COLOR	+ Creates a color with the hue and saturation +of the source and the luminosity of the target. This preserves the gray +levels of the target and is useful for coloring monochrome images or +tinting color images. (Since 1.10) +
CAIRO_OPERATOR_HSL_LUMINOSITY	+ Creates a color with the luminosity of +the source and the hue and saturation of the target. This produces an +inverse effect to `CAIRO_OPERATOR_HSL_COLOR` +. (Since 1.10) +

Since: 1.0

cairo_rectangle_t

typedef struct {
+    double x, y, width, height;
+} cairo_rectangle_t;
+

A data structure for holding a rectangle.

Members

+++++ + + + + + + + + + + + + + + + + + + + + + + +

double `x`;	X coordinate of the left side of the rectangle
double `y`;	Y coordinate of the the top side of the rectangle
double `width`;	width of the rectangle
double `height`;	height of the rectangle

Since: 1.4

cairo_rectangle_list_t

typedef struct {
+    cairo_status_t     status;
+    cairo_rectangle_t *rectangles;
+    int                num_rectangles;
+} cairo_rectangle_list_t;
+

A data structure for holding a dynamically allocated +array of rectangles.

Members

+++++ + + + + + + + + + + + + + + + + + +

cairo_status_t `status`;	Error status of the rectangle list
cairo_rectangle_t *`rectangles`;	Array containing the rectangles
int `num_rectangles`;	Number of rectangles in this list

Since: 1.4