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 round_rect X1, Y1, X2, Y2, MAX_DIAMETER
96 Adds round rectangle to the path.
97 sector CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y, ANGLE_START,
99 ANGLE_END
100 Adds sector to the path. Is there only for compatibility with
101 "Prima::Drawable".
102 spline, rspline $POINTS, %OPTIONS.
104 Adds B-spline to path. See "spline" in Prima::Drawable for %OPTIONS
105 descriptions.
106 text TEXT, %OPTIONS
108 Adds "TEXT" to the path. %OPTIONS are same as in "render_glyph" in
109 Prima::Drawable, except that "unicode" is deduced automatically
110 based on whether "TEXT" has utf8 bit on or off; and an extra option
111 "cache" with a hash can be used to speed up the function with
112 subsequent calls. "baseline" option is same as "textOutBaseline" in
113 Prima::Drawable.
114 Properties
116 canvas DRAWABLE
117 Provides access to the attached drawable object
118 Transformations
120 Transformation calls change the current path properties (matrix etc) so
121 that all subsequent calls will use them until a call to "restore" is
122 used. "save" and "restore" implement a stacking mechanism, so that
123 local transformations can be made.
124 The final transformations calculate coordinates the new and the
126 existing matrices:
127 P' = NewMatrix * P
129 matrix A, B, C, D, Tx, Ty
131 Applies transformation matrix to the path. The matrix, as used by
132 the module, is formed as such:
133 A B 0
135 C D 0
136 Tx Ty 1
137 and when applied to 2D coordinates, is calculated as
139 X' = AX + CY + Tx
141 Y' = BX + DY + Ty
142 precision INTEGER
144 Selects current precision for splines and arcs. See "spline" in
145 Prima::Drawable, "precision" entry.
146 antialias BOOLEAN
148 Turns on and off slow but more visually pleasant antialiased
149 drawing mode.
150 Default: false
152 restore
154 Pops the stack entry and replaces the current matrix and graphic
155 properties with it.
156 rotate ANGLE
158 Adds rotation to the current matrix
159 save
161 Duplicates the current matrix and graphic properties and pushes
162 them to the stack.
163 shear X, Y = X
165 Adds shearing to the current matrix
166 scale X, Y = X
168 Adds scaling to the current matrix
169 translate X, Y = X
171 Adds offset to the current matrix
172 Operations
174 These methods perform actual path rendering, that was delayed until
175 that, and will create an array of points that can be used for actual
176 drawing.
177 clip %options
179 Returns 1-bit image with clipping mask of the path. %options can be
180 used to pass "fillMode" property that affects the result of the
181 filled shape.
182 contours
184 Same as points but further reduces lines into a 8-connected set of
185 points, suitable to be traced pixel-by-pixel.
186 extents
188 Returns 2 points that box the path.
189 last_matrix
191 Return CTM resulted after running all commands
192 fill fillMode=undef
194 Paints a filled shape over the path. If "fillMode" is set, it is
195 used instead of the one selected on the canvas.
196 fill_stroke fillMode=undef
198 Paints a filled shape over the path with back color. If "fillMode"
199 is set, it is used instead of the one selected on the canvas.
200 Thereafter, draws a polyline over the path.
201 flatten PRESCALE
203 Returns new objects where arcs are flattened into lines. The lines
204 are rasterized with scaling factor that is as close as possible to
205 the device pixels, to be suitable for direct send to the polyline()
206 API call. If PRESCALE factor is set, it is used instead to
207 premultiply coordinates of arc anchor points used to render the
208 lines.
209 points FOR_FILL_POLY=0
211 Runs all accumulated commands, and returns rendered set of points,
212 suitable for further calls to either "Prima::Drawable::polyline" or
213 "Prima::Drawable::fillpoly" depending on the "FOR_FILL_POLY" flag.
214 region MODE=fm::Winding|fm::Overlay, RGNOP=rgnop::Union
216 Creates a region object from polygonal shape. If MODE is set,
217 applies fill mode (see "fillMode" in Prima::Drawable for more); if
218 RGNOP is set, applies region set operation (see "combine" in
219 Prima::Region).
220 stroke
222 Draws a polyline over the path
223 widen %OPTIONS
225 Expands path into a new path object containing outlines of the
226 original path as if drawn with selected line properties.
227 "lineWidth", "lineEnd", "lineJoin", "linePattern" are read from
228 %OPTIONS, or from the attached canvas when available. Supports
229 "miterLimit" option with values from 0 to 20.
230 Note: if the intention is to immediately render lines, decrease
232 lineWidth by 1 (they are 1 pixel wider because paths are built
233 around assumption that pixel size is 0, which makes them scalable).
234 Methods for custom primitives
236 append PATH
237 Copies all commands from another PATH object. The PATH object
238 doesn't need to have balanced stacking brackets "save" and
239 "restore", and can be viewed as a macro.
240 identity
242 Returns identity matrix
243 matrix_apply @POINTS
245 Applies current matrix to POINTS, returns the transformed points.
246 If @POINTS is a list, returns list; if it is an array reference,
247 returns array reference.
248
250 Dmitry Karasik, <dmitry@karasik.eu.org>.
251
253 Prima::Drawable
254perl v5.34.0 2021-07-22 Prima::Drawable::Path(3)