cairo.c.types

#cairo_bool_t is used for boolean values. Returns of type #cairo_bool_t will always be either 0 or 1, but testing against these values explicitly is not encouraged; just use the value as a boolean condition.

if (cairo_in_stroke (cr, x, y)) { /<!-- --> do something <!-- -->/ }

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

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

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

Specifies if color fonts are to be rendered using the color glyphs or outline glyphs. Glyphs that do not have a color presentation, and non-color fonts are not affected by this font option.

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

#cairo_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.Device.getDeviceType]

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

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

New entries may be added in future versions.

Dither is an intentionally applied form of noise used to randomize quantization error, preventing large-scale patterns such as color banding in images (e.g. for gradients). Ordered dithering applies a precomputed threshold matrix to spread the errors smoothly.

#cairo_dither_t is modeled on pixman dithering algorithm choice. As of Pixman 0.40, FAST corresponds to a 8x8 ordered bayer noise and GOOD and BEST use an ordered 64x64 precomputed blue noise.

#cairo_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 [cairo.types.Extend.None] for surface patterns and [cairo.types.Extend.Pad] for gradient patterns.

New entries may be added in future versions.

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

The default fill rule is [cairo.types.FillRule.Winding].

New entries may be added in future versions.

#cairo_filter_t is used to indicate what filtering should be applied when reading pixel values from patterns. See [cairo.pattern.Pattern.setFilter] for indicating the desired filter to be used with a particular pattern.

Specifies variants of a font face based on their slant.

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

The type of a font face is determined by the function used to create it, which will generally be of the form

The font face type can be queried with [cairo.font_face.FontFace.getFontType]

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.global.scaledFontCreate]. The scaled font type can be queried with [cairo.scaled_font.ScaledFont.getFontType]

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

such as cairo_ft_scaled_font_lock_face().

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

New entries may be added in future versions.

Specifies variants of a font face based on their weight.

#cairo_format_t is used to identify the memory format of image data.

New entries may be added in future versions.

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.

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

New entries may be added in future versions.

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

The default line cap style is [cairo.types.LineCap.Butt].

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

The default line join style is [cairo.types.LineJoin.Miter].

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

The default operator is [cairo.types.Operator.Over].

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

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

#cairo_path_data_t is used to describe the type of one portion of a path when represented as a #cairo_path_t. See #cairo_path_data_t for details.

#cairo_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.global.patternCreateRgb] and [cairo.global.patternCreateRgba] 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.Pattern.getPatternType]

Most #cairo_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.Pattern.addColorStopRgb] and [cairo.pattern.Pattern.addColorStopRgba] which must only be called with gradient patterns (either LINEAR or RADIAL). Otherwise the pattern will be shutdown and put into an error state.

New entries may be added in future versions.

#cairo_pdf_metadata_t is used by the [cairo.global.pdfSurfaceSetMetadata] function specify the metadata to set.

#cairo_pdf_outline_flags_t is used by the [cairo.global.pdfSurfaceAddOutline] function specify the attributes of an outline item. These flags may be bitwise-or'd to produce any combination of flags.

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

#cairo_ps_level_t is used to describe the language level of the PostScript Language Reference that a generated PostScript file will conform to.

Used as the return value for [cairo.region.Region.containsRectangle].

A set of script output variants.

#cairo_status_t is used to indicate errors that can occur when using Cairo. In some cases it is returned directly by functions. but when using #cairo_t, the last error, if any, is stored in the context and can be retrieved with [cairo.context.Context.status].

New entries may be added in future versions. Use [cairo.global.statusToString] to get a human-readable representation of an error message.

The subpixel order specifies the order of color elements within each pixel on the display device when rendering with an antialiasing mode of [cairo.types.Antialias.Subpixel].

Whether operations should be recorded.

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

(though see [cairo.surface.Surface.createSimilar] as well).

The surface type can be queried with [cairo.surface.Surface.getSurfaceType]

The various #cairo_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

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

New entries may be added in future versions.

#cairo_svg_unit_t is used to describe the units valid for coordinates and lengths in the SVG specification.

See also:

• SVG Units
• SVG Types
• CSS Length

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

Specifies properties of a text cluster mapping.

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

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

Memory management of #cairo_t is done with [cairo.global.reference] and [cairo.global.destroy].

A #cairo_device_t represents the driver interface for drawing operations to a #cairo_surface_t. There are different subtypes of #cairo_device_t for different drawing backends.

The type of a device can be queried with [cairo.device.Device.getDeviceType].

Memory management of #cairo_device_t is done with [cairo.device.Device.reference] and [cairo.device.Device.destroy].

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

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

A #cairo_font_face_t specifies all aspects of a font other than the size or font matrix (a font matrix is used to distort a font by shearing it or scaling it unequally in the two directions) . A font face can be set on a #cairo_t by using [cairo.context.Context.setFontFace]; the size and font matrix are set with [cairo.context.Context.setFontSize] and [cairo.context.Context.setFontMatrix].

There are various types of font faces, depending on the

font face can be queried using [cairo.font_face.FontFace.getFontType].

Memory management of #cairo_font_face_t is done with [cairo.font_face.FontFace.reference] and [cairo.font_face.FontFace.destroy].

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

Individual features of a #cairo_font_options_t can be set or accessed using functions named

[cairo.font_options.FontOptions.setAntialias] and [cairo.font_options.FontOptions.getAntialias].

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

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

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

A #cairo_matrix_t holds an affine transformation, such as a scale, rotation, shear, or a combination of those. The transformation of a point (x, y) is given by:

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

A data structure for holding a path. This data structure serves as the return value for [cairo.context.Context.copyPath] and [cairo.context.Context.copyPathFlat] as well the input value for [cairo.context.Context.appendPath].

See #cairo_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 #cairo_path_data_type_t), since the data includes both headers and coordinates for each portion.

#cairo_path_data_t is used to represent the path data inside a #cairo_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 #cairo_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:

[cairo.types.PathDataType.MoveTo]: 1 point [cairo.types.PathDataType.LineTo]: 1 point [cairo.types.PathDataType.CurveTo]: 3 points [cairo.types.PathDataType.ClosePath]: 0 points

The semantics and ordering of the coordinate values are consistent with [cairo.context.Context.moveTo], [cairo.context.Context.lineTo], [cairo.context.Context.curveTo], and [cairo.context.Context.closePath].

Here is sample code for iterating through a #cairo_path_t:

int i; cairo_path_t *path; cairo_path_data_t *data;   path = cairo_copy_path (cr);   for (i=0; i < path->num_data; i += path->data[i].header.length) { data = &path->data[i]; switch (data->header.type) { case CAIRO_PATH_MOVE_TO: do_move_to_things (data[1].point.x, data[1].point.y); break; case CAIRO_PATH_LINE_TO: do_line_to_things (data[1].point.x, data[1].point.y); break; case CAIRO_PATH_CURVE_TO: do_curve_to_things (data[1].point.x, data[1].point.y, data[2].point.x, data[2].point.y, data[3].point.x, data[3].point.y); break; case CAIRO_PATH_CLOSE_PATH: do_close_path_things (); break; } } 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 <literal>data->header.length</literal> to iterate over the path data, instead of hardcoding the number of elements for each element type.

A #cairo_pattern_t represents a source when drawing onto a surface. There are different subtypes of #cairo_pattern_t, for different types of sources; for example, [cairo.global.patternCreateRgb] creates a pattern for a solid opaque color.

Other than various

functions, some of the pattern types can be implicitly created using various

for example [cairo.context.Context.setSourceRgb].

The type of a pattern can be queried with [cairo.pattern.Pattern.getPatternType].

Memory management of #cairo_pattern_t is done with [cairo.pattern.Pattern.reference] and [cairo.pattern.Pattern.destroy].

A data structure for holding a rectangle.

A data structure for holding a rectangle with integer coordinates.

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

A #cairo_region_t represents a set of integer-aligned rectangles.

It allows set-theoretical operations like [cairo.region.Region.union_] and [cairo.region.Region.intersect] to be performed on them.

Memory management of #cairo_region_t is done with [cairo.region.Region.reference] and [cairo.region.Region.destroy].

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

There are various types of scaled fonts, depending on the

scaled font can be queried using [cairo.scaled_font.ScaledFont.getFontType].

Memory management of #cairo_scaled_font_t is done with [cairo.scaled_font.ScaledFont.reference] and [cairo.scaled_font.ScaledFont.destroy].

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

There are different subtypes of #cairo_surface_t for different drawing backends; for example, [cairo.global.imageSurfaceCreate] creates a bitmap image in memory. The type of a surface can be queried with [cairo.surface.Surface.getSurfaceType].

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.global.imageSurfaceCreate] and [cairo.surface.Surface.createSimilar]. Alternatively, if the user passes in a reference to some backing storage and asks cairo to wrap that in a #cairo_surface_t, then the contents are not modified; for example, [cairo.global.imageSurfaceCreateForData] and cairo_xlib_surface_create().

Memory management of #cairo_surface_t is done with [cairo.surface.Surface.reference] and [cairo.surface.Surface.destroy].

The #cairo_text_cluster_t structure holds information about a single

mapping of some glyphs corresponding to some UTF-8 text.

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

See [cairo.context.Context.showTextGlyphs] for how clusters are used in advanced text operations.

The #cairo_text_extents_t structure stores the extents of a single glyph or a string of glyphs in user-space coordinates. Because text extents are in user-space coordinates, they are mostly, but not entirely, independent of the current transformation matrix. If you call

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.

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