## 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_format_t;
    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_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_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.

### 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     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_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_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` |
`CAIRO_STATUS_NO_CURRENT_POINT` | no current point defined
`CAIRO_STATUS_INVALID_MATRIX` | invalid matrix (not invertible)
`CAIRO_STATUS_INVALID_STATUS` |
`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` : |

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

### 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 written, CAIRO_STATUS_READ_ERROR otherwise.

`closure` : |
`data` : |
`length` : |
Returns : |

### 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` : |
`data` : |
`length` : |
Returns : |