Prima::Drawable::Path - stroke and fill complex paths
The module augments the Prima::Drawable's drawing and plotting functionality by implementing paths that allow arbitrary combinations of polylines, splines, and arcs, to be used for drawing or clipping shapes.
Prima::Drawable
# draws an elliptic spiral my ( $d1, $dx ) = ( 0.8, 0.05 ); $canvas-> new_path-> rotate(45)-> translate(200, 100)-> scale(200, 100)-> arc( 0, 0, $d1 + $dx * 0, $d1 + $dx * 1, 0, 90)-> arc( 0, 0, $d1 + $dx * 2, $d1 + $dx * 1, 90, 180)-> arc( 0, 0, $d1 + $dx * 2, $d1 + $dx * 3, 180, 270)-> arc( 0, 0, $d1 + $dx * 4, $d1 + $dx * 3, 270, 360)-> stroke;
All primitives come in two versions, with absolute and relative coordinates. The absolute version draws a graphic primitive so that its starting point (or a reference point) is at (0,0). The relative version, called with an 'r' (f.ex. line vs rline) has its starting point as the ending point of the previous primitive (or (0,0) if there's none).
line
rline
Adds an elliptic arc to the path. The arc is centered around the (CENTER_X,CENTER_Y) point.
Important: if the intention is an immediate rendering, especially with a 1-pixel line width, consider decreasing diameters by 1. This is because all arc calculations are made with the floating point precision, where the diameter is also given not in pixels but in geometrical coordinates, to allow for matrix transformations. Before rendering is performed, arcs are transformed into spline vertices and then the transformation matrix is applied, and by that time the notion of an arc diameter is lost to be successfully converted into pixel size minus one.
Read more about this in "Antialiasing and alpha" in Prima::Drawable .
Closes the current shape and opens a new one. close() is the same as open() but makes sure the shape's first point is equal to its last point.
Adds a circular arc to the path. Note that adding transformations will effectively make it into an elliptic arc, which is used internally by arc and rarc.
arc
rarc
Adds a chord to the path. Is there only for compatibility with Prima::Drawable.
Adds a full ellipse to the path.
Adds a glyph outline to the path. %OPTIONS are passed as is to "renger_glyph" in Prima::Drawable, except the fill option.
%OPTIONS
fill
Note that filled glyphs require fillMode without the fm::Overlay bit set, and also the fill option set to generate proper shapes with holes.
fillMode
fm::Overlay
Adds a polyline to the path
Adds a set of multiple, unconnected lines to the path. Is there only for compatibility with Prima::Drawable.
Stops plotting the current shape and moves the plotting position to X, Y.
Adds an elliptic arc to the path so that the first point of the arc starts on the last point of the previous primitive, or (0,0) if there's none.
Adds a rectangle to the path. Is there only for compatibility with Prima::Drawable.
Adds a round rectangle to the path.
Adds a sector to the path. Is there only for compatibility with Prima::Drawable.
Adds a B-spline to the path. See "spline" in Prima::Drawable for %OPTIONS descriptions.
Adds TEXT to the path. %OPTIONS are the same as in "render_glyph" in Prima::Drawable, except that unicode is deduced automatically based on whether the TEXT has utf8 bit on or off. An extra option cache with a hash can be used to speed up the function with subsequent calls. The baseline option is the same as "textOutBaseline" in Prima::Drawable.
TEXT
unicode
cache
baseline
Transformation calls change the current path properties (matrix etc) so that all subsequent calls would use them until a call to restore is made. The save and restore methods implement the stacking mechanism so that local transformations can be made.
restore
save
Provides access to the attached drawable object
Applies a transformation matrix to the path. The matrix, as used by the module, is formed as follows:
A B 0 C D 0 Tx Ty 1
When applied to 2D coordinates, the transformed coordinates are calculated as
X' = AX + CY + Tx Y' = BX + DY + Ty
Selects current precision for splines and arcs. See "spline" in Prima::Drawable, precision entry.
precision
Turns on and off slow but more visually pleasant antialiased drawing mode.
Default: false
Pops the stack entry and replaces the current matrix and graphic properties with it.
Adds rotation to the current matrix
Saves the current matrix and graphic properties on the stack.
Adds shearing to the current matrix
Adds scaling to the current matrix
Turns on and off slow but more precise floating-point calculation mode
Default: depends on canvas antialiasing mode
Adds an offset to the current matrix
These methods perform path rendering and create an array of points that can be used for drawing
Returns a 1-bit image with the clipping mask created from the path. %options can be used to pass the fillMode property that affects the result of the filled shape.
%options
Same as points but further reduces lines into a set of 8-connected points, suitable to be traced pixel-by-pixel.
Returns two points that box the path.
Returns the current transform matrix (CTM) after running all commands
Paints a filled shape over the path. If fillMode is set, it is used instead of the one selected on the canvas.
Paints a filled shape over the path with the background color. If fillMode is set, it is used instead of the one selected on the canvas. Thereafter, draws a polyline over the path.
Returns new objects where arcs are flattened into lines. The lines are rasterized with a scaling factor that is as close as possible to the device pixels, to be suitable for a call to the polyline() method. If the PRESCALE factor is set, it is used instead to premultiply coordinates of arc anchor points used to render the lines.
Runs all accumulated commands, returns rendered set of points suitable for the Prima::Drawable::polyline and Prima::Drawable::fillpoly methods.
Prima::Drawable::polyline
Prima::Drawable::fillpoly
Creates a region object from the path. If MODE is set, applies fill mode (see "fillMode" in Prima::Drawable for more); if RGNOP is set, applies region set operation (see "combine" in Prima::Region).
Draws a polyline over the path
Expands the path into a new path object containing outlines of the original path as if drawn with selected line properties. The values of lineWidth, lineEnd, lineJoin, and linePattern are read from %OPTIONS, or from the attached canvas when available. Supports the miterLimit option with values from 0 to 20.
lineWidth
lineEnd
lineJoin
linePattern
miterLimit
Note: if the intention is to immediately render lines, decrease lineWidth by 1 (they are 1 pixel wider because paths are built around the assumption that pixel size is 0, which makes them scalable).
Copies all commands from another PATH object. The PATH object doesn't need to have balanced stacking brackets save and restore, and can be viewed as a macro.
Returns the identity matrix
Applies the CTM to POINTS, returns the transformed points. If @POINTS is a list, returns the transformed points as a list; if it is an array reference, returns an array reference.
Dmitry Karasik, <dmitry@karasik.eu.org>.
To install Prima, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Prima
CPAN shell
perl -MCPAN -e shell install Prima
For more information on module installation, please visit the detailed CPAN module installation guide.