cairo_t

cairo_t — Drawing contexts.

Synopsis




typedef     cairo_t;
cairo_t*    cairo_create                    (cairo_surface_t *target);
void        cairo_reference                 (cairo_t *cr);
void        cairo_destroy                   (cairo_t *cr);
void        cairo_save                      (cairo_t *cr);
void        cairo_restore                   (cairo_t *cr);
enum        cairo_content_t;
#define     CAIRO_CONTENT_VALID             (content)
enum        cairo_format_t;
#define     CAIRO_FORMAT_VALID              (format)
enum        cairo_operator_t;
void        cairo_set_operator              (cairo_t *cr,
                                             cairo_operator_t op);
void        cairo_set_source_rgb            (cairo_t *cr,
                                             double red,
                                             double green,
                                             double blue);
void        cairo_set_source_rgba           (cairo_t *cr,
                                             double red,
                                             double green,
                                             double blue,
                                             double alpha);
void        cairo_set_source                (cairo_t *cr,
                                             cairo_pattern_t *source);
void        cairo_set_source_surface        (cairo_t *cr,
                                             cairo_surface_t *surface,
                                             double x,
                                             double y);
void        cairo_set_tolerance             (cairo_t *cr,
                                             double tolerance);
enum        cairo_fill_rule_t;
void        cairo_set_fill_rule             (cairo_t *cr,
                                             cairo_fill_rule_t fill_rule);
void        cairo_set_line_width            (cairo_t *cr,
                                             double width);
enum        cairo_line_cap_t;
void        cairo_set_line_cap              (cairo_t *cr,
                                             cairo_line_cap_t line_cap);
enum        cairo_line_join_t;
void        cairo_set_line_join             (cairo_t *cr,
                                             cairo_line_join_t line_join);
void        cairo_set_dash                  (cairo_t *cr,
                                             double *dashes,
                                             int ndash,
                                             double offset);
void        cairo_set_miter_limit           (cairo_t *cr,
                                             double limit);
void        cairo_translate                 (cairo_t *cr,
                                             double tx,
                                             double ty);
void        cairo_scale                     (cairo_t *cr,
                                             double sx,
                                             double sy);
void        cairo_rotate                    (cairo_t *cr,
                                             double angle);
void        cairo_transform                 (cairo_t *cr,
                                             const cairo_matrix_t *matrix);
void        cairo_set_matrix                (cairo_t *cr,
                                             const cairo_matrix_t *matrix);
void        cairo_identity_matrix           (cairo_t *cr);
void        cairo_user_to_device            (cairo_t *cr,
                                             double *x,
                                             double *y);
void        cairo_user_to_device_distance   (cairo_t *cr,
                                             double *dx,
                                             double *dy);
void        cairo_device_to_user            (cairo_t *cr,
                                             double *x,
                                             double *y);
void        cairo_device_to_user_distance   (cairo_t *cr,
                                             double *dx,
                                             double *dy);
void        cairo_new_path                  (cairo_t *cr);
void        cairo_move_to                   (cairo_t *cr,
                                             double x,
                                             double y);
void        cairo_line_to                   (cairo_t *cr,
                                             double x,
                                             double y);
void        cairo_curve_to                  (cairo_t *cr,
                                             double x1,
                                             double y1,
                                             double x2,
                                             double y2,
                                             double x3,
                                             double y3);
void        cairo_arc                       (cairo_t *cr,
                                             double xc,
                                             double yc,
                                             double radius,
                                             double angle1,
                                             double angle2);
void        cairo_arc_negative              (cairo_t *cr,
                                             double xc,
                                             double yc,
                                             double radius,
                                             double angle1,
                                             double angle2);
void        cairo_rel_move_to               (cairo_t *cr,
                                             double dx,
                                             double dy);
void        cairo_rel_line_to               (cairo_t *cr,
                                             double dx,
                                             double dy);
void        cairo_rel_curve_to              (cairo_t *cr,
                                             double dx1,
                                             double dy1,
                                             double dx2,
                                             double dy2,
                                             double dx3,
                                             double dy3);
void        cairo_rectangle                 (cairo_t *cr,
                                             double x,
                                             double y,
                                             double width,
                                             double height);
void        cairo_close_path                (cairo_t *cr);
void        cairo_paint                     (cairo_t *cr);
void        cairo_paint_with_alpha          (cairo_t *cr,
                                             double alpha);
void        cairo_mask                      (cairo_t *cr,
                                             cairo_pattern_t *pattern);
void        cairo_mask_surface              (cairo_t *cr,
                                             cairo_surface_t *surface,
                                             double surface_x,
                                             double surface_y);
void        cairo_stroke                    (cairo_t *cr);
void        cairo_stroke_preserve           (cairo_t *cr);
void        cairo_fill                      (cairo_t *cr);
void        cairo_fill_preserve             (cairo_t *cr);
void        cairo_copy_page                 (cairo_t *cr);
void        cairo_show_page                 (cairo_t *cr);
cairo_bool_t cairo_in_stroke                (cairo_t *cr,
                                             double x,
                                             double y);
cairo_bool_t cairo_in_fill                  (cairo_t *cr,
                                             double x,
                                             double y);
typedef     cairo_bool_t;
void        cairo_stroke_extents            (cairo_t *cr,
                                             double *x1,
                                             double *y1,
                                             double *x2,
                                             double *y2);
void        cairo_fill_extents              (cairo_t *cr,
                                             double *x1,
                                             double *y1,
                                             double *x2,
                                             double *y2);
void        cairo_clip                      (cairo_t *cr);
void        cairo_clip_preserve             (cairo_t *cr);
void        cairo_reset_clip                (cairo_t *cr);
            cairo_glyph_t;
enum        cairo_font_slant_t;
enum        cairo_font_weight_t;
void        cairo_select_font_face          (cairo_t *cr,
                                             const char *family,
                                             cairo_font_slant_t slant,
                                             cairo_font_weight_t weight);
void        cairo_set_font_size             (cairo_t *cr,
                                             double size);
void        cairo_set_font_matrix           (cairo_t *cr,
                                             const cairo_matrix_t *matrix);
void        cairo_get_font_matrix           (cairo_t *cr,
                                             cairo_matrix_t *matrix);
void        cairo_set_font_options          (cairo_t *cr,
                                             const cairo_font_options_t *options);
void        cairo_get_font_options          (cairo_t *cr,
                                             cairo_font_options_t *options);
void        cairo_show_text                 (cairo_t *cr,
                                             const char *utf8);
void        cairo_show_glyphs               (cairo_t *cr,
                                             cairo_glyph_t *glyphs,
                                             int num_glyphs);
cairo_font_face_t* cairo_get_font_face      (cairo_t *cr);
void        cairo_font_extents              (cairo_t *cr,
                                             cairo_font_extents_t *extents);
void        cairo_set_font_face             (cairo_t *cr,
                                             cairo_font_face_t *font_face);
void        cairo_text_extents              (cairo_t *cr,
                                             const char *utf8,
                                             cairo_text_extents_t *extents);
void        cairo_glyph_extents             (cairo_t *cr,
                                             cairo_glyph_t *glyphs,
                                             int num_glyphs,
                                             cairo_text_extents_t *extents);
void        cairo_text_path                 (cairo_t *cr,
                                             const char *utf8);
void        cairo_glyph_path                (cairo_t *cr,
                                             cairo_glyph_t *glyphs,
                                             int num_glyphs);
cairo_operator_t cairo_get_operator         (cairo_t *cr);
cairo_pattern_t* cairo_get_source           (cairo_t *cr);
double      cairo_get_tolerance             (cairo_t *cr);
void        cairo_get_current_point         (cairo_t *cr,
                                             double *x,
                                             double *y);
cairo_fill_rule_t cairo_get_fill_rule       (cairo_t *cr);
double      cairo_get_line_width            (cairo_t *cr);
cairo_line_cap_t cairo_get_line_cap         (cairo_t *cr);
cairo_line_join_t cairo_get_line_join       (cairo_t *cr);
double      cairo_get_miter_limit           (cairo_t *cr);
void        cairo_get_matrix                (cairo_t *cr,
                                             cairo_matrix_t *matrix);
cairo_surface_t* cairo_get_target           (cairo_t *cr);
cairo_path_t* cairo_copy_path               (cairo_t *cr);
cairo_path_t* cairo_copy_path_flat          (cairo_t *cr);
void        cairo_append_path               (cairo_t *cr,
                                             cairo_path_t *path);
enum        cairo_path_data_type_t;
            cairo_path_t;
void        cairo_path_destroy              (cairo_path_t *path);
enum        cairo_status_t;
cairo_status_t cairo_status                 (cairo_t *cr);
#define     cairo_status_string
const char* cairo_status_to_string          (cairo_status_t status);
enum        cairo_filter_t;
cairo_surface_t* cairo_image_surface_create (cairo_format_t format,
                                             int width,
                                             int height);
cairo_surface_t* cairo_image_surface_create_for_data
                                            (unsigned char *data,
                                             cairo_format_t format,
                                             int width,
                                             int height,
                                             int stride);
int         cairo_image_surface_get_width   (cairo_surface_t *surface);
int         cairo_image_surface_get_height  (cairo_surface_t *surface);
void        (*cairo_destroy_func_t)         (void *data);
            cairo_user_data_key_t;
cairo_status_t (*cairo_read_func_t)         (void *closure,
                                             unsigned char *data,
                                             unsigned int length);
cairo_status_t (*cairo_write_func_t)        (void *closure,
                                             unsigned char *data,
                                             unsigned int length);

Description

cairo_t is the main object used when drawing with Cairo. To draw with Cairo, you create a cairo_t, set the target surface, and drawing options for the cairo_t, create shapes with functions like cairo_move_to() and cairo_line_to(), and then draw ships with cairo_stroke() or cairo_fill().

cairo_t's can be pushed to a stack via cairo_save(). They may then safely be changed, without loosing the current state. Use cairo_restore() to restore to the saved state.

Details

cairo_t

typedef struct _cairo cairo_t;

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


cairo_create ()

cairo_t*    cairo_create                    (cairo_surface_t *target);

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

Note that there are restrictions on using the same surface in multiple contexts at the same time. If, after creating cr_a with surface you also create cr_b with the same surface, you must ensure that cr_b has finished using surface before resuming use of cr_a. Currently, the only way time at which this is guaranteed is when the the last reference to cr_b is released with cairo_destroy(). (XXX: We need to add a cairo_finish() call to provide a way to achieve this explicitly). See also the CAIRO_STATUS_BAD_NESTING status.

target : target surface for the context
Returns : a newly allocated cairo_t with a reference count of 1. The initial reference count should be released with cairo_destroy() when you are done using the cairo_t. This function never returns NULL. If memory cannot be allocated, a special cairo_t object will be returned on which cairo_status() returns CAIRO_STATUS_NO_MEMORY. You can use this object normally, but no drawing will be done.

cairo_reference ()

void        cairo_reference                 (cairo_t *cr);

Increases the reference count on cr by one. This prevents cr from being destroyed until a matching call to cairo_destroy() is made.

cr : a cairo_t

cairo_destroy ()

void        cairo_destroy                   (cairo_t *cr);

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

cr : a cairo_t

cairo_save ()

void        cairo_save                      (cairo_t *cr);

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

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

cr : a cairo_t

cairo_restore ()

void        cairo_restore                   (cairo_t *cr);

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

cr : a cairo_t

enum cairo_content_t

typedef enum _cairo_content {
    CAIRO_CONTENT_COLOR		= 0x1000,
    CAIRO_CONTENT_ALPHA		= 0x2000,
    CAIRO_CONTENT_COLOR_ALPHA	= 0x3000
} cairo_content_t;

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

Note: The large values here are designed to keep cairo_content_t values distinct from cairo_format_t values so that the implementation can detect the error if users confuse the two types.

CAIRO_CONTENT_COLOR The surface will hold color content only.
CAIRO_CONTENT_ALPHA The surface will hold alpha content only.
CAIRO_CONTENT_COLOR_ALPHA The surface will hold color and alpha content.

CAIRO_CONTENT_VALID()

#define     CAIRO_CONTENT_VALID(content)

content :

enum cairo_format_t

typedef enum _cairo_format {
    CAIRO_FORMAT_ARGB32,
    CAIRO_FORMAT_RGB24,
    CAIRO_FORMAT_A8,
    CAIRO_FORMAT_A1
} cairo_format_t;

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

CAIRO_FORMAT_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.)
CAIRO_FORMAT_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.
CAIRO_FORMAT_A8 each pixel is a 8-bit quantity holding an alpha value.
CAIRO_FORMAT_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 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.

CAIRO_FORMAT_VALID()

#define     CAIRO_FORMAT_VALID(format)

format :

enum cairo_operator_t

typedef enum _cairo_operator {
    CAIRO_OPERATOR_CLEAR,

    CAIRO_OPERATOR_SOURCE,
    CAIRO_OPERATOR_OVER,
    CAIRO_OPERATOR_IN,
    CAIRO_OPERATOR_OUT,
    CAIRO_OPERATOR_ATOP,

    CAIRO_OPERATOR_DEST,
    CAIRO_OPERATOR_DEST_OVER,
    CAIRO_OPERATOR_DEST_IN,
    CAIRO_OPERATOR_DEST_OUT,
    CAIRO_OPERATOR_DEST_ATOP,

    CAIRO_OPERATOR_XOR,
    CAIRO_OPERATOR_ADD,
    CAIRO_OPERATOR_SATURATE
} cairo_operator_t;


cairo_set_operator ()

void        cairo_set_operator              (cairo_t *cr,
                                             cairo_operator_t op);

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

XXX: I'd also like to direct the reader's attention to some (not-yet-written) section on cairo's imaging model. How would I do that if such a section existed? (cworth).

cr : a cairo_t
op : a compositing operator, specified as a cairo_operator_t

cairo_set_source_rgb ()

void        cairo_set_source_rgb            (cairo_t *cr,
                                             double red,
                                             double green,
                                             double blue);

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 to 1. If the values passed in are outside that range, they will be clamped.

cr : a cairo context
red : red component of color
green : green component of color
blue : blue component of color

cairo_set_source_rgba ()

void        cairo_set_source_rgba           (cairo_t *cr,
                                             double red,
                                             double green,
                                             double blue,
                                             double alpha);

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.

cr : a cairo context
red : red component of color
green : green component of color
blue : blue component of color
alpha : alpha component of color

cairo_set_source ()

void        cairo_set_source                (cairo_t *cr,
                                             cairo_pattern_t *source);

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.

XXX: I'd also like to direct the reader's attention to some (not-yet-written) section on cairo's imaging model. How would I do that if such a section existed? (cworth).

cr : a cairo context
source : a cairo_pattern_t to be used as the source for subsequent drawing operations.

cairo_set_source_surface ()

void        cairo_set_source_surface        (cairo_t *cr,
                                             cairo_surface_t *surface,
                                             double x,
                                             double y);

This is a convenience function for creating a pattern from surface and setting it as the source in cr with cairo_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 patterns 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 cairo_get_source() so that these attributes can be modified if desired, (eg. to create a repeating pattern with cairo_pattern_set_extend()).

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

cairo_set_tolerance ()

void        cairo_set_tolerance             (cairo_t *cr,
                                             double tolerance);

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

cr : a cairo_t
tolerance : the tolerance, in device units (typically pixels)

enum cairo_fill_rule_t

typedef enum _cairo_fill_rule {
    CAIRO_FILL_RULE_WINDING,
    CAIRO_FILL_RULE_EVEN_ODD
} cairo_fill_rule_t;

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

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

cairo_set_fill_rule ()

void        cairo_set_fill_rule             (cairo_t *cr,
                                             cairo_fill_rule_t fill_rule);

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

cr : a cairo_t
fill_rule : a fill rule, specified as a cairo_fill_rule_t

cairo_set_line_width ()

void        cairo_set_line_width            (cairo_t *cr,
                                             double width);

Sets the current line width within the cairo context. The line width specifies the diameter of a pen that is circular in user-space.

As with the other stroke parameters, the current line cap style is examined by cairo_stroke(), cairo_stroke_extents(), and cairo_stroke_to_path(), but does not have any effect during path construction.

cr : a cairo_t
width : a line width, as a user-space value

enum cairo_line_cap_t

typedef enum _cairo_line_cap {
    CAIRO_LINE_CAP_BUTT,
    CAIRO_LINE_CAP_ROUND,
    CAIRO_LINE_CAP_SQUARE
} cairo_line_cap_t;

enumeration for style of line-endings

CAIRO_LINE_CAP_BUTT start(stop) the line exactly at the start(end) point
CAIRO_LINE_CAP_ROUND use a round ending, the center of the circle is the end point
CAIRO_LINE_CAP_SQUARE use squared ending, the center of the square is the end point

cairo_set_line_cap ()

void        cairo_set_line_cap              (cairo_t *cr,
                                             cairo_line_cap_t line_cap);

Sets the current line cap style within the cairo context. See cairo_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 cairo_stroke(), cairo_stroke_extents(), and cairo_stroke_to_path(), but does not have any effect during path construction.

cr : a cairo context, as a cairo_t
line_cap : a line cap style, as a cairo_line_cap_t

enum cairo_line_join_t

typedef enum _cairo_line_join {
    CAIRO_LINE_JOIN_MITER,
    CAIRO_LINE_JOIN_ROUND,
    CAIRO_LINE_JOIN_BEVEL
} cairo_line_join_t;


cairo_set_line_join ()

void        cairo_set_line_join             (cairo_t *cr,
                                             cairo_line_join_t line_join);

Sets the current line join style within the cairo context. See cairo_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 cairo_stroke(), cairo_stroke_extents(), and cairo_stroke_to_path(), but does not have any effect during path construction.

cr : a cairo context, as a cairo_t
line_join : a line joint style, as a cairo_line_join_t

cairo_set_dash ()

void        cairo_set_dash                  (cairo_t *cr,
                                             double *dashes,
                                             int ndash,
                                             double offset);

cr :
dashes :
ndash :
offset :

cairo_set_miter_limit ()

void        cairo_set_miter_limit           (cairo_t *cr,
                                             double limit);

cr :
limit :

cairo_translate ()

void        cairo_translate                 (cairo_t *cr,
                                             double tx,
                                             double ty);

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 cairo_translate. In other words, the translation of the user-space origin takes place after any existing transformation.

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

cairo_scale ()

void        cairo_scale                     (cairo_t *cr,
                                             double sx,
                                             double sy);

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.

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

cairo_rotate ()

void        cairo_rotate                    (cairo_t *cr,
                                             double angle);

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.

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

cairo_transform ()

void        cairo_transform                 (cairo_t *cr,
                                             const cairo_matrix_t *matrix);

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.

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

cairo_set_matrix ()

void        cairo_set_matrix                (cairo_t *cr,
                                             const cairo_matrix_t *matrix);

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

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

cairo_identity_matrix ()

void        cairo_identity_matrix           (cairo_t *cr);

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.

cr : a cairo context

cairo_user_to_device ()

void        cairo_user_to_device            (cairo_t *cr,
                                             double *x,
                                             double *y);

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

cr : a cairo context
x : X value of coordinate (in/out parameter)
y : Y value of coordinate (in/out parameter)

cairo_user_to_device_distance ()

void        cairo_user_to_device_distance   (cairo_t *cr,
                                             double *dx,
                                             double *dy);

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

cr : a cairo context
dx : X component of a distance vector (in/out parameter)
dy : Y component of a distance vector (in/out parameter)

cairo_device_to_user ()

void        cairo_device_to_user            (cairo_t *cr,
                                             double *x,
                                             double *y);

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

cr : a cairo
x : X value of coordinate (in/out parameter)
y : Y value of coordinate (in/out parameter)

cairo_device_to_user_distance ()

void        cairo_device_to_user_distance   (cairo_t *cr,
                                             double *dx,
                                             double *dy);

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

cr : a cairo context
dx : X component of a distance vector (in/out parameter)
dy : Y component of a distance vector (in/out parameter)

cairo_new_path ()

void        cairo_new_path                  (cairo_t *cr);

cr :

cairo_move_to ()

void        cairo_move_to                   (cairo_t *cr,
                                             double x,
                                             double y);

cr :
x :
y :

cairo_line_to ()

void        cairo_line_to                   (cairo_t *cr,
                                             double x,
                                             double y);

cr :
x :
y :

cairo_curve_to ()

void        cairo_curve_to                  (cairo_t *cr,
                                             double x1,
                                             double y1,
                                             double x2,
                                             double y2,
                                             double x3,
                                             double y3);

cr :
x1 :
y1 :
x2 :
y2 :
x3 :
y3 :

cairo_arc ()

void        cairo_arc                       (cairo_t *cr,
                                             double xc,
                                             double yc,
                                             double radius,
                                             double angle1,
                                             double angle2);

Adds an arc from angle1 to angle2 to the current path. If there is a current point, that point is connected to the start of the arc by a straight line segment. Angles are measured in radians with an angle of 0 along the X axis and an angle of M_PI radians (90 degrees) along the Y axis, so with the default transformation matrix, positive angles are clockwise. (To convert from degrees to radians, use degrees * (M_PI / 180.).) This function gives the arc in the direction of increasing angle; see cairo_arc_negative() to get the arc in the direction of decreasing angle.

A full arc is drawn as a circle. To make an oval arc, you can scale the current transformation matrix by different amounts in the X and Y directions. For example, to draw a full oval in the box given by x, y, width, height:

cairo_save (cr);
cairo_translate (x + width / 2., y + height / 2.);
cairo_scale (1. / (height / 2.), 1. / (width / 2.));
cairo_arc (cr, 0., 0., 1., 0., 2 * M_PI);
cairo_restore (cr);

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

cairo_arc_negative ()

void        cairo_arc_negative              (cairo_t *cr,
                                             double xc,
                                             double yc,
                                             double radius,
                                             double angle1,
                                             double angle2);

Adds an arc from angle1 to angle2 to the current path. The function behaves identically to cairo_arc() except that instead of giving the arc in the direction of increasing angle, it gives the arc in the direction of decreasing angle.

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

cairo_rel_move_to ()

void        cairo_rel_move_to               (cairo_t *cr,
                                             double dx,
                                             double dy);

cr :
dx :
dy :

cairo_rel_line_to ()

void        cairo_rel_line_to               (cairo_t *cr,
                                             double dx,
                                             double dy);

cr :
dx :
dy :

cairo_rel_curve_to ()

void        cairo_rel_curve_to              (cairo_t *cr,
                                             double dx1,
                                             double dy1,
                                             double dx2,
                                             double dy2,
                                             double dx3,
                                             double dy3);

cr :
dx1 :
dy1 :
dx2 :
dy2 :
dx3 :
dy3 :

cairo_rectangle ()

void        cairo_rectangle                 (cairo_t *cr,
                                             double x,
                                             double y,
                                             double width,
                                             double height);

cr :
x :
y :
width :
height :

cairo_close_path ()

void        cairo_close_path                (cairo_t *cr);

cr :

cairo_paint ()

void        cairo_paint                     (cairo_t *cr);

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

cr : a cairo context

cairo_paint_with_alpha ()

void        cairo_paint_with_alpha          (cairo_t *cr,
                                             double alpha);

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 cairo_paint(), but the drawing is faded out using the alpha value.

cr : a cairo context
alpha : alpha value, between 0 (transparent) and 1 (opaque)

cairo_mask ()

void        cairo_mask                      (cairo_t *cr,
                                             cairo_pattern_t *pattern);

A drawing operator that paints the current source using the alpha channel of pattern as a mask. (Opaque areas of mask are painted with the source, transparent areas are not painted.)

cr : a cairo context
pattern : a cairo_pattern_t

cairo_mask_surface ()

void        cairo_mask_surface              (cairo_t *cr,
                                             cairo_surface_t *surface,
                                             double surface_x,
                                             double surface_y);

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

cr : a cairo context
surface : a cairo_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

cairo_stroke ()

void        cairo_stroke                    (cairo_t *cr);

A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. After cairo_stroke, the current path will be cleared from the cairo context. See cairo_set_line_width(), cairo_set_line_join(), cairo_set_line_cap(), cairo_set_dash(), and cairo_stroke_preserve().

cr : a cairo context

cairo_stroke_preserve ()

void        cairo_stroke_preserve           (cairo_t *cr);

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

See cairo_set_line_width(), cairo_set_line_join(), cairo_set_line_cap(), cairo_set_dash(), and cairo_stroke_preserve().

cr : a cairo context

cairo_fill ()

void        cairo_fill                      (cairo_t *cr);

A drawing operator that fills the current path according to the current fill rule. After cairo_fill, the current path will be cleared from the cairo context. See cairo_set_fill_rule() and cairo_fill_preserve().

cr : a cairo context

cairo_fill_preserve ()

void        cairo_fill_preserve             (cairo_t *cr);

A drawing operator that fills the current path according to the current fill rule. Unlike cairo_fill(), cairo_fill_preserve preserves the path within the cairo context.

See cairo_set_fill_rule() and cairo_fill().

cr : a cairo context

cairo_copy_page ()

void        cairo_copy_page                 (cairo_t *cr);

cr :

cairo_show_page ()

void        cairo_show_page                 (cairo_t *cr);

cr :

cairo_in_stroke ()

cairo_bool_t cairo_in_stroke                (cairo_t *cr,
                                             double x,
                                             double y);

cr :
x :
y :
Returns :

cairo_in_fill ()

cairo_bool_t cairo_in_fill                  (cairo_t *cr,
                                             double x,
                                             double y);

cr :
x :
y :
Returns :

cairo_bool_t

typedef int cairo_bool_t;

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 */
 }


cairo_stroke_extents ()

void        cairo_stroke_extents            (cairo_t *cr,
                                             double *x1,
                                             double *y1,
                                             double *x2,
                                             double *y2);

cr :
x1 :
y1 :
x2 :
y2 :

cairo_fill_extents ()

void        cairo_fill_extents              (cairo_t *cr,
                                             double *x1,
                                             double *y1,
                                             double *x2,
                                             double *y2);

cr :
x1 :
y1 :
x2 :
y2 :

cairo_clip ()

void        cairo_clip                      (cairo_t *cr);

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

After cairo_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 cairo_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 cairo_clip() within a cairo_save()/cairo_restore() pair. The only other means of increasing the size of the clip region is cairo_reset_clip().

cr : a cairo context

cairo_clip_preserve ()

void        cairo_clip_preserve             (cairo_t *cr);

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

Unlike cairo_clip(), cairo_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 cairo_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 cairo_clip() within a cairo_save()/cairo_restore() pair. The only other means of increasing the size of the clip region is cairo_reset_clip().

cr : a cairo context

cairo_reset_clip ()

void        cairo_reset_clip                (cairo_t *cr);

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 cairo_reset_clip() as it will cause results unexpected by higher-level code which calls cairo_clip(). Consider using cairo_save() and cairo_restore() around cairo_clip() as a more robust means of temporarily restricting the clip region.

cr : a cairo context

cairo_glyph_t

typedef struct {
  unsigned long        index;
  double               x;
  double               y;
} cairo_glyph_t;

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

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

enum cairo_font_slant_t

typedef enum _cairo_font_slant {
  CAIRO_FONT_SLANT_NORMAL,
  CAIRO_FONT_SLANT_ITALIC,
  CAIRO_FONT_SLANT_OBLIQUE
} cairo_font_slant_t;


enum cairo_font_weight_t

typedef enum _cairo_font_weight {
  CAIRO_FONT_WEIGHT_NORMAL,
  CAIRO_FONT_WEIGHT_BOLD
} cairo_font_weight_t;


cairo_select_font_face ()

void        cairo_select_font_face          (cairo_t *cr,
                                             const char *family,
                                             cairo_font_slant_t slant,
                                             cairo_font_weight_t weight);

Selects a family and style of font from a simplified description as a family name, slant and weight. This function is meant to be used only for applications with simple font needs: Cairo doesn't provide for operations such as listing all available fonts on the system, and it is expected that most applications will need to use a more comprehensive font handling and text layout library in addition to Cairo.

cr : a cairo_t
family : a font family name, encoded in UTF-8
slant : the slant for the font
weight : the weight for the font

cairo_set_font_size ()

void        cairo_set_font_size             (cairo_t *cr,
                                             double size);

Sets the current font matrix to a scale by a factor of size, replacing any font matrix previously set with cairo_set_font_size() or cairo_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.)

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

cairo_set_font_matrix ()

void        cairo_set_font_matrix           (cairo_t *cr,
                                             const cairo_matrix_t *matrix);

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 cairo_set_font_size()), but a more complex font matrix can be used to shear the font or stretch it unequally along the two axes

cr : a cairo_t
matrix : a cairo_matrix_t describing a transform to be applied to the current font.

cairo_get_font_matrix ()

void        cairo_get_font_matrix           (cairo_t *cr,
                                             cairo_matrix_t *matrix);

Stores the current font matrix into matrix. See cairo_set_font_matrix().

cr : a cairo_t
matrix : return value for the matrix

cairo_set_font_options ()

void        cairo_set_font_options          (cairo_t *cr,
                                             const cairo_font_options_t *options);

Sets a set of custom font rendering options for the cairo_t. Rendering options are derived by merging these options with the options derived from underlying surface; if the value in options has a default value (like CAIRO_ANTIALIAS_DEFAULT), then the value from the surface is used.

cr : a cairo_t
options : font options to use

cairo_get_font_options ()

void        cairo_get_font_options          (cairo_t *cr,
                                             cairo_font_options_t *options);

Retrieves font rendering options set via cairo_set_font_options. Note that the returned options do not include any options derived from the underlying surface; they are literally the options passed to cairo_set_font_options().

cr : a cairo_t
options : a cairo_font_options_t object into which to store the retrieved options. All existing values are overwritten

cairo_show_text ()

void        cairo_show_text                 (cairo_t *cr,
                                             const char *utf8);

cr :
utf8 :

cairo_show_glyphs ()

void        cairo_show_glyphs               (cairo_t *cr,
                                             cairo_glyph_t *glyphs,
                                             int num_glyphs);

cr :
glyphs :
num_glyphs :

cairo_get_font_face ()

cairo_font_face_t* cairo_get_font_face      (cairo_t *cr);

Gets the current font face for a cairo_t.

cr : a cairo_t
Returns : the current font object. Can return NULL on out-of-memory or if the context is already in an error state. This object is owned by cairo. To keep a reference to it, you must call cairo_font_face_reference().

cairo_font_extents ()

void        cairo_font_extents              (cairo_t *cr,
                                             cairo_font_extents_t *extents);

Gets the font extents for the currently selected font.

cr : a cairo_t
extents : a cairo_font_extents_t object into which the results will be stored.

cairo_set_font_face ()

void        cairo_set_font_face             (cairo_t *cr,
                                             cairo_font_face_t *font_face);

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

cr : a cairo_t
font_face : a cairo_font_face_t, or NULL to restore to the default font

cairo_text_extents ()

void        cairo_text_extents              (cairo_t *cr,
                                             const char *utf8,
                                             cairo_text_extents_t *extents);

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 cairo_show_text). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by cairo_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.

cr : a cairo_t
utf8 : a string of text, encoded in utf-8
extents : a cairo_text_extents_t object into which the results will be stored.

cairo_glyph_extents ()

void        cairo_glyph_extents             (cairo_t *cr,
                                             cairo_glyph_t *glyphs,
                                             int num_glyphs,
                                             cairo_text_extents_t *extents);

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 cairo_show_glyphs). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by cairo_show_glyphs.

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

cr : a cairo_t
glyphs : an array of cairo_glyph_t objects
num_glyphs : the number of elements in glyphs
extents : a cairo_text_extents_t object into which the results will be stored

cairo_text_path ()

void        cairo_text_path                 (cairo_t *cr,
                                             const char *utf8);

cr :
utf8 :

cairo_glyph_path ()

void        cairo_glyph_path                (cairo_t *cr,
                                             cairo_glyph_t *glyphs,
                                             int num_glyphs);

cr :
glyphs :
num_glyphs :

cairo_get_operator ()

cairo_operator_t cairo_get_operator         (cairo_t *cr);

Gets the current compositing operator for a cairo context.

cr : a cairo context
Returns : the current compositing operator.

cairo_get_source ()

cairo_pattern_t* cairo_get_source           (cairo_t *cr);

Gets the current source pattern for cr.

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

cairo_get_tolerance ()

double      cairo_get_tolerance             (cairo_t *cr);

Gets the current tolerance value, as set by cairo_set_tolerance().

cr : a cairo context
Returns : the current tolerance value.

cairo_get_current_point ()

void        cairo_get_current_point         (cairo_t *cr,
                                             double *x,
                                             double *y);

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 then x and y will both be set to 0.0.

Most path construction functions alter the current point. See the following for details on how they affect the current point:

cairo_new_path(), cairo_move_to(), cairo_line_to(), cairo_curve_to(), cairo_arc(), cairo_rel_move_to(), cairo_rel_line_to(), cairo_rel_curve_to(), cairo_arc(), cairo_text_path(), cairo_stroke_to_path()

cr : a cairo context
x : return value for X coordinate of the current point
y : return value for Y coordinate of the current point

cairo_get_fill_rule ()

cairo_fill_rule_t cairo_get_fill_rule       (cairo_t *cr);

Gets the current fill rule, as set by cairo_set_fill_rule().

cr : a cairo context
Returns : the current fill rule.

cairo_get_line_width ()

double      cairo_get_line_width            (cairo_t *cr);

Gets the current line width, as set by cairo_set_line_width().

cr : a cairo context
Returns : the current line width, in user-space units.

cairo_get_line_cap ()

cairo_line_cap_t cairo_get_line_cap         (cairo_t *cr);

Gets the current line cap style, as set by cairo_set_line_cap().

cr : a cairo context
Returns : the current line cap style.

cairo_get_line_join ()

cairo_line_join_t cairo_get_line_join       (cairo_t *cr);

Gets the current line join style, as set by cairo_set_line_join().

cr : a cairo context
Returns : the current line join style.

cairo_get_miter_limit ()

double      cairo_get_miter_limit           (cairo_t *cr);

Gets the current miter limit, as set by cairo_set_miter_limit().

cr : a cairo context
Returns : the current miter limit.

cairo_get_matrix ()

void        cairo_get_matrix                (cairo_t *cr,
                                             cairo_matrix_t *matrix);

Stores the current transformation matrix (CTM) into matrix.

cr : a cairo context
matrix : return value for the matrix

cairo_get_target ()

cairo_surface_t* cairo_get_target           (cairo_t *cr);

Gets the target surface for the cairo context as passed to cairo_create().

cr : a cairo context
Returns : the target surface, (or NULL if cr is in an error state). This object is owned by cairo. To keep a reference to it, you must call cairo_surface_reference().

cairo_copy_path ()

cairo_path_t* cairo_copy_path               (cairo_t *cr);

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

cr : a cairo context
Returns : the copy of the current path. The caller owns the returned object and should call cairo_path_destroy() when finished with it. This function will always return a valid pointer, but the result will have no data, (data==NULL and num_data==0), if either of the following conditions hold: 1) If there is insufficient memory to copy the path. In this case path->status will be set to CAIRO_STATUS_NO_MEMORY. 2) If cr is already in an error state. In this case path->status will contain the same status that would be returned by cairo_status(cr).

cairo_copy_path_flat ()

cairo_path_t* cairo_copy_path_flat          (cairo_t *cr);

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

This function is like cairo_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 CAIRO_PATH_CURVE_TO which will instead be replaced by a series of CAIRO_PATH_LINE_TO elements.

cr : a cairo context
Returns : the copy of the current path. The caller owns the returned object and should call cairo_path_destroy() when finished with it. This function will always return a valid pointer, but the result will have no data, (data==NULL and num_data==0), if either of the following conditions hold: 1) If there is insufficient memory to copy the path. In this case path->status will be set to CAIRO_STATUS_NO_MEMORY. 2) If cr is already in an error state. In this case path->status will contain the same status that would be returned by cairo_status(cr).

cairo_append_path ()

void        cairo_append_path               (cairo_t *cr,
                                             cairo_path_t *path);

Append the path onto the current path. The path may be either the return value from one of cairo_copy_path() or cairo_copy_path_flat() or it may be constructed manually. See cairo_path_t for details on how the path data structure should be initialized, and note that path->status must be initialized to CAIRO_STATUS_SUCCESS.

cr : a cairo context
path : path to be appended

enum cairo_path_data_type_t

typedef enum _cairo_path_data_type {
    CAIRO_PATH_MOVE_TO,
    CAIRO_PATH_LINE_TO,
    CAIRO_PATH_CURVE_TO,
    CAIRO_PATH_CLOSE_PATH
} cairo_path_data_type_t;


cairo_path_t

typedef struct {
    cairo_status_t status;
    cairo_path_data_t *data;
    int num_data;
} cairo_path_t;

A data structure for holding a path. This data structure serves as the return value for cairo_copy_path_data() and cairo_copy_path_data_flat() as well the input value for cairo_append_path().

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 (MOVE_TO, LINE_TO, CURVE_TO, CLOSE_PATH), since the data includes both headers and coordinates for each portion.

cairo_status_t status; the current error status
cairo_path_data_t *data; the elements in the path
int num_data; the number of elements in the data array

cairo_path_destroy ()

void        cairo_path_destroy              (cairo_path_t *path);

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

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

path : a path to destroy which was previously returned by either cairo_copy_path or cairo_copy_path_flat.

enum cairo_status_t

typedef enum _cairo_status {
    CAIRO_STATUS_SUCCESS = 0,
    CAIRO_STATUS_NO_MEMORY,
    CAIRO_STATUS_INVALID_RESTORE,
    CAIRO_STATUS_INVALID_POP_GROUP,
    CAIRO_STATUS_NO_CURRENT_POINT,
    CAIRO_STATUS_INVALID_MATRIX,
    CAIRO_STATUS_INVALID_STATUS,
    CAIRO_STATUS_NULL_POINTER,
    CAIRO_STATUS_INVALID_STRING,
    CAIRO_STATUS_INVALID_PATH_DATA,
    CAIRO_STATUS_READ_ERROR,
    CAIRO_STATUS_WRITE_ERROR,
    CAIRO_STATUS_SURFACE_FINISHED,
    CAIRO_STATUS_SURFACE_TYPE_MISMATCH,
    CAIRO_STATUS_PATTERN_TYPE_MISMATCH
} cairo_status_t;

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

CAIRO_STATUS_SUCCESS no error has occurred
CAIRO_STATUS_NO_MEMORY out of memory
CAIRO_STATUS_INVALID_RESTORE cairo_restore without matching cairo_save
CAIRO_STATUS_INVALID_POP_GROUP no saved group to pop
CAIRO_STATUS_NO_CURRENT_POINT no current point defined
CAIRO_STATUS_INVALID_MATRIX invalid matrix (not invertible)
CAIRO_STATUS_INVALID_STATUS invalid value for an input cairo_status_t
CAIRO_STATUS_NULL_POINTER NULL pointer
CAIRO_STATUS_INVALID_STRING input string not valid UTF-8
CAIRO_STATUS_INVALID_PATH_DATA input path data not valid
CAIRO_STATUS_READ_ERROR error while reading from input stream
CAIRO_STATUS_WRITE_ERROR error while writing to output stream
CAIRO_STATUS_SURFACE_FINISHED target surface has been finished
CAIRO_STATUS_SURFACE_TYPE_MISMATCH the surface type is not appropriate for the operation
CAIRO_STATUS_PATTERN_TYPE_MISMATCH the pattern type is not appropriate for the operation

cairo_status ()

cairo_status_t cairo_status                 (cairo_t *cr);

cr :
Returns :

cairo_status_string

#define cairo_status_string		cairo_status_string_DEPRECATED_BY_cairo_status_AND_cairo_status_to_string


cairo_status_to_string ()

const char* cairo_status_to_string          (cairo_status_t status);

status :
Returns :

enum cairo_filter_t

typedef enum _cairo_filter {
    CAIRO_FILTER_FAST,
    CAIRO_FILTER_GOOD,
    CAIRO_FILTER_BEST,
    CAIRO_FILTER_NEAREST,
    CAIRO_FILTER_BILINEAR,
    CAIRO_FILTER_GAUSSIAN
} cairo_filter_t;


cairo_image_surface_create ()

cairo_surface_t* cairo_image_surface_create (cairo_format_t format,
                                             int width,
                                             int height);

Creates an image surface of the specified format and dimensions. The initial contents of the surface is undefined; you must explicitely clear the buffer, using, for example, cairo_rectangle() and cairo_fill() if you want it cleared.

format : format of pixels in the surface to create
width : width of the surface, in pixels
height : height of the surface, in pixels
Returns : the newly created surface, or NULL if it couldn't be created because of lack of memory

cairo_image_surface_create_for_data ()

cairo_surface_t* cairo_image_surface_create_for_data
                                            (unsigned char *data,
                                             cairo_format_t format,
                                             int width,
                                             int height,
                                             int stride);

Creates an image surface for the provided pixel data. The output buffer must be kept around until the cairo_surface_t is destroyed or cairo_surface_finish() is called on the surface. The initial contents of buffer will be used as the inital image contents; you must explicitely clear the buffer, using, for example, cairo_rectangle() and cairo_fill() if you want it cleared.

data : a pointer to a buffer supplied by the application in which to write contents.
format : the format of pixels in the buffer
width : the width of the image to be stored in the buffer
height : the height of the image to be stored in the buffer
stride : the number of bytes between the start of rows in the buffer. Having this be specified separate from width allows for padding at the end of rows, or for writing to a subportion of a larger image.
Returns : the newly created surface, or NULL if it couldn't be created because of lack of memory

cairo_image_surface_get_width ()

int         cairo_image_surface_get_width   (cairo_surface_t *surface);

Get the width of the image surface in pixels.

surface : a cairo_image_surface_t
Returns : the width of the surface in pixels.

cairo_image_surface_get_height ()

int         cairo_image_surface_get_height  (cairo_surface_t *surface);

Get the height of the image surface in pixels.

surface : a cairo_image_surface_t
Returns : the height of the surface in pixels.

cairo_destroy_func_t ()

void        (*cairo_destroy_func_t)         (void *data);

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

data : The data element being destroyed.

cairo_user_data_key_t

typedef struct {
    int unused;
} cairo_user_data_key_t;

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.

int unused; not used; ignore.

cairo_read_func_t ()

cairo_status_t (*cairo_read_func_t)         (void *closure,
                                             unsigned char *data,
                                             unsigned int length);

cairo_read_func_t is the type of function which is called when a backend needs to read data from an intput stream. It is passed the closure which was specified by the user at the time the read function was registered, the buffer to read the data into and the length of the data in bytes. The read function should return CAIRO_STATUS_SUCCESS if all the data was successfully read, CAIRO_STATUS_READ_ERROR otherwise.

closure : the input closure
data : the buffer into which to read the data
length : the amount of data to read
Returns : the status code of the read operation

cairo_write_func_t ()

cairo_status_t (*cairo_write_func_t)        (void *closure,
                                             unsigned char *data,
                                             unsigned int length);

cairo_write_func_t is the type of function which is called when a backend needs to write data to an output stream. It is passed the closure which was specified by the user at the time the write function was registered, the data to write and the length of the data in bytes. The write function should return CAIRO_STATUS_SUCCESS if all the data was successfully written, CAIRO_STATUS_WRITE_ERROR otherwise.

closure : the output closure
data : the buffer containing the data to write
length : the amount of data to write
Returns : the status code of the write operation