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 and "fill" option set
72 to generate proper shapes with holes.
73 line, rline @POINTS
75 Adds a polyline to path
76 lines [X1, Y1, X2, Y2]..
78 Adds set of multiple, unconnected lines to the path. Is there only
79 for compatibility with "Prima::Drawable".
80 moveto, rmoveto X, Y
82 Stops plotting the current shape and moves the plotting position to
83 X, Y.
84 rarc DIAMETER_X, DIAMETER_Y, ANGLE_START, ANGLE_END, TILT = 0
86 Adds elliptic arc to path so that the first point of the arc starts
87 on the last point of the previous primitive, or (0,0) if there's
88 none.
89 rectangle X1, Y1, X2, Y2
91 Adds rectangle to the path. Is there only for compatibility with
92 "Prima::Drawable".
93 sector CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y, ANGLE_START,
95 ANGLE_END
96 Adds sector to the path. Is there only for compatibility with
97 "Prima::Drawable".
98 spline, rspline $POINTS, %OPTIONS.
100 Adds B-spline to path. See "spline" in Prima::Drawable for %OPTIONS
101 descriptions.
102 text TEXT, %OPTIONS
104 Adds "TEXT" to the path. %OPTIONS are same as in "render_glyph" in
105 Prima::Drawable, except that "unicode" is deduced automatically
106 based on whether "TEXT" has utf8 bit on or off; and an extra option
107 "cache" with a hash can be used to speed up the function with
108 subsequent calls. "baseline" option is same as "textOutBaseline" in
109 Prima::Drawable.
110 Properties
112 canvas DRAWABLE
113 Provides access to the attached drawable object
114 Transformations
116 Transformation calls change the current path properties (matrix etc) so
117 that all subsequent calls will use them until a call to "restore" is
118 used. "save" and "restore" implement a stacking mechanism, so that
119 local transformations can be made.
120 The final transformations calculate coordinates the new and the
122 existing matrices:
123 P' = NewMatrix * P
125 matrix A, B, C, D, Tx, Ty
127 Applies transformation matrix to the path. The matrix, as used by
128 the module, is formed as such:
129 A B 0
131 C D 0
132 Tx Ty 1
133 and when applied to 2D coordinates, is calculated as
135 X' = AX + CY + Tx
137 Y' = BX + DY + Ty
138 precision INTEGER
140 Selects current precision for splines and arcs. See "spline" in
141 Prima::Drawable, "precision" entry.
142 restore
144 Pops the stack entry and replaces the current matrix and graphic
145 properties with it.
146 rotate ANGLE
148 Adds rotation to the current matrix
149 save
151 Duplicates the current matrix and graphic properties and pushes
152 them to the stack.
153 shear X, Y = X
155 Adds shearing to the current matrix
156 scale X, Y = X
158 Adds scaling to the current matrix
159 translate X, Y = X
161 Adds offset to the current matrix
162 Operations
164 These methods perform actual path rendering, that was delayed until
165 that, and will create an array of points that can be used for actual
166 drawing.
167 clip %options
169 Returns 1-bit image with clipping mask of the path. %options can be
170 used to pass "fillMode" property that affects the result of the
171 filled shape.
172 contours
174 Same as points but further reduces lines into a 8-connected set of
175 points, suitable to be traced pixel-by-pixel.
176 extents
178 Returns 2 points that box the path.
179 last_matrix
181 Return CTM resulted after running all commands
182 fill fillMode=undef
184 Paints a filled shape over the path. If "fillMode" is set, it is
185 used instead of the one selected on the canvas.
186 flatten PRESCALE
188 Returns new objects where arcs are flattened into lines. The lines
189 are rasterized with scaling factor that is as close as possible to
190 the device pixels, to be suitable for direct send to the polyline()
191 API call. If PRESCALE factor is set, it is used instead to
192 premultiply coordinates of arc anchor points used to render the
193 lines.
194 points FOR_FILL_POLY=0
196 Runs all accumulated commands, and returns rendered set of points,
197 suitable for further calls to either "Prima::Drawable::polyline" or
198 "Prima::Drawable::fillpoly" depending on the "FOR_FILL_POLY" flag.
199 region MODE=fm::Winding|fm::Overlay, RGNOP=rgnop::Union
201 Creates a region object from polygonal shape. If MODE is set,
202 applies fill mode (see "fillMode" in Prima::Drawable for more); if
203 RGNOP is set, applies region set operation (see "combine" in
204 Prima::Region).
205 stroke
207 Draws a polyline over the path
208 widen %OPTIONS
210 Expands path into a new path object containing outlines of the
211 original path as if drawn with selected line properties.
212 "lineWidth", "lineEnd", "lineJoin", "linePattern" are read from
213 %OPTIONS, or from the attached canvas when available. Supports
214 "miterLimit" option with values from 0 to 20.
215 Note: if the intention is to immediately render lines, decrease
217 lineWidth by 1 (they are 1 pixel wider because paths are built
218 around assumption that pixel size is 0, which makes them scalable).
219 Methods for custom primitives
221 append PATH
222 Copies all commands from another PATH object. The PATH object
223 doesn't need to have balanced stacking brackets "save" and
224 "restore", and can be viewed as a macro.
225 identity
227 Returns identity matrix
228 matrix_apply @POINTS
230 Applies current matrix to POINTS, returns the transformed points.
231 If @POINTS is a list, returns list; if it is an array reference,
232 returns array reference.
233
235 Dmitry Karasik, <dmitry@karasik.eu.org>.
236
238 Prima::Drawable
239perl v5.32.0 2020-07-28 Prima::Drawable::Path(3)