NAME

Prima::Drawable::Path - stroke and fill complex paths

DESCRIPTION

The module augments the "Prima::Drawable" drawing and plotting functionality by implementing paths that allow arbitrary combination of polylines, splines, and arcs, to be used for drawing or clipping shapes.

SYNOPSIS

        # draws 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;

API

Primitives

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).

arc CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y, ANGLE_START, ANGLE_END, TILT = 0: Adds elliptic arc to path centered around (CENTER_X,CENTER_Y).
Important: if the intention is an immediate rendering, especially with 1-pixel line width, consider decreasing diameters by 1. This is because all arc calculations are made with floating point, where diameter is also given not in pixels but in geometrical coordinates, to allow for matrix transformations. Before rendering is performed, arcs are tranformed into spline vertices and then 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.
close, open: Closes the current shape and opens a new one close() is same as open() but makes sure the shape's first point is equal to its last point.
circular_arc ANGLE_START, ANGLE_END: Adds circular arc to the path. Note that adding transformations will effectively make it into elliptic arc, which is used internally by "arc" and "rarc".
chord CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y, ANGLE_START, ANGLE_END.: Adds chord to the path. Is there only for compatibility with "Prima::Drawable".
ellipse CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y = DIAMETER_X, TILT = 0: Adds full ellipse to the path.
glyph INDEX, %OPTIONS: Adds glyph outline to the path. %OPTIONS are passed as is to "renger_glyph" in Prima::Drawable. Note that filled glyphs require "fillMode" without the "fm::Overlay" bit set and "fill" option set to generate proper shapes with holes.
line, rline @POINTS: Adds a polyline to path
lines [X1, Y1, X2, Y2]..: Adds set of multiple, unconnected lines to the path. Is there only for compatibility with "Prima::Drawable".
moveto, rmoveto X, Y: Stops plotting the current shape and moves the plotting position to X, Y.
rarc DIAMETER_X, DIAMETER_Y, ANGLE_START, ANGLE_END, TILT = 0: Adds elliptic arc to 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.
rectangle X1, Y1, X2, Y2: Adds rectangle to the path. Is there only for compatibility with "Prima::Drawable".
round_rect X1, Y1, X2, Y2, MAX_DIAMETER: Adds round rectangle to the path.
sector CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y, ANGLE_START, ANGLE_END: Adds sector to the path. Is there only for compatibility with "Prima::Drawable".
spline, rspline $POINTS, %OPTIONS.: Adds B-spline to path. See "spline" in Prima::Drawable for %OPTIONS descriptions.
text TEXT, %OPTIONS: Adds "TEXT" to the path. %OPTIONS are same as in "render_glyph" in Prima::Drawable, except that "unicode" is deduced automatically based on whether "TEXT" has utf8 bit on or off; and an extra option "cache" with a hash can be used to speed up the function with subsequent calls. "baseline" option is same as "textOutBaseline" in Prima::Drawable.

Properties

canvas DRAWABLE: Provides access to the attached drawable object

Transformations

Transformation calls change the current path properties (matrix etc) so that all subsequent calls will use them until a call to "restore" is used. "save" and "restore" implement a stacking mechanism, so that local transformations can be made.

The final transformations calculate coordinates the new and the existing matrices:

  P' = NewMatrix * P

matrix A, B, C, D, Tx, Ty

Applies transformation matrix to the path. The matrix, as used by the module, is formed as such:

  A  B  0
  C  D  0
  Tx Ty 1

and when applied to 2D coordinates, is calculated as

  X' = AX + CY + Tx
  Y' = BX + DY + Ty

precision INTEGER

Selects current precision for splines and arcs. See "spline" in Prima::Drawable, "precision" entry.

antialias BOOLEAN

Turns on and off slow but more visually pleasant antialiased drawing mode.

Default: false

restore

Pops the stack entry and replaces the current matrix and graphic properties with it.

rotate ANGLE

Adds rotation to the current matrix

save

Duplicates the current matrix and graphic properties and pushes them to the stack.

shear X, Y = X

Adds shearing to the current matrix

scale X, Y = X

Adds scaling to the current matrix

subpixel BOOLEAN

Turns on and off slow but more precise floating-point calculation mode

Default: depends on canvas antialiasing mode

translate X, Y = X

Adds offset to the current matrix

Operations

These methods perform actual path rendering, that was delayed until that, and will create an array of points that can be used for actual drawing.

clip %options: Returns 1-bit image with clipping mask of the path. %options can be used to pass "fillMode" property that affects the result of the filled shape.
contours: Same as points but further reduces lines into a 8-connected set of points, suitable to be traced pixel-by-pixel.
extents: Returns 2 points that box the path.
last_matrix: Return CTM resulted after running all commands
fill fillMode=undef: Paints a filled shape over the path. If "fillMode" is set, it is used instead of the one selected on the canvas.
fill_stroke fillMode=undef: Paints a filled shape over the path with back color. If "fillMode" is set, it is used instead of the one selected on the canvas. Thereafter, draws a polyline over the path.
flatten PRESCALE: Returns new objects where arcs are flattened into lines. The lines are rasterized with scaling factor that is as close as possible to the device pixels, to be suitable for direct send to the polyline() API call. If PRESCALE factor is set, it is used instead to premultiply coordinates of arc anchor points used to render the lines.
points FOR_FILL_POLY=0: Runs all accumulated commands, and returns rendered set of points, suitable for further calls to either "Prima::Drawable::polyline" or "Prima::Drawable::fillpoly" depending on the "FOR_FILL_POLY" flag.
region MODE=fm::Winding|fm::Overlay, RGNOP=rgnop::Union: Creates a region object from polygonal shape. 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).
stroke: Draws a polyline over the path
widen %OPTIONS: Expands path into a new path object containing outlines of the original path as if drawn with selected line properties. "lineWidth", "lineEnd", "lineJoin", "linePattern" are read from %OPTIONS, or from the attached canvas when available. Supports "miterLimit" option with values from 0 to 20.
Note: if the intention is to immediately render lines, decrease lineWidth by 1 (they are 1 pixel wider because paths are built around assumption that pixel size is 0, which makes them scalable).

Methods for custom primitives

append PATH: 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.
identity: Returns identity matrix
matrix_apply @POINTS: Applies current matrix to POINTS, returns the transformed points. If @POINTS is a list, returns list; if it is an array reference, returns array reference.

AUTHOR

Dmitry Karasik, <dmitry@karasik.eu.org>.