1Prima::Drawable::Path(3U)ser Contributed Perl DocumentatiPornima::Drawable::Path(3)
2
3
4

NAME

6       Prima::Drawable::Path - stroke and fill complex paths
7

DESCRIPTION

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

SYNOPSIS

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

API

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
36       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
40           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
50       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
55       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
60       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
65       ellipse CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y = DIAMETER_X, TILT =
66       0
67           Adds full ellipse to the path.
68
69       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
75       line, rline @POINTS
76           Adds a polyline to path
77
78       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
82       moveto, rmoveto X, Y
83           Stops plotting the current shape and moves the plotting position to
84           X, Y.
85
86       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
91       rectangle X1, Y1, X2, Y2
92           Adds rectangle to the path. Is there only for compatibility with
93           "Prima::Drawable".
94
95       round_rect X1, Y1, X2, Y2, MAX_DIAMETER
96           Adds round rectangle to the path.
97
98       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
103       spline, rspline $POINTS, %OPTIONS.
104           Adds B-spline to path. See "spline" in Prima::Drawable for %OPTIONS
105           descriptions.
106
107       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
115   Properties
116       canvas DRAWABLE
117           Provides access to the attached drawable object
118
119   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
125       The final transformations calculate coordinates the new and the
126       existing matrices:
127
128         P' = NewMatrix * P
129
130       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
134             A  B  0
135             C  D  0
136             Tx Ty 1
137
138           and when applied to 2D coordinates, is calculated as
139
140             X' = AX + CY + Tx
141             Y' = BX + DY + Ty
142
143       precision INTEGER
144           Selects current precision for splines and arcs. See "spline" in
145           Prima::Drawable, "precision" entry.
146
147       antialias BOOLEAN
148           Turns on and off slow but more visually pleasant antialiased
149           drawing mode.
150
151           Default: false
152
153       restore
154           Pops the stack entry and replaces the current matrix and graphic
155           properties with it.
156
157       rotate ANGLE
158           Adds rotation to the current matrix
159
160       save
161           Duplicates the current matrix and graphic properties and pushes
162           them to the stack.
163
164       shear X, Y = X
165           Adds shearing to the current matrix
166
167       scale X, Y = X
168           Adds scaling to the current matrix
169
170       subpixel BOOLEAN
171           Turns on and off slow but more precise floating-point calculation
172           mode
173
174           Default: depends on canvas antialiasing mode
175
176       translate X, Y = X
177           Adds offset to the current matrix
178
179   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
184       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
189       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
193       extents
194           Returns 2 points that box the path.
195
196       last_matrix
197           Return CTM resulted after running all commands
198
199       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
203       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
208       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
216       points FOR_FILL_POLY=0
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 "FOR_FILL_POLY" flag.
220
221       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
227       stroke
228           Draws a polyline over the path
229
230       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
237           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
241   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
247       identity
248           Returns identity matrix
249
250       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

AUTHOR

256       Dmitry Karasik, <dmitry@karasik.eu.org>.
257

SEE ALSO

259       Prima::Drawable
260
261
262
263perl v5.34.1                      2022-04-20          Prima::Drawable::Path(3)
Impressum