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. "baseline" option is same as "textOutBaseline" in
108 Prima::Drawable.
109 Properties
111 canvas DRAWABLE
112 Provides access to the attached drawable object
113 Transformations
115 Transformation calls change the current path properties (matrix etc) so
116 that all subsequent calls will use them until a call to "restore" is
117 used. "save" and "restore" implement a stacking mechanism, so that
118 local transformations can be made.
119 The final transformations calculate coordinates the new and the
121 existing matrices:
122 P' = NewMatrix * P
124 matrix A, B, C, D, Tx, Ty
126 Applies transformation matrix to the path. The matrix, as used by
127 the module, is formed as such:
128 A B 0
130 C D 0
131 Tx Ty 1
132 and when applied to 2D coordinates, is calculated as
134 X' = AX + CY + Tx
136 Y' = BX + DY + Ty
137 precision INTEGER
139 Selects current precision for splines and arcs. See "spline" in
140 Prima::Drawable, "precision" entry.
141 restore
143 Pops the stack entry and replaces the current matrix and graphic
144 properties with it.
145 rotate ANGLE
147 Adds rotation to the current matrix
148 save
150 Duplicates the current matrix and graphic properties and pushes
151 them to the stack.
152 shear X, Y = X
154 Adds shearing to the current matrix
155 scale X, Y = X
157 Adds scaling to the current matrix
158 translate X, Y = X
160 Adds offset to the current matrix
161 Operations
163 These methods perform actual path rendering, that was delayed until
164 that, and will create an array of points that can be used for actual
165 drawing.
166 clip %options
168 Returns 1-bit image with clipping mask of the path. %options can be
169 used to pass "fillMode" property that affects the result of the
170 filled shape.
171 contours
173 Same as points but further reduces lines into a 8-connected set of
174 points, suitable to be traced pixel-by-pixel.
175 extents
177 Returns 2 points that box the path.
178 last_matrix
180 Return CTM resulted after running all commands
181 fill fillMode=undef
183 Paints a filled shape over the path. If "fillMode" is set, it is
184 used instead of the one selected on the canvas.
185 flatten PRESCALE
187 Returns new objects where arcs are flattened into lines. The lines
188 are rasterized with scaling factor that is as close as possible to
189 the device pixels, to be suitable for direct send to the polyline()
190 API call. If PRESCALE factor is set, it is used instead to
191 premultiply coordinates of arc anchor points used to render the
192 lines.
193 points FOR_FILL_POLY=0
195 Runs all accumulated commands, and returns rendered set of points,
196 suitable for further calls to either "Prima::Drawable::polyline" or
197 "Prima::Drawable::fillpoly" depending on the "FOR_FILL_POLY" flag.
198 region MODE=fm::Winding|fm::Overlay, RGNOP=rgnop::Union
200 Creates a region object from polygonal shape. If MODE is set,
201 applies fill mode (see "fillMode" in Prima::Drawable for more); if
202 RGNOP is set, applies region set operation (see "combine" in
203 Prima::Region).
204 stroke
206 Draws a polyline over the path
207 widen %OPTIONS
209 Expands path into a new path object containing outlines of the
210 original path as if drawn with selected line properties.
211 "lineWidth", "lineEnd", "lineJoin", "linePattern" are read from
212 %OPTIONS, or from the attached canvas when available. Supports
213 "miterLimit" option with values from 0 to 20.
214 Note: if the intention is to immediately render lines, decrease
216 lineWidth by 1 (they are 1 pixel wider because paths are built
217 around assumption that pixel size is 0, which makes them scalable).
218 Methods for custom primitives
220 append PATH
221 Copies all commands from another PATH object. The PATH object
222 doesn't need to have balanced stacking brackets "save" and
223 "restore", and can be viewed as a macro.
224 identity
226 Returns identity matrix
227 matrix_apply @POINTS
229 Applies current matrix to POINTS, returns the transformed points.
230 If @POINTS is a list, returns list; if it is an array reference,
231 returns array reference.
232
234 Dmitry Karasik, <dmitry@karasik.eu.org>.
235
237 Prima::Drawable
238perl v5.30.1 2020-01-30 Prima::Drawable::Path(3)