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 the same character (alternates to be used in different contexts, for example), or a glyph can be a ligature of multiple characters. Converting text to positioned glyphs is shaping.
Cairo itself provides a “toy” text API that only does simple shaping: no ligature or kerning; one glyph per character, positioned by moving the cursor by the X and Y advance of each glyph.
It is expected that most applications will need to use Pango or a similar library in conjunction with cairo for more comprehensive font handling and text layout.
Note
At the moment cairocffi only supports cairo’s “toy” font selection API. FontFace objects of other types could be obtained eg. from Context.get_font_face(), but they can not be instantiated directly.
Some parameters or return values in the cairo API only have a fixed, finite set of valid values. These are represented as enumerated types in C, and as integers in CFFI. Users are encouraged to use the constants defined here in the cairocffi module rather than literal integers. For example:
surface = cairocffi.ImageSurface(cairocffi.FORMAT_ARGB32, 300, 400)
Used to describe the content that a Surface will contain, whether color information, alpha information (translucence vs. opacity), or both.
The surface will hold color content only.
The surface will hold alpha content only.
The surface will hold color and alpha content.
Used to identify the memory format of image data.
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.)
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.
Each pixel is a 8-bit quantity holding an alpha value.
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 endianess 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.
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.
Like FORMAT_RGB24, but with the upper 2 bits unused and 10 bits per components.
Used to set the compositing operator for all cairo drawing operations.
The default operator is OPERATOR_OVER.
The operators marked as unbounded modify their destination even outside of the mask layer (that is, their effect is not bound by the mask layer). However, their effect can still be limited by way of clipping.
To keep things simple, the operator descriptions here document the behavior for when both source and destination are either fully transparent or fully opaque. The actual implementation works for translucent layers too. For a more detailed explanation of the effects of each operator, including the mathematical definitions, see http://cairographics.org/operators/.
Clear destination layer. (bounded)
Replace destination layer. (bounded)
Draw source layer on top of destination layer. (bounded)
Draw source where there was destination content. (unbounded)
Draw source where there was no destination content. (unbounded)
Draw source on top of destination content and only there.
Ignore the source.
Draw destination on top of source.
Leave destination only where there was source content. (unbounded)
Leave destination only where there was no source content.
Leave destination on top of source content and only there. (unbounded)
Source and destination are shown where there is only one of them.
Source and destination layers are accumulated.
Like OPERATOR_OVER, but assuming source and destination are disjoint geometries.
Source and destination layers are multiplied. This causes the result to be at least as dark as the darker inputs. (Since 1.10)
Source and destination are complemented and multiplied. This causes the result to be at least as light as the lighter inputs. (Since cairo 1.10)
Multiplies or screens, depending on the lightness of the destination color. (Since cairo 1.10)
Replaces the destination with the source if it is darker, otherwise keeps the source. (Since cairo 1.10)
Replaces the destination with the source if it is lighter, otherwise keeps the source. (Since cairo 1.10)
Brightens the destination color to reflect the source color. (Since cairo 1.10)
Darkens the destination color to reflect the source color. (Since cairo 1.10)
Multiplies or screens, dependent on source color. (Since cairo 1.10)
Darkens or lightens, dependent on source color. (Since cairo 1.10)
Takes the difference of the source and destination color. (Since cairo 1.10)
Produces an effect similar to difference, but with lower contrast. (Since cairo 1.10)
Creates a color with the hue of the source and the saturation and luminosity of the target. (Since cairo 1.10)
Creates a color with the saturation of the source and the hue and luminosity of the target. Painting with this mode onto a gray area produces no change. (Since cairo 1.10)
Creates a color with the hue and saturation of the source and the luminosity of the target. This preserves the gray levels of the target and is useful for coloring monochrome images or tinting color images. (Since cairo 1.10)
Creates a color with the luminosity of the source and the hue and saturation of the target. This produces an inverse effect to OPERATOR_HSL_COLOR. (Since cairo 1.10)
Specifies the type of antialiasing to do when rendering text or shapes.
Use the default antialiasing for the subsystem and target device.
Use a bilevel alpha mask.
Perform single-color antialiasing.
Perform antialiasing by taking advantage of the order of subpixel elements on devices such as LCD panels.
As it is not necessarily clear from the above what advantages a particular antialias method provides, since cairo 1.12, there is also a set of hints:
Allow the backend to degrade raster quality for speed.
A balance between speed and quality.
A high-fidelity, but potentially slow, raster mode.
These make no guarantee on how the backend will perform its rasterisation (if it even rasterises!), nor that they have any differing effect other than to enable some form of antialiasing. In the case of glyph rendering, ANTIALIAS_FAST and ANTIALIAS_GOOD will be mapped to ANTIALIAS_GRAY, with ANTIALIAS_BEST being equivalent to ANTIALIAS_SUBPIXEL.
The interpretation of ANTIALIAS_DEFAULT is left entirely up to the backend, typically this will be similar to ANTIALIAS_GOOD.
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 FILL_RULE_WINDING.
New entries may be added in future versions.
If the path crosses the ray fromleft-to-right, counts +1. If the path crosses the rayfrom 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.
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.
Specifies how to render the endpoints of the path when stroking.
The default line cap style is LINE_CAP_BUTT.
Start (stop) the line exactly at the start (end) point.
Use a round ending, the center of the circle is the end point.
Use squared ending, the center of the square is the end point.
Specifies how to render the junction of two lines when stroking.
The default line join style is LINE_JOIN_MITER.
Use a sharp (angled) corner, see Context.set_miter_limit().
Use a rounded join, the center of the circle is the joint point.
Use a cut-off join, the join is cut off at half the line width from the joint point.
Specifies variants of a font face based on their slant.
Upright font style.
Italic font style.
Oblique font style.
Specifies variants of a font face based on their weight.
Normal font weight.
Bold font weight.
The subpixel order specifies the order of color elements within each pixel on the display device when rendering with an antialiasing mode of ANTIALIAS_SUBPIXEL.
Use the default subpixel order for for the target device.
Subpixel elements are arranged horizontally with red at the left.
Subpixel elements are arranged horizontally with blue at the left.
Subpixel elements are arranged vertically with red at the top.
Subpixel elements are arranged vertically with blue at the top.
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.
Use the default hint style for font backend and target device.
Do not hint outlines.
Hint outlines slightly to improve contrast while retaining good fidelity to the original shapes.
Hint outlines with medium strength giving a compromise between fidelity to the original shapes and contrast.
Hint outlines to maximize contrast.
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.
Hint metrics in the default manner for the font backend and target device.
Do not hint font metrics.
Hint font metrics.
Used to describe the type of one portion of a path when represented as a list. See Context.copy_path() for details.
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 EXTEND_NONE for SurfacePattern and EXTEND_PAD for Gradient patterns.
New entries may be added in future versions.
Pixels outside of the source pattern are fully transparent.
The pattern is tiled by repeating.
The pattern is tiled by reflecting at the edges.
Pixels outside of the pattern copy the closest pixel from the source.
Used to indicate what filtering should be applied when reading pixel values from patterns. See Pattern.set_filter() for indicating the desired filter to be used with a particular pattern.
A high-performance filter, with quality similar to FILTER_NEAREST.
A reasonable-performance filter, with quality similar to FILTER_BILINEAR.
The highest-quality available, performance may not be suitable for interactive use.
Nearest-neighbor filtering.
Linear interpolation in two dimensions.
This filter value is currently unimplemented, and should not be used in current code.
Used to describe the version number of the PDF specification that a generated PDF file will conform to.
The version 1.4 of the PDF specification.
The version 1.5 of the PDF specification.
Used to describe the language level of the PostScript Language Reference that a generated PostScript file will conform to.
The language level 2 of the PostScript specification.
The language level 3 of the PostScript specification.