1Prima::Drawable::Path(3U)ser Contributed Perl DocumentatiPornima::Drawable::Path(3)
2
6 Prima::Drawable::Path - stroke and fill complex paths
7
9 The module augments the "Prima::Drawable" drawing and plotting
10 functionality by implementing paths that allow arbitrary combination of
11 polylines, splines, and arcs, to be used for drawing or clipping
12 shapes.
13
15 # draws elliptic spiral
16 my ( $d1, $dx ) = ( 0.8, 0.05 );
17 $canvas-> new_path->
18 scale(200, 100)->
19 rotate(45)->
20 arc( 0, 0, $d1 + $dx * 0, $d1 + $dx * 1, 0, 90)->
21 arc( 0, 0, $d1 + $dx * 2, $d1 + $dx * 1, 90, 180)->
22 arc( 0, 0, $d1 + $dx * 2, $d1 + $dx * 3, 180, 270)->
23 arc( 0, 0, $d1 + $dx * 4, $d1 + $dx * 3, 270, 360)->
24 stroke;
25
27 Primitives
28 All primitives come in two versions, with absolute and relative
29 coordinates. The absolute version draws a graphic primitive so that
30 its starting point (or a reference point) is at (0,0). The relative
31 version, called with an 'r' (f.ex. "line" vs "rline") has its starting
32 point as the ending point of the previous primitive (or (0,0) if
33 there's none).
34 arc CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y, ANGLE_START, ANGLE_END,
36 TILT = 0
37 Adds elliptic arc to path centered around (CENTER_X,CENTER_Y).
38 Important: if the intention is an immediate rendering, especially
40 with 1-pixel line width, consider decreasing diameters by 1. This
41 is because all arc calculations are made with floating point, where
42 diameter is also given not in pixels but in geometrical
43 coordinates, to allow for matrix transformations. Before rendering
44 is performed, arcs are tranformed into spline vertices and then
45 transformation matrix is applied, and by that time the notion of an
46 arc diameter is lost to be successfully converted into pixel size
47 minus one.
48 close, open
50 Closes the current shape and opens a new one close() is same as
51 open() but makes sure the shape's first point is equal to its last
52 point.
53 circular_arc ANGLE_START, ANGLE_END
55 Adds circular arc to the path. Note that adding transformations
56 will effectively make it into elliptic arc, which is used
57 internally by "arc" and "rarc".
58 chord CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y, ANGLE_START,
60 ANGLE_END.
61 Adds chord to the path. Is there only for compatibility with
62 "Prima::Drawable".
63 ellipse CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y = DIAMETER_X, TILT =
65 0
66 Adds full ellipse to the path.
67 glyph INDEX, %OPTIONS
69 Adds glyph outline to the path. %OPTIONS are passed as is to
70 "renger_glyph" in Prima::Drawable. Note that filled glyphs require
71 "fillMode" without the "fm::Overlay" bit set.
72 line, rline @POINTS
74 Adds a polyline to path
75 lines [X1, Y1, X2, Y2]..
77 Adds set of multiple, unconnected lines to the path. Is there only
78 for compatibility with "Prima::Drawable".
79 moveto, rmoveto X, Y
81 Stops plotting the current shape and moves the plotting position to
82 X, Y.
83 rarc DIAMETER_X, DIAMETER_Y, ANGLE_START, ANGLE_END, TILT = 0
85 Adds elliptic arc to path so that the first point of the arc starts
86 on the last point of the previous primitive, or (0,0) if there's
87 none.
88 rectangle X1, Y1, X2, Y2
90 Adds rectangle to the path. Is there only for compatibility with
91 "Prima::Drawable".
92 sector CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y, ANGLE_START,
94 ANGLE_END
95 Adds sector to the path. Is there only for compatibility with
96 "Prima::Drawable".
97 spline, rspline $POINTS, %OPTIONS.
99 Adds B-spline to path. See "spline" in Prima::Drawable for %OPTIONS
100 descriptions.
101 text TEXT, %OPTIONS
103 Adds "TEXT" to the path. %OPTIONS are same as in "render_glyph" in
104 Prima::Drawable, except that "unicode" is deduced automatically
105 based on whether "TEXT" has utf8 bit on or off; and an extra option
106 "cache" with a hash can be used to speed up the function with
107 subsequent calls.
108 Properties
110 canvas DRAWABLE
111 Provides access to the attached drawable object
112 Transformations
114 Transformation calls change the current path properties (matrix etc) so
115 that all subsequent calls will use them until a call to "restore" is
116 used. "save" and "restore" implement a stacking mechanism, so that
117 local transformations can be made.
118 The final transformations calculate coordinates the new and the
120 existing matrices:
121 P' = NewMatrix * P
123 matrix A, B, C, D, Tx, Ty
125 Applies transformation matrix to the path. The matrix, as used by
126 the module, is formed as such:
127 A B 0
129 C D 0
130 Tx Ty 1
131 and when applied to 2D coordinates, is calculated as
133 X' = AX + CY + Tx
135 Y' = BX + DY + Ty
136 precision INTEGER
138 Selects current precision for splines and arcs. See "spline" in
139 Prima::Drawable, "precision" entry.
140 restore
142 Pops the stack entry and replaces the current matrix and graphic
143 properties with it.
144 rotate ANGLE
146 Adds rotation to the current matrix
147 save
149 Duplicates the current matrix and graphic properties and pushes
150 them to the stack.
151 shear X, Y = X
153 Adds shearing to the current matrix
154 scale X, Y = X
156 Adds scaling to the current matrix
157 translate X, Y = X
159 Adds offset to the current matrix
160 Operations
162 These methods perform actual path rendering, that was delayed until
163 that, and will create an array of points that can be used for actual
164 drawing.
165 clip %options
167 Returns 1-bit image with clipping mask of the path. %options can be
168 used to pass "fillMode" property that affects the result of the
169 filled shape.
170 contours
172 Same as points but further reduces lines into a 8-connected set of
173 points, suitable to be traced pixel-by-pixel.
174 extents
176 Returns 2 points that box the path.
177 last_matrix
179 Return CTM resulted after running all commands
180 fill fillMode=undef
182 Paints a filled shape over the path. If "fillMode" is set, it is
183 used instead of the one selected on the canvas.
184 flatten PRESCALE
186 Returns new objects where arcs are flattened into lines. The lines
187 are rasterized with scaling factor that is as close as possible to
188 the device pixels, to be suitable for direct send to the polyline()
189 API call. If PRESCALE factor is set, it is used instead to
190 premultiply coordinates of arc anchor points used to render the
191 lines.
192 points FOR_FILL_POLY=0
194 Runs all accumulated commands, and returns rendered set of points,
195 suitable for further calls to either "Prima::Drawable::polyline" or
196 "Prima::Drawable::fillpoly" depending on the "FOR_FILL_POLY" flag.
197 region MODE=fm::Winding|fm::Overlay, RGNOP=rgnop::Union
199 Creates a region object from polygonal shape. If MODE is set,
200 applies fill mode (see "fillMode" in Prima::Drawable for more); if
201 RGNOP is set, applies region set operation (see "combine" in
202 Prima::Region).
203 stroke
205 Draws a polyline over the path
206 widen %OPTIONS
208 Expands path into a new path object containing outlines of the
209 original path as if drawn with selected line properties.
210 "lineWidth", "lineEnd", "lineJoin", "linePattern" are read from
211 %OPTIONS, or from the attached canvas when available. Supports
212 "miterLimit" option with values from 0 to 20.
213 Note: if the intention is to immediately render lines, decrease
215 lineWidth by 1 (they are 1 pixel wider because paths are built
216 around assumption that pixel size is 0, which makes them scalable).
217 Methods for custom primitives
219 append PATH
220 Copies all commands from another PATH object. The PATH object
221 doesn't need to have balanced stacking brackets "save" and
222 "restore", and can be viewed as a macro.
223 identity
225 Returns identity matrix
226 matrix_apply @POINTS
228 Applies current matrix to POINTS, returns the transformed points.
229 If @POINTS is a list, returns list; if it is an array reference,
230 returns array reference.
231
233 Dmitry Karasik, <dmitry@karasik.eu.org>.
234
236 Prima::Drawable
237perl v5.30.0 2019-08-21 Prima::Drawable::Path(3)