| jpayne@68: Top jpayne@68: | jpayne@68: |
jpayne@68: |
jpayne@68: |
jpayne@68: |
jpayne@68:
jpayne@68: Pathsjpayne@68:Paths — Creating paths and manipulating path data jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: cairo_path_t * jpayne@68: | jpayne@68:jpayne@68: cairo_copy_path () jpayne@68: | jpayne@68:
| jpayne@68: cairo_path_t * jpayne@68: | jpayne@68:jpayne@68: cairo_copy_path_flat () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_path_destroy () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_append_path () jpayne@68: | jpayne@68:
| jpayne@68: cairo_bool_t jpayne@68: | jpayne@68:jpayne@68: cairo_has_current_point () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_get_current_point () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_new_path () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_new_sub_path () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_close_path () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_arc () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_arc_negative () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_curve_to () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_line_to () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_move_to () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_rectangle () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_glyph_path () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_text_path () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_rel_curve_to () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_rel_line_to () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_rel_move_to () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_path_extents () jpayne@68: | jpayne@68:
| jpayne@68: | cairo_path_t | jpayne@68:
| union | jpayne@68:cairo_path_data_t | jpayne@68:
| enum | jpayne@68:cairo_path_data_type_t | jpayne@68:
Paths are the most basic drawing tools and are primarily used to implicitly jpayne@68: generate simple masks.
jpayne@68:cairo_path_t *
jpayne@68: cairo_copy_path (cairo_t *cr);
jpayne@68: Creates a copy of the current path and returns it to the user as a jpayne@68: cairo_path_t. See cairo_path_data_t for hints on how to iterate jpayne@68: over the returned data structure.
jpayne@68:This function will always return a valid pointer, but the result
jpayne@68: will have no data (data== and
jpayne@68: NULLnum_data==0), if either of the following
jpayne@68: conditions hold:
path->status will be set to
jpayne@68: CAIRO_STATUS_NO_MEMORY.cr is already in an error state. In this case
jpayne@68: path->status will contain the same status that
jpayne@68: would be returned by cairo_status().cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
the copy of the current path. The caller owns the
jpayne@68: returned object and should call cairo_path_destroy() when finished
jpayne@68: with it.
Since: 1.0
jpayne@68:cairo_path_t *
jpayne@68: cairo_copy_path_flat (cairo_t *cr);
jpayne@68: Gets a flattened copy of the current path and returns it to the jpayne@68: user as a cairo_path_t. See cairo_path_data_t for hints on jpayne@68: how to iterate over the returned data structure.
jpayne@68:This function is like cairo_copy_path() except that any curves
jpayne@68: in the path will be approximated with piecewise-linear
jpayne@68: approximations, (accurate to within the current tolerance
jpayne@68: value). That is, the result is guaranteed to not have any elements
jpayne@68: of type CAIRO_PATH_CURVE_TO which will instead be replaced by a
jpayne@68: series of CAIRO_PATH_LINE_TO elements.
This function will always return a valid pointer, but the result
jpayne@68: will have no data (data== and
jpayne@68: NULLnum_data==0), if either of the following
jpayne@68: conditions hold:
path->status will be set to
jpayne@68: CAIRO_STATUS_NO_MEMORY.cr is already in an error state. In this case
jpayne@68: path->status will contain the same status that
jpayne@68: would be returned by cairo_status().cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
the copy of the current path. The caller owns the
jpayne@68: returned object and should call cairo_path_destroy() when finished
jpayne@68: with it.
Since: 1.0
jpayne@68:void
jpayne@68: cairo_path_destroy (cairo_path_t *path);
jpayne@68: Immediately releases all memory associated with path
jpayne@68: . After a call
jpayne@68: to cairo_path_destroy() the path
jpayne@68: pointer is no longer valid and
jpayne@68: should not be used further.
Note: cairo_path_destroy() should only be called with a
jpayne@68: pointer to a cairo_path_t returned by a cairo function. Any path
jpayne@68: that is created manually (ie. outside of cairo) should be destroyed
jpayne@68: manually as well.
path |
jpayne@68: a path previously returned by either |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_append_path (jpayne@68:cairo_t *cr, jpayne@68:const cairo_path_t *path);
Append the path
jpayne@68: onto the current path. The path
jpayne@68: may be either the
jpayne@68: return value from one of cairo_copy_path() or
jpayne@68: cairo_copy_path_flat() or it may be constructed manually. See
jpayne@68: cairo_path_t for details on how the path data structure should be
jpayne@68: initialized, and note that path->status must be
jpayne@68: initialized to CAIRO_STATUS_SUCCESS.
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
path |
jpayne@68: path to be appended |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:cairo_bool_t
jpayne@68: cairo_has_current_point (cairo_t *cr);
jpayne@68: Returns whether a current point is defined on the current path.
jpayne@68: See cairo_get_current_point() for details on the current point.
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
Since: 1.6
jpayne@68:void jpayne@68: cairo_get_current_point (jpayne@68:cairo_t *cr, jpayne@68:double *x, jpayne@68:double *y);
Gets the current point of the current path, which is jpayne@68: conceptually the final point reached by the path so far.
jpayne@68:The current point is returned in the user-space coordinate
jpayne@68: system. If there is no defined current point or if cr
jpayne@68: is in an
jpayne@68: error status, x
jpayne@68: and y
jpayne@68: will both be set to 0.0. It is possible to
jpayne@68: check this in advance with cairo_has_current_point().
Most path construction functions alter the current point. See the
jpayne@68: following for details on how they affect the current point:
jpayne@68: cairo_new_path(), cairo_new_sub_path(),
jpayne@68: cairo_append_path(), cairo_close_path(),
jpayne@68: cairo_move_to(), cairo_line_to(), cairo_curve_to(),
jpayne@68: cairo_rel_move_to(), cairo_rel_line_to(), cairo_rel_curve_to(),
jpayne@68: cairo_arc(), cairo_arc_negative(), cairo_rectangle(),
jpayne@68: cairo_text_path(), cairo_glyph_path(), cairo_stroke_to_path().
Some functions use and alter the current point but do not
jpayne@68: otherwise change current path:
jpayne@68: cairo_show_text().
Some functions unset the current path and as a result, current point:
jpayne@68: cairo_fill(), cairo_stroke().
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
x |
jpayne@68: return value for X coordinate of the current point |
jpayne@68: jpayne@68: |
y |
jpayne@68: return value for Y coordinate of the current point |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void
jpayne@68: cairo_new_path (cairo_t *cr);
jpayne@68: Clears the current path. After this call there will be no path and jpayne@68: no current point.
jpayne@68:cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void
jpayne@68: cairo_new_sub_path (cairo_t *cr);
jpayne@68: Begin a new sub-path. Note that the existing path is not jpayne@68: affected. After this call there will be no current point.
jpayne@68:In many cases, this call is not needed since new sub-paths are
jpayne@68: frequently started with cairo_move_to().
A call to cairo_new_sub_path() is particularly useful when
jpayne@68: beginning a new sub-path with one of the cairo_arc() calls. This
jpayne@68: makes things easier as it is no longer necessary to manually
jpayne@68: compute the arc's initial coordinates for a call to
jpayne@68: cairo_move_to().
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
Since: 1.2
jpayne@68:void
jpayne@68: cairo_close_path (cairo_t *cr);
jpayne@68: Adds a line segment to the path from the current point to the
jpayne@68: beginning of the current sub-path, (the most recent point passed to
jpayne@68: cairo_move_to()), and closes this sub-path. After this call the
jpayne@68: current point will be at the joined endpoint of the sub-path.
The behavior of cairo_close_path() is distinct from simply calling
jpayne@68: cairo_line_to() with the equivalent coordinate in the case of
jpayne@68: stroking. When a closed sub-path is stroked, there are no caps on
jpayne@68: the ends of the sub-path. Instead, there is a line join connecting
jpayne@68: the final and initial segments of the sub-path.
If there is no current point before the call to cairo_close_path(),
jpayne@68: this function will have no effect.
Note: As of cairo version 1.2.4 any call to cairo_close_path() will
jpayne@68: place an explicit MOVE_TO element into the path immediately after
jpayne@68: the CLOSE_PATH element, (which can be seen in cairo_copy_path() for
jpayne@68: example). This can simplify path processing in some cases as it may
jpayne@68: not be necessary to save the "last move_to point" during processing
jpayne@68: as the MOVE_TO immediately after the CLOSE_PATH will provide that
jpayne@68: point.
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_arc (jpayne@68:cairo_t *cr, jpayne@68:double xc, jpayne@68:double yc, jpayne@68:double radius, jpayne@68:double angle1, jpayne@68:double angle2);
Adds a circular arc of the given radius
jpayne@68: to the current path. The
jpayne@68: arc is centered at (xc
jpayne@68: , yc
jpayne@68: ), begins at angle1
jpayne@68: and proceeds in
jpayne@68: the direction of increasing angles to end at angle2
jpayne@68: . If angle2
jpayne@68: is
jpayne@68: less than angle1
jpayne@68: it will be progressively increased by
jpayne@68: 2*M_PI until it is greater than angle1
jpayne@68: .
If there is a current point, an initial line segment will be added
jpayne@68: to the path to connect the current point to the beginning of the
jpayne@68: arc. If this initial line is undesired, it can be avoided by
jpayne@68: calling cairo_new_sub_path() before calling cairo_arc().
Angles are measured in radians. An angle of 0.0 is in the direction
jpayne@68: of the positive X axis (in user space). An angle of
jpayne@68: M_PI/2.0 radians (90 degrees) is in the
jpayne@68: direction of the positive Y axis (in user space). Angles increase
jpayne@68: in the direction from the positive X axis toward the positive Y
jpayne@68: axis. So with the default transformation matrix, angles increase in
jpayne@68: a clockwise direction.
(To convert from degrees to radians, use degrees * (M_PI /
jpayne@68: 180.).)
This function gives the arc in the direction of increasing angles;
jpayne@68: see cairo_arc_negative() to get the arc in the direction of
jpayne@68: decreasing angles.
The arc is circular in user space. To achieve an elliptical arc,
jpayne@68: you can scale the current transformation matrix by different
jpayne@68: amounts in the X and Y directions. For example, to draw an ellipse
jpayne@68: in the box given by x
jpayne@68: , y
jpayne@68: , width
jpayne@68: , height
jpayne@68: :
1 jpayne@68: 2 jpayne@68: 3 jpayne@68: 4 jpayne@68: 5 |
jpayne@68: cairo_save (cr); jpayne@68: cairo_translate (cr, x + width / 2., y + height / 2.); jpayne@68: cairo_scale (cr, width / 2., height / 2.); jpayne@68: cairo_arc (cr, 0., 0., 1., 0., 2 * M_PI); jpayne@68: cairo_restore (cr); |
jpayne@68:
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
xc |
jpayne@68: X position of the center of the arc |
jpayne@68: jpayne@68: |
yc |
jpayne@68: Y position of the center of the arc |
jpayne@68: jpayne@68: |
radius |
jpayne@68: the radius of the arc |
jpayne@68: jpayne@68: |
angle1 |
jpayne@68: the start angle, in radians |
jpayne@68: jpayne@68: |
angle2 |
jpayne@68: the end angle, in radians |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_arc_negative (jpayne@68:cairo_t *cr, jpayne@68:double xc, jpayne@68:double yc, jpayne@68:double radius, jpayne@68:double angle1, jpayne@68:double angle2);
Adds a circular arc of the given radius
jpayne@68: to the current path. The
jpayne@68: arc is centered at (xc
jpayne@68: , yc
jpayne@68: ), begins at angle1
jpayne@68: and proceeds in
jpayne@68: the direction of decreasing angles to end at angle2
jpayne@68: . If angle2
jpayne@68: is
jpayne@68: greater than angle1
jpayne@68: it will be progressively decreased by
jpayne@68: 2*M_PI until it is less than angle1
jpayne@68: .
See cairo_arc() for more details. This function differs only in the
jpayne@68: direction of the arc between the two angles.
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
xc |
jpayne@68: X position of the center of the arc |
jpayne@68: jpayne@68: |
yc |
jpayne@68: Y position of the center of the arc |
jpayne@68: jpayne@68: |
radius |
jpayne@68: the radius of the arc |
jpayne@68: jpayne@68: |
angle1 |
jpayne@68: the start angle, in radians |
jpayne@68: jpayne@68: |
angle2 |
jpayne@68: the end angle, in radians |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_curve_to (jpayne@68:cairo_t *cr, jpayne@68:double x1, jpayne@68:double y1, jpayne@68:double x2, jpayne@68:double y2, jpayne@68:double x3, jpayne@68:double y3);
Adds a cubic Bézier spline to the path from the current point to
jpayne@68: position (x3
jpayne@68: , y3
jpayne@68: ) in user-space coordinates, using (x1
jpayne@68: , y1
jpayne@68: ) and
jpayne@68: (x2
jpayne@68: , y2
jpayne@68: ) as the control points. After this call the current point
jpayne@68: will be (x3
jpayne@68: , y3
jpayne@68: ).
If there is no current point before the call to cairo_curve_to()
jpayne@68: this function will behave as if preceded by a call to
jpayne@68: cairo_move_to(cr
jpayne@68: , x1
jpayne@68: , y1
jpayne@68: ).
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
x1 |
jpayne@68: the X coordinate of the first control point |
jpayne@68: jpayne@68: |
y1 |
jpayne@68: the Y coordinate of the first control point |
jpayne@68: jpayne@68: |
x2 |
jpayne@68: the X coordinate of the second control point |
jpayne@68: jpayne@68: |
y2 |
jpayne@68: the Y coordinate of the second control point |
jpayne@68: jpayne@68: |
x3 |
jpayne@68: the X coordinate of the end of the curve |
jpayne@68: jpayne@68: |
y3 |
jpayne@68: the Y coordinate of the end of the curve |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_line_to (jpayne@68:cairo_t *cr, jpayne@68:double x, jpayne@68:double y);
Adds a line to the path from the current point to position (x
jpayne@68: , y
jpayne@68: )
jpayne@68: in user-space coordinates. After this call the current point
jpayne@68: will be (x
jpayne@68: , y
jpayne@68: ).
If there is no current point before the call to cairo_line_to()
jpayne@68: this function will behave as cairo_move_to(cr
jpayne@68: , x
jpayne@68: , y
jpayne@68: ).
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
x |
jpayne@68: the X coordinate of the end of the new line |
jpayne@68: jpayne@68: |
y |
jpayne@68: the Y coordinate of the end of the new line |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_move_to (jpayne@68:cairo_t *cr, jpayne@68:double x, jpayne@68:double y);
Begin a new sub-path. After this call the current point will be (x
jpayne@68: ,
jpayne@68: y
jpayne@68: ).
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
x |
jpayne@68: the X coordinate of the new position |
jpayne@68: jpayne@68: |
y |
jpayne@68: the Y coordinate of the new position |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_rectangle (jpayne@68:cairo_t *cr, jpayne@68:double x, jpayne@68:double y, jpayne@68:double width, jpayne@68:double height);
Adds a closed sub-path rectangle of the given size to the current
jpayne@68: path at position (x
jpayne@68: , y
jpayne@68: ) in user-space coordinates.
This function is logically equivalent to:
jpayne@68:1 jpayne@68: 2 jpayne@68: 3 jpayne@68: 4 jpayne@68: 5 |
jpayne@68: cairo_move_to (cr, x, y); jpayne@68: cairo_rel_line_to (cr, width, 0); jpayne@68: cairo_rel_line_to (cr, 0, height); jpayne@68: cairo_rel_line_to (cr, -width, 0); jpayne@68: cairo_close_path (cr); |
jpayne@68:
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
x |
jpayne@68: the X coordinate of the top left corner of the rectangle |
jpayne@68: jpayne@68: |
y |
jpayne@68: the Y coordinate to the top left corner of the rectangle |
jpayne@68: jpayne@68: |
width |
jpayne@68: the width of the rectangle |
jpayne@68: jpayne@68: |
height |
jpayne@68: the height of the rectangle |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_glyph_path (jpayne@68:cairo_t *cr, jpayne@68:const cairo_glyph_t *glyphs, jpayne@68:int num_glyphs);
Adds closed paths for the glyphs to the current path. The generated
jpayne@68: path if filled, achieves an effect similar to that of
jpayne@68: cairo_show_glyphs().
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
glyphs |
jpayne@68: array of glyphs to show |
jpayne@68: jpayne@68: |
num_glyphs |
jpayne@68: number of glyphs to show |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_text_path (jpayne@68:cairo_t *cr, jpayne@68:const char *utf8);
Adds closed paths for text to the current path. The generated
jpayne@68: path if filled, achieves an effect similar to that of
jpayne@68: 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
jpayne@68: moved to the origin of where the next glyph would be placed in
jpayne@68: this same progression. That is, the current point will be at
jpayne@68: the origin of the final glyph offset by its advance values.
jpayne@68: This allows for chaining multiple calls to to cairo_text_path()
jpayne@68: without having to set current point in between.
Note: The cairo_text_path() function call is part of what the cairo
jpayne@68: designers call the "toy" text API. It is convenient for short demos
jpayne@68: and simple programs, but it is not expected to be adequate for
jpayne@68: serious text-using applications. See cairo_glyph_path() for the
jpayne@68: "real" text path API in cairo.
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
utf8 |
jpayne@68: a NUL-terminated string of text encoded in UTF-8, or |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_rel_curve_to (jpayne@68:cairo_t *cr, jpayne@68:double dx1, jpayne@68:double dy1, jpayne@68:double dx2, jpayne@68:double dy2, jpayne@68:double dx3, jpayne@68:double dy3);
Relative-coordinate version of cairo_curve_to(). All offsets are
jpayne@68: relative to the current point. Adds a cubic Bézier spline to the
jpayne@68: path from the current point to a point offset from the current
jpayne@68: point by (dx3
jpayne@68: , dy3
jpayne@68: ), using points offset by (dx1
jpayne@68: , dy1
jpayne@68: ) and
jpayne@68: (dx2
jpayne@68: , dy2
jpayne@68: ) as the control points. After this call the current
jpayne@68: point will be offset by (dx3
jpayne@68: , dy3
jpayne@68: ).
Given a current point of (x, y), cairo_rel_curve_to(cr
jpayne@68: , dx1
jpayne@68: ,
jpayne@68: dy1
jpayne@68: , dx2
jpayne@68: , dy2
jpayne@68: , dx3
jpayne@68: , dy3
jpayne@68: ) is logically equivalent to
jpayne@68: cairo_curve_to(cr
jpayne@68: , x+dx1
jpayne@68: , y+dy1
jpayne@68: , x+dx2
jpayne@68: , y+dy2
jpayne@68: , x+dx3
jpayne@68: , y+dy3
jpayne@68: ).
It is an error to call this function with no current point. Doing
jpayne@68: so will cause cr
jpayne@68: to shutdown with a status of
jpayne@68: CAIRO_STATUS_NO_CURRENT_POINT.
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
dx1 |
jpayne@68: the X offset to the first control point |
jpayne@68: jpayne@68: |
dy1 |
jpayne@68: the Y offset to the first control point |
jpayne@68: jpayne@68: |
dx2 |
jpayne@68: the X offset to the second control point |
jpayne@68: jpayne@68: |
dy2 |
jpayne@68: the Y offset to the second control point |
jpayne@68: jpayne@68: |
dx3 |
jpayne@68: the X offset to the end of the curve |
jpayne@68: jpayne@68: |
dy3 |
jpayne@68: the Y offset to the end of the curve |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_rel_line_to (jpayne@68:cairo_t *cr, jpayne@68:double dx, jpayne@68:double dy);
Relative-coordinate version of cairo_line_to(). Adds a line to the
jpayne@68: path from the current point to a point that is offset from the
jpayne@68: current point by (dx
jpayne@68: , dy
jpayne@68: ) in user space. After this call the
jpayne@68: current point will be offset by (dx
jpayne@68: , dy
jpayne@68: ).
Given a current point of (x, y), cairo_rel_line_to(cr
jpayne@68: , dx
jpayne@68: , dy
jpayne@68: )
jpayne@68: is logically equivalent to cairo_line_to(cr
jpayne@68: , x + dx
jpayne@68: , y + dy
jpayne@68: ).
It is an error to call this function with no current point. Doing
jpayne@68: so will cause cr
jpayne@68: to shutdown with a status of
jpayne@68: CAIRO_STATUS_NO_CURRENT_POINT.
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
dx |
jpayne@68: the X offset to the end of the new line |
jpayne@68: jpayne@68: |
dy |
jpayne@68: the Y offset to the end of the new line |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_rel_move_to (jpayne@68:cairo_t *cr, jpayne@68:double dx, jpayne@68:double dy);
Begin a new sub-path. After this call the current point will offset
jpayne@68: by (x
jpayne@68: , y
jpayne@68: ).
Given a current point of (x, y), cairo_rel_move_to(cr
jpayne@68: , dx
jpayne@68: , dy
jpayne@68: )
jpayne@68: is logically equivalent to cairo_move_to(cr
jpayne@68: , x + dx
jpayne@68: , y + dy
jpayne@68: ).
It is an error to call this function with no current point. Doing
jpayne@68: so will cause cr
jpayne@68: to shutdown with a status of
jpayne@68: CAIRO_STATUS_NO_CURRENT_POINT.
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
dx |
jpayne@68: the X offset |
jpayne@68: jpayne@68: |
dy |
jpayne@68: the Y offset |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_path_extents (jpayne@68:cairo_t *cr, jpayne@68:double *x1, jpayne@68:double *y1, jpayne@68:double *x2, jpayne@68:double *y2);
Computes a bounding box in user-space coordinates covering the jpayne@68: points on the current path. If the current path is empty, returns jpayne@68: an empty rectangle ((0,0), (0,0)). Stroke parameters, fill rule, jpayne@68: surface dimensions and clipping are not taken into account.
jpayne@68:Contrast with cairo_fill_extents() and cairo_stroke_extents() which
jpayne@68: return the extents of only the area that would be "inked" by
jpayne@68: the corresponding drawing operations.
The result of cairo_path_extents() is defined as equivalent to the
jpayne@68: limit of cairo_stroke_extents() with CAIRO_LINE_CAP_ROUND as the
jpayne@68: line width approaches 0.0, (but never reaching the empty-rectangle
jpayne@68: returned by cairo_stroke_extents() for a line width of 0.0).
Specifically, this means that zero-area sub-paths such as
jpayne@68: cairo_move_to();cairo_line_to() segments, (even degenerate cases
jpayne@68: where the coordinates to both calls are identical), will be
jpayne@68: considered as contributing to the extents. However, a lone
jpayne@68: cairo_move_to() will not contribute to the results of
jpayne@68: cairo_path_extents().
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
x1 |
jpayne@68: left of the resulting extents |
jpayne@68: jpayne@68: |
y1 |
jpayne@68: top of the resulting extents |
jpayne@68: jpayne@68: |
x2 |
jpayne@68: right of the resulting extents |
jpayne@68: jpayne@68: |
y2 |
jpayne@68: bottom of the resulting extents |
jpayne@68: jpayne@68: |
Since: 1.6
jpayne@68:typedef struct {
jpayne@68: cairo_status_t status;
jpayne@68: cairo_path_data_t *data;
jpayne@68: int num_data;
jpayne@68: } cairo_path_t;
jpayne@68:
jpayne@68: A data structure for holding a path. This data structure serves as
jpayne@68: the return value for cairo_copy_path() and
jpayne@68: cairo_copy_path_flat() as well the input value for
jpayne@68: cairo_append_path().
See cairo_path_data_t for hints on how to iterate over the jpayne@68: actual data within the path.
jpayne@68:The num_data member gives the number of elements in the data jpayne@68: array. This number is larger than the number of independent path jpayne@68: portions (defined in cairo_path_data_type_t), since the data jpayne@68: includes both headers and coordinates for each portion.
jpayne@68:cairo_status_t |
jpayne@68: the current error status |
jpayne@68: jpayne@68: |
cairo_path_data_t * |
jpayne@68: the elements in the path |
jpayne@68: jpayne@68: |
| jpayne@68: | the number of elements in the data array |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:cairo_path_data_t is used to represent the path data inside a jpayne@68: cairo_path_t.
jpayne@68:The data structure is designed to try to balance the demands of jpayne@68: efficiency and ease-of-use. A path is represented as an array of jpayne@68: cairo_path_data_t, which is a union of headers and points.
jpayne@68:Each portion of the path is represented by one or more elements in jpayne@68: the array, (one header followed by 0 or more points). The length jpayne@68: value of the header is the number of array elements for the current jpayne@68: portion including the header, (ie. length == 1 + # of points), and jpayne@68: where the number of points for each element type is as follows:
jpayne@68:jpayne@68: %CAIRO_PATH_MOVE_TO: 1 point jpayne@68: %CAIRO_PATH_LINE_TO: 1 point jpayne@68: %CAIRO_PATH_CURVE_TO: 3 points jpayne@68: %CAIRO_PATH_CLOSE_PATH: 0 points jpayne@68:jpayne@68:
The semantics and ordering of the coordinate values are consistent
jpayne@68: with cairo_move_to(), cairo_line_to(), cairo_curve_to(), and
jpayne@68: cairo_close_path().
Here is sample code for iterating through a cairo_path_t:
jpayne@68:1 jpayne@68: 2 jpayne@68: 3 jpayne@68: 4 jpayne@68: 5 jpayne@68: 6 jpayne@68: 7 jpayne@68: 8 jpayne@68: 9 jpayne@68: 10 jpayne@68: 11 jpayne@68: 12 jpayne@68: 13 jpayne@68: 14 jpayne@68: 15 jpayne@68: 16 jpayne@68: 17 jpayne@68: 18 jpayne@68: 19 jpayne@68: 20 jpayne@68: 21 jpayne@68: 22 jpayne@68: 23 jpayne@68: 24 jpayne@68: 25 jpayne@68: 26 |
jpayne@68: int i; jpayne@68: cairo_path_t *path; jpayne@68: cairo_path_data_t *data; jpayne@68: jpayne@68: path = cairo_copy_path (cr); jpayne@68: jpayne@68: for (i=0; i < path->num_data; i += path->data[i].header.length) { jpayne@68: data = &path->data[i]; jpayne@68: switch (data->header.type) { jpayne@68: case CAIRO_PATH_MOVE_TO: jpayne@68: do_move_to_things (data[1].point.x, data[1].point.y); jpayne@68: break; jpayne@68: case CAIRO_PATH_LINE_TO: jpayne@68: do_line_to_things (data[1].point.x, data[1].point.y); jpayne@68: break; jpayne@68: case CAIRO_PATH_CURVE_TO: jpayne@68: do_curve_to_things (data[1].point.x, data[1].point.y, jpayne@68: data[2].point.x, data[2].point.y, jpayne@68: data[3].point.x, data[3].point.y); jpayne@68: break; jpayne@68: case CAIRO_PATH_CLOSE_PATH: jpayne@68: do_close_path_things (); jpayne@68: break; jpayne@68: } jpayne@68: } jpayne@68: cairo_path_destroy (path); |
jpayne@68:
As of cairo 1.4, cairo does not mind if there are more elements in
jpayne@68: a portion of the path than needed. Such elements can be used by
jpayne@68: users of the cairo API to hold extra values in the path data
jpayne@68: structure. For this reason, it is recommended that applications
jpayne@68: always use data->header.length to
jpayne@68: iterate over the path data, instead of hardcoding the number of
jpayne@68: elements for each element type.
Since: 1.0
jpayne@68:cairo_path_data_t is used to describe the type of one portion jpayne@68: of a path when represented as a cairo_path_t. jpayne@68: See cairo_path_data_t for details.
jpayne@68:| jpayne@68: |
jpayne@68: A move-to operation, since 1.0 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: A line-to operation, since 1.0 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: A curve-to operation, since 1.0 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: A close-path operation, since 1.0 jpayne@68: |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68: