Cairo: A Vector Graphics Library  

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);
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 
the current error status 
cairo_path_data_t * 
the elements in the path 
int 
the number of elements in the data array 
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 easeofuse. 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 ""
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);
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* 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.

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_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 piecewiselinear
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:
path>status
will be set to
CAIRO_STATUS_NO_MEMORY
.cr
is already in an error state. In this case
path>status
will contain the same status that
would be returned by cairo_status()
.

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.

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.

a path previously returned by either cairo_copy_path() or
cairo_copy_path_flat() .

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
.

a cairo context 

path to be appended 
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 userspace 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()

a cairo context 

return value for X coordinate of the current point 

return value for Y coordinate of the current point 
void cairo_new_path (cairo_t *cr);
Clears the current path. After this call there will be no current point.

a cairo context 
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.

a cairo context 
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 userspace). An angle of M_PI
radians
(90 degrees) is in the direction of the positive Y axis (in
userspace). 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 userspace. 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);

a cairo context 

X position of the center of the arc 

Y position of the center of the arc 

the radius of the arc 

the start angle, in radians 

the end angle, in radians 
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.

a cairo context 

X position of the center of the arc 

Y position of the center of the arc 

the radius of the arc 

the start angle, in radians 

the end angle, in radians 
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 userspace coordinates, using (x1
, y1
) and
(x2
, y2
) as the control points. After this call the current point
will be (x3
, y3
).

a cairo context 

the X coordinate of the first control point 

the Y coordinate of the first control point 

the X coordinate of the second control point 

the Y coordinate of the second control point 

the X coordinate of the end of the curve 

the Y coordinate of the end of the curve 
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 userspace coordinates. After this call the current point
will be (x
, y
).

a cairo context 

the X coordinate of the end of the new line 

the Y coordinate of the end of the new line 
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
).

a cairo context 

the X coordinate of the new position 

the Y coordinate of the new position 
void cairo_rectangle (cairo_t *cr, double x, double y, double width, double height);
Adds a closedsubpath rectangle of the given size to the current
path at position (x
, y
) in userspace 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);

a cairo context 

the X coordinate of the top left corner of the rectangle 

the Y coordinate to the top left corner of the rectangle 

the width of the rectangle 

the height of the rectangle 
void cairo_glyph_path (cairo_t *cr, cairo_glyph_t *glyphs, int num_glyphs);





void cairo_rel_curve_to (cairo_t *cr, double dx1, double dy1, double dx2, double dy2, double dx3, double dy3);
Relativecoordinate 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
).

a cairo context 

the X offset to the first control point 

the Y offset to the first control point 

the X offset to the second control point 

the Y offset to the second control point 

the X offset to the end of the curve 

the Y offset to the end of the curve 
void cairo_rel_line_to (cairo_t *cr, double dx, double dy);
Relativecoordinate 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
).

a cairo context 

the X offset to the end of the new line 

the Y offset to the end of the new line 
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
).

a cairo context 

the X offset 

the Y offset 