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_new_sub_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);

cairo_copy_path_flat ()

cairo_path_t* cairo_copy_path_flat          (cairo_t *cr);

cairo_path_destroy ()

void        cairo_path_destroy              (cairo_path_t *path);

cairo_append_path ()

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

cairo_get_current_point ()

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

cairo_new_path ()

void        cairo_new_path                  (cairo_t *cr);

cairo_new_sub_path ()

void        cairo_new_sub_path              (cairo_t *cr);

Since 1.2


cairo_close_path ()

void        cairo_close_path                (cairo_t *cr);

cairo_arc ()

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

cairo_arc_negative ()

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

cairo_curve_to ()

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

cairo_line_to ()

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

cairo_move_to ()

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

cairo_rectangle ()

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

cairo_glyph_path ()

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

cairo_text_path ()

void        cairo_text_path                 (cairo_t *cr,
                                             const char *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);

cairo_rel_line_to ()

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

cairo_rel_move_to ()

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