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().
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().
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.
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.
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().
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.
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().
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.
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
:
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.
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
).
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
).
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
).
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:
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().
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.
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.
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.
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.
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().
Since: 1.6