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 subpixel BOOLEAN
171 Turns on and off slow but more precise floating-point calculation
172 mode
173 Default: depends on canvas antialiasing mode
175 translate X, Y = X
177 Adds offset to the current matrix
178 Operations
180 These methods perform actual path rendering, that was delayed until
181 that, and will create an array of points that can be used for actual
182 drawing.
183 clip %options
185 Returns 1-bit image with clipping mask of the path. %options can be
186 used to pass "fillMode" property that affects the result of the
187 filled shape.
188 contours
190 Same as points but further reduces lines into a 8-connected set of
191 points, suitable to be traced pixel-by-pixel.
192 extents
194 Returns 2 points that box the path.
195 last_matrix
197 Return CTM resulted after running all commands
198 fill fillMode=undef
200 Paints a filled shape over the path. If "fillMode" is set, it is
201 used instead of the one selected on the canvas.
202 fill_stroke fillMode=undef
204 Paints a filled shape over the path with back color. If "fillMode"
205 is set, it is used instead of the one selected on the canvas.
206 Thereafter, draws a polyline over the path.
207 flatten PRESCALE
209 Returns new objects where arcs are flattened into lines. The lines
210 are rasterized with scaling factor that is as close as possible to
211 the device pixels, to be suitable for direct send to the polyline()
212 API call. If PRESCALE factor is set, it is used instead to
213 premultiply coordinates of arc anchor points used to render the
214 lines.
215 points %opt
217 Runs all accumulated commands, and returns rendered set of points,
218 suitable for further calls to either "Prima::Drawable::polyline" or
219 "Prima::Drawable::fillpoly" depending on the $opt{fill} flag.
220 region MODE=fm::Winding|fm::Overlay, RGNOP=rgnop::Union
222 Creates a region object from polygonal shape. If MODE is set,
223 applies fill mode (see "fillMode" in Prima::Drawable for more); if
224 RGNOP is set, applies region set operation (see "combine" in
225 Prima::Region).
226 stroke
228 Draws a polyline over the path
229 widen %OPTIONS
231 Expands path into a new path object containing outlines of the
232 original path as if drawn with selected line properties.
233 "lineWidth", "lineEnd", "lineJoin", "linePattern" are read from
234 %OPTIONS, or from the attached canvas when available. Supports
235 "miterLimit" option with values from 0 to 20.
236 Note: if the intention is to immediately render lines, decrease
238 lineWidth by 1 (they are 1 pixel wider because paths are built
239 around assumption that pixel size is 0, which makes them scalable).
240 Methods for custom primitives
242 append PATH
243 Copies all commands from another PATH object. The PATH object
244 doesn't need to have balanced stacking brackets "save" and
245 "restore", and can be viewed as a macro.
246 identity
248 Returns identity matrix
249 matrix_apply @POINTS
251 Applies current matrix to POINTS, returns the transformed points.
252 If @POINTS is a list, returns list; if it is an array reference,
253 returns array reference.
254
256 Dmitry Karasik, <dmitry@karasik.eu.org>.
257
259 Prima::Drawable
260perl v5.36.0 2023-03-20 Prima::Drawable::Path(3)