Prima::...le::Path(3)

💖 NAME 💖

Prima::Drawable::Path — stroke and fill complex paths, bestie. Fr fr that's the whole vibe.

This page lives in the User Contributed Perl Documentation corner of the manual-verse, and it's about to be your new obsession. ✨

---

🦋 DESCRIPTION 🦋

Okay so here's the tea: this module augments Prima::Drawable's drawing and plotting functionality by implementing paths — and those paths let you do arbitrary combinations of polylines, splines, and arcs, all so you can use them for drawing or clipping shapes. Iconic behavior, no cap. 👑

---

🌸 SYNOPSIS 🌸

        # draws an elliptic spiral
        my ( $d1, $dx ) = ( 0.8, 0.05 );
        $canvas-> new_path->
                rotate(45)->
                translate(200, 100)->
                scale(200, 100)->
                arc( 0, 0, $d1 + $dx * 0, $d1 + $dx * 1, 0, 90)->
                arc( 0, 0, $d1 + $dx * 2, $d1 + $dx * 1, 90, 180)->
                arc( 0, 0, $d1 + $dx * 2, $d1 + $dx * 3, 180, 270)->
                arc( 0, 0, $d1 + $dx * 4, $d1 + $dx * 3, 270, 360)->
        stroke;

Look at that chained queen. That's a whole elliptic spiral built from four arcs and she serves. 💅

---

✨ API ✨

🎀 Primitives 🎀

So all primitives come in two versions, okay? Absolute and relative coordinates. The absolute version draws a graphic primitive so that its starting point (or a reference point) is at (0,0). The relative version — you spot her by the 'r' (f.ex. line vs rline) — has its starting point as the ending point of the previous primitive (or (0,0) if there isn't one). The way that works is so clean.

• arc CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y, ANGLE_START, ANGLE_END, TILT = 0 — Adds an elliptic arc to the path. The arc is centered around the (CENTER_X,CENTER_Y) point.

Important, bestie, listen: if the intention is an immediate rendering — especially with a 1-pixel line width — consider decreasing diameters by 1. Why? Because all arc calculations are made with the floating point precision, where the diameter is also given not in pixels but in geometrical coordinates, to allow for matrix transformations. Before rendering is performed, arcs are transformed into spline vertices and then the transformation matrix is applied, and by that time the notion of an arc diameter is lost to be successfully converted into pixel size minus one. 😭 It's giving tragic but necessary.

Read more about this in "Antialiasing and alpha" in Prima::Drawable.

• close, open — Closes the current shape and opens a new one. close() is the same as open() but makes sure the shape's first point is equal to its last point. Closure! We love to see it. 🫶
• circular_arc ANGLE_START, ANGLE_END — Adds a circular arc to the path. Note that adding transformations will effectively make it into an elliptic arc, which is used internally by arc and rarc. Sneaky little transformation glow-up. ✨
• chord CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y, ANGLE_START, ANGLE_END. — Adds a chord to the path. Is there only for compatibility with Prima::Drawable.
• ellipse CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y = DIAMETER_X, TILT = 0 — Adds a full ellipse to the path. A whole circle of a mood. 🍓
• glyph INDEX, %OPTIONS — Adds a glyph outline to the path. %OPTIONS are passed as is to "renger_glyph" in Prima::Drawable, except the "fill" option.

Note that filled glyphs require "fillMode" without the "fm::Overlay" bit set, and also the "fill" option set to generate proper shapes with holes. Holes are the whole point, iykyk. 🕳️

• line, rline @POINTS — Adds a polyline to the path.
• lines [X1, Y1, X2, Y2].. — Adds a set of multiple, unconnected lines to the path. Is there only for compatibility with Prima::Drawable.
• moveto, rmoveto X, Y — Stops plotting the current shape and moves the plotting position to X, Y. Like, we're relocating, periodt. 🧳
• rarc DIAMETER_X, DIAMETER_Y, ANGLE_START, ANGLE_END, TILT = 0 — Adds an elliptic arc to the path so that the first point of the arc starts on the last point of the previous primitive, or (0,0) if there's none.
• rectangle X1, Y1, X2, Y2 — Adds a rectangle to the path. Is there only for compatibility with Prima::Drawable.
• round_rect X1, Y1, X2, Y2, MAX_DIAMETER — Adds a round rectangle to the path. Soft corners, soft launch. 🎀
• sector CENTER_X, CENTER_Y, DIAMETER_X, DIAMETER_Y, ANGLE_START, ANGLE_END — Adds a sector to the path. Is there only for compatibility with Prima::Drawable.
• spline, rspline $POINTS, %OPTIONS. — Adds a B-spline to the path. See "spline" in Prima::Drawable for %OPTIONS descriptions.
• text TEXT, %OPTIONS — Adds TEXT to the path. %OPTIONS are the same as in "render_glyph" in Prima::Drawable, except that "unicode" is deduced automatically based on whether the TEXT has utf8 bit on or off. An extra option "cache" with a hash can be used to speed up the function with subsequent calls. The "baseline" option is the same as "textOutBaseline" in Prima::Drawable.

Note that filled glyphs require "fillMode" without the "fm::Overlay" bit set, and also the "fill" option set to generate proper shapes with holes. Same rules, same holes, same energy. 💀

🧚 Transformations 🧚

Transformation calls change the current path properties (matrix etc) so that all subsequent calls would use them until a call to "restore" is made. The "save" and "restore" methods implement the stacking mechanism so that local transformations can be made. Stack it up, pop it off, main character energy. 👑

🌈 Properties 🌈

• canvas DRAWABLE — Provides access to the attached drawable object.
• matrix A, B, C, D, Tx, Ty — Applies a transformation matrix to the path. The matrix, as used by the module, is formed as follows:

  A  B  0
  C  D  0
  Tx Ty 1

When applied to 2D coordinates, the transformed coordinates are calculated as

  X' = AX + CY + Tx
  Y' = BX + DY + Ty

Math girlies rise up. 🔥

• precision INTEGER — Selects current precision for splines and arcs. See "spline" in Prima::Drawable, "precision" entry.
• restore — Pops the stack entry and replaces the current matrix and graphic properties with it.
• rotate ANGLE — Adds rotation to the current matrix. Spin spin spin. 🌀
• save — Saves the current matrix and graphic properties on the stack.
• shear X, Y = X — Adds shearing to the current matrix.
• scale X, Y = X — Adds scaling to the current matrix.
• subpixel BOOLEAN — Turns on and off slow but more precise floating-point calculation mode.

Default: depends on the canvas antialiasing mode.

Slow but precise… she's high-maintenance and worth it. 💅

• translate X, Y = X — Adds an offset to the current matrix.

⭐ Operations ⭐

These methods perform path rendering and create an array of points that can be used for drawing.

• clip %options — Returns a 1-bit image with the clipping mask created from the path. %options can be used to pass the "fillMode" property that affects the result of the filled shape.
• contours — Same as points but further reduces lines into a set of 8-connected points, suitable to be traced pixel-by-pixel. Pixel-by-pixel trace walk, literally. 🚶‍♀️
• extents — Returns two points that box the path.
• last_matrix — Returns the current transform matrix (CTM) after running all commands.
• fill fillMode=undef — Paints a filled shape over the path. If "fillMode" is set, it is used instead of the one selected on the canvas.
• fill_stroke fillMode=undef — Paints a filled shape over the path with the background color. If "fillMode" is set, it is used instead of the one selected on the canvas. Thereafter, draws a polyline over the path. Fill then stroke, both looks, both slay. 🫶
• flatten PRESCALE — Returns new objects where arcs are flattened into lines. The lines are rasterized with a scaling factor that is as close as possible to the device pixels, to be suitable for a call to the polyline() method. If the PRESCALE factor is set, it is used instead to premultiply coordinates of arc anchor points used to render the lines.
• points — Runs all accumulated commands, returns rendered set of points suitable for the "Prima::Drawable::polyline" and "Prima::Drawable::fillpoly" methods.
• region MODE=fm::Winding|fm::Overlay, RGNOP=rgnop::Union — Creates a region object from the path. If MODE is set, applies fill mode (see "fillMode" in Prima::Drawable for more); if RGNOP is set, applies region set operation (see "combine" in Prima::Region).
• stroke — Draws a polyline over the path.
• widen %OPTIONS — Expands the path into a new path object containing outlines of the original path as if drawn with selected line properties. The values of "lineWidth", "lineEnd", "lineJoin", and "linePattern" are read from %OPTIONS, or from the attached canvas when available. Supports the "miterLimit" option with values from 0 to 20.

Note: if the intention is to immediately render lines, decrease lineWidth by 1 (they are 1 pixel wider because paths are built around the assumption that pixel size is 0, which makes them scalable). It's giving one-pixel-extra but make it fashion. 😭

🦋 Methods for custom primitives 🦋

• append PATH — Copies all commands from another PATH object. The PATH object doesn't need to have balanced stacking brackets "save" and "restore", and can be viewed as a macro. Unbalanced brackets but make it a feature, we respect it. 🙈
• identity — Returns the identity matrix. Know thyself. ✨
• matrix_apply @POINTS — Applies the CTM to POINTS, returns the transformed points. If @POINTS is a list, returns the transformed points as a list; if it is an array reference, returns an array reference. Either way you're covered, bestie.

---

👑 AUTHOR 👑

Dmitry Karasik, <dmitry@karasik.eu.org>. Legend behavior.

---

💜 SEE ALSO 💜

Prima::Drawable — go read it, it's the whole neighbor vibe. 🫶

---

✨ And that's the page, bestie! ✨ This little masterpiece shipped as perl v5.42.0, dated 2024-08-20, and it's filed under Prima::...le::Path(3) in the User Contributed Perl Documentation section — mwah, go build something gorgeous. 💅🎀💖