23.1 Creation
A reference to a new empty path can be created using fz_new_path
:
/* fz_new_path: Create an empty path, and return a reference to it. Throws exception on failure to allocate. */ fz_path *fz_new_path(fz_context *ctx);
Once a path exists, commands can be added to it. The first command must always be
a ‘move’.
/* fz_moveto: Append a ’moveto’ command to a path. path: The path to modify. x, y: The coordinate to move to. Throws exceptions on failure to allocate. */ void fz_moveto(fz_context *ctx, fz_path *path, float x, float y);
Once we have moved to a point, subsequent commands can be added, such as lines,
quads (quadratic beziers) and curves (cubic beziers).
/* fz_lineto: Append a ’lineto’ command to a path. path: The path to modify. x, y: The coordinate to line to. Throws exceptions on failure to allocate. */ void fz_lineto(fz_context *ctx, fz_path *path, float x, float y); /* fz_quadto: Append a ’quadto’ command to a path. (For a quadratic bezier). path: The path to modify. x0, y0: The control coordinates for the quadratic curve. x1, y1: The end coordinates for the quadratic curve. Throws exceptions on failure to allocate. */ void fz_quadto(fz_context *ctx, fz_path *path, float x0, float y0, float x1, float y1); /* fz_curveto: Append a ’curveto’ command to a path. (For a cubic bezier). path: The path to modify. x0, y0: The coordinates of the first control point for the curve. x1, y1: The coordinates of the second control point for the curve. x2, y2: The end coordinates for the curve. Throws exceptions on failure to allocate. */ void fz_curveto(fz_context *ctx, fz_path *path, float x0, float y0, float x1, float y1, float x2, float y2);
In addition, we have 2 functions for adding curves (cubic beziers) where one of the
control points is coincident with the neighbouring endpoints. These functions mirror
the usage in PDF, but offer no benefits other than convenience as such curves are
detected automatically as part of an fz_curveto
call.
/* fz_curvetov: Append a ’curvetov’ command to a path. (For a cubic bezier with the first control coordinate equal to the start point). path: The path to modify. x1, y1: The coordinates of the second control point for the curve. x2, y2: The end coordinates for the curve. Throws exceptions on failure to allocate. */ void fz_curvetov(fz_context *ctx, fz_path *path, float x1, float y1, float x2, float y2); /* fz_curvetoy: Append a ’curvetoy’ command to a path. (For a cubic bezier with the second control coordinate equal to the end point). path: The path to modify. x0, y0: The coordinates of the first control point for the curve. x2, y2: The end coordinates for the curve (and the second control coordinate). Throws exceptions on failure to allocate. */ void fz_curvetoy(fz_context *ctx, fz_path *path, float x0, float y0, float x2, float y2);
At any point after the initial move, we can close the path using fz_closepath
:
/* fz_closepath: Close the current subpath. path: The path to modify. Throws exceptions on failure to allocate, and illegal path closes. */ void fz_closepath(fz_context *ctx, fz_path *path);
After a path has been closed, the only acceptable next command is a move. A path
need not be closed before a second or subsequent move is sent.
For details of exactly what each of these path segment types means, see “The PDF
Reference Manual” or “The Postscript Language Reference Manual”.
Finally, we have one additional path construction function, fz_rectto
. This appends a rectangle to the current path. This rectangle is equivalent
to a move, 3 lines and a closepath, and so is the one exception to the rule
that paths must begin with a move (as one is implicit within the rectangle
command).
/* fz_rectto: Append a ’rectto’ command to a path. The rectangle is equivalent to: moveto x0 y0 lineto x1 y0 lineto x1 y1 lineto x0 y1 closepath path: The path to modify. x0, y0: First corner of the rectangle. x1, y1: Second corner of the rectangle. Throws exceptions on failure to allocate. */ void fz_rectto(fz_context *ctx, fz_path *path, float x0, float y0, float x1, float y1);
Finally, during path construction, the coordinate at which the notional path cursor
has reached can be read using the fz_currentpoint
function.
/* fz_currentpoint: Return the current point that a path has reached or (0,0) if empty. path: path to return the current point of. */ fz_point fz_currentpoint(fz_context *ctx, fz_path *path);