type antialias_t[link]

type antialias_t = enum {
	DEFAULT,
	NONE,
	GRAY,
	SUBPIXEL,
	FAST,
	GOOD,
	BEST,
};

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

Members

• DEFAULT: Use the default antialiasing for the subsystem and target device
• NONE: Use a bilevel alpha mask
• GRAY: Perform single-color antialiasing (using shades of gray for black text on a white background, for example)
• SUBPIXEL: Perform antialiasing by taking advantage of the order of subpixel elements on devices such as LCD panels
• FAST: Hint that the backend should perform some antialiasing but prefer speed over quality
• GOOD: The backend should balance quality against performance
• BEST: Hint that the backend should render at the highest quality, sacrificing speed if necessary

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, FAST and GOOD will be mapped to GRAY, with BEST being equivalent to SUBPIXEL.

The interpretation of DEFAULT is left entirely up to the backend, typically this will be similar to GOOD.

type content_t[link]

type content_t = enum {
	COLOR = 4096,
	ALPHA = 8192,
	COLOR_ALPHA = 12288,
};

A content_t is used to describe the content that a surface will contain, whether color information, alpha information (translucence vs. opacity), or both.

type context_t[link]

type context_t = opaque;

The cairo drawing context context_t is the main object used when drawing with cairo. To draw with cairo, you create a context_t, set the target surface, and drawing options for the context_t, create shapes with functions like move_to and line_to, and then draw shapes with stroke or fill.

context_t's can be pushed to a stack via save. They may then safely be changed, without losing the current state. Use restore to restore to the saved state.

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

Memory management of context_t is done with reference and destroy.

type destroy_func_t[link]

type destroy_func_t = nullable *fn(data: *opaque) void;

destroy_func_t the type of function which is called when a data element is destroyed. It is passed the pointer to the data element and should free any memory and resources allocated for it.

type device_t[link]

type device_t = opaque;

A device_t represents the driver interface for drawing operations to a surface_t. There are different subtypes of device_t for different drawing backends; for example, cairo_egl_device_create() creates a device that wraps an EGL display and context.

The type of a device can be queried with cairo::device::get_type.

Memory management of device_t is done with cairo::device::reference and cairo::device::destroy.

type device_type_t[link]

type device_type_t = enum {
	DRM, // The device is of type Direct Render Manager
	GL, // The device is of type OpenGL
	SCRIPT, // The device is of type script
	XCB, // The device is of type xcb
	XLIB, // The device is of type xlib
	XML, // The device is of type XML
	COGL, // The device is of type cogl
	WIN32, // The device is of type win32
	INVALID = -1, // The device is invalid
};

device_type_t is used to describe the type of a given device. The devices types are also known as "backends" within cairo.

The device type can be queried with cairo::device::get_type. The various cairo::device_t functions can be used with devices of any type, but some backends also provide type-specific functions that must only be called with a device of the appropriate type. These functions have names that begin with cairo_type_device such as cairo::xcb_device::debug_cap_xrender_version.

The behavior of calling a type-specific function with a device of the wrong type is undefined.

type extend_t[link]

type extend_t = enum {
	NONE,
	REPEAT,
	REFLECT,
	PAD,
};

An extend_t is used to describe how pattern color/alpha will be determined for areas "outside" the pattern's natural area, (for example, outside the surface bounds or outside the gradient geometry).

Mesh patterns are not affected by the extend mode.

The default extend mode is NONE for surface patterns and PAD for gradient patterns.

Members

• NONE: pixels outside of the source pattern are fully transparent
• REPEAT: the pattern is tiled by repeating
• REFLECT: the pattern is tiled by reflecting at the edges
• PAD: pixels outside of the pattern copy the closest pixel from the source

type fill_rule_t[link]

type fill_rule_t = enum {
	WINDING,
	EVEN_ODD,
};

A 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.)

Members

• 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.
• 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.

The default fill rule is WINDING.

type filter_t[link]

type filter_t = enum {
	FAST,
	GOOD,
	BEST,
	NEAREST,
	BILINEAR,
	GAUSSIAN,
};

A filter_t is used to indicate what filtering should be applied when reading pixel values from patterns. See cairo::pattern::set_filter for indicating the desired filter to be used with a particular pattern.

Members

• FAST: A high-performance filter, with quality similar to NEAREST
• GOOD: A reasonable-performance filter, with quality similar to BILINEAR
• BEST: The highest-quality available, performance may not be suitable for interactive use.
• NEAREST: Nearest-neighbor filtering
• BILINEAR: Linear interpolation in two dimensions
• GAUSSIAN: This filter value is currently unimplemented, and should not be used in current code.

type font_extents_t[link]

type font_extents_t = struct {
	ascent: f64,
	descent: f64,
	height: f64,
	max_x_advance: f64,
	max_y_advance: f64,
};

The font_extents_t structure stores metric information for a font. Values are given in the current user-space coordinate system.

Because font metrics are in user-space coordinates, they are mostly, but not entirely, independent of the current transformation matrix. If you call scale(cr, 2.0, 2.0), text will be drawn twice as big, but the reported text extents will not be doubled. They will change slightly due to hinting (so you can't assume that metrics are independent of the transformation matrix), but otherwise will remain unchanged.

Members

• ascent: the distance that the font extends above the baseline. Note that this is not always exactly equal to the maximum of the extents of all the glyphs in the font, but rather is picked to express the font designer's intent as to how the font should align with elements above it.
• descent: the distance that the font extends below the baseline. This value is positive for typical fonts that include portions below the baseline. Note that this is not always exactly equal to the maximum of the extents of all the glyphs in the font, but rather is picked to express the font designer's intent as to how the font should align with elements below it.
• height: the recommended vertical distance between baselines when setting consecutive lines of text with the font. This is greater than ascent +descent by a quantity known as the line spacing or external leading. When space is at a premium, most fonts can be set with only a distance of ascent +descent between lines.
• max_x_advance: the maximum distance in the X direction that the origin is advanced for any glyph in the font.
• max_y_advance: the maximum distance in the Y direction that the origin is advanced for any glyph in the font. This will be zero for normal fonts used for horizontal writing. (The scripts of East Asia are sometimes written vertically.)

type font_face_t[link]

type font_face_t = opaque;

A font_face_t specifies all aspects of a font other than the size or font matrix (a font matrix is used to distort a font by shearing it or scaling it unequally in the two directions). A font face can be set on a context_t by using set_font_face; the size and font matrix are set with set_font_size and set_font_matrix.

There are various types of font faces, depending on the font backend they use. The type of a font face can be queried using cairo::font_face::get_type.

Memory management of font_face_t is done with cairo::font_face::reference and cairo::font_face::destroy.

type font_options_t[link]

type font_options_t = opaque;

An opaque structure holding all options that are used when rendering fonts.

Individual features of a font_options_t can be set or accessed using functions named cairo::font_options::set_feature_name() and cairo::font_options::get_feature_name(), like cairo::font_options::set_antialias and cairo::font_options::get_antialias.

New features may be added to a cairo::font_options_t in the future. For this reason, cairo::font_options::copy, cairo::font_options::equal, cairo::font_options::merge, and cairo::font_options::hash should be used to copy, check for equality, merge, or compute a hash value of cairo::font_options_t objects.

type font_slant_t[link]

type font_slant_t = enum {
	NORMAL,
	ITALIC,
	OBLIQUE,
};

Specifies variants of a font face based on their slant.

Members

• NORMAL: Upright font style
• ITALIC: Italic font style
• OBLIQUE: Oblique font style

type font_type_t[link]

type font_type_t = enum {
	TOY,
	FT,
	WIN32,
	QUARTZ,
	USER,
};

A font_type_t is used to describe the type of a given font face or scaled font. The font types are also known as "font backends" within cairo.

The type of a font face is determined by the function used to create it, which will generally be of the form cairo::type_font_face::create(). The font face type can be queried with cairo::font_face::get_type.

The various cairo::font_face_t functions can be used with a font face of any type.

The type of a scaled font is determined by the type of the font face passed to cairo::scaled_font::create. The scaled font type can be queried with cairo::scaled_font::get_type.

The various cairo::scaled_font_t functions can be used with scaled fonts of any type, but some font backends also provide type-specific functions that must only be called with a scaled font of the appropriate type. These functions have names that begin with cairo::type_scaled_font such as cairo::ft_scaled_font::lock_face.

The behavior of calling a type-specific function with a scaled font of the wrong type is undefined.

Members

• TOY: The font was created using cairo's toy font api
• FT: The font is of type FreeType
• WIN32: The font is of type Win32
• QUARTZ: The font is of type Quartz
• USER: The font was create using cairo's user font api

type font_weight_t[link]

type font_weight_t = enum {
	NORMAL,
	BOLD,
};

Specifies variants of a font face based on their weight.

Members

• NORMAL: Normal font weight
• BOLD: Bold font weight

type format_t[link]

type format_t = enum {
	INVALID = -1,
	ARGB32 = 0,
	RGB24 = 1,
	A8 = 2,
	A1 = 3,
	RGB16_565 = 4,
	RGB30 = 5,
	RGB96F = 6,
	RGBA128F = 7,
};

A format_t is used to identify the memory format of image data.

Members

• INVALID: no such format exists or is supported.
• ARGB32: each pixel is a 32-bit quantity, with alpha in the upper 8 bits, then red, then green, then blue. The 32-bit quantities are stored native-endian. Pre-multiplied alpha is used. (That is, 50% transparent red is 0x80800000, not 0x80ff0000.)
• RGB24: each pixel is a 32-bit quantity, with the upper 8 bits unused. Red, Green, and Blue are stored in the remaining 24 bits in that order.
• A8: each pixel is a 8-bit quantity holding an alpha value.
• A1: each pixel is a 1-bit quantity holding an alpha value. Pixels are packed together into 32-bit quantities. The ordering of the bits matches the endianness of the platform. On a big-endian machine, the first pixel is in the uppermost bit, on a little-endian machine the first pixel is in the least-significant bit.
• RGB16_565: each pixel is a 16-bit quantity with red in the upper 5 bits, then green in the middle 6 bits, and blue in the lower 5 bits.
• RGB30: like RGB24 but with 10bpc
• RGB96F: 3 floats, R, G, B.
• RGBA128F: 4 floats, R, G, B, A.

type glyph_t[link]

type glyph_t = struct {
	index: u64,
	x: f64,
	y: f64,
};

The glyph_t structure holds information about a single glyph when drawing or measuring text. A font is (in simple terms) a collection of shapes used to draw text. A glyph is one of these shapes. There can be multiple glyphs for a single character (alternates to be used in different contexts, for example), or a glyph can be a ligature of multiple characters. Cairo doesn't expose any way of converting input text into glyphs, so in order to use the Cairo interfaces that take arrays of glyphs, you must directly access the appropriate underlying font system.

Note that the offsets given by x and y are not cumulative. When drawing or measuring text, each glyph is individually positioned with respect to the overall origin

Members

• index: glyph index in the font. The exact interpretation of the glyph index depends on the font technology being used.
• x: the offset in the X direction between the origin used for drawing or measuring the string and the origin of this glyph.
• y: the offset in the Y direction between the origin used for drawing or measuring the string and the origin of this glyph.

type hint_metrics_t[link]

type hint_metrics_t = enum {
	DEFAULT,
	OFF,
	ON,
};

Specifies whether to hint font metrics; hinting font metrics means quantizing them so that they are integer values in device space. Doing this improves the consistency of letter and line spacing, however it also means that text will be laid out differently at different zoom factors.

Members

• DEFAULT: Hint metrics in the default manner for the font backend and target device
• OFF: Do not hint font metrics
• ON: Hint font metrics

type hint_style_t[link]

type hint_style_t = enum {
	DEFAULT,
	NONE,
	SLIGHT,
	MEDIUM,
	FULL,
};

Specifies the type of hinting to do on font outlines. Hinting is the process of fitting outlines to the pixel grid in order to improve the appearance of the result. Since hinting outlines involves distorting them, it also reduces the faithfulness to the original outline shapes. Not all of the outline hinting styles are supported by all font backends.

Members

• DEFAULT: Use the default hint style for font backend and target device
• NONE: Do not hint outlines
• SLIGHT: Hint outlines slightly to improve contrast while retaining good fidelity to the original shapes
• MEDIUM: Hint outlines with medium strength giving a compromise between fidelity to the original shapes and contrast
• FULL: Hint outlines to maximize contrast

type line_cap_t[link]

type line_cap_t = enum {
	BUTT,
	ROUND,
	SQUARE,
};

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

Members

• BUTT: start(stop) the line exactly at the start(end) point
• ROUND: use a round ending, the center of the circle is the end point
• SQUARE: use squared ending, the center of the square is the end point

The default line cap style is BUTT.

type line_join_t[link]

type line_join_t = enum {
	MITER,
	ROUND,
	BEVEL,
};

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

Members

• MITER: use a sharp (angled) corner, see set_miter_limit
• ROUND: use a rounded join, the center of the circle is the joint point
• BEVEL: use a cut-off join, the join is cut off at half the line width from the joint point

The default line join style is MITER.

type matrix_t[link]

type matrix_t = struct {
	xx: f64,
	yx: f64,
	xy: f64,
	yy: f64,
	x0: f64,
	y0: f64,
};

A matrix_t holds an affine transformation, such as a scale, rotation, shear, or a combination of those.

Members

• xx: xx component of the affine transformation
• yx: yx component of the affine transformation
• xy: xy component of the affine transformation
• yy: yy component of the affine transformation
• x0: X translation component of the affine transformation
• y0: Y translation component of the affine transformation

The transformation of a point (x, y) is given by:

x_new = xx * x + xy * y + x0; y_new = yx * x + yy * y + y0;

type operator_t[link]

type operator_t = enum {
	CLEAR,
	SOURCE,
	OVER,
	IN,
	OUT,
	ATOP,
	DEST,
	DEST_OVER,
	DEST_IN,
	DEST_OUT,
	DEST_ATOP,
	XOR,
	ADD,
	SATURATE,
	MULTIPLY,
	SCREEN,
	OVERLAY,
	DARKEN,
	LIGHTEN,
	COLOR_DODGE,
	COLOR_BURN,
	HARD_LIGHT,
	SOFT_LIGHT,
	DIFFERENCE,
	EXCLUSION,
	HSL_HUE,
	HSL_SATURATION,
	HSL_COLOR,
	HSL_LUMINOSITY,
};

An operator_t is used to set the compositing operator for all cairo drawing operations.

Members

• CLEAR: clear destination layer (bounded)
• SOURCE: replace destination layer (bounded)
• OVER: draw source layer on top of destination layer (bounded)
• IN: draw source where there was destination content (unbounded)
• OUT: draw source where there was no destination content (unbounded)
• ATOP: draw source on top of destination content and only there
• DEST: ignore the source
• DEST_OVER: draw destination on top of source
• DEST_IN: leave destination only where there was source content (unbounded)
• DEST_OUT: leave destination only where there was no source content
• DEST_ATOP: leave destination on top of source content and only there (unbounded)
• XOR: source and destination are shown where there is only one of them
• ADD: source and destination layers are accumulated
• SATURATE: like over, but assuming source and dest are disjoint geometries
• MULTIPLY: source and destination layers are multiplied. This causes the result to be at least as dark as the darker inputs
• SCREEN: source and destination are complemented and multiplied. This causes the result to be at least as light as the lighter inputs
• OVERLAY: multiplies or screens, depending on the lightness of the destination color
• DARKEN: replaces the destination with the source if it is darker, otherwise keeps the source
• LIGHTEN: replaces the destination with the source if it is lighter, otherwise keeps the source
• COLOR_DODGE: brightens the destination color to reflect the source color
• COLOR_BURN: darkens the destination color to reflect the source color
• HARD_LIGHT: Multiplies or screens, dependent on source color
• SOFT_LIGHT: Darkens or lightens, dependent on source color
• DIFFERENCE: Takes the difference of the source and destination color
• EXCLUSION: Produces an effect similar to difference, but with lower contrast
• HSL_HUE: Creates a color with the hue of the source and the saturation and luminosity of the target
• 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.
• 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.
• 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 HSL_COLOR

The default operator is 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/.

type path_data_t[link]

type path_data_t = union {
	struct {
		type_: path_data_type_t,
		length: int,
	},
	struct {
		x: f64,
		y: f64,
	},
};

A path_data_t is used to represent the path data inside a path_t.

The data structure is designed to try to balance the demands of efficiency and ease-of-use. A path is represented as an array of path_data_t, which is a union of headers and points.

Each portion of the path is represented by one or more elements in the array, (one header followed by 0 or more points). The length value of the header is the number of array elements for the current portion including the header, (ie. length == 1 + # of points), and where the number of points for each element type is as follows:

• MOVE_TO: 1 point
• LINE_TO: 1 point
• CURVE_TO: 3 points
• CLOSE_PATH: 0 points

The semantics and ordering of the coordinate values are consistent with move_to, line_to, curve_to, and close_path.

Here is sample code for iterating through a path_t:

let path = cairo::copy_path(c)!; let data = path.data: *[*]cairo::path_data_t;

for (let i = 0; i < path.num_data; i += data[i].length: int) { switch (data[i].type_) { case cairo::path_data_type_t::MOVE_TO => do_move_to_things(data[i+1].x, data[i+1].y); case cairo::path_data_type_t::LINE_TO => do_line_to_things(data[i+1].x, data[i+1].y); case cairo::path_data_type_t::CURVE_TO => do_curve_to_things(data[i+1].x, data[i+1].y, data[i+2].x, data[i+2].y, data[i+3].x, data[i+3].y); case cairo::path_data_type_t::CLOSE_PATH => do_close_path_things(); }; }; cairo::path_destroy(path);

As of cairo 1.4, cairo does not mind if there are more elements in a portion of the path than needed. Such elements can be used by users of the cairo API to hold extra values in the path data structure. For this reason, it is recommended that applications always use data[i].length to iterate over the path data, instead of hardcoding the number of elements for each element type.

type path_data_type_t[link]

type path_data_type_t = enum {
	MOVE_TO, // A move-to operation
	LINE_TO, // A line-to operation
	CURVE_TO, // A curve-to operation
	CLOSE_PATH, // A close-path operation
};

A path_data_type_t is used to describe the type of one portion of a path when represented as a path_t. See path_data_t for details.

type path_t[link]

type path_t = struct {
	status: status_t,
	data: *path_data_t,
	num_data: int,
};

A data structure for holding a path. This data structure serves as the return value for copy_path and copy_path_flat as well the input value for append_path.

See path_data_t for hints on how to iterate over the actual data within the path.

The num_data member gives the number of elements in the data array. This number is larger than the number of independent path portions (defined in path_data_type_t, since the data includes both headers and coordinates for each portion.

Members

• status: the current error status
• data: the elements in the path
• num_data: the number of elements in the data array

type pattern_t[link]

type pattern_t = opaque;

A pattern_t represents a source when drawing onto a surface. There are different subtypes of pattern_t, for different types of sources; for example, cairo::pattern::create_rgb creates a pattern for a solid opaque color.

Other than various cairo::pattern::create_type() functions, some of the pattern types can be implicitly created using various cairo::set_source_type() functions; for example set_source_rgb.

The type of a pattern can be queried with cairo::pattern::get_type.

Memory management of pattern_t is done with cairo::pattern::reference and cairo::pattern::destroy.

type pattern_type_t[link]

type pattern_type_t = enum {
	SOLID,
	SURFACE,
	LINEAR,
	RADIAL,
	MESH,
	RASTER_SOURCE,
};

A pattern_type_t is used to describe the type of a given pattern. The type of a pattern is determined by the function used to create it. The cairo::pattern::create_rgb and cairo::pattern::create_rgba functions create SOLID patterns. The remaining cairo::pattern::create functions map to pattern types in obvious ways.

The pattern type can be queried with cairo::pattern::get_type Most pattern_t functions can be called with a pattern of any type, (though trying to change the extend or filter for a solid pattern will have no effect).

A notable exception is cairo::pattern::add_color_stop_rgb and cairo::pattern::add_color_stop_rgba which must only be called with gradient patterns (either LINEAR or RADIAL). Otherwise the pattern will be shutdown and put into an error state.

Members

• SOLID: The pattern is a solid (uniform) color. It may be opaque or translucent.
• SURFACE: The pattern is a based on a surface (an image)
• LINEAR: The pattern is a linear gradient
• RADIAL: The pattern is a radial gradient
• MESH: The pattern is a mesh
• RASTER_SOURCE: The pattern is a user pattern providing raster data

type pdf_metadata_t[link]

type pdf_metadata_t = enum {
	TITLE,
	AUTHOR,
	SUBJECT,
	KEYWORDS,
	CREATOR,
	CREATE_DATE,
	MOD_DATE,
};

A pdf_metadata_t is used by the cairo::pdf_surface::set_metadata function to specify the metadata to set.

Members

• TITLE: The document title
• AUTHOR: The document author
• SUBJECT: The document subject
• KEYWORDS: The document keywords
• CREATOR: The document creator
• CREATE_DATE: The document creation date
• MOD_DATE: The document modification date

type pdf_outline_flags_t[link]

type pdf_outline_flags_t = enum {
	OPEN = 1,
	BOLD = 2,
	ITALIC = 4,
};

A pdf_outline_flags_t is used by the cairo::pdf_surface::add_outline function to specify the attributes of an outline item. These flags may be bitwise-or'd to produce any combination of flags.

Members

• OPEN: The outline item defaults to open in the PDF viewer
• BOLD: The outline item is displayed by the viewer in bold text
• ITALIC: The outline item is displayed by the viewer in italic text

type pdf_version_t[link]

type pdf_version_t = enum {
	VERSION_1_4,
	VERSION_1_5,
};

A pdf_version_t is used to describe the version number of the PDF specification that a generated PDF file will conform to.

• VERSION_1_4: The version 1.4 of the PDF specification.
• VERSION_1_5: The version 1.5 of the PDF specification.

type rectangle_int_t[link]

type rectangle_int_t = struct {
	x: int,
	y: int,
	width: int,
	height: int,
};

A data structure for holding a rectangle with integer coordinates.

Members

• x: X coordinate of the left side of the rectangle
• y: Y coordinate of the the top side of the rectangle
• width: width of the rectangle
• height: height of the rectangle

type region_overlap_t[link]

type region_overlap_t = enum {
	IN,
	OUT,
	PART,
};

A region_overlap_t is used as the return value for cairo::region::contains_rectangle.

Members

• IN: The contents are entirely inside the region.
• OUT: The contents are entirely outside the region.
• PART: The contents are partially inside and partially outside the region.

type region_t[link]

type region_t = opaque;

A region_t represents a set of integer-aligned rectangles. It allows set-theoretical operations like cairo::region::union_ and cairo::region::intersect to be performed on them.

Memory management of region_t is done with cairo::region::reference and cairo::region::destroy.

type scaled_font_t[link]

type scaled_font_t = opaque;

A scaled_font_t is a font scaled to a particular size and device resolution. A scaled_font_t is most useful for low-level font usage where a library or application wants to cache a reference to a scaled font to speed up the computation of metrics.

There are various types of scaled fonts, depending on the font backend they use. The type of a scaled font can be queried using cairo::scaled_font::get_type.

Memory management of scaled_font_t is done with cairo::scaled_font::reference and cairo::scaled_font::destroy.

type status_t[link]

type status_t = enum {
	SUCCESS = 0,
	NO_MEMORY,
	INVALID_RESTORE,
	INVALID_POP_GROUP,
	NO_CURRENT_POINT,
	INVALID_MATRIX,
	INVALID_STATUS,
	NULL_POINTER,
	INVALID_STRING,
	INVALID_PATH_DATA,
	READ_ERROR,
	WRITE_ERROR,
	SURFACE_FINISHED,
	SURFACE_TYPE_MISMATCH,
	PATTERN_TYPE_MISMATCH,
	INVALID_CONTENT,
	INVALID_FORMAT,
	INVALID_VISUAL,
	FILE_NOT_FOUND,
	INVALID_DASH,
	INVALID_DSC_COMMENT,
	INVALID_INDEX,
	CLIP_NOT_REPRESENTABLE,
	TEMP_FILE_ERROR,
	INVALID_STRIDE,
	FONT_TYPE_MISMATCH,
	USER_FONT_IMMUTABLE,
	USER_FONT_ERROR,
	NEGATIVE_COUNT,
	INVALID_CLUSTERS,
	INVALID_SLANT,
	INVALID_WEIGHT,
	INVALID_SIZE,
	USER_FONT_NOT_IMPLEMENTED,
	DEVICE_TYPE_MISMATCH,
	DEVICE_ERROR,
	INVALID_MESH_CONSTRUCTION,
	DEVICE_FINISHED,
	JBIG2_GLOBAL_MISSING,
	PNG_ERROR,
	FREETYPE_ERROR,
	WIN32_GDI_ERROR,
	TAG_ERROR,
	LAST_STATUS,
};

A status_t is used to indicate errors that can occur when using Cairo. In some cases it is returned directly by functions. But when using context_t, the last error, if any, is stored in the context and can be retrieved with status.

type subpixel_order_t[link]

type subpixel_order_t = enum {
	DEFAULT,
	RGB,
	BGR,
	VRGB,
	VBGR,
};

The subpixel order specifies the order of color elements within each pixel on the display device when rendering with an antialiasing mode of antialias_t::SUBPIXEL.

Members

• DEFAULT: Use the default subpixel order for for the target device
• RGB: Subpixel elements are arranged horizontally with red at the left
• BGR: Subpixel elements are arranged horizontally with blue at the left
• VRGB: Subpixel elements are arranged vertically with red at the top
• VBGR: Subpixel elements are arranged vertically with blue at the top

type surface_t[link]

type surface_t = opaque;

A surface_t represents an image, either as the destination of a drawing operation or as source when drawing onto another surface. To draw to a surface_t, create a cairo context with the surface as the target, using create.

There are different subtypes of surface_t for different drawing backends; for example, cairo::image_surface::create creates a bitmap image in memory. The type of a surface can be queried with cairo::surface::get_type.

The initial contents of a surface after creation depend upon the manner of its creation. If cairo creates the surface and backing storage for the user, it will be initially cleared; for example, cairo::image_surface::create and cairo::surface::create_similar.

Alternatively, if the user passes in a reference to some backing storage and asks cairo to wrap that in a surface_t, then the contents are not modified; for example, cairo::image_surface::create_for_data and cairo::xlib_surface::create.

Memory management of surface_t is done with cairo::surface::reference and cairo::surface::destroy.

type surface_type_t[link]

type surface_type_t = enum {
	IMAGE,
	PDF,
	PS,
	XLIB,
	XCB,
	GLITZ,
	QUARTZ,
	WIN32,
	BEOS,
	DIRECTFB,
	SVG,
	OS2,
	WIN32_PRINTING,
	QUARTZ_IMAGE,
	SCRIPT,
	QT,
	RECORDING,
	VG,
	GL,
	DRM,
	TEE,
	XML,
	SKIA,
	SUBSURFACE,
	COGL,
};

A surface_type_t is used to describe the type of a given surface. The surface types are also known as "backends" or "surface backends" within cairo.

The type of a surface is determined by the function used to create it, which will generally be of the form cairo::type_surface::create(), (though see cairo::surface::create_similar as well).

The surface type can be queried with cairo::surface::get_type.

The various surface_t functions can be used with surfaces of any type, but some backends also provide type-specific functions that must only be called with a surface of the appropriate type. These functions have names that begin with cairo::type_surface such as cairo::image_surface::get_width.

The behavior of calling a type-specific function with a surface of the wrong type is undefined.

Members

• IMAGE: The surface is of type image
• PDF: The surface is of type pdf
• PS: The surface is of type ps
• XLIB: The surface is of type xlib
• XCB: The surface is of type xcb
• GLITZ: The surface is of type glitz
• QUARTZ: The surface is of type quartz
• WIN32: The surface is of type win32
• BEOS: The surface is of type beos
• DIRECTFB: The surface is of type directfb
• SVG: The surface is of type svg
• OS2: The surface is of type os2
• WIN32_PRINTING: The surface is a win32 printing surface
• QUARTZ_IMAGE: The surface is of type quartz_image
• SCRIPT: The surface is of type script
• QT: The surface is of type Qt
• RECORDING: The surface is of type recording
• VG: The surface is a OpenVG surface
• GL: The surface is of type OpenGL
• DRM: The surface is of type Direct Render Manager
• TEE: The surface is of type 'tee' (a multiplexing surface)
• XML: The surface is of type XML (for debugging)
• SKIA
• SUBSURFACE: The surface is a subsurface created with cairo::surface::create_for_rectangle
• COGL: This surface is of type Cogl

type svg_unit_t[link]

type svg_unit_t = enum {
	USER = 0,
	EM,
	EX,
	PX,
	IN,
	CM,
	MM,
	PT,
	PC,
	PERCENT,
};

A svg_unit_t is used to describe the units valid for coordinates and lengths in the SVG specification. See also:

• https://www.w3.org/TR/SVG/coords.htmlUnits
• https://www.w3.org/TR/SVG/types.htmlDataTypeLength
• https://www.w3.org/TR/css-values-3/lengths

type svg_version_t[link]

type svg_version_t = enum {
	VERSION_1_1,
	VERSION_1_2,
};

A svg_version_t is used to describe the version number of the SVG specification that a generated SVG file will conform to.

Members

• VERSION_1_1: The version 1.1 of the SVG specification.
• VERSION_1_2: The version 1.2 of the SVG specification.

type text_cluster_flags_t[link]

type text_cluster_flags_t = enum {
	BACKWARD = 1,
};

Specifies properties of a text cluster mapping.

Members

• BACKWARD: The clusters in the cluster array map to glyphs in the glyph array from end to start.

type text_cluster_t[link]

type text_cluster_t = struct {
	num_bytes: int,
	num_glyphs: int,
};

The text_cluster_t structure holds information about a single text cluster. A text cluster is a minimal mapping of some glyphs corresponding to some UTF-8 text.

For a cluster to be valid, both num_bytes and num_glyphs should be non-negative, and at least one should be non-zero. Note that clusters with zero glyphs are not as well supported as normal clusters. For example, PDF rendering applications typically ignore those clusters when PDF text is being selected.

See show_text_glyphs for how clusters are used in advanced text operations.

Members

• num_bytes: the number of bytes of UTF-8 text covered by cluster
• num_glyphs: the number of glyphs covered by cluster

type text_extents_t[link]

type text_extents_t = struct {
	x_bearing: f64,
	y_bearing: f64,
	width: f64,
	height: f64,
	x_advance: f64,
	y_advance: f64,
};

The text_extents_t structure stores the extents of a single glyph or a string of glyphs in user-space coordinates. Because text extents are in user-space coordinates, they are mostly, but not entirely, independent of the current transformation matrix. If you call scale(cr, 2.0, 2.0), text will be drawn twice as big, but the reported text extents will not be doubled. They will change slightly due to hinting (so you can't assume that metrics are independent of the transformation matrix), but otherwise will remain unchanged.

Members

• x_bearing: the horizontal distance from the origin to the leftmost part of the glyphs as drawn. Positive if the glyphs lie entirely to the right of the origin.
• y_bearing: the vertical distance from the origin to the topmost part of the glyphs as drawn. Positive only if the glyphs lie completely below the origin; will usually be negative.
• width: width of the glyphs as drawn
• height: height of the glyphs as drawn
• x_advance: distance to advance in the X direction after drawing these glyphs
• y_advance: distance to advance in the Y direction after drawing these glyphs. Will typically be zero except for vertical text layout as found in East-Asian languages.

type user_data_key_t[link]

type user_data_key_t = struct {
	unused: int,
};

user_data_key_t is used for attaching user data to cairo data structures. The actual contents of the struct is never used, and there is no need to initialize the object; only the unique address of a user_data_key_t object is used. Typically, you would just use the address of a static user_data_key_t object.

type user_scaled_font_init_func_t[link]

type user_scaled_font_init_func_t = *fn(scaled_font: *scaled_font_t, cr: *context_t, extents: *font_extents_t) status_t;

cairo::user_scaled_font_init_func_t is the type of function which is called when a scaled-font needs to be created for a user font-face.

The cairo context cr is not used by the caller, but is prepared in font space, similar to what the cairo contexts passed to the render_glyph method will look like. The callback can use this context for extents computation for example. After the callback is called, cr is checked for any error status.

The extents argument is where the user font sets the font extents for scaled_font. It is in font space, which means that for most cases its ascent and descent members should add to 1.0. extents is preset to hold a value of 1.0 for ascent, height, and max_x_advance, and 0.0 for descent and max_y_advance members.

The callback is optional. If not set, default font extents as described in the previous paragraph will be used.

Note that scaled_font is not fully initialized at this point and trying to use it for text operations in the callback will result in deadlock.

Parameters

• scaled_font: the scaled-font being created
• cr: a cairo context, in font space
• extents: font extents to fill in, in font space

Returns SUCCESS upon success, or an error status on error.

type user_scaled_font_render_glyph_func_t[link]

type user_scaled_font_render_glyph_func_t = *fn(scaled_font: *scaled_font_t, glyph: u64, cr: *context_t, extents: *text_extents_t) status_t;

cairo::user_scaled_font_render_glyph_func_t is the type of function which is called when a user scaled-font needs to render a glyph.

The callback is mandatory, and expected to draw the glyph with code glyph to the cairo context cr. cr is prepared such that the glyph drawing is done in font space. That is, the matrix set on cr is the scale matrix of scaled_font. The extents argument is where the user font sets the font extents for scaled_font. However, if user prefers to draw in user space, they can achieve that by changing the matrix on cr. All cairo rendering operations to cr are permitted, however, the result is undefined if any source other than the default source on cr is used. That means, glyph bitmaps should be rendered using mask instead of paint.

Other non-default settings on cr include a font size of 1.0 (given that it is set up to be in font space), and font options corresponding to scaled_font.

The extents argument is preset to have x_bearing, width, and y_advance of zero, y_bearing set to -font_extents.ascent, height to font_extents.ascent+font_extents.descent, and x_advance to font_extents.max_x_advance. The only field user needs to set in majority of cases is x_advance. If the width field is zero upon the callback returning (which is its preset value), the glyph extents are automatically computed based on the drawings done to cr. This is in most cases exactly what the desired behavior is. However, if for any reason the callback sets the extents, it must be ink extents, and include the extents of all drawing done to cr in the callback.

Parameters

• scaled_font: user scaled-font
• glyph: glyph code to render
• cr: cairo context to draw to, in font space
• extents: glyph extents to fill in, in font space

Returns SUCCESS upon success, or USER_FONT_ERROR or any other error status on error.

type user_scaled_font_text_to_glyphs_func_t[link]

type user_scaled_font_text_to_glyphs_func_t = *fn(scaled_font: *scaled_font_t, utf8: *const types::c::char, utf8_len: int, glyphs: nullable **glyph_t, num_glyphs: *int, clusters: nullable **text_cluster_t, num_clusters: *int, cluster_flags: nullable *text_cluster_flags_t) status_t;

cairo::user_scaled_font_text_to_glyphs_func_t is the type of function which is called to convert input text to an array of glyphs. This is used by the show_text operation.

Using this callback the user-font has full control on glyphs and their positions. That means, it allows for features like ligatures and kerning, as well as complex shaping required for scripts like Arabic and Indic.

The num_glyphs argument is preset to the number of glyph entries available in the glyphs buffer. If the glyphs buffer is null, the value of num_glyphs will be zero. If the provided glyph array is too short for the conversion (or for convenience), a new glyph array may be allocated using glyph_allocate and placed in glyphs. Upon return, num_glyphs should contain the number of generated glyphs. If the value glyphs points at has changed after the call, the caller will free the allocated glyph array using glyph_free. The caller will also free the original value of glyphs, so the callback shouldn't do so. The callback should populate the glyph indices and positions (in font space) assuming that the text is to be shown at the origin.

If clusters is not null, num_clusters and cluster_flags are also non-null, and cluster mapping should be computed. The semantics of how cluster array allocation works is similar to the glyph array. That is, if clusters initially points to a non-null value, that array may be used as a cluster buffer, and num_clusters points to the number of cluster entries available there. If the provided cluster array is too short for the conversion (or for convenience), a new cluster array may be allocated using cairo::text_cluster::allocate and placed in clusters . In this case, the original value of clusters will still be freed by the caller. Upon return, num_clusters should contain the number of generated clusters. If the value clusters points at has changed after the call, the caller will free the allocated cluster array using cairo::text_cluster::free_.

The callback is optional. If num_glyphs is negative upon the callback returning or if the return value is USER_FONT_NOT_IMPLEMENTED, the unicode_to_glyph callback is tried. See user_scaled_font_unicode_to_glyph_func_t.

Note: While cairo does not impose any limitation on glyph indices, some applications may assume that a glyph index fits in a 16-bit unsigned integer. As such, it is advised that user-fonts keep their glyphs in the 0 to 65535 range. Furthermore, some applications may assume that glyph 0 is a special glyph-not-found glyph. User-fonts are advised to use glyph 0 for such purposes and do not use that glyph value for other purposes.

Parameters

• scaled_font: the scaled-font being created
• utf8: a string of text encoded in UTF-8
• utf8_len: length of utf8 in bytes
• glyphs: pointer to array of glyphs to fill, in font space
• num_glyphs: pointer to number of glyphs
• clusters: pointer to array of cluster mapping information to fill, or null
• num_clusters: pointer to number of clusters
• cluster_flags: pointer to location to store cluster flags corresponding to the output clusters

Returns SUCCESS upon success, USER_FONT_NOT_IMPLEMENTED if fallback options should be tried, or USER_FONT_ERROR or any other error status on error.

type user_scaled_font_unicode_to_glyph_func_t[link]

type user_scaled_font_unicode_to_glyph_func_t = *fn(scaled_font: *scaled_font_t, unicode: u64, glyph_index: *u64) status_t;

cairo::user_scaled_font_unicode_to_glyph_func_t is the type of function which is called to convert an input Unicode character to a single glyph. This is used by the show_text operation.

This callback is used to provide the same functionality as the text_to_glyphs callback does (see user_scaled_font_text_to_glyphs_func_t) but has much less control on the output, in exchange for increased ease of use. The inherent assumption to using this callback is that each character maps to one glyph, and that the mapping is context independent. It also assumes that glyphs are positioned according to their advance width. These mean no ligatures, kerning, or complex scripts can be implemented using this callback.

The callback is optional, and only used if text_to_glyphs callback is not set or fails to return glyphs. If this callback is not set or if it returns USER_FONT_NOT_IMPLEMENTED, an identity mapping from Unicode code-points to glyph indices is assumed.

Note: While cairo does not impose any limitation on glyph indices, some applications may assume that a glyph index fits in a 16-bit unsigned integer. As such, it is advised that user-fonts keep their glyphs in the 0 to 65535 range. Furthermore, some applications may assume that glyph 0 is a special glyph-not-found glyph. User-fonts are advised to use glyph 0 for such purposes and do not use that glyph value for other purposes.

Parameters

• scaled_font: the scaled-font being created
• unicode: input unicode character code-point
• glyph_index: output glyph index

Returns SUCCESS upon success, USER_FONT_NOT_IMPLEMENTED if fallback options should be tried, or USER_FONT_ERROR or any other error status on error.

type error[link]

type error = !status_t;

All cairo errors. See strerror.

def PDF_OUTLINE_ROOT[link]

def PDF_OUTLINE_ROOT: int = 0;

The root outline item in cairo::pdf_surface::add_outline.

fn append_path[link]

fn append_path(cr: *context_t, path: *path_t) void;

Append the path onto the current path. The path may be either the return value from one of copy_path or copy_path_flat or it may be constructed manually. See path_t for details on how the path data structure should be initialized, and note that path.status must be initialized to status_t::SUCCESS.

Parameters

• cr: a cairo context
• path: path to be appended

fn arc[link]

fn arc(cr: *context_t, xc: f64, yc: f64, radius: f64, angle1: f64, angle2: f64) void;

Adds a circular arc of the given radius to the current path. The arc is centered at (xc, yc), begins at angle1 and proceeds in the direction of increasing angles to end at angle2. If angle2 is less than angle1 it will be progressively increased by 2*PI until it is greater than angle1.

If there is a current point, an initial line segment will be added to the path to connect the current point to the beginning of the arc. If this initial line is undesired, it can be avoided by calling new_sub_path before calling arc.

Angles are measured in radians. An angle of 0.0 is in the direction of the positive X axis (in user space). An angle of PI/2.0 radians (90 degrees) is in the direction of the positive Y axis (in user space). Angles increase in the direction from the positive X axis toward the positive Y axis. So with the default transformation matrix, angles increase in a clockwise direction.

This function gives the arc in the direction of increasing angles; see arc_negative to get the arc in the direction of decreasing angles.

The arc is circular in user space. To achieve an elliptical arc, you can scale the current transformation matrix by different amounts in the X and Y directions. For example, to draw an ellipse in the box given by x, y, width, height:

cairo::save(cr); cairo::translate(cr, x + width / 2.0, y + height / 2.0); cairo::scale(cr, width / 2.0, height / 2.0); cairo::arc(cr, 0.0, 0.0, 1.0, 0.0, 2.0*math::PI); cairo::restore(cr);

Parameters

• cr: a cairo context
• xc: X position of the center of the arc
• yc: Y position of the center of the arc
• radius: the radius of the arc
• angle1: the start angle, in radians
• angle2: the end angle, in radians

fn arc_negative[link]

fn arc_negative(cr: *context_t, xc: f64, yc: f64, radius: f64, angle1: f64, angle2: f64) void;

Adds a circular arc of the given radius to the current path. The arc is centered at (xc, yc), begins at angle1 and proceeds in the direction of decreasing angles to end at angle2. If angle2 is greater than angle1 it will be progressively decreased by 2*PI until it is less than angle1.

See arc for more details. This function differs only in the direction of the arc between the two angles.

Parameters

• cr: a cairo context
• xc: X position of the center of the arc
• yc: Y position of the center of the arc
• radius: the radius of the arc
• angle1: the start angle, in radians
• angle2: the end angle, in radians

fn clip[link]

fn clip(cr: *context_t) void;

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

After 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 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 clip within a save/restore pair. The only other means of increasing the size of the clip region is reset_clip.

fn clip_extents[link]

fn clip_extents(cr: *context_t) (f64, f64, f64, f64);

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

Returns a tuple (x1, y1, x2, y2).

• x1: left of the resulting extents
• y1: top of the resulting extents
• x2: right of the resulting extents
• y2: bottom of the resulting extents

fn clip_preserve[link]

fn clip_preserve(cr: *context_t) void;

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

Unlike clip, 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 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 clip_preserve within a save/restore pair. The only other means of increasing the size of the clip region is reset_clip.

fn close_path[link]

fn close_path(cr: *context_t) void;

Adds a line segment to the path from the current point to the beginning of the current sub-path, (the most recent point passed to move_to), and closes this sub-path. After this call the current point will be at the joined endpoint of the sub-path.

The behavior of close_path is distinct from simply calling line_to with the equivalent coordinate in the case of stroking. When a closed sub-path is stroked, there are no caps on the ends of the sub-path. Instead, there is a line join connecting the final and initial segments of the sub-path.

If there is no current point before the call to close_path, this function will have no effect.

Note: As of cairo version 1.2.4 any call to close_path will place an explicit MOVE_TO element into the path immediately after the CLOSE_PATH element, (which can be seen in copy_path for example). This can simplify path processing in some cases as it may not be necessary to save the "last move_to point" during processing as the MOVE_TO immediately after the CLOSE_PATH will provide that point.

fn copy_page[link]

fn copy_page(cr: *context_t) void;

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 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.

fn copy_path[link]

fn copy_path(cr: *context_t) (*path_t | error);

Creates a copy of the current path and returns it to the user as a path_t. See path_data_t for hints on how to iterate over the returned data structure.

Returns the copy of the current path. The caller owns the returned object and should call path_destroy when finished with it.

fn copy_path_flat[link]

fn copy_path_flat(cr: *context_t) (*path_t | error);

Gets a flattened copy of the current path and returns it to the user as a path_t. See path_data_t for hints on how to iterate over the returned data structure.

This function is like copy_path except that any curves in the path will be approximated with piecewise-linear approximations, (accurate to within the current tolerance value). That is, the result is guaranteed to not have any elements of type path_data_type_t::CURVE_TO which will instead be replaced by a series of path_data_type_t::LINE_TO elements.

Returns the copy of the current path. The caller owns the returned object and should call path_destroy when finished with it. If an error occurs, cairo::error is returned instead.

fn create[link]

fn create(target: *surface_t) (*context_t | error);

Creates a new context_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.

Returns a newly allocated context_t with a reference count of 1. The initial reference count should be released with destroy when you are done using the context_t. If an error such as out of memory occurs, cairo::error is returned instead.

fn curve_to[link]

fn curve_to(cr: *context_t, x1: f64, y1: f64, x2: f64, y2: f64, x3: f64, y3: f64) void;

Adds a cubic Bézier spline to the path from the current point to position (x3, y3) in user-space coordinates, using (x1, y1) and (x2, y2) as the control points. After this call the current point will be (x3, y3).

If there is no current point before the call to curve_to this function will behave as if preceded by a call to move_to(cr, x1, y1).

Parameters

• cr: a cairo context
• x1: the X coordinate of the first control point
• y1: the Y coordinate of the first control point
• x2: the X coordinate of the second control point
• y2: the Y coordinate of the second control point
• x3: the X coordinate of the end of the curve
• y3: the Y coordinate of the end of the curve

fn debug_reset_static_data[link]

fn debug_reset_static_data() void;

Resets all static data within cairo to its original state, (ie. identical to the state at the time of program invocation). For example, all caches within cairo will be flushed empty.

This function is intended to be useful when using memory-checking tools such as valgrind. When valgrind's memcheck analyzes a cairo-using program without a call to debug_reset_static_data, it will report all data reachable via cairo's static objects as "still reachable". Calling debug_reset_static_data just prior to program termination will make it easier to get squeaky clean reports from valgrind.

WARNING: It is only safe to call this function when there are no active cairo objects remaining, (ie. the appropriate destroy functions have been called as necessary). If there are active cairo objects, this call is likely to cause a crash, (eg. an assertion failure due to a hash table being destroyed when non-empty).

fn destroy[link]

fn destroy(cr: *context_t) void;

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

fn device_to_user[link]

fn device_to_user(cr: *context_t, x: f64, y: f64) (f64, f64);

Transform a coordinate from device space to user space by multiplying the given point by the inverse of the current transformation matrix (CTM).

Parameters

• cr: a cairo context
• x: X value of coordinate
• y: Y value of coordinate

fn device_to_user_distance[link]

fn device_to_user_distance(cr: *context_t, dx: *f64, dy: *f64) void;

Transform a distance vector from device space to user space. This function is similar to device_to_user except that the translation components of the inverse CTM will be ignored when transforming (dx, dy).

Parameters

• cr: a cairo context
• dx: X component of a distance vector
• dy: Y component of a distance vector

fn fill[link]

fn fill(cr: *context_t) void;

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

fn fill_extents[link]

fn fill_extents(cr: *context_t, x1: *f64, y1: *f64, x2: *f64, y2: *f64) void;

XXX: HAREFY. Computes a bounding box in user coordinates covering the area that would be affected, (the "inked" area), by a 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 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 fill_extents must necessarily do more work to compute the precise inked areas in light of the fill rule, so path_extents may be more desirable for sake of performance if the non-inked path extents are desired.

See fill, set_fill_rule and 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

fn fill_preserve[link]

fn fill_preserve(cr: *context_t) void;

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

See set_fill_rule and fill.

fn get_antialias[link]

fn get_antialias(cr: *context_t) antialias_t;

Gets the current shape antialiasing mode, as set by set_antialias.

fn get_current_point[link]

fn get_current_point(cr: *context_t) ((f64, f64) | error);

Gets the current point of the current path, which is conceptually the final point reached by the path so far.

The current point is returned in the user-space coordinate system. If there is no defined current point or if cr is in an error status, this function will return an error.

Most path construction functions alter the current point. See the following for details on how they affect the current point: new_path, new_sub_path, append_path, close_path, move_to, line_to, curve_to, rel_move_to, rel_line_to, rel_curve_to, arc, arc_negative, rectangle, text_path, glyph_path.

Some functions use and alter the current point but do not otherwise change current path: show_text.

Some functions unset the current path and as a result, current point: fill, stroke.

fn get_dash[link]

fn get_dash(cr: *context_t, dashes: *f64, offset_: *f64) void;

XXX: HAREFY. Gets the current dash array. If not NULL, dashes should be big enough to hold at least the number of values returned by get_dash_count.

Parameters

• cr: a cairo context
• dashes: return value for the dash array, or NULL
• offset_: return value for the current dash offset, or NULL

fn get_dash_count[link]

fn get_dash_count(cr: *context_t) int;

XXX: HAREFY. This function returns the length of the dash array in cr (0 if dashing is not currently in effect). See also set_dash and get_dash.

fn get_fill_rule[link]

fn get_fill_rule(cr: *context_t) fill_rule_t;

Gets the current fill rule, as set by set_fill_rule.

fn get_font_face[link]

fn get_font_face(cr: *context_t) (*font_face_t | error);

Returns the current font face. This object is owned by cairo. To keep a reference to it, you must call cairo::font_face::reference. If an error occurs, cairo::error is returned instead.

fn get_font_matrix[link]

fn get_font_matrix(cr: *context_t) matrix_t;

Returns the current font matrix. See set_font_matrix.

fn get_group_target[link]

fn get_group_target(cr: *context_t) (*surface_t | error);

Gets the current destination surface for the context. This is either the original target surface as passed to create or the target surface for the current group as started by the most recent call to push_group or push_group_with_content.

Returns the target surface. This object is owned by cairo. To keep a reference to it, you must call cairo::surface::reference.

fn get_line_cap[link]

fn get_line_cap(cr: *context_t) line_cap_t;

Gets the current line cap style, as set by set_line_cap.

fn get_line_join[link]

fn get_line_join(cr: *context_t) line_join_t;

Gets the current line join style, as set by set_line_join.

fn get_line_width[link]

fn get_line_width(cr: *context_t) f64;

This function returns the current line width value exactly as set by set_line_width. Note that the value is unchanged even if the CTM has changed between the calls to set_line_width and get_line_width.

fn get_matrix[link]

fn get_matrix(cr: *context_t) matrix_t;

Returns the current transformation matrix (CTM).

fn get_miter_limit[link]

fn get_miter_limit(cr: *context_t) f64;

Gets the current miter limit, as set by set_miter_limit.

fn get_operator[link]

fn get_operator(cr: *context_t) operator_t;

Gets the current compositing operator for a cairo context.

fn get_reference_count[link]

fn get_reference_count(cr: *context_t) uint;

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

fn get_source[link]

fn get_source(cr: *context_t) *pattern_t;

Returns the current source pattern. This object is owned by cairo. To keep a reference to it, you must call cairo::pattern::reference.

fn get_target[link]

fn get_target(cr: *context_t) (*surface_t | error);

Returns the target surface. This object is owned by cairo. To keep a reference to it, you must call cairo::surface::reference. If cr is in an error state, cairo::error is returned instead.

fn get_tolerance[link]

fn get_tolerance(cr: *context_t) f64;

Gets the current tolerance value, as set by set_tolerance.

fn glyph_extents[link]

fn glyph_extents(cr: *context_t, glyphs: []glyph_t) text_extents_t;

Gets the extents for an array of glyphs. The extents describe a user-space rectangle that encloses the "inked" portion of the glyphs, (as they would be drawn by show_glyphs). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by show_glyphs.

Note that whitespace glyphs do not contribute to the size of the rectangle (extents.width and extents.height).

Parameters

• cr: a cairo context
• glyphs: an array of glyph_t objects

fn glyph_path[link]

fn glyph_path(cr: *context_t, glyphs: []glyph_t) void;

Adds closed paths for the glyphs to the current path. The generated path if filled, achieves an effect similar to that of show_glyphs.

Parameters

• cr: a cairo context
• glyphs: array of glyphs to show

fn has_current_point[link]

fn has_current_point(cr: *context_t) bool;

Returns whether a current point is defined on the current path. See get_current_point for details on the current point.

fn identity_matrix[link]

fn identity_matrix(cr: *context_t) void;

Resets the current transformation matrix (CTM) by setting it equal to the identity matrix. That is, the user-space and device-space axes will be aligned and one user-space unit will transform to one device-space unit.

Parameters

• cr: a cairo context

fn in_clip[link]

fn in_clip(cr: *context_t, x: f64, y: f64) bool;

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 paint operation. See clip, and clip_preserve.

Parameters

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

Returns true if the point is inside, or false if outside.

fn in_fill[link]

fn in_fill(cr: *context_t, x: f64, y: f64) bool;

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

See fill, set_fill_rule and fill_preserve.

Parameters

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

Returns true if the point is inside, or false if outside.

fn in_stroke[link]

fn in_stroke(cr: *context_t, x: f64, y: f64) bool;

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

See stroke, set_line_width, set_line_join, set_line_cap, set_dash, and stroke_preserve.

Parameters

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

Returns true if the point is inside, or false if outside.

fn line_to[link]

fn line_to(cr: *context_t, x: f64, y: f64) void;

Adds a line to the path from the current point to position (x, y) in user-space coordinates. After this call the current point will be (x, y).

If there is no current point before the call to line_to this function will behave as move_to(cr, x, y).

Parameters

• cr: a cairo context
• x: the X coordinate of the end of the new line
• y: the Y coordinate of the end of the new line

fn mask[link]

fn mask(cr: *context_t, pattern: *pattern_t) void;

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.)

fn mask_surface[link]

fn mask_surface(cr: *context_t, surface: *surface_t, surface_x: f64, surface_y: f64) void;

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 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

fn move_to[link]

fn move_to(cr: *context_t, x: f64, y: f64) void;

Begin a new sub-path. After this call the current point will be (x, y).

Parameters

• cr: a cairo context
• x: the X coordinate of the new position
• y: the Y coordinate of the new position

fn new_path[link]

fn new_path(cr: *context_t) void;

Clears the current path. After this call there will be no path and no current point.

fn new_sub_path[link]

fn new_sub_path(cr: *context_t) void;

Begin a new sub-path. Note that the existing path is not affected. After this call there will be no current point.

In many cases, this call is not needed since new sub-paths are frequently started with move_to.

A call to new_sub_path is particularly useful when beginning a new sub-path with one of the arc calls. This makes things easier as it is no longer necessary to manually compute the arc's initial coordinates for a call to move_to.

fn paint[link]

fn paint(cr: *context_t) void;

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

fn paint_with_alpha[link]

fn paint_with_alpha(cr: *context_t, alpha: f64) void;

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 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)

fn path_destroy[link]

fn path_destroy(path: *path_t) void;

Immediately releases all memory associated with path. After a call to path_destroy the path pointer is no longer valid and should not be used further.

Note: path_destroy should only be called with a pointer to a path_t returned by a cairo function. Any path that is created manually (ie. outside of cairo) should be destroyed manually as well.

fn path_extents[link]

fn path_extents(cr: *context_t, x1: *f64, y1: *f64, x2: *f64, y2: *f64) void;

XXX: HAREFY. Computes a bounding box in user-space coordinates covering the points on the current path. If the current path is empty, returns an empty rectangle((0,0), (0,0)). Stroke parameters, fill rule, surface dimensions and clipping are not taken into account.

Contrast with fill_extents and stroke_extents which return the extents of only the area that would be "inked" by the corresponding drawing operations.

The result of path_extents is defined as equivalent to the limit of stroke_extents with line_cap_t::ROUND as the line width approaches 0.0, (but never reaching the empty-rectangle returned by stroke_extents for a line width of 0.0).

Specifically, this means that zero-area sub-paths such as move_to;line_to segments, (even degenerate cases where the coordinates to both calls are identical), will be considered as contributing to the extents. However, a lone move_to will not contribute to the results of path_extents.

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

fn pop_group[link]

fn pop_group(cr: *context_t) *pattern_t;

Terminates the redirection begun by a call to push_group or push_group_with_content and returns a new pattern containing the results of all drawing operations performed to the group.

The pop_group function calls restore, (balancing a call to save by the push_group function), so that any changes to the graphics state will not be visible outside the group.

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.

fn pop_group_to_source[link]

fn pop_group_to_source(cr: *context_t) void;

Terminates the redirection begun by a call to push_group or 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:

let 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.

The pop_group function calls restore, (balancing a call to save by the push_group function), so that any changes to the graphics state will not be visible outside the group.

fn push_group[link]

fn push_group(cr: *context_t) void;

Temporarily redirects drawing to an intermediate surface known as a group. The redirection lasts until the group is completed by a call to pop_group or 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 push_group/pop_group. Each call pushes/pops the new target group onto/from a stack.

The push_group function calls save so that any changes to the graphics state will not be visible outside the group, (the pop_group functions call restore).

By default the intermediate group will have a content type of content_t::COLOR_ALPHA. Other content types can be chosen for the group by using 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:

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);

fn push_group_with_content[link]

fn push_group_with_content(cr: *context_t, content: content_t) void;

Temporarily redirects drawing to an intermediate surface known as a group. The redirection lasts until the group is completed by a call to pop_group or 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).

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

fn rectangle[link]

fn rectangle(cr: *context_t, x: f64, y: f64, width: f64, height: f64) void;

Adds a closed sub-path rectangle of the given size to the current path at position (x, y) in user-space coordinates. This function is logically equivalent to:

cairo::move_to(cr, x, y); cairo::rel_line_to(cr, width, 0.0); cairo::rel_line_to(cr, 0.0, height); cairo::rel_line_to(cr, -width, 0.0); cairo::close_path(cr);

Parameters

• cr: a cairo context
• x: the X coordinate of the top left corner of the rectangle
• y: the Y coordinate to the top left corner of the rectangle
• width: the width of the rectangle
• height: the height of the rectangle

fn reference[link]

fn reference(cr: *context_t) *context_t;

Increases the reference count on cr by one. This prevents cr from being destroyed until a matching call to destroy is made. Use get_reference_count to get the number of references to a context_t.

Returns the referenced context_t.

fn rel_curve_to[link]

fn rel_curve_to(cr: *context_t, dx1: f64, dy1: f64, dx2: f64, dy2: f64, dx3: f64, dy3: f64) (void | error);

Relative-coordinate version of curve_to. All offsets are relative to the current point. Adds a cubic Bézier spline to the path from the current point to a point offset from the current point by (dx3, dy3), using points offset by (dx1, dy1) and (dx2, dy2) as the control points. After this call the current point will be offset by (dx3, dy3).

Given a current point of (x, y), rel_curve_to(cr, dx1, dy1, dx2, dy2, dx3, dy3) is logically equivalent to curve_to(cr, x+dx1, y+dy1, x+dx2, y+dy2, x+dx3, y+dy3).

It is an error to call this function with no current point. Doing so will cause cr to shutdown with a status of status_t::NO_CURRENT_POINT.

Parameters

• cr: a cairo context
• dx1: the X offset to the first control point
• dy1: the Y offset to the first control point
• dx2: the X offset to the second control point
• dy2: the Y offset to the second control point
• dx3: the X offset to the end of the curve
• dy3: the Y offset to the end of the curve

fn rel_line_to[link]

fn rel_line_to(cr: *context_t, dx: f64, dy: f64) (void | error);

Relative-coordinate version of line_to. Adds a line to the path from the current point to a point that is offset from the current point by (dx, dy) in user space. After this call the current point will be offset by (dx, dy).

Given a current point of (x, y), rel_line_to(cr, dx, dy) is logically equivalent to line_to(cr, x + dx, y + dy).

It is an error to call this function with no current point. Doing so will cause cr to shutdown with a status of status_t::NO_CURRENT_POINT.

Parameters

• cr: a cairo context
• dx: the X offset to the end of the new line
• dy: the Y offset to the end of the new line

fn rel_move_to[link]

fn rel_move_to(cr: *context_t, dx: f64, dy: f64) (void | error);

Begin a new sub-path. After this call the current point will offset by (x, y).

Given a current point of (x, y), rel_move_to(cr, dx, dy) is logically equivalent to move_to(cr, x + dx, y + dy).

It is an error to call this function with no current point. Doing so will cause cr to shutdown with a status of status_t::NO_CURRENT_POINT.

Parameters

• cr: a cairo context
• dx: the X offset
• dy: the Y offset

fn reset_clip[link]

fn reset_clip(cr: *context_t) void;

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 reset_clip as it will cause results unexpected by higher-level code which calls clip. Consider using save and restore around clip as a more robust means of temporarily restricting the clip region.

fn restore[link]

fn restore(cr: *context_t) void;

Restores cr to the state saved by a preceding call to save and removes that state from the stack of saved states.

fn rotate[link]

fn rotate(cr: *context_t, angle: f64) void;

Modifies the current transformation matrix (CTM) by rotating the user-space axes by angle radians. The rotation of the axes takes places after any existing transformation of user space. The rotation direction for positive angles is from the positive X axis toward the positive Y axis.

Parameters

• cr: a cairo context
• angle: angle (in radians) by which the user-space axes will be rotated

fn save[link]

fn save(cr: *context_t) void;

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

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

fn scale[link]

fn scale(cr: *context_t, sx: f64, sy: f64) void;

Modifies the current transformation matrix (CTM) by scaling the X and Y user-space axes by sx and sy respectively. The scaling of the axes takes place after any existing transformation of user space.

Parameters

• cr: a cairo context
• sx: scale factor for the X dimension
• sy: scale factor for the Y dimension

fn select_font_face[link]

fn select_font_face(cr: *context_t, family: str, slant: font_slant_t, weight: font_weight_t) void;

Note: The select_font_face function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications.

Selects a family and style of font from a simplified description as a family name, slant and weight. Cairo provides no operation to list available family names on the system (this is a "toy", remember), but the standard CSS2 generic family names, ("serif", "sans-serif", "cursive", "fantasy", "monospace"), are likely to work as expected.

If family starts with the string "cairo :", or if no native font backends are compiled in, cairo will use an internal font family. The internal font family recognizes many modifiers in the family string, most notably, it recognizes the string "monospace". That is, the family name "cairo :monospace" will use the monospace version of the internal font family.

For "real" font selection, see the font-backend-specific font_face_create functions for the font backend you are using. (For example, if you are using the freetype-based cairo-ft font backend, see cairo::ft::font_face_create_for_ft_face() or cairo::ft::font_face_create_for_pattern().) The resulting font face could then be used with cairo::scaled_font::create() and cairo::set_scaled_font().

Similarly, when using the "real" font support, you can call directly into the underlying font system, (such as fontconfig or freetype), for operations such as listing available fonts, etc.

It is expected that most applications will need to use a more comprehensive font handling and text layout library, (for example, pango), in conjunction with cairo.

If text is drawn without a call to select_font_face, (nor set_font_face nor set_scaled_font, the default family is platform-specific, but is essentially "sans-serif". Default slant is font_slant_t::NORMAL, and default weight is font_weight_t::NORMAL.

This function is equivalent to a call to toy_font_face_create followed by set_font_face.

fn set_antialias[link]

fn set_antialias(cr: *context_t, antialias: antialias_t) void;

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 antialias_t::SUBPIXEL when drawing shapes.

Note that this option does not affect text rendering, instead see cairo::font_options::set_antialias().

Parameters

• cr: a context_t
• antialias: the new antialiasing mode

fn set_dash[link]

fn set_dash(cr: *context_t, dashes: *const f64, num_dashes: int, offset_: f64) void;

XXX: HAREFY. Sets the dash pattern to be used by 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 line_cap_t::ROUND or line_cap_t::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 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 status_t::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

fn set_fill_rule[link]

fn set_fill_rule(cr: *context_t, fill_rule: fill_rule_t) void;

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 fill and clip. See fill_rule_t for details on the semantics of each available fill rule.

fn set_font_face[link]

fn set_font_face(cr: *context_t, font_face: *font_face_t) void;

Replaces the current font_face_t object in the context_t with font_face. The replaced font face in the context_t will be destroyed if there are no other references to it.

fn set_font_matrix[link]

fn set_font_matrix(cr: *context_t, matrix: *matrix_t) void;

Sets the current font matrix to matrix. The font matrix gives a transformation from the design space of the font (in this space, the em-square is 1 unit by 1 unit) to user space. Normally, a simple scale is used (see set_font_size), but a more complex font matrix can be used to shear the font or stretch it unequally along the two axes.

Parameters

• cr: a cairo context
• matrix: a *cairo::matrix_t describing a transform to be applied to the current font.

fn set_font_size[link]

fn set_font_size(cr: *context_t, size_: f64) void;

Sets the current font matrix to a scale by a factor of size, replacing any font matrix previously set with set_font_size or set_font_matrix.

This results in a font size of size user space units. (More precisely, this matrix will result in the font's em-square being a size by size square in user space.)

If text is drawn without a call to set_font_size, (nor set_font_matrix nor set_scaled_font), the default font size is 10.0.

Parameters

• cr: a context_t
• size: the new font size, in user space units

fn set_line_cap[link]

fn set_line_cap(cr: *context_t, line_cap: line_cap_t) void;

Sets the current line cap style within the cairo context. See 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 stroke and stroke_extents, but does not have any effect during path construction.

fn set_line_join[link]

fn set_line_join(cr: *context_t, line_join: line_join_t) void;

Sets the current line join style within the cairo context. See 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 stroke and stroke_extents, but does not have any effect during path construction.

fn set_line_width[link]

fn set_line_width(cr: *context_t, width: f64) void;

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 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 set_line_width and the stroking operation, then one can just pass user-space values to set_line_width and ignore this note.

As with the other stroke parameters, the current line width is examined by stroke and stroke_extents, but does not have any effect during path construction.

The default line width value is 2.0.

fn set_matrix[link]

fn set_matrix(cr: *context_t, matrix: *matrix_t) void;

Modifies the current transformation matrix (CTM) by setting it equal to matrix.

Parameters

• cr: a cairo context
• matrix: a transformation matrix from user space to device space

fn set_miter_limit[link]

fn set_miter_limit(cr: *context_t, limit: f64) void;

Sets the current miter limit within the cairo context. If the current line join style is set to line_join_t::MITER (see 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 stroke and stroke_extents, 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).

fn set_operator[link]

fn set_operator(cr: *context_t, op: operator_t) void;

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

fn set_source[link]

fn set_source(cr: *context_t, source: *pattern_t) void;

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 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 set_source_rgb(cr, 0.0, 0.0, 0.0)).

fn set_source_rgb[link]

fn set_source_rgb(cr: *context_t, red: f64, green: f64, blue: f64) void;

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.0 to 1.0.

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 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

fn set_source_rgba[link]

fn set_source_rgba(cr: *context_t, red: f64, green: f64, blue: f64, alpha: f64) void;

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 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

fn set_source_surface[link]

fn set_source_surface(cr: *context_t, surface: *surface_t, x: f64, y: f64) void;

This is a convenience function for creating a pattern from surface and setting it as the source in cr with 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 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

fn set_tolerance[link]

fn set_tolerance(cr: *context_t, tolerance: f64) void;

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 context
• tolerance: the tolerance, in device units (typically pixels)

fn show_glyphs[link]

fn show_glyphs(cr: *context_t, glyphs: []glyph_t) void;

A drawing operator that generates the shape from an array of glyphs, rendered according to the current font face, font size (font matrix), and font options.

Parameters

• cr: a cairo context
• glyphs: array of glyphs to show

fn show_page[link]

fn show_page(cr: *context_t) void;

Emits and clears the current page for backends that support multiple pages. Use 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.

fn show_text[link]

fn show_text(cr: *context_t, utf8: str) void;

Note: The show_text function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications. See show_glyphs for the "real" text display API in cairo.

fn status[link]

fn status(cr: *context_t) status_t;

Checks whether an error has previously occurred for this context. Returns the current status of this context, see status_t.

fn status_to_string[link]

fn status_to_string(status: status_t) str;

Provides a human-readable description of a status_t.

fn strerror[link]

fn strerror(e: error) str;

Returns a human-friendly representation of an error.

fn stroke[link]

fn stroke(cr: *context_t) void;

A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. After stroke, the current path will be cleared from the cairo context. See set_line_width, set_line_join, set_line_cap, set_dash, and 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 set_dash. If the cap style is line_cap_t::ROUND or line_cap_t::SQUARE then these segments will be drawn as circular dots or squares respectively. In the case of line_cap_t::SQUARE, the orientation of the squares is determined by the direction of the underlying path.

A sub-path created by move_to followed by either a close_path or one or more calls to line_to to the same coordinate as the move_to. If the cap style is line_cap_t::ROUND then these sub-paths will be drawn as circular dots.

Note that in the case of line_cap_t::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 line_cap_t::BUTT cause anything to be drawn in the case of either degenerate segments or sub-paths.

fn stroke_extents[link]

fn stroke_extents(cr: *context_t, x1: *f64, y1: *f64, x2: *f64, y2: *f64) void;

XXX: HAREFY. Computes a bounding box in user coordinates covering the area that would be affected, (the "inked" area), by a 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 stroke_extents will return an empty rectangle.

Contrast with path_extents which can be used to compute the non-empty bounds as the line width approaches zero.

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

See stroke, set_line_width, set_line_join, set_line_cap, set_dash, and 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

fn stroke_preserve[link]

fn stroke_preserve(cr: *context_t) void;

A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. Unlike stroke, stroke_preserve preserves the path within the cairo context.

See set_line_width, set_line_join, set_line_cap, set_dash, and stroke_preserve.

fn text_extents[link]

fn text_extents(cr: *context_t, utf8: str) (f64, f64, f64, f64, f64, f64);

Gets the extents for a string of text. The extents describe a user-space rectangle that encloses the "inked" portion of the text, (as it would be drawn by show_text). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by show_text.

Note that whitespace characters do not directly contribute to the size of the rectangle (extents.width and extents.height). They do contribute indirectly by changing the position of non-whitespace characters. In particular, trailing whitespace characters are likely to not affect the size of the rectangle, though they will affect the x_advance and y_advance values.

Parameters

• cr: a context_t
• utf8: a string of text encoded in UTF-8

fn text_path[link]

fn text_path(cr: *context_t, utf8: str) void;

Adds closed paths for text to the current path. The generated path if filled, achieves an effect similar to that of show_text.

Text conversion and positioning is done similar to show_text.

Like show_text, After this call the current point is moved to the origin of where the next glyph would be placed in this same progression. That is, the current point will be at the origin of the final glyph offset by its advance values. This allows for chaining multiple calls to to text_path without having to set current point in between.

Note: The text_path function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications.

See glyph_path for the "real" text path API in cairo.

fn transform[link]

fn transform(cr: *context_t, matrix: *matrix_t) void;

Modifies the current transformation matrix (CTM) by applying matrix as an additional transformation. The new transformation of user space takes place after any existing transformation.

Parameters

• cr: a cairo context
• matrix: a transformation to be applied to the user-space axes

fn translate[link]

fn translate(cr: *context_t, tx: f64, ty: f64) void;

Modifies the current transformation matrix (CTM) by translating the user-space origin by (tx, ty). This offset is interpreted as a user-space coordinate according to the CTM in place before the new call to translate. In other words, the translation of the user-space origin takes place after any existing transformation.

Parameters

• cr: a cairo context
• tx: amount to translate in the X direction
• ty: amount to translate in the Y direction

fn user_to_device[link]

fn user_to_device(cr: *context_t, x: f64, y: f64) (f64, f64);

Transform a coordinate from user space to device space by multiplying the given point by the current transformation matrix (CTM).

Parameters

• cr: a cairo context
• x: X value of coordinate
• y: Y value of coordinate

fn user_to_device_distance[link]

fn user_to_device_distance(cr: *context_t, dx: f64, dy: f64) (f64, f64);

Transform a distance vector from user space to device space. This function is similar to user_to_device except that the translation components of the CTM will be ignored when transforming (dx, dy).

Parameters

• cr: a cairo context
• dx: X component of a distance vector
• dy: Y component of a distance vector

fn version[link]

fn version() int;

Returns the version of the cairo library encoded in a single integer. The encoding ensures that later versions compare greater than earlier versions.

fn version_string[link]

fn version_string() const str;

Returns the version of the cairo library as a human-readable string of the form "X.Y.Z".