@woosh/meep-engine 2.164.0 → 2.165.0

package/src/core/geom/2d/packing/skyline.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Bottom-left skyline rectangle packer (Jylänki's skyline-BL). The skyline is a
+ * left-to-right sequence of horizontal segments giving the free height at each
+ * column; a rectangle is placed at the lowest-then-leftmost position whose span
+ * fits, raising the skyline over its footprint. O(segments) per placement — the
+ * scalable packer for large atlases where the exact bitmap canBlit scan is too
+ * slow.
+ *
+ * Segments are packed as `(x, y, width)` uint32 triplets in a single typed
+ * array (not an array of objects) for cache locality and zero per-placement
+ * allocation: {@link place} rebuilds into a reused scratch buffer and swaps.
+ * Rectangles never overlap; simple skyline (no waste-map), so a little space is
+ * left under overhangs — fine for texture atlases.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Skyline {
+    /**
+     * @param {number} width
+     * @param {number} height
+     */
+    constructor(width: number, height: number);
+    /** Current bounds width. @type {number} */
+    width: number;
+    /** Current bounds height. @type {number} */
+    height: number;
+    /**
+     * x of the most recent successful {@link find} (valid only when `find`
+     * returned true).
+     * @type {number}
+     */
+    found_x: number;
+    /** y of the most recent successful {@link find}. @type {number} */
+    found_y: number;
+    /**
+     * Live segment count.
+     * @type {number}
+     * @private
+     */
+    private __count;
+    /**
+     * Capacity in triplets of {@link __segments} and {@link __scratch}.
+     * @type {number}
+     * @private
+     */
+    private __capacity;
+    /**
+     * Packed `(x, y, width)` triplets, x-ascending. Segment k spans columns
+     * `[x_k, x_k + width_k)` at free height `y_k`.
+     * @type {Uint32Array}
+     * @private
+     */
+    private __segments;
+    /**
+     * Scratch buffer reused by {@link place} to rebuild the segment list, then
+     * swapped with {@link __segments}.
+     * @type {Uint32Array}
+     * @private
+     */
+    private __scratch;
+    /**
+     * Grow the segment and scratch buffers to hold at least `triplets`
+     * segments, preserving the live segments.
+     * @param {number} triplets
+     * @private
+     */
+    private __ensure_capacity;
+    /**
+     * Highest segment `y` across the columns `[segments[i].x, x_right)` — the
+     * floor a rectangle would rest on if its left edge started at segment `i`.
+     * @param {number} i start segment index
+     * @param {number} x_right exclusive right edge of the span
+     * @returns {number}
+     * @private
+     */
+    private __level;
+    /**
+     * Find the lowest-then-leftmost position for a `w x h` rectangle. On success
+     * stores it in {@link found_x}/{@link found_y}. Does not mutate the skyline.
+     * @param {number} w rectangle width
+     * @param {number} h rectangle height
+     * @returns {boolean} true if it fits within the current bounds
+     */
+    find(w: number, h: number): boolean;
+    /**
+     * Append segment `(x, y, width)` to `scratch[n]`, merging into the previous
+     * scratch segment when they are adjacent at the same height.
+     * @param {Uint32Array} scratch
+     * @param {number} n current scratch segment count
+     * @param {number} x
+     * @param {number} y
+     * @param {number} width
+     * @returns {number} the new scratch segment count
+     * @private
+     */
+    private __emit;
+    /**
+     * Raise the skyline to account for a `w x h` rectangle placed at (x, y).
+     * Rebuilds the (still x-sorted) segment list into the scratch buffer — the
+     * portions of old segments left of x and right of x+w, with the new top
+     * segment between them — then swaps it in. No per-segment allocation.
+     * @param {number} x placement left edge
+     * @param {number} y placement bottom edge
+     * @param {number} w rectangle width
+     * @param {number} h rectangle height
+     */
+    place(x: number, y: number, w: number, h: number): void;
+    /**
+     * Enlarge the bounds, preserving placements. The new width starts at y=0.
+     * @param {number} width new width (>= current)
+     * @param {number} height new height (>= current)
+     */
+    grow(width: number, height: number): void;
+}
+//# sourceMappingURL=skyline.d.ts.map

package/src/core/geom/2d/packing/skyline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skyline.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/2d/packing/skyline.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH;IA6CI;;;OAGG;IACH,mBAHW,MAAM,UACN,MAAM,EAYhB;IA1DD,2CAA2C;IAC3C,OADiC,MAAM,CAC7B;IACV,4CAA4C;IAC5C,QADkC,MAAM,CAC7B;IAEX;;;;OAIG;IACH,SAFU,MAAM,CAEJ;IACZ,mEAAmE;IACnE,SADyD,MAAM,CACnD;IAEZ;;;;OAIG;IACH,gBAAY;IAEZ;;;;OAIG;IACH,mBAAgB;IAEhB;;;;;OAKG;IACH,mBAAkD;IAElD;;;;;OAKG;IACH,kBAAiD;IAkBjD;;;;;OAKG;IACH,0BAaC;IAED;;;;;;;OAOG;IACH,gBAWC;IAED;;;;;;OAMG;IACH,QAJW,MAAM,KACN,MAAM,GACJ,OAAO,CA0BnB;IAED;;;;;;;;;;OAUG;IACH,eAeC;IAED;;;;;;;;;OASG;IACH,SALW,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,QAsChB;IAED;;;;OAIG;IACH,YAHW,MAAM,UACN,MAAM,QAsBhB;CACJ"}

package/src/core/geom/2d/packing/skyline.js

@@ -0,0 +1,258 @@
+import { assert } from "../../../assert.js";
+
+/**
+ * Bottom-left skyline rectangle packer (Jylänki's skyline-BL). The skyline is a
+ * left-to-right sequence of horizontal segments giving the free height at each
+ * column; a rectangle is placed at the lowest-then-leftmost position whose span
+ * fits, raising the skyline over its footprint. O(segments) per placement — the
+ * scalable packer for large atlases where the exact bitmap canBlit scan is too
+ * slow.
+ *
+ * Segments are packed as `(x, y, width)` uint32 triplets in a single typed
+ * array (not an array of objects) for cache locality and zero per-placement
+ * allocation: {@link place} rebuilds into a reused scratch buffer and swaps.
+ * Rectangles never overlap; simple skyline (no waste-map), so a little space is
+ * left under overhangs — fine for texture atlases.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class Skyline {
+    /** Current bounds width. @type {number} */
+    width = 0;
+    /** Current bounds height. @type {number} */
+    height = 0;
+
+    /**
+     * x of the most recent successful {@link find} (valid only when `find`
+     * returned true).
+     * @type {number}
+     */
+    found_x = 0;
+    /** y of the most recent successful {@link find}. @type {number} */
+    found_y = 0;
+
+    /**
+     * Live segment count.
+     * @type {number}
+     * @private
+     */
+    __count = 1;
+
+    /**
+     * Capacity in triplets of {@link __segments} and {@link __scratch}.
+     * @type {number}
+     * @private
+     */
+    __capacity = 16;
+
+    /**
+     * Packed `(x, y, width)` triplets, x-ascending. Segment k spans columns
+     * `[x_k, x_k + width_k)` at free height `y_k`.
+     * @type {Uint32Array}
+     * @private
+     */
+    __segments = new Uint32Array(this.__capacity * 3);
+
+    /**
+     * Scratch buffer reused by {@link place} to rebuild the segment list, then
+     * swapped with {@link __segments}.
+     * @type {Uint32Array}
+     * @private
+     */
+    __scratch = new Uint32Array(this.__capacity * 3);
+
+    /**
+     * @param {number} width
+     * @param {number} height
+     */
+    constructor(width, height) {
+        assert.isNonNegativeInteger(width, "width");
+        assert.isNonNegativeInteger(height, "height");
+
+        this.width = width;
+        this.height = height;
+        this.__count = 1;
+        this.__segments[0] = 0;
+        this.__segments[1] = 0;
+        this.__segments[2] = width;
+    }
+
+    /**
+     * Grow the segment and scratch buffers to hold at least `triplets`
+     * segments, preserving the live segments.
+     * @param {number} triplets
+     * @private
+     */
+    __ensure_capacity(triplets) {
+        if (this.__capacity >= triplets) {
+            return;
+        }
+        let cap = this.__capacity;
+        while (cap < triplets) {
+            cap *= 2;
+        }
+        const grown = new Uint32Array(cap * 3);
+        grown.set(this.__segments.subarray(0, this.__count * 3));
+        this.__segments = grown;
+        this.__scratch = new Uint32Array(cap * 3);
+        this.__capacity = cap;
+    }
+
+    /**
+     * Highest segment `y` across the columns `[segments[i].x, x_right)` — the
+     * floor a rectangle would rest on if its left edge started at segment `i`.
+     * @param {number} i start segment index
+     * @param {number} x_right exclusive right edge of the span
+     * @returns {number}
+     * @private
+     */
+    __level(i, x_right) {
+        const seg = this.__segments;
+        const count = this.__count;
+        let max_y = 0;
+        for (let j = i; j < count && seg[j * 3] < x_right; j++) {
+            const y = seg[j * 3 + 1];
+            if (y > max_y) {
+                max_y = y;
+            }
+        }
+        return max_y;
+    }
+
+    /**
+     * Find the lowest-then-leftmost position for a `w x h` rectangle. On success
+     * stores it in {@link found_x}/{@link found_y}. Does not mutate the skyline.
+     * @param {number} w rectangle width
+     * @param {number} h rectangle height
+     * @returns {boolean} true if it fits within the current bounds
+     */
+    find(w, h) {
+        const seg = this.__segments;
+        const count = this.__count;
+        let best_y = Infinity;
+        let best_x = -1;
+
+        for (let i = 0; i < count; i++) {
+            const x = seg[i * 3];
+            if (x + w > this.width) {
+                break; // segments are x-ascending: nothing further right fits
+            }
+            const y = this.__level(i, x + w);
+            if (y + h <= this.height && (y < best_y || (y === best_y && x < best_x))) {
+                best_y = y;
+                best_x = x;
+            }
+        }
+
+        if (best_x === -1) {
+            return false;
+        }
+        this.found_x = best_x;
+        this.found_y = best_y;
+        return true;
+    }
+
+    /**
+     * Append segment `(x, y, width)` to `scratch[n]`, merging into the previous
+     * scratch segment when they are adjacent at the same height.
+     * @param {Uint32Array} scratch
+     * @param {number} n current scratch segment count
+     * @param {number} x
+     * @param {number} y
+     * @param {number} width
+     * @returns {number} the new scratch segment count
+     * @private
+     */
+    __emit(scratch, n, x, y, width) {
+        if (width <= 0) {
+            return n;
+        }
+        if (n > 0) {
+            const last = (n - 1) * 3;
+            if (scratch[last + 1] === y && scratch[last] + scratch[last + 2] === x) {
+                scratch[last + 2] += width;
+                return n;
+            }
+        }
+        scratch[n * 3] = x;
+        scratch[n * 3 + 1] = y;
+        scratch[n * 3 + 2] = width;
+        return n + 1;
+    }
+
+    /**
+     * Raise the skyline to account for a `w x h` rectangle placed at (x, y).
+     * Rebuilds the (still x-sorted) segment list into the scratch buffer — the
+     * portions of old segments left of x and right of x+w, with the new top
+     * segment between them — then swaps it in. No per-segment allocation.
+     * @param {number} x placement left edge
+     * @param {number} y placement bottom edge
+     * @param {number} w rectangle width
+     * @param {number} h rectangle height
+     */
+    place(x, y, w, h) {
+        // worst case: one segment straddling both edges -> 2 clips + the new top
+        this.__ensure_capacity(this.__count + 2);
+
+        const seg = this.__segments;
+        const scratch = this.__scratch;
+        const count = this.__count;
+        const top = y + h;
+        const xr = x + w;
+        let n = 0;
+
+        // portions of segments left of x (x-ascending -> emitted in order)
+        for (let i = 0; i < count; i++) {
+            const sx = seg[i * 3];
+            if (sx < x) {
+                const right = Math.min(sx + seg[i * 3 + 2], x);
+                n = this.__emit(scratch, n, sx, seg[i * 3 + 1], right - sx);
+            }
+        }
+
+        // the new top segment, in x-order between the left and right portions
+        n = this.__emit(scratch, n, x, top, w);
+
+        // portions of segments right of x+w
+        for (let i = 0; i < count; i++) {
+            const sx = seg[i * 3];
+            const send = sx + seg[i * 3 + 2];
+            if (send > xr) {
+                const left = Math.max(sx, xr);
+                n = this.__emit(scratch, n, left, seg[i * 3 + 1], send - left);
+            }
+        }
+
+        this.__segments = scratch;
+        this.__scratch = seg;
+        this.__count = n;
+    }
+
+    /**
+     * Enlarge the bounds, preserving placements. The new width starts at y=0.
+     * @param {number} width new width (>= current)
+     * @param {number} height new height (>= current)
+     */
+    grow(width, height) {
+        if (width > this.width) {
+            const last = (this.__count - 1) * 3;
+            const seg = this.__segments;
+            if (seg[last + 1] === 0 && seg[last] + seg[last + 2] === this.width) {
+                // extend the trailing floor segment in place
+                seg[last + 2] += width - this.width;
+            } else {
+                this.__ensure_capacity(this.__count + 1);
+                const k = this.__count * 3;
+                this.__segments[k] = this.width;
+                this.__segments[k + 1] = 0;
+                this.__segments[k + 2] = width - this.width;
+                this.__count++;
+            }
+            this.width = width;
+        }
+        if (height > this.height) {
+            this.height = height;
+        }
+    }
+}

package/src/core/geom/2d/triangle/tri2_rasterize_conservative.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Conservative rasterization of a 2D triangle into a bit image: every cell
+ * whose unit square overlaps the triangle is set (a superset of exact coverage),
+ * so the resulting mask never under-covers — required for packing gutters.
+ * Overlap is decided by the separating-axis test between the triangle and each
+ * candidate cell square.
+ *
+ * @param {{width:number, height:number, set:(x:number,y:number)=>void}} image
+ * @param {number} x0 @param {number} y0
+ * @param {number} x1 @param {number} y1
+ * @param {number} x2 @param {number} y2
+ */
+export function tri2_rasterize_conservative(image: {
+    width: number;
+    height: number;
+    set: (x: number, y: number) => void;
+}, x0: number, y0: number, x1: number, y1: number, x2: number, y2: number): void;
+//# sourceMappingURL=tri2_rasterize_conservative.d.ts.map

package/src/core/geom/2d/triangle/tri2_rasterize_conservative.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tri2_rasterize_conservative.d.ts","sourceRoot":"","sources":["../../../../../../src/core/geom/2d/triangle/tri2_rasterize_conservative.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH;WALkB,MAAM;YAAS,MAAM;aAAS,MAAM,KAAG,MAAM,KAAG,IAAI;OAC3D,MAAM,MAAa,MAAM,MACzB,MAAM,MAAa,MAAM,MACzB,MAAM,MAAa,MAAM,QAoBnC"}

package/src/core/geom/2d/triangle/tri2_rasterize_conservative.js

@@ -0,0 +1,86 @@
+/**
+ * Conservative rasterization of a 2D triangle into a bit image: every cell
+ * whose unit square overlaps the triangle is set (a superset of exact coverage),
+ * so the resulting mask never under-covers — required for packing gutters.
+ * Overlap is decided by the separating-axis test between the triangle and each
+ * candidate cell square.
+ *
+ * @param {{width:number, height:number, set:(x:number,y:number)=>void}} image
+ * @param {number} x0 @param {number} y0
+ * @param {number} x1 @param {number} y1
+ * @param {number} x2 @param {number} y2
+ */
+export function tri2_rasterize_conservative(image, x0, y0, x1, y1, x2, y2) {
+    let min_x = Math.floor(Math.min(x0, x1, x2));
+    let min_y = Math.floor(Math.min(y0, y1, y2));
+    let max_x = Math.ceil(Math.max(x0, x1, x2));
+    let max_y = Math.ceil(Math.max(y0, y1, y2));
+
+    if (min_x < 0) min_x = 0;
+    if (min_y < 0) min_y = 0;
+    if (max_x > image.width) max_x = image.width;
+    if (max_y > image.height) max_y = image.height;
+
+    for (let py = min_y; py < max_y; py++) {
+        for (let px = min_x; px < max_x; px++) {
+            if (tri_box_overlap(x0, y0, x1, y1, x2, y2, px, py, px + 1, py + 1)) {
+                image.set(px, py);
+            }
+        }
+    }
+}
+
+/**
+ * Separating-axis overlap test between a triangle and an axis-aligned box.
+ *
+ * @param {number} ax @param {number} ay first triangle vertex
+ * @param {number} bx @param {number} by second triangle vertex
+ * @param {number} cx @param {number} cy third triangle vertex
+ * @param {number} bminx @param {number} bminy box minimum corner
+ * @param {number} bmaxx @param {number} bmaxy box maximum corner
+ * @returns {boolean} true if the triangle and box overlap
+ */
+function tri_box_overlap(ax, ay, bx, by, cx, cy, bminx, bminy, bmaxx, bmaxy) {
+    // Box axes (x then y).
+    if (Math.max(ax, bx, cx) < bminx || Math.min(ax, bx, cx) > bmaxx) return false;
+    if (Math.max(ay, by, cy) < bminy || Math.min(ay, by, cy) > bmaxy) return false;
+
+    // Triangle edge normals.
+    if (edge_separates(ax, ay, bx, by, cx, cy, bminx, bminy, bmaxx, bmaxy)) return false;
+    if (edge_separates(bx, by, cx, cy, ax, ay, bminx, bminy, bmaxx, bmaxy)) return false;
+    if (edge_separates(cx, cy, ax, ay, bx, by, bminx, bminy, bmaxx, bmaxy)) return false;
+
+    return true;
+}
+
+/**
+ * Does the outward normal of edge (p->q) separate the box from the triangle?
+ * `r` is the triangle's third vertex (to orient the normal inward).
+ *
+ * @param {number} px @param {number} py edge start vertex
+ * @param {number} qx @param {number} qy edge end vertex
+ * @param {number} rx @param {number} ry triangle's third vertex
+ * @param {number} bminx @param {number} bminy box minimum corner
+ * @param {number} bmaxx @param {number} bmaxy box maximum corner
+ * @returns {boolean} true if this edge's axis separates the box from the triangle
+ */
+function edge_separates(px, py, qx, qy, rx, ry, bminx, bminy, bmaxx, bmaxy) {
+    const nx = -(qy - py);
+    const ny = qx - px;
+
+    // triangle interval along n
+    const dp = nx * px + ny * py;
+    const dr = nx * rx + ny * ry;
+    let tri_min, tri_max;
+    if (dp < dr) { tri_min = dp; tri_max = dr; } else { tri_min = dr; tri_max = dp; }
+
+    // box interval along n (4 corners)
+    const c0 = nx * bminx + ny * bminy;
+    const c1 = nx * bmaxx + ny * bminy;
+    const c2 = nx * bminx + ny * bmaxy;
+    const c3 = nx * bmaxx + ny * bmaxy;
+    const box_min = Math.min(c0, c1, c2, c3);
+    const box_max = Math.max(c0, c1, c2, c3);
+
+    return box_max < tri_min || box_min > tri_max;
+}