Paths

## Paths Paths — Creating paths and manipulating path data |

## Synopsis

                cairo_path_t;
    union       cairo_path_data_t;
    enum        cairo_path_data_type_t;
    cairo_path_t* cairo_copy_path               (cairo_t *cr);
    cairo_path_t* cairo_copy_path_flat          (cairo_t *cr);
    void        cairo_path_destroy              (cairo_path_t *path);
    void        cairo_append_path               (cairo_t *cr,
                                                 cairo_path_t *path);
    void        cairo_get_current_point         (cairo_t *cr,
                                                 double *x,
                                                 double *y);
    void        cairo_new_path                  (cairo_t *cr);
    void        cairo_close_path                (cairo_t *cr);
    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_curve_to                  (cairo_t *cr,
                                                 double x1,
                                                 double y1,
                                                 double x2,
                                                 double y2,
                                                 double x3,
                                                 double y3);
    void        cairo_line_to                   (cairo_t *cr,
                                                 double x,
                                                 double y);
    void        cairo_move_to                   (cairo_t *cr,
                                                 double x,
                                                 double y);
    void        cairo_rectangle                 (cairo_t *cr,
                                                 double x,
                                                 double y,
                                                 double width,
                                                 double height);
    void        cairo_glyph_path                (cairo_t *cr,
                                                 cairo_glyph_t *glyphs,
                                                 int num_glyphs);
    void        cairo_text_path                 (cairo_t *cr,
                                                 const char *utf8);
    void        cairo_rel_curve_to              (cairo_t *cr,
                                                 double dx1,
                                                 double dy1,
                                                 double dx2,
                                                 double dy2,
                                                 double dx3,
                                                 double dy3);
    void        cairo_rel_line_to               (cairo_t *cr,
                                                 double dx,
                                                 double dy);
    void        cairo_rel_move_to               (cairo_t *cr,
                                                 double dx,
                                                 double dy);

## Description

## Details

### 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 (defined in cairo_path_data_type_t), 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

### union cairo_path_data_t

    union cairo_path_data_t {
        struct {
    	cairo_path_data_type_t type;
    	int length;
        } header;
        struct {
    	double x, y;
        } point;
    };

cairo_path_data_t is used to represent the path data inside a cairo_path_t.

The data structure is designed to try to balance the demands of efficiency and ease-of-use. A path is represented as an array of cairo_path_data_t, which is a union of headers and points.

Each portion of the path is represented by one or more elements in the array, (one header followed by 0 or more points). The length value of the header is the number of array elements for the current portion including the header, (ie. length == 1 + # of points), and where the number of points for each element type must be as follows:

        CAIRO_PATH_MOVE_TO:     1 point
        CAIRO_PATH_LINE_TO:     1 point
        CAIRO_PATH_CURVE_TO:    3 points
        CAIRO_PATH_CLOSE_PATH:  0 points

The semantics and ordering of the coordinate values are consistent with `cairo_move_to()`, `cairo_line_to()`, `cairo_curve_to()`, and `cairo_close_path()`.

Here is sample code for iterating through a cairo_path_t:

         int i;
         cairo_path_t *path;
         cairo_path_data_t *data;

         path = cairo_copy_path (cr);

         for (i=0; i < path->num_data; i += path->data[i].header.length) {
             data = &path->data[i];
             switch (data->header.type) {
             case CAIRO_PATH_MOVE_TO:
                 do_move_to_things (data[1].point.x, data[1].point.y);
                 break;
             case CAIRO_PATH_LINE_TO:
                 do_line_to_things (data[1].point.x, data[1].point.y);
                 break;
             case CAIRO_PATH_CURVE_TO:
                 do_curve_to_things (data[1].point.x, data[1].point.y,
                                     data[2].point.x, data[2].point.y,
                                     data[3].point.x, data[3].point.y);
                 break;
             case CAIRO_PATH_CLOSE_PATH:
                 do_close_path_things();
                 break;
             }
         }
         cairo_path_destroy (path);

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

Return value: 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.
2. If `cr` is already in an error state.

In either case, `path->status` will be set to `CAIRO_STATUS_NO_MEMORY` (regardless of what the error status in `cr` might have been).

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

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

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` : | 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.

### 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 previously returned by either `cairo_copy_path()` or `cairo_copy_path_flat()`.

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

### 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_new_path ()

    void        cairo_new_path                  (cairo_t *cr);

Clears the current path. After this call there will be no current point.

`cr` : | a cairo context

### cairo_close_path ()

    void        cairo_close_path                (cairo_t *cr);

Adds a line segment to the path from the current point to the beginning of the current subpath, (the most recent point passed to `cairo_move_to()`), and closes this subpath.

The behavior of `cairo_close_path()` is distinct from simply calling `cairo_line_to()` with the equivalent coordinate in the case of stroking. When a closed subpath is stroked, there are no caps on the ends of the subpath. Instead, their is a line join connecting the final and initial segments of the subpath.

`cr` : | a cairo context

### cairo_arc ()

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

Adds a circular arc of the given `radius` to the current path. The arc is centered at (`xc`, `yc`), begins at `angle1` and proceeds in the direction of increasing angles to end at `angle2`. If `angle2` is less than `angle1` it will be progressively increased by 2*M_PI until it is greater than `angle1`.

If there is a current point, an initial line segment will be added to the path to connect the current point to the beginning of the arc.

Angles are measured in radians. An angle of 0 is in the direction of the positive X axis (in user-space). An angle of `M_PI` radians (90 degrees) is in the direction of the positive Y axis (in user-space). Angles increase in the direction from the positive X axis toward the positive Y axis. So with the default transformation matrix, angles increase in a clockwise direction.

(To convert from degrees to radians, use `degrees * (M_PI / 180.)`.)

This function gives the arc in the direction of increasing angles; see `cairo_arc_negative()` to get the arc in the direction of decreasing angles.

The arc is circular in user-space. To achieve an elliptical arc, you can scale the current transformation matrix by different amounts in the X and Y directions. For example, to draw an ellipse 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 a circular arc of the given `radius` to the current path. The arc is centered at (`xc`, `yc`), begins at `angle1` and proceeds in the direction of decreasing angles to end at `angle2`. If `angle2` is greater than `angle1` it will be progressively decreased by 2*M_PI until it is greater than `angle1`.

See `cairo_arc()` for more details. This function differs only in the direction of the arc between the two angles.

`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_curve_to ()

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

Adds a cubic Bézier spline to the path from the current point to position (`x3`, `y3`) in user-space coordinates, using (`x1`, `y1`) and (`x2`, `y2`) as the control points. After this call the current point will be (`x3`, `y3`).

`cr` : | a cairo context
`x1` : | the X coordinate of the first control point
`y1` : | the Y coordinate of the first control point
`x2` : | the X coordinate of the second control point
`y2` : | the Y coordinate of the second control point
`x3` : | the X coordinate of the end of the curve
`y3` : | the Y coordinate of the end of the curve

### cairo_line_to ()

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

Adds a line to the path from the current point to position (`x`, `y`) in user-space coordinates. After this call the current point will be (`x`, `y`).

`cr` : | a cairo context
`x` : | the X coordinate of the end of the new line
`y` : | the Y coordinate of the end of the new line

### cairo_move_to ()

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

If the current subpath is not empty, begin a new subpath. After this call the current point will be (`x`, `y`).

`cr` : | a cairo context
`x` : | the X coordinate of the new position
`y` : | the Y coordinate of the new position

### cairo_rectangle ()

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

Adds a closed-subpath rectangle of the given size to the current path at position (`x`, `y`) in user-space coordinates.

This function is logically equivalent to:

    cairo_move_to (cr, x, y);
    cairo_rel_line_to (cr, width, 0);
    cairo_rel_line_to (cr, 0, height);
    cairo_rel_line_to (cr, -width, 0);
    cairo_close_path (cr);

`cr` : | a cairo context
`x` : | the X coordinate of the top left corner of the rectangle
`y` : | the Y coordinate to the top left corner of the rectangle
`width` : | the width of the rectangle
`height` : | the height of the rectangle

### cairo_glyph_path ()

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

`cr` : |
`glyphs` : |
`num_glyphs` : |

### cairo_text_path ()

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

`cr` : |
`utf8` : |

### cairo_rel_curve_to ()

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

Relative-coordinate version of `cairo_curve_to()`. All offsets are relative to the current point. Adds a cubic Bézier spline to the path from the current point to a point offset from the current point by (`dx3`, `dy3`), using points offset by (`dx1`, `dy1`) and (`dx2`, `dy2`) as the control points. After this call the current point will be offset by (`dx3`, `dy3`).

Given a current point of (x, y), cairo_rel_curve_to (`cr`, `dx1`, `dy1`, `dx2`, `dy2`, `dx3`, `dy3`) is logically equivalent to cairo_curve_to (`cr`, x + `dx1`, y + `dy1`, x + `dx2`, y + `dy2`, x + `dx3`, y + `dy3`).

`cr` : | a cairo context
`dx1` : | the X offset to the first control point
`dy1` : | the Y offset to the first control point
`dx2` : | the X offset to the second control point
`dy2` : | the Y offset to the second control point
`dx3` : | the X offset to the end of the curve
`dy3` : | the Y offset to the end of the curve

### cairo_rel_line_to ()

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

Relative-coordinate version of `cairo_line_to()`. Adds a line to the path from the current point to a point that is offset from the current point by (`dx`, `dy`) in user space. After this call the current point will be offset by (`dx`, `dy`).

Given a current point of (x, y), cairo_rel_line_to(`cr`, `dx`, `dy`) is logically equivalent to cairo_line_to (`cr`, x + `dx`, y + `dy`).

`cr` : | a cairo context
`dx` : | the X offset to the end of the new line
`dy` : | the Y offset to the end of the new line

### cairo_rel_move_to ()

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

If the current subpath is not empty, begin a new subpath. After this call the current point will offset by (`x`, `y`).

Given a current point of (x, y), cairo_rel_move_to(`cr`, `dx`, `dy`) is logically equivalent to cairo_move_to (`cr`, x + `dx`, y + `dy`).

`cr` : | a cairo context
`dx` : | the X offset
`dy` : | the Y offset