Package cairo

A cairo-t context is the main object used when drawing with Cairo. To draw with Cairo, you create a cairo-t context, set the target surface, and drawing options for the cairo-t context, create shapes with functions like the cairo-move-to and cairo-line-to functions, and then draw shapes with the cairo-stroke or cairo-fill functions.

The cairo-t context can be pushed to a stack via the cairo-save function. They may then safely be changed, without losing the current state. Use the cairo-restore function to restore to the saved state.

Creating paths and manipulating path data.

Paths are the most basic drawing tools and are primarily used to implicitly generate simple masks.

Sources for drawing.

The cairo-pattern-t structure is the paint with which Cairo draws. The primary use of patterns is as the source for all Cairo drawing operations, although they can also be used as masks, that is, as the brush too.

A Cairo pattern is created by using one of the many constructors, of the form cairo-pattern-create-type or implicitly through the cairo-set-source-type functions.

Representing a pixel-aligned area.

Regions are a simple graphical data type representing an area of integer-aligned rectangles. They are often used on raster surfaces to track areas of interest, such as change or clip areas.

Manipulating the current transformation matrix.

The current transformation matrix, CTM, is a two-dimensional affine transformation that maps all coordinates and other drawing instruments from the user space into the surface's canonical coordinate system, also known as the device space.

Rendering text and glyphs.

The functions with text in their name form Cairo's toy text API. The toy API takes UTF-8 encoded text and is limited in its functionality to rendering simple left-to-right text with no advanced features. That means for example that most complex scripts like Hebrew, Arabic, and Indic scripts are out of question. No kerning or correct positioning of diacritical marks either. The font selection is pretty limited too and does not handle the case that the selected font does not cover the characters in the text. This set of functions are really that, a toy text API, for testing and demonstration purposes. Any serious application should avoid them.

The functions with glyphs in their name form Cairo's low-level text API. The low-level API relies on the user to convert text to a set of glyph indexes and positions. This is a very hard problem and is best handled by external libraries, like the pangocairo library that is part of the Pango text layout and rendering library. Pango is available from the Pango library.

Supplying arbitrary image data.

Hyperlinks and document structure

Base class for font faces.

The cairo-font-face-t structure represents a particular font at a particular weight, slant, and other characteristic but no size, transformation, or size.

Font faces are created using font-backend-specific constructors, typically of the form cairo-backend-font-face-create, or implicitly using the toy text API by way of the cairo-select-font-face function. The resulting face can be accessed using the cairo-get-font-face function.

Font face at particular size and options.

The cairo-scaled-font-t structure represents a realization of a font face at a particular size and transformation and a certain set of font options.

How a font should be rendered.

The font options specify how fonts should be rendered. Most of the time the font options implied by a surface are just right and do not need any changes, but for pixel-based targets tweaking font options may result in superior output on a particular display.

Font support for FreeType

Font support for Microsoft Windows

Font support via CGFont on OS X

Font support with font data provided by the user

Interface to underlying rendering system.

Base class for surfaces.

A cairo-surface-t structure is the abstract type representing all different drawing targets that cairo can render to. The actual drawings are performed using a Cairo context.

A cairo surface is created by using backend-specific constructors, typically of the form cairo-backend-surface-create.

Most surface types allow accessing the surface without using Cairo functions. If you do this, keep in mind that it is mandatory that you call the cairo-surface-flush function before reading from or writing to the surface and that you must use the cairo-surface-mark-dirty function after modifying it.

Example 1. Directly modifying an image surface

 void
 modify_image_surface (cairo_surface_t *surface)
 {
   unsigned char *data;
   int width, height, stride;


   // flush to ensure all writing to the image was done
   cairo_surface_flush (surface);


   // modify the image
   data = cairo_image_surface_get_data (surface);
   width = cairo_image_surface_get_width (surface);
   height = cairo_image_surface_get_height (surface);
   stride = cairo_image_surface_get_stride (surface);
   modify_image_data (data, width, height, stride);


   // mark the image dirty so Cairo clears its caches.
   cairo_surface_mark_dirty (surface);
 }      

Note that for other surface types it might be necessary to acquire the surface's device first. See the cairo-device-acquire function for a discussion of devices.

Rendering to memory buffers.

Image surfaces provide the ability to render to memory buffers either allocated by Cairo or by the calling code. The supported image formats are those defined in the cairo-format-t enumeration.

Rendering PDF documents

Reading and writing PNG images.

The PNG functions allow reading PNG images into image surfaces, and writing any surface to a PNG file.

It is a toy API. It only offers very simple support for reading and writing PNG files, which is sufficient for testing and demonstration purposes. Applications which need more control over the generated PNG file should access the pixel data directly, using the cairo-image-surface-data function or a backend-specific access function, and process it with another library, e.g. GdkPixbuf or libpng.

Rendering PostScript documents

Records all drawing operations

Microsoft Windows surface support

Rendering SVG documents

Rendering to Quartz surfaces

X Window System rendering using the XCB library

X Window System rendering using XLib

X Window System rendering using the X Render extension

Rendering to replayable scripts

Generic matrix operations.

Decoding Cairo's status.

Cairo uses a single status type to represent all kinds of errors. A status value of :success represents no error and has an integer value of zero. All other status values represent an error.

Cairo's error handling is designed to be easy to use and safe. All major Cairo objects retain an error status internally which can be queried anytime by the users using cairo*-status calls. In the mean time, it is safe to call all Cairo functions normally even if the underlying object is in an error status. This means that no error handling code is required before or after each individual Cairo function call.

Cairo provides the ability to examine the version at either compile-time or run-time and in both a human readable form as well as an encoded form suitable for direct comparison. Cairo also provides the cairo-version-encode function to perform the encoding.

This section lists generic data types used in the cairo API.