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