Creating paths and manipulating path data
Paths are the most basic drawing tools and are primarily used to implicitly generate simple masks.
<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:
cairo-status.a cairo context
the copy of the current path. The caller owns the returned object and
should call cairo-path-destroy when finished with it.
<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:
cairo-status.a cairo context
the copy of the current path. The caller owns the returned object and
should call cairo-path-destroy when finished with it.
<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’.
a cairo context
path to be appended
<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.
a cairo context
whether a current point is defined.
Since 1.6
<cairo-t>) ⇒ (x <double>) (y <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.
a cairo context
return value for X coordinate of the current point
return value for Y coordinate of the current point
<cairo-t>)Clears the current path. After this call there will be no path and no current point.
a cairo context
<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.
a cairo context
Since 1.2
<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.
a cairo context
<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);
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
<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.
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
<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).
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
<cairo-t>) (x <double>) (y <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).
a cairo context
the X coordinate of the end of the new line
the Y coordinate of the end of the new line
<cairo-t>) (x <double>) (y <double>)Begin a new sub-path. 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
<cairo-t>) (x <double>) (y <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);
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
<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.
a cairo context
array of glyphs to show
number of glyphs to show
<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.
a cairo context
a NUL-terminated string of text encoded in UTF-8, or ‘#f’
<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’.
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
<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’.
a cairo context
the X offset to the end of the new line
the Y offset to the end of the new line
<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’.
a cairo context
the X offset
the Y offset
<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.
a cairo context
left of the resulting extents
top of the resulting extents
right of the resulting extents
bottom of the resulting extents
Since 1.6