Paths: Cairo: A Vector Graphics Library

- - -

Paths

Paths — Creating paths and manipulating path data

Functions

---- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

-cairo_path_t * -	-cairo_copy_path () -
-cairo_path_t * -	-cairo_copy_path_flat () -
-void -	-cairo_path_destroy () -
-void -	-cairo_append_path () -
-cairo_bool_t -	-cairo_has_current_point () -
-void -	-cairo_get_current_point () -
-void -	-cairo_new_path () -
-void -	-cairo_new_sub_path () -
-void -	-cairo_close_path () -
-void -	-cairo_arc () -
-void -	-cairo_arc_negative () -
-void -	-cairo_curve_to () -
-void -	-cairo_line_to () -
-void -	-cairo_move_to () -
-void -	-cairo_rectangle () -
-void -	-cairo_glyph_path () -
-void -	-cairo_text_path () -
-void -	-cairo_rel_curve_to () -
-void -	-cairo_rel_line_to () -
-void -	-cairo_rel_move_to () -
-void -	-cairo_path_extents () -

Types and Values

---- - - - - - - - - - - - - - - -

	cairo_path_t
union	cairo_path_data_t
enum	cairo_path_data_type_t

Description

Paths are the most basic drawing tools and are primarily used to implicitly -generate simple masks.

Functions

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.

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:

If there is insufficient memory to copy the path. In this - case path->status will be set to - CAIRO_STATUS_NO_MEMORY.
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().

Parameters

----- - - - - - -

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.

Since: 1.0

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:

If there is insufficient memory to copy the path. In this - case path->status will be set to - CAIRO_STATUS_NO_MEMORY.
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().

Parameters

----- - - - - - -

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.

Since: 1.0

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

Parameters

----- - - - - - -

path

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

Since: 1.0

cairo_append_path ()

void
-cairo_append_path (cairo_t *cr,
-                   const 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.

Parameters

----- - - - - - - - - - - - - -

cr	a cairo context
path	path to be appended

Since: 1.0

cairo_has_current_point ()

cairo_bool_t
-cairo_has_current_point (cairo_t *cr);

Returns whether a current point is defined on the current path. -See cairo_get_current_point() for details on the current point.

Parameters

----- - - - - - -

a cairo context

Returns

whether a current point is defined.

Since: 1.6

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 or if cr - is in an -error status, x - and y - will both be set to 0.0. It is possible to -check this in advance with cairo_has_current_point().

Most path construction functions alter the current point. See the -following for details on how they affect the current point: -cairo_new_path(), cairo_new_sub_path(), -cairo_append_path(), cairo_close_path(), -cairo_move_to(), cairo_line_to(), cairo_curve_to(), -cairo_rel_move_to(), cairo_rel_line_to(), cairo_rel_curve_to(), -cairo_arc(), cairo_arc_negative(), cairo_rectangle(), -cairo_text_path(), cairo_glyph_path(), cairo_stroke_to_path().

Some functions use and alter the current point but do not -otherwise change current path: -cairo_show_text().

Some functions unset the current path and as a result, current point: -cairo_fill(), cairo_stroke().

Parameters

----- - - - - - - - - - - - - - - - - - -

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

Since: 1.0

cairo_new_path ()

void
-cairo_new_path (cairo_t *cr);

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

Parameters

----- - - - - - -

a cairo context

Since: 1.0

cairo_new_sub_path ()

void
-cairo_new_sub_path (cairo_t *cr);

Begin a new sub-path. Note that the existing path is not -affected. After this call there will be no current point.

In many cases, this call is not needed since new sub-paths are -frequently started with cairo_move_to().

A call to cairo_new_sub_path() is particularly useful when -beginning a new sub-path with one of the cairo_arc() calls. This -makes things easier as it is no longer necessary to manually -compute the arc's initial coordinates for a call to -cairo_move_to().

Parameters

----- - - - - - -

a cairo context

Since: 1.2

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 sub-path, (the most recent point passed to -cairo_move_to()), and closes this sub-path. After this call the -current point will be at the joined endpoint of the sub-path.

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 sub-path is stroked, there are no caps on -the ends of the sub-path. Instead, there is a line join connecting -the final and initial segments of the sub-path.

If there is no current point before the call to cairo_close_path(), -this function will have no effect.

Note: As of cairo version 1.2.4 any call to cairo_close_path() will -place an explicit MOVE_TO element into the path immediately after -the CLOSE_PATH element, (which can be seen in cairo_copy_path() for -example). This can simplify path processing in some cases as it may -not be necessary to save the "last move_to point" during processing -as the MOVE_TO immediately after the CLOSE_PATH will provide that -point.

Parameters

----- - - - - - -

a cairo context

Since: 1.0

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. If this initial line is undesired, it can be avoided by -calling cairo_new_sub_path() before calling cairo_arc().

Angles are measured in radians. An angle of 0.0 is in the direction -of the positive X axis (in user space). An angle of -M_PI/2.0 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 -:

- - - - - - - -

1
-2
-3
-4
-5

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

- -

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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

Since: 1.0

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 less than angle1 -.

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

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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

Since: 1.0

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

If there is no current point before the call to cairo_curve_to() -this function will behave as if preceded by a call to -cairo_move_to(cr -, x1 -, y1 -).

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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

Since: 1.0

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

If there is no current point before the call to cairo_line_to() -this function will behave as cairo_move_to(cr -, x -, y -).

Parameters

----- - - - - - - - - - - - - - - - - - -

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

Since: 1.0

cairo_move_to ()

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

Begin a new sub-path. After this call the current point will be (x -, -y -).

Parameters

----- - - - - - - - - - - - - - - - - - -

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

Since: 1.0

cairo_rectangle ()

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

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

This function is logically equivalent to:

- - - - - - - -

1
-2
-3
-4
-5

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

- -

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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

Since: 1.0

cairo_glyph_path ()

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

Adds closed paths for the glyphs to the current path. The generated -path if filled, achieves an effect similar to that of -cairo_show_glyphs().

Parameters

----- - - - - - - - - - - - - - - - - - -

cr	a cairo context
glyphs	array of glyphs to show
num_glyphs	number of glyphs to show

Since: 1.0

cairo_text_path ()

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

Adds closed paths for text to the current path. The generated -path if filled, achieves an effect similar to that of -cairo_show_text().

Text conversion and positioning is done similar to cairo_show_text().

Like cairo_show_text(), After this call the current point is -moved to the origin of where the next glyph would be placed in -this same progression. That is, the current point will be at -the origin of the final glyph offset by its advance values. -This allows for chaining multiple calls to to cairo_text_path() -without having to set current point in between.

Note: The cairo_text_path() function call is part of what the cairo -designers call the "toy" text API. It is convenient for short demos -and simple programs, but it is not expected to be adequate for -serious text-using applications. See cairo_glyph_path() for the -"real" text path API in cairo.

Parameters

----- - - - - - - - - - - - - -

cr	a cairo context
utf8	a NUL-terminated string of text encoded in UTF-8, or `NULL`

Since: 1.0

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

It is an error to call this function with no current point. Doing -so will cause cr - to shutdown with a status of -CAIRO_STATUS_NO_CURRENT_POINT.

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

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

Since: 1.0

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

It is an error to call this function with no current point. Doing -so will cause cr - to shutdown with a status of -CAIRO_STATUS_NO_CURRENT_POINT.

Parameters

----- - - - - - - - - - - - - - - - - - -

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

Since: 1.0

cairo_rel_move_to ()

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

Begin a new sub-path. 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 -).

It is an error to call this function with no current point. Doing -so will cause cr - to shutdown with a status of -CAIRO_STATUS_NO_CURRENT_POINT.

Parameters

----- - - - - - - - - - - - - - - - - - -

cr	a cairo context
dx	the X offset
dy	the Y offset

Since: 1.0

cairo_path_extents ()

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

Computes a bounding box in user-space coordinates covering the -points on the current path. If the current path is empty, returns -an empty rectangle ((0,0), (0,0)). Stroke parameters, fill rule, -surface dimensions and clipping are not taken into account.

Contrast with cairo_fill_extents() and cairo_stroke_extents() which -return the extents of only the area that would be "inked" by -the corresponding drawing operations.

The result of cairo_path_extents() is defined as equivalent to the -limit of cairo_stroke_extents() with CAIRO_LINE_CAP_ROUND as the -line width approaches 0.0, (but never reaching the empty-rectangle -returned by cairo_stroke_extents() for a line width of 0.0).

Specifically, this means that zero-area sub-paths such as -cairo_move_to();cairo_line_to() segments, (even degenerate cases -where the coordinates to both calls are identical), will be -considered as contributing to the extents. However, a lone -cairo_move_to() will not contribute to the results of -cairo_path_extents().

Parameters

----- - - - - - - - - - - - - - - - - - - - - - - - - - - - -

cr	a cairo context
x1	left of the resulting extents
y1	top of the resulting extents
x2	right of the resulting extents
y2	bottom of the resulting extents

Since: 1.6

Types and Values

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() and -cairo_copy_path_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.

Members

----- - - - - - - - - - - - - - - - - - -

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

Since: 1.0

union cairo_path_data_t

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

- - - - - - - -

1
-2
-3
-4
-5
-6
-7
-8
-9
-10
-11
-12
-13
-14
-15
-16
-17
-18
-19
-20
-21
-22
-23
-24
-25
-26

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

- -

As of cairo 1.4, cairo does not mind if there are more elements in -a portion of the path than needed. Such elements can be used by -users of the cairo API to hold extra values in the path data -structure. For this reason, it is recommended that applications -always use data->header.length to -iterate over the path data, instead of hardcoding the number of -elements for each element type.

Since: 1.0

enum cairo_path_data_type_t

cairo_path_data_t is used to describe the type of one portion -of a path when represented as a cairo_path_t. -See cairo_path_data_t for details.

Members

----- - - - - - - - - - - - - - - - - - - - - - - -

CAIRO_PATH_MOVE_TO	- A move-to operation, since 1.0 -
CAIRO_PATH_LINE_TO	- A line-to operation, since 1.0 -
CAIRO_PATH_CURVE_TO	- A curve-to operation, since 1.0 -
CAIRO_PATH_CLOSE_PATH	- A close-path operation, since 1.0 -

Since: 1.0