vgpu-render 0.2.0 → 0.3.0

package/dist/frame-draw-list-2d.js

@@ -9,6 +9,10 @@
  *
  * See `camera-2d.ts` for what `world2d` and `screen` mean.
  */
+import { gridLines2D } from "./geometry-generators.js";
+import { sampleCurve2D } from "./curve.js";
+const WIRE = { filled: false };
+const SOLID = { filled: true };
 const DEFAULT_2D_COLOR = [1, 1, 1, 1];
 const DEFAULT_2D_LAYER = 1;
 /** An unfilled shape still has to be visible, so a stroke defaults to one pixel. */
@@ -47,6 +51,21 @@ function angleRange(options) {
     }
     return { startAngle, sweep };
 }
+/** `[visible, gap, phase]` of a dashed outline; a dash needs a real gap to break the stroke. */
+function dashValue(value) {
+    const visible = finite(value[0], "dash visible");
+    const gap = finite(value[1], "dash gap");
+    const phase = finite(value[2], "dash phase");
+    if (visible <= 0)
+        throw new RangeError("dash visible must be greater than zero");
+    if (gap <= 0)
+        throw new RangeError("dash gap must be greater than zero");
+    return [visible, gap, phase];
+}
+/** A dashed outline: the pattern is validated once, here. */
+function dashed(dash) {
+    return { filled: false, dash: dashValue(dash) };
+}
 function vec2(value, name) {
     if (value.length !== 2) {
         throw new RangeError(`${name} must contain two values`);
@@ -127,7 +146,86 @@ export class FrameDrawList2D {
         });
         return this;
     }
+    /** Straight segment (the 3D `draw_line`). */
     line(start, end, options = {}) {
+        return this.#line(start, end, options, undefined);
+    }
+    /** Straight segment dashed along its length (the 3D `draw_line_d`). */
+    line_d(start, end, dash, options = {}) {
+        return this.#line(start, end, options, dashValue(dash));
+    }
+    /**
+     * Arrow with an open V head, the 2D twin of `FrameDrawList.arrow`: the shaft runs to `origin +
+     * direction`, and the head is two lines back from the tip.
+     */
+    arrow(origin, direction, options = {}) {
+        const { end, left, right } = this.#arrowParts(origin, direction, options);
+        // The open head is an outline, so the shaft runs all the way to the tip and the two head lines
+        // sit on top of it.
+        this.line(origin, end, options);
+        this.line(end, left, options);
+        this.line(end, right, options);
+        return this;
+    }
+    /** Arrow with a filled triangular head (`arrow` keeps the open line head). */
+    arrow_s(origin, direction, options = {}) {
+        const { end, base, left, right } = this.#arrowParts(origin, direction, options);
+        this.line(origin, base, options);
+        this.triangle_s(end, left, right, {
+            ...(options.color === undefined ? {} : { color: options.color }),
+            ...(options.space === undefined ? {} : { space: options.space }),
+            ...(options.layer === undefined ? {} : { layer: options.layer }),
+        });
+        return this;
+    }
+    /** Arrow whose shaft is dashed; the two head lines stay solid like the filled head. */
+    arrow_d(origin, direction, dash, options = {}) {
+        const { end, left, right } = this.#arrowParts(origin, direction, options);
+        this.line_d(origin, end, dashValue(dash), options);
+        // Only the shaft dashes: the head outline stays solid so the tip keeps its shape, matching the
+        // filled head of `arrow_s_d`.
+        this.line(end, left, options);
+        this.line(end, right, options);
+        return this;
+    }
+    /** Arrow with a filled head and a dashed shaft. */
+    arrow_s_d(origin, direction, dash, options = {}) {
+        const { end, base, left, right } = this.#arrowParts(origin, direction, options);
+        this.line_d(origin, base, dashValue(dash), options);
+        this.triangle_s(end, left, right, {
+            ...(options.color === undefined ? {} : { color: options.color }),
+            ...(options.space === undefined ? {} : { space: options.space }),
+            ...(options.layer === undefined ? {} : { layer: options.layer }),
+        });
+        return this;
+    }
+    #arrowParts(origin, direction, options) {
+        const from = vec2(origin, "origin");
+        const delta = vec2(direction, "direction");
+        const length = Math.hypot(delta[0], delta[1]);
+        const end = [from[0] + delta[0], from[1] + delta[1]];
+        const unit = length > 0 ? [delta[0] / length, delta[1] / length] : [1, 0];
+        const headLength = finite(options.headLength ?? Math.min(14, Math.max(6, length * 0.25)), "headLength");
+        const headAngle = finite(options.headAngle ?? Math.PI / 6, "headAngle");
+        const back = Math.cos(headAngle) * headLength;
+        const spread = Math.sin(headAngle) * headLength;
+        const side = [-unit[1], unit[0]];
+        return {
+            end,
+            base: [end[0] - unit[0] * back, end[1] - unit[1] * back],
+            left: [end[0] - unit[0] * back + side[0] * spread, end[1] - unit[1] * back + side[1] * spread],
+            right: [end[0] - unit[0] * back - side[0] * spread, end[1] - unit[1] * back - side[1] * spread],
+            back,
+        };
+    }
+    ray(origin, direction, options = {}) {
+        return this.#line(origin, [origin[0] + direction[0], origin[1] + direction[1]], options, undefined);
+    }
+    /** Ray dashed along its length. */
+    ray_d(origin, direction, dash, options = {}) {
+        return this.#line(origin, [origin[0] + direction[0], origin[1] + direction[1]], options, dashValue(dash));
+    }
+    #line(start, end, options, dashArgument) {
         this.#assertOpen();
         const resolvedStart = vec2(start, "start");
         const resolvedEnd = vec2(end, "end");
@@ -137,7 +235,7 @@ export class FrameDrawList2D {
         const width = finite(options.width ?? this.#defaults.line.width ?? 1, "width");
         if (width <= 0)
             throw new RangeError("width must be greater than zero");
-        const dash = options.dash ?? this.#defaults.line.dash;
+        const dash = dashArgument ?? this.#defaults.line.dash;
         const joint = options.joint ?? this.#defaults.line.joint;
         this.#lines.push({
             kind: "line2d",
@@ -154,23 +252,31 @@ export class FrameDrawList2D {
         });
         return this;
     }
-    ray(origin, direction, options = {}) {
-        return this.line(origin, [origin[0] + direction[0], origin[1] + direction[1]], options);
-    }
     /**
      * Path of segments, the 2D twin of `FrameDrawList.lineStrip`. Dash distance accumulates over
      * the whole path and an open strip joins only its interior vertices, matching the 3D layer.
      */
     lineStrip(points, options = {}, closed = false) {
+        return this.#strip(points, options, undefined, closed);
+    }
+    /** Open strip dashed along its length. */
+    lineStrip_d(points, dash, options = {}, closed = false) {
+        return this.#strip(points, options, dashValue(dash), closed);
+    }
+    /** Closed strip: the last point joins the first (the 3D `draw_line_loop`). */
+    lineLoop(points, options = {}) {
+        return this.#strip(points, options, undefined, true);
+    }
+    /** Closed strip dashed along its length. */
+    lineLoop_d(points, dash, options = {}) {
+        return this.#strip(points, options, dashValue(dash), true);
+    }
+    #strip(points, options, dash, closed) {
         this.#assertOpen();
-        const dash = options.dash ?? this.#defaults.line.dash;
         const vertexDistances = [0];
         let traveled = 0;
         const segment = (a, b) => {
-            this.line(a, b, {
-                ...options,
-                ...(dash === undefined ? {} : { dash: [dash[0], dash[1], dash[2] + traveled] }),
-            });
+            this.#line(a, b, options, dash === undefined ? undefined : [dash[0], dash[1], dash[2] + traveled]);
             traveled += Math.hypot(b[0] - a[0], b[1] - a[1]);
             vertexDistances.push(traveled);
         };
@@ -192,90 +298,233 @@ export class FrameDrawList2D {
     polyline(points, options = {}, closed = false) {
         return this.lineStrip(points, options, closed);
     }
+    polyline_d(points, dash, options = {}, closed = false) {
+        return this.lineStrip_d(points, dash, options, closed);
+    }
+    /**
+     * Cubic curve sampled into a polyline, the 2D twin of `FrameDrawList.curve`. The curve's own
+     * `closed` flag decides whether the last point joins the first.
+     */
+    curve(curve, options = {}) {
+        const { tolerance, transform, ...lineOptions } = options;
+        return this.#strip(sampleCurve2D(curve, tolerance, transform), lineOptions, undefined, curve.closed ?? false);
+    }
+    /** Cubic curve sampled into a dashed polyline. */
+    curve_d(curve, dash, options = {}) {
+        const { tolerance, transform, ...lineOptions } = options;
+        return this.#strip(sampleCurve2D(curve, tolerance, transform), lineOptions, dashValue(dash), curve.closed ?? false);
+    }
     /**
      * Axis-aligned grid of lines, the 2D twin of `FrameDrawList.grid` and reference `grid_2d`: `cells`
      * are the cells per axis, so the drawn line count is one more on each side.
      */
     grid(center, cells, spacing, options = {}) {
+        return this.#grid(center, cells, spacing, options, undefined);
+    }
+    /** Grid whose lines are dashed along their length. */
+    grid_d(center, cells, spacing, dash, options = {}) {
+        return this.#grid(center, cells, spacing, options, dashValue(dash));
+    }
+    #grid(center, cells, spacing, options, dash) {
         this.#assertOpen();
+        const { rotation = 0, skew = [0, 0], outer = "none", ...lineOptions } = options;
         const [columns, rows] = cells;
         if (!Number.isInteger(columns) || !Number.isInteger(rows) || columns < 1 || rows < 1) {
             throw new RangeError("grid cells must be positive integers");
         }
         const [stepX, stepY] = positiveSize(spacing, "spacing");
         const [centerX, centerY] = vec2(center, "center");
-        const halfWidth = (columns * stepX) / 2;
-        const halfHeight = (rows * stepY) / 2;
-        for (let column = 0; column <= columns; column++) {
-            const x = centerX - halfWidth + column * stepX;
-            this.line([x, centerY - halfHeight], [x, centerY + halfHeight], options);
+        const angle = finite(rotation, "rotation");
+        const [skewX, skewY] = skew;
+        finite(skewX, "skew x");
+        finite(skewY, "skew y");
+        if (outer !== "none" && outer !== "x" && outer !== "y" && outer !== "xy") {
+            throw new RangeError('grid outer must be "none", "x", "y" or "xy"');
         }
-        for (let row = 0; row <= rows; row++) {
-            const y = centerY - halfHeight + row * stepY;
-            this.line([centerX - halfWidth, y], [centerX + halfWidth, y], options);
+        for (const [a, b] of gridLines2D([columns, rows], [stepX, stepY], [centerX, centerY], angle, [skewX, skewY], outer)) {
+            this.#line(a, b, lineOptions, dash);
         }
         return this;
     }
-    /** Rectangle with the given full width and height (reference `Rectangle::new`). */
+    /**
+     * Rectangle with the given full width and height, stroked by default like the 3D `draw_rect`.
+     * `rect_s` fills it and `rect_d` dashes the outline.
+     */
     rect(center, size, options = {}) {
-        const full = positiveSize(size, "size");
-        this.#pushShape("rect", center, { size: [full[0] / 2, full[1] / 2] }, options);
+        this.#rectVariant(center, size, options, WIRE);
         return this;
     }
-    /** Rectangle with rounded corners; the shader clamps the radius to half the shorter side. */
-    roundedRect(center, size, cornerRadius, options = {}) {
+    /** Solid rectangle (reference `Rectangle`, the 3D `draw_rect_s`). */
+    rect_s(center, size, options = {}) {
+        this.#rectVariant(center, size, options, SOLID);
+        return this;
+    }
+    /**
+     * Rectangle outline dashed along its perimeter (the 3D `draw_rect_d`). `dash` is
+     * `[visible, gap, phase]` in shape-space units, the same triple the line layer takes.
+     */
+    rect_d(center, size, dash, options = {}) {
+        this.#rectVariant(center, size, options, dashed(dash));
+        return this;
+    }
+    #rectVariant(center, size, options, variant) {
         const full = positiveSize(size, "size");
-        this.#pushShape("rounded-rect", center, { size: [full[0] / 2, full[1] / 2], cornerRadius: nonNegative(cornerRadius, "cornerRadius") }, options);
+        this.#pushShape("rect", center, { size: [full[0] / 2, full[1] / 2] }, options, variant);
+    }
+    /** Rounded rectangle outline; the shader clamps the radius to half the shorter side. */
+    rect_r(center, size, cornerRadius, options = {}) {
+        this.#rectRVariant(center, size, cornerRadius, options, WIRE);
+        return this;
+    }
+    /** Solid rounded rectangle (reference `RoundedRectangle`, the 3D `_s` counterpart). */
+    rect_r_s(center, size, cornerRadius, options = {}) {
+        this.#rectRVariant(center, size, cornerRadius, options, SOLID);
+        return this;
+    }
+    /** Rounded rectangle outline dashed along its perimeter. */
+    rect_r_d(center, size, cornerRadius, dash, options = {}) {
+        this.#rectRVariant(center, size, cornerRadius, options, dashed(dash));
         return this;
     }
-    /** Filled disc with the given radius (reference `Circle::new`). */
+    #rectRVariant(center, size, cornerRadius, options, variant) {
+        const full = positiveSize(size, "size");
+        this.#pushShape("rounded-rect", center, { size: [full[0] / 2, full[1] / 2], cornerRadius: nonNegative(cornerRadius, "cornerRadius") }, options, variant);
+    }
+    /** Disc outline with the given radius (reference `Circle`, the 3D `draw_circle`). */
     circle(center, radius, options = {}) {
-        const r = positive(radius, "radius");
-        this.#pushShape("circle", center, { size: [r, r] }, options);
+        this.#circleVariant(center, radius, options, WIRE);
+        return this;
+    }
+    /** Solid disc (reference `Circle::new`, the 3D `draw_circle_s`). */
+    circle_s(center, radius, options = {}) {
+        this.#circleVariant(center, radius, options, SOLID);
         return this;
     }
-    /** Ellipse with independent x and y radii (reference `Ellipse::new(x_radius, y_radius)`). */
+    /** Dashed circle outline. */
+    circle_d(center, radius, dash, options = {}) {
+        this.#circleVariant(center, radius, options, dashed(dash));
+        return this;
+    }
+    #circleVariant(center, radius, options, variant) {
+        const r = positive(radius, "radius");
+        this.#pushShape("circle", center, { size: [r, r] }, options, variant);
+    }
+    /** Ellipse outline with independent x and y radii (reference `Ellipse`). */
     ellipse(center, radii, options = {}) {
-        const r = positiveSize(radii, "radii");
-        this.#pushShape("ellipse", center, { size: r }, options);
+        this.#ellipseVariant(center, radii, options, WIRE);
+        return this;
+    }
+    /** Solid ellipse (reference `Ellipse::new`, the 3D `_s` counterpart). */
+    ellipse_s(center, radii, options = {}) {
+        this.#ellipseVariant(center, radii, options, SOLID);
         return this;
     }
+    /** Dashed ellipse outline. */
+    ellipse_d(center, radii, dash, options = {}) {
+        this.#ellipseVariant(center, radii, options, dashed(dash));
+        return this;
+    }
+    #ellipseVariant(center, radii, options, variant) {
+        const r = positiveSize(radii, "radii");
+        this.#pushShape("ellipse", center, { size: r }, options, variant);
+    }
     /**
-     * Circular arc from `startAngle` through `sweep`. It is a curve without an interior, so an
-     * unfilled arc (the default) strokes it with `strokeWidth` while `fill: true` leaves a hairline.
+     * Circular arc from `startAngle` through `sweep`. It is a curve without an interior, so it is
+     * only ever stroked; `arc_s` would have nothing to fill.
      */
     arc(center, radius, options = {}) {
+        this.#arcVariant(center, radius, options, WIRE);
+        return this;
+    }
+    /** Arc outline dashed along its sweep. */
+    arc_d(center, radius, dash, options = {}) {
+        this.#arcVariant(center, radius, options, dashed(dash));
+        return this;
+    }
+    #arcVariant(center, radius, options, variant) {
         const r = positive(radius, "radius");
         const angles = angleRange(options);
-        this.#pushShape("arc", center, { size: [r, r], ...angles }, options);
-        return this;
+        this.#pushShape("arc", center, { size: [r, r], ...angles }, options, variant);
     }
-    /** Ring band between two radii (reference `Annulus::new(inner_radius, outer_radius)`). */
+    /** Ring outline between two radii (reference `Annulus`). */
     annulus(center, innerRadius, outerRadius, options = {}) {
+        this.#annulusVariant(center, innerRadius, outerRadius, options, WIRE);
+        return this;
+    }
+    /** Filled ring band (reference `Annulus::new`, the 3D `_s` counterpart). */
+    annulus_s(center, innerRadius, outerRadius, options = {}) {
+        this.#annulusVariant(center, innerRadius, outerRadius, options, SOLID);
+        return this;
+    }
+    /** Dashed annulus outline; both boundaries are stroked. */
+    annulus_d(center, innerRadius, outerRadius, dash, options = {}) {
+        this.#annulusVariant(center, innerRadius, outerRadius, options, dashed(dash));
+        return this;
+    }
+    #annulusVariant(center, innerRadius, outerRadius, options, variant) {
         const inner = nonNegative(innerRadius, "innerRadius");
         const outer = positive(outerRadius, "outerRadius");
         if (inner >= outer)
             throw new RangeError("innerRadius must be smaller than outerRadius");
-        this.#pushShape("annulus", center, { size: [outer, inner] }, options);
-        return this;
+        this.#pushShape("annulus", center, { size: [outer, inner] }, options, variant);
     }
-    /** Capsule whose straight section is `length` long along y (reference `Capsule2d::new(radius, length)`). */
+    /** Capsule outline whose straight section is `length` long along y (reference `Capsule2d`). */
     capsule(center, radius, length, options = {}) {
+        this.#capsuleVariant(center, radius, length, options, WIRE);
+        return this;
+    }
+    /** Solid capsule (reference `Capsule2d::new`, the 3D `_s` counterpart). */
+    capsule_s(center, radius, length, options = {}) {
+        this.#capsuleVariant(center, radius, length, options, SOLID);
+        return this;
+    }
+    /** Dashed capsule outline. */
+    capsule_d(center, radius, length, dash, options = {}) {
+        this.#capsuleVariant(center, radius, length, options, dashed(dash));
+        return this;
+    }
+    #capsuleVariant(center, radius, length, options, variant) {
         const r = positive(radius, "radius");
         const straight = nonNegative(length, "length");
-        this.#pushShape("capsule", center, { size: [r, straight / 2] }, options);
-        return this;
+        this.#pushShape("capsule", center, { size: [r, straight / 2] }, options, variant);
     }
-    /** Regular polygon with a vertex on the +x axis (reference `RegularPolygon::new(circumradius, sides)`). */
+    /** Regular polygon outline with a vertex on the +x axis (reference `RegularPolygon`). */
     polygon(center, circumradius, sides, options = {}) {
+        this.#polygonVariant(center, circumradius, sides, options, WIRE);
+        return this;
+    }
+    /** Solid regular polygon (reference `RegularPolygon::new`, the 3D `_s` counterpart). */
+    polygon_s(center, circumradius, sides, options = {}) {
+        this.#polygonVariant(center, circumradius, sides, options, SOLID);
+        return this;
+    }
+    /** Dashed regular polygon outline. */
+    polygon_d(center, circumradius, sides, dash, options = {}) {
+        this.#polygonVariant(center, circumradius, sides, options, dashed(dash));
+        return this;
+    }
+    #polygonVariant(center, circumradius, sides, options, variant) {
         const r = positive(circumradius, "circumradius");
         if (!Number.isInteger(sides) || sides < 3)
             throw new RangeError("sides must be an integer of at least 3");
-        this.#pushShape("polygon", center, { size: [r, r], sides }, options);
-        return this;
+        this.#pushShape("polygon", center, { size: [r, r], sides }, options, variant);
     }
-    /** Arbitrary triangle (reference `Triangle2d::new(a, b, c)`); `rotation` turns about its centroid. */
+    /** Triangle outline (reference `Triangle2d`); `rotation` turns about its centroid. */
     triangle(a, b, c, options = {}) {
+        this.#triangleVariant(a, b, c, options, WIRE);
+        return this;
+    }
+    /** Solid triangle (reference `Triangle2d::new`, the 3D `_s` counterpart). */
+    triangle_s(a, b, c, options = {}) {
+        this.#triangleVariant(a, b, c, options, SOLID);
+        return this;
+    }
+    /** Dashed triangle outline. */
+    triangle_d(a, b, c, dash, options = {}) {
+        this.#triangleVariant(a, b, c, options, dashed(dash));
+        return this;
+    }
+    #triangleVariant(a, b, c, options, variant) {
         const p0 = vec2(a, "a");
         const p1 = vec2(b, "b");
         const p2 = vec2(c, "c");
@@ -284,28 +533,66 @@ export class FrameDrawList2D {
             size: [p0[0] - center[0], p0[1] - center[1]],
             vertexB: [p1[0] - center[0], p1[1] - center[1]],
             vertexC: [p2[0] - center[0], p2[1] - center[1]],
-        }, options);
-        return this;
+        }, options, variant);
     }
-    /** Diamond with the given full diagonals (reference `Rhombus::new(horizontal, vertical)`). */
+    /** Diamond outline with the given full diagonals (reference `Rhombus`). */
     rhombus(center, diagonals, options = {}) {
-        const d = positiveSize(diagonals, "diagonals");
-        this.#pushShape("rhombus", center, { size: [d[0] / 2, d[1] / 2] }, options);
+        this.#rhombusVariant(center, diagonals, options, WIRE);
         return this;
     }
-    /** Disc sector from `startAngle` through `sweep` (reference `CircularSector`). */
+    /** Solid diamond (reference `Rhombus::new`, the 3D `_s` counterpart). */
+    rhombus_s(center, diagonals, options = {}) {
+        this.#rhombusVariant(center, diagonals, options, SOLID);
+        return this;
+    }
+    /** Dashed diamond outline. */
+    rhombus_d(center, diagonals, dash, options = {}) {
+        this.#rhombusVariant(center, diagonals, options, dashed(dash));
+        return this;
+    }
+    #rhombusVariant(center, diagonals, options, variant) {
+        const d = positiveSize(diagonals, "diagonals");
+        this.#pushShape("rhombus", center, { size: [d[0] / 2, d[1] / 2] }, options, variant);
+    }
+    /** Disc sector outline from `startAngle` through `sweep` (reference `CircularSector`). */
     sector(center, radius, options = {}) {
+        this.#sectorVariant(center, radius, options, WIRE);
+        return this;
+    }
+    /** Solid disc sector (reference `CircularSector`, the 3D `_s` counterpart). */
+    sector_s(center, radius, options = {}) {
+        this.#sectorVariant(center, radius, options, SOLID);
+        return this;
+    }
+    /** Dashed sector outline: the arc plus both radii. */
+    sector_d(center, radius, dash, options = {}) {
+        this.#sectorVariant(center, radius, options, dashed(dash));
+        return this;
+    }
+    #sectorVariant(center, radius, options, variant) {
         const r = positive(radius, "radius");
         const angles = angleRange(options);
-        this.#pushShape("sector", center, { size: [r, r], ...angles }, options);
-        return this;
+        this.#pushShape("sector", center, { size: [r, r], ...angles }, options, variant);
     }
-    /** Disc region between a chord and its arc (reference `CircularSegment`). */
+    /** Disc segment outline between a chord and its arc (reference `CircularSegment`). */
     segment(center, radius, options = {}) {
+        this.#segmentVariant(center, radius, options, WIRE);
+        return this;
+    }
+    /** Solid disc segment (reference `CircularSegment`, the 3D `_s` counterpart). */
+    segment_s(center, radius, options = {}) {
+        this.#segmentVariant(center, radius, options, SOLID);
+        return this;
+    }
+    /** Dashed segment outline: the arc plus the chord. */
+    segment_d(center, radius, dash, options = {}) {
+        this.#segmentVariant(center, radius, options, dashed(dash));
+        return this;
+    }
+    #segmentVariant(center, radius, options, variant) {
         const r = positive(radius, "radius");
         const angles = angleRange(options);
-        this.#pushShape("segment", center, { size: [r, r], ...angles }, options);
-        return this;
+        this.#pushShape("segment", center, { size: [r, r], ...angles }, options, variant);
     }
     /**
      * One joint instance for a path vertex. Degenerate wedges whose centre coincides with a
@@ -336,14 +623,16 @@ export class FrameDrawList2D {
             ...(dash === undefined ? {} : { dash: [dash[0], dash[1], dash[2] + distance] }),
         });
     }
-    /** Records one shape once its per-shape arguments have been validated. */
-    #pushShape(shape, center, fields, options) {
+    /** One instanced quad per shape is enough because the shader resolves the outline, and the
+     * dash variant only needs one extra per-instance pattern. */
+    #pushShape(shape, center, fields, options, variant) {
         this.#assertOpen();
         const thickness = positive(options.strokeWidth ?? DEFAULT_2D_STROKE_WIDTH, "strokeWidth");
         const rotation = finite(options.rotation ?? 0, "rotation");
         const cornerRadius = fields.cornerRadius ?? 0;
         if (cornerRadius < 0)
             throw new RangeError("cornerRadius must not be negative");
+        const dash = variant?.dash;
         this.#shapes.push({
             kind: "shape2d",
             shape,
@@ -353,7 +642,7 @@ export class FrameDrawList2D {
             vertexC: fields.vertexC ?? [0, 0],
             cornerRadius,
             thickness,
-            filled: options.fill ?? true,
+            filled: variant.filled,
             rotation,
             startAngle: fields.startAngle ?? 0,
             sweep: fields.sweep ?? 0,
@@ -361,6 +650,7 @@ export class FrameDrawList2D {
             color: color(options.color),
             space: spaceValue(options.space),
             layer: layer(options.layer),
+            ...(dash === undefined ? {} : { dash }),
         });
     }
     get points() {

package/dist/geometry-generators.d.ts

@@ -1,7 +1,9 @@
+import type { Vec2 } from "./camera-2d.js";
 import type { Vec3 } from "./frame-draw-list.js";
 import { type CircleBasis } from "./vector-math.js";
 export type Triangle = readonly [Vec3, Vec3, Vec3];
 export type Segment = readonly [Vec3, Vec3];
+export type Segment2D = readonly [Vec2, Vec2];
 export type MeshData = {
     readonly triangles: readonly Triangle[];
     readonly segments: readonly Segment[];
@@ -99,3 +101,10 @@ export declare function coneWire(radius: number, height: number, segments: numbe
  */
 export declare function cylinderWire(radius: number, halfHeight: number, segments: number, sideSegmentCount: number, center: Vec3, basis: CircleBasis): ShapeWire;
 export declare function gridLines(cells: readonly [number, number], spacing: readonly [number, number], center?: Vec3, rotation?: readonly [number, number, number], skew?: readonly [number, number], outer?: "none" | "x" | "z" | "xz"): Segment[];
+/**
+ * 2D counterpart of `gridLines`: the same cell/skew/outer contract in the XY plane.
+ *
+ * `rotation` is one anticlockwise angle around the grid centre. `outer` keeps the x-axis
+ * boundary lines (`"x"`), the y-axis ones (`"y"`), or both (`"xy"`).
+ */
+export declare function gridLines2D(cells: readonly [number, number], spacing: readonly [number, number], center?: Vec2, rotation?: number, skew?: readonly [number, number], outer?: "none" | "x" | "y" | "xy"): Segment2D[];

package/dist/geometry-generators.js

@@ -479,3 +479,39 @@ export function gridLines(cells, spacing, center = [0, 0, 0], rotation = [0, 0,
     }
     return segments;
 }
+/**
+ * 2D counterpart of `gridLines`: the same cell/skew/outer contract in the XY plane.
+ *
+ * `rotation` is one anticlockwise angle around the grid centre. `outer` keeps the x-axis
+ * boundary lines (`"x"`), the y-axis ones (`"y"`), or both (`"xy"`).
+ */
+export function gridLines2D(cells, spacing, center = [0, 0], rotation = 0, skew = [0, 0], outer = "none") {
+    const [cellX, cellY] = cells;
+    const [spacingX, spacingY] = spacing;
+    if (cellX <= 0 || cellY <= 0 || spacingX <= 0 || spacingY <= 0)
+        return [];
+    const skewTan = [Math.tan(skew[0]), Math.tan(skew[1])];
+    const dx = [spacingX, spacingX * skewTan[1]];
+    const dy = [spacingY * skewTan[0], spacingY];
+    const start = [-dx[0] * cellX * 0.5 - dy[0] * cellY * 0.5, -dx[1] * cellX * 0.5 - dy[1] * cellY * 0.5];
+    const cos = Math.cos(rotation);
+    const sin = Math.sin(rotation);
+    const place = (p) => [
+        center[0] + p[0] * cos - p[1] * sin,
+        center[1] + p[0] * sin + p[1] * cos,
+    ];
+    const plus = (a, b) => [a[0] + b[0], a[1] + b[1]];
+    const scale = (v, n) => [v[0] * n, v[1] * n];
+    const keepX = outer === "x" || outer === "xy";
+    const keepY = outer === "y" || outer === "xy";
+    const segments = [];
+    for (let yIndex = keepX ? 0 : 1; yIndex < (keepX ? cellY + 1 : cellY); yIndex++) {
+        const from = plus(start, scale(dy, yIndex));
+        segments.push([place(from), place(plus(from, scale(dx, cellX)))]);
+    }
+    for (let xIndex = keepY ? 0 : 1; xIndex < (keepY ? cellX + 1 : cellX); xIndex++) {
+        const from = plus(start, scale(dx, xIndex));
+        segments.push([place(from), place(plus(from, scale(dy, cellY)))]);
+    }
+    return segments;
+}

package/dist/gpu-debug-draw-2d.js

@@ -43,6 +43,12 @@ function sameVec2(a, b) {
 function sameColor(a, b) {
     return a[0] === b[0] && a[1] === b[1] && a[2] === b[2] && a[3] === b[3];
 }
+/** Dash patterns are optional, so both sides being absent is also a match. */
+function sameDash(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    return a[0] === b[0] && a[1] === b[1] && a[2] === b[2];
+}
 function samePoint2D(a, b) {
     return sameVec2(a.position, b.position) && sameColor(a.color, b.color) && a.size === b.size && a.sizeMode === b.sizeMode && a.round === b.round;
 }
@@ -83,6 +89,7 @@ function sameShape2D(a, b) {
         a.startAngle === b.startAngle &&
         a.sweep === b.sweep &&
         a.sides === b.sides &&
+        sameDash(a.dash, b.dash) &&
         sameColor(a.color, b.color));
 }
 /** Two-dimensional point lifted onto the near plane the projection matrix maps to. */
@@ -163,7 +170,7 @@ class SpaceBucket2D {
         this.#points = instances({ capacity: capacities.points, attributes: { point: "float32x3", color: "float32x4", size: "float32", flags: "uint32" } });
         this.#lines = instances({ capacity: capacities.lines, attributes: { start: "float32x3", end: "float32x3", color: "float32x4", colorEnd: "float32x4", width: "float32", flags: "uint32", dash: "float32x3", normal: "float32x3", joint: "uint32" } });
         this.#joints = instances({ capacity: capacities.joints, attributes: { previous: "float32x3", center: "float32x3", next: "float32x3", color: "float32x4", width: "float32", flags: "uint32", dash: "float32x3", joint: "uint32", previousNormal: "float32x3", nextNormal: "float32x3" } });
-        this.#shapes = instances({ capacity: capacities.shapes, attributes: { shape: "uint32", center: "float32x3", size: "float32x2", vertexB: "float32x2", vertexC: "float32x2", params: "float32x4", rotationRadius: "float32x2", color: "float32x4", flags: "uint32" } });
+        this.#shapes = instances({ capacity: capacities.shapes, attributes: { shape: "uint32", center: "float32x3", size: "float32x2", vertexB: "float32x2", vertexC: "float32x2", params: "float32x4", rotationRadius: "float32x2", color: "float32x4", flags: "uint32", dash: "float32x3" } });
         this.#pointBridge = instanceGeometry(gpu, this.#points, { mesh: zeroGeometry(gpu) });
         this.#lineBridge = instanceGeometry(gpu, this.#lines, { mesh: zeroGeometry(gpu) });
         this.#jointBridge = instanceGeometry(gpu, this.#joints, { mesh: jointGeometry(gpu, options.jointVertexCount) });
@@ -380,10 +387,11 @@ class SpaceBucket2D {
             rotationRadius: [command.rotation, boundingRadius(command)],
             color: command.color,
             flags: (command.filled ? 1 : 0) | (command.sides << 8),
+            dash: command.dash ?? [0, 0, 0],
         });
     }
     #addShapeId(index) {
-        const id = this.#shapes.add({ shape: 0, center: [0, 0, 0], size: [0, 0], vertexB: [0, 0], vertexC: [0, 0], params: [0, 0, 0, 0], rotationRadius: [0, 0], color: [0, 0, 0, 0], flags: 0 });
+        const id = this.#shapes.add({ shape: 0, center: [0, 0, 0], size: [0, 0], vertexB: [0, 0], vertexC: [0, 0], params: [0, 0, 0, 0], rotationRadius: [0, 0], color: [0, 0, 0, 0], flags: 0, dash: [0, 0, 0] });
         world(this.#shapes, id);
         this.#shapeIds[index] = id;
         return id;