Package cairo

The cairo:context-t structure is the main object used when drawing with Cairo. To draw with Cairo, you create a cairo:context-t instance, set the target surface, and drawing options for the cairo:context-t instance, 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:context-t instance 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.

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.

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.

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.

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.

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:font-face function.

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.

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.

Devices are the abstraction Cairo employs for the rendering system used by a cairo:surface-t instance. You can get the device of a surface using the cairo:surface-device function.

Devices are created using custom functions specific to the rendering system you want to use. See the documentation for the surface types for those functions.

An important function that devices fulfill is sharing access to the rendering system between Cairo and your application. If you want to access a device directly that you used to draw to with Cairo, you must first call the cairo:device-flush function to ensure that Cairo finishes all operations on the device and resets it to a clean state.

Cairo also provides the cairo:device-acquire and cairo:device-release functions to synchronize access to the rendering system in a multithreaded environment. This is done internally, but can also be used by applications.

Putting this all together, a function that works with devices should look something like this:

(defun my-device-modifying-function (device)
  (let (status)
    ;; Ensure the device is properly reset
    (cairo:device-flush device)
    ;; Try to aquire the device
    (unless (eq :success
                (setf status
                      (cairo:device-aquire device)))
      (warn "Failed to aquire the device: ~a" (cairo:status-to-string status))
      (return-from my-device-modifying-function))


    ;; Do the custom operations on the device here.
    ;; But do not call any Cairo functions that might acquire devices.


    ;; Release the device when done.
    (cairo:device-release device)))      

Note: Please refer to the documentation of each backend for additional usage requirements, guarantees provided, and interactions with existing surface API of the device functions for surfaces of that type.

The 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. Directly modifying an image surface

(defun modify-image-surface (surface)
  (let ((data (cairo:image-surface-data surface))
        (width (cairo:image-surface-width surface))
        (height (cairo:image-surface-height surface))
        (stride (cairo:image-surface-stride surface)))


    ;; flush to ensure all writing to the image was done
    (cairo:surface-flush surface)


    ;; modify the image
    (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 device of the surface first. See the cairo:device-acquire function for a discussion of devices.

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.

The PDF surface is used to render Cairo graphics to Adobe PDF files and is a multi-page vector surface backend.

The following mime types are supported: CAIRO_MIME_TYPE_JPEG, CAIRO_MIME_TYPE_JP2, CAIRO_MIME_TYPE_UNIQUE_ID, CAIRO_MIME_TYPE_JBIG2, CAIRO_MIME_TYPE_JBIG2_GLOBAL, CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID, CAIRO_MIME_TYPE_CCITT_FAX, CAIRO_MIME_TYPE_CCITT_FAX_PARAMS.

JBIG2 Images

JBIG2 data in PDF must be in the embedded format as described in ISO/IEC 11544. Image specific JBIG2 data must be in CAIRO_MIME_TYPE_JBIG2. Any global segments in the JBIG2 data (segments with page association field set to 0) must be in CAIRO_MIME_TYPE_JBIG2_GLOBAL. The global data may be shared by multiple images. All images sharing the same global data must set CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID to a unique identifier. At least one of the images must provide the global data using CAIRO_MIME_TYPE_JBIG2_GLOBAL. The global data will only be embedded once and shared by all JBIG2 images with the same CAIRO_MIME_TYPE_JBIG2_GLOBAL_ID.

CCITT Fax Images

The CAIRO_MIME_TYPE_CCITT_FAX mime data requires a number of decoding parameters These parameters are specified using CAIRO_MIME_TYPE_CCITT_FAX_PARAMS. CAIRO_MIME_TYPE_CCITT_FAX_PARAMS mime data must contain a string of the form "param1=value1 param2=value2 ...".

Columns

An integer specifying the width of the image in pixels. [required]

Rows

An integer specifying the height of the image in scan lines. [required]

K

An integer identifying the encoding scheme used. < 0 is 2 dimensional Group 4, = 0 is Group 3 1 dimensional, > 0 is mixed 1 and 2 dimensional encoding. Default is 0. [optional]

EndOfLine

If true end-of-line bit patterns are present. Default is false. [optional]

EncodedByteAlign

If true the end of line is padded with 0 bits so the next line begins on a byte boundary. Default is false. [optional]

EndOfBlock

If true the data contains an end-of-block pattern. Default is true. [optional]

BlackIs1

If true 1 bits are black pixels. Default is false. [optional]

DamagedRowsBeforeError

An integer specifying the number of damages rows tolerated before an error occurs. Default is 0. [optional]

Boolean values may be "true" or "false", or 1 or 0.

These parameters are the same as the CCITTFaxDecode parameters in the PostScript Language Reference and Portable Document Format (PDF). Refer to these documents for further details.

An example CAIRO_MIME_TYPE_CCITT_FAX_PARAMS string is:

"Columns=10230 Rows=40000 K=1 EndOfLine=true EncodedByteAlign=1 BlackIs1=false"      

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, for example GdkPixbuf or libpng.

The PostScript surface is used to render Cairo graphics to Adobe PostScript files and is a multi-page vector surface backend.

The following mime types are supported: CAIRO_MIME_TYPE_JPEG, CAIRO_MIME_TYPE_UNIQUE_ID, CAIRO_MIME_TYPE_CCITT_FAX, CAIRO_MIME_TYPE_CCITT_FAX_PARAMS, CAIRO_MIME_TYPE_CCITT_FAX, CAIRO_MIME_TYPE_CCITT_FAX_PARAMS, CAIRO_MIME_TYPE_EPS, CAIRO_MIME_TYPE_EPS_PARAMS.

Source surfaces used by the PostScript surface that have a CAIRO_MIME_TYPE_UNIQUE_ID mime type will be stored in PostScript printer memory for the duration of the print job. The CAIRO_MIME_TYPE_UNIQUE_ID mime type should only be used for small frequently used sources.

The CAIRO_MIME_TYPE_CCITT_FAX and CAIRO_MIME_TYPE_CCITT_FAX_PARAMS mime types are documented in CCITT Fax Images.

Embedding EPS files

Encapsulated PostScript files can be embedded in the PS output by setting the CAIRO_MIME_TYPE_EPS mime data on a surface to the EPS data and painting the surface. The EPS will be scaled and translated to the extents of the surface the EPS data is attached to.

The CAIRO_MIME_TYPE_EPS mime type requires the CAIRO_MIME_TYPE_EPS_PARAMS mime data to also be provided in order to specify the embeddding parameters. CAIRO_MIME_TYPE_EPS_PARAMS mime data must contain a string of the form "bbox=[llx lly urx ury]" that specifies the bounding box (in PS coordinates) of the EPS graphics. The parameters are: lower left x, lower left y, upper right x, upper right y. Normally the bbox data is identical to the %%BoundingBox data in the EPS file.

A recording surface is a surface that records all drawing operations at the highest level of the surface backend interface, that is, the level of paint, mask, stroke, fill, and text glyphs. The recording surface can then be "replayed" against any target surface by using it as a source surface.

If you want to replay a surface so that the results in target will be identical to the results that would have been obtained if the original operations applied to the recording surface had instead been applied to the target surface, you can use code like this:

(cairo:with-context (context target)
  (cairo:set-source-surface context recording-surface 0.0 0.0)
  (cairo:paint context)
  ...)      

A recording surface is logically unbounded, that is, it has no implicit constraint on the size of the drawing surface. However, in practice this is rarely useful as you wish to replay against a particular target surface with known bounds. For this case, it is more efficient to specify the target extents to the recording surface upon creation.

The recording phase of the recording surface is careful to snapshot all necessary objects, paths, patterns, etc., in order to achieve accurate replay.

The SVG surface is used to render Cairo graphics to SVG files and is a multi-page vector surface backend.

The script surface provides the ability to render to a native script that matches the Cairo drawing model. The scripts can be replayed using tools under the util/cairo-script directory, or with the cairo-perf-trace utility.

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.