Next: , Previous: cairo_t, Up: Top


2 Paths

Creating paths and manipulating path data

2.1 Overview

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

2.2 Usage

— Function: cairo-copy-path (cr <cairo-t>) ⇒  (ret <cairo-path-t >)

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==‘#f’ 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
ret
the copy of the current path. The caller owns the returned object and should call cairo-path-destroy when finished with it.
— Function: cairo-copy-path-flat (cr <cairo-t>) ⇒  (ret <cairo-path-t >)

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==‘#f’ 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
ret
the copy of the current path. The caller owns the returned object and should call cairo-path-destroy when finished with it.
— Function: cairo-append-path (cr <cairo-t>) (path <cairo-path-t>)

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
— Function: cairo-has-current-point (cr <cairo-t>) ⇒  (ret <cairo-bool-t>)

Returns whether a current point is defined on the current path. See cairo-get-current-point for details on the current point.

cr
a cairo context
ret
whether a current point is defined.

Since 1.6

— Function: cairo-get-current-point (cr <cairo-t>) ⇒  (<double>) (<double>)

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.

cr
a cairo context
x
return value for X coordinate of the current point
y
return value for Y coordinate of the current point
— Function: cairo-new-path (cr <cairo-t>)

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

cr
a cairo context
— Function: cairo-new-sub-path (cr <cairo-t>)

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.

cr
a cairo context

Since 1.2

— Function: cairo-close-path (cr <cairo-t>)

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.

cr
a cairo context
— Function: cairo-arc (cr <cairo-t>) (xc <double>) (yc <double>) (radius <double>) (angle1 <double>) (angle2 <double>)

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:

          
          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);
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
— Function: cairo-arc-negative (cr <cairo-t>) (xc <double>) (yc <double>) (radius <double>) (angle1 <double>) (angle2 <double>)

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.

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
— Function: cairo-curve-to (cr <cairo-t>) (x1 <double>) (y1 <double>) (x2 <double>) (y2 <double>) (x3 <double>) (y3 <double>)

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

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
— Function: cairo-line-to (cr <cairo-t>) (<double>) (<double>)

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

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
— Function: cairo-move-to (cr <cairo-t>) (<double>) (<double>)

Begin a new sub-path. 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
— Function: cairo-rectangle (cr <cairo-t>) (<double>) (<double>) (width <double>) (height <double>)

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:

          
          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
— Function: cairo-glyph-path (cr <cairo-t>) (glyphs <cairo-glyph-t>) (num-glyphs <int>)

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.

cr
a cairo context
glyphs
array of glyphs to show
num-glyphs
number of glyphs to show
— Function: cairo-text-path (cr <cairo-t>) (utf8 <char>)

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.

cr
a cairo context
utf8
a NUL-terminated string of text encoded in UTF-8, or ‘#f
— Function: cairo-rel-curve-to (cr <cairo-t>) (dx1 <double>) (dy1 <double>) (dx2 <double>) (dy2 <double>) (dx3 <double>) (dy3 <double>)

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

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
— Function: cairo-rel-line-to (cr <cairo-t>) (dx <double>) (dy <double>)

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

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
— Function: cairo-rel-move-to (cr <cairo-t>) (dx <double>) (dy <double>)

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

cr
a cairo context
dx
the X offset
dy
the Y offset
— Function: cairo-path-extents (cr <cairo-t>) ⇒  (x1 <double>) (y1 <double>) (x2 <double>) (y2 <double>)

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.

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