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