@expofp/renderer 3.44.8 → 3.45.0

package/dist/events/placement/grid.js

@@ -0,0 +1,235 @@
+/**
+ * Whether a def in mode `a` is allowed to cover one already placed in mode `b`.
+ *
+ * Ported from maplibre's `overlapAllowed` in `src/symbol/grid_index.ts`. With two modes the rule
+ * reduces to `a === 'always'`, and this stays as the one place it is written.
+ *
+ * The `_b` parameter is unused: an `always` entry is never inserted into the grid, so the mode of
+ * the def already there is always `never`. Re-adding a third mode brings it back.
+ * @param a - The mode of the def being tested.
+ * @param _b - The mode of the def already in the grid. Unused, see above.
+ * @returns Whether the overlap is allowed.
+ */
+export function overlapAllowed(a, _b) {
+    return a === 'always';
+}
+/**
+ * Whether two boxes overlap, by the rule {@link PlacementGrid.blockerOf} applies: edge contact is
+ * clear, so two boxes sharing a border do not overlap.
+ * @param a - One box.
+ * @param b - The other.
+ * @returns Whether they overlap.
+ */
+export function overlaps(a, b) {
+    return a.minX < b.maxX && a.maxX > b.minX && a.minY < b.maxY && a.maxY > b.minY;
+}
+/**
+ * A uniform-cell index of screen rectangles, which answers which rectangle already in it, if any,
+ * blocks a new one.
+ *
+ * Modeled on maplibre's `GridIndex`, without the circle half. Circles exist there for labels that
+ * follow a curved line, which this renderer does not draw. Entries live in flat arrays that a reset
+ * keeps at their length and refills from the front under a count cursor: setting `length = 0`
+ * instead lets V8 trim the backing store, so every pass would grow it again through its doublings.
+ * The per-cell id lists are short and are still cleared with `length = 0`, but only the cells an
+ * entry was filed under: a pass resets the grid once per collision scope, and every registered
+ * layer is a scope, most of them with no participant at all. Clearing all 1820 cells of a 1440 by
+ * 900 canvas for each of imexamerica25-3d's 21 scopes was 0.9–1.2 ms of a 1.1–1.4 ms pass.
+ *
+ * The index covers the canvas plus {@link GRID_MARGIN_PX} on every side, so a def crossing the
+ * edge of the screen decides off screen, where the churn is invisible.
+ */
+export class PlacementGrid {
+    /** Each cell's entry ids. Index is `y * xCells + x`. */
+    cells = [];
+    /** The index of every cell that holds an entry since the last reset, which is all it clears. */
+    filled = [];
+    /**
+     * Four numbers per entry: `minX`, `minY`, `maxX`, `maxY`. Only the first `count * 4` are live; the
+     * rest are the last pass's, kept so the next pass overwrites them in place.
+     */
+    boxes = [];
+    /** One mode per entry, parallel to {@link boxes} and live up to `count` in the same way. */
+    modes = [];
+    count = 0;
+    xCells = 0;
+    yCells = 0;
+    /** The canvas width the cells were built for. `-1` until the first `reset`, so it always rebuilds. */
+    width = -1;
+    /** The canvas height the cells were built for. `-1` until the first `reset`, so it always rebuilds. */
+    height = -1;
+    /**
+     * @param width - The canvas width in CSS pixels.
+     * @param height - The canvas height in CSS pixels.
+     */
+    constructor(width, height) {
+        this.reset(width, height);
+    }
+    /**
+     * Empties the index and sizes it for a canvas, which is what every pass starts with.
+     *
+     * The cell array is rebuilt only when the canvas size changed, so an unresized canvas pays only
+     * for clearing the cells the last fill used.
+     * @param width - The canvas width in CSS pixels.
+     * @param height - The canvas height in CSS pixels.
+     */
+    reset(width, height) {
+        this.count = 0;
+        for (const index of this.filled)
+            this.cells[index].length = 0;
+        this.filled.length = 0;
+        if (width !== this.width || height !== this.height) {
+            this.width = width;
+            this.height = height;
+            this.xCells = Math.max(1, Math.ceil((width + 2 * GRID_MARGIN_PX) / GRID_CELL_PX));
+            this.yCells = Math.max(1, Math.ceil((height + 2 * GRID_MARGIN_PX) / GRID_CELL_PX));
+            this.cells = [];
+            for (let i = 0; i < this.xCells * this.yCells; i++)
+                this.cells.push([]);
+        }
+    }
+    /**
+     * Whether the box intersects the indexed area, which is the canvas plus its margin. A box that
+     * only partly overlaps it passes; only one wholly outside fails.
+     *
+     * A box wholly outside it is not placed and not inserted. That is a correctness rule rather than a
+     * priority one: the index cannot hold it, so it cannot be tested against later defs either.
+     * @param box - The box to test.
+     * @returns Whether the index covers it.
+     */
+    intersects(box) {
+        return (box.maxX >= -GRID_MARGIN_PX &&
+            box.minX <= this.width + GRID_MARGIN_PX &&
+            box.maxY >= -GRID_MARGIN_PX &&
+            box.minY <= this.height + GRID_MARGIN_PX);
+    }
+    /**
+     * The earliest-inserted entry that blocks this box, or nothing when it is clear.
+     *
+     * **Earliest, not first found.** The cell walk reaches a box filed under a later cell before one
+     * filed under an earlier cell, so returning the first match would make the answer depend on cell
+     * iteration order — and the answer is load-bearing: in a clustering scope the blocker is the
+     * cluster's seed, and first come, first served means the earliest. Scanning every cell the box
+     * touches costs the early exit a boolean test could take, against a few hundred entries in a
+     * handful of cells.
+     *
+     * Edge contact does not block: two boxes sharing a border are treated as clear, so a row of
+     * abutting labels is placeable.
+     *
+     * Test {@link intersects} first: a box wholly outside the indexed area is clamped into an edge cell,
+     * which is safe only because stored coordinates are then compared exactly.
+     * @param box - The box to test.
+     * @param overlap - How the def being tested competes.
+     * @returns The blocking entry's id, as {@link insert} returned it, or `undefined` when clear.
+     */
+    blockerOf(box, overlap) {
+        if (overlap === 'always')
+            return undefined;
+        const x0 = this.cellX(box.minX);
+        const x1 = this.cellX(box.maxX);
+        const y0 = this.cellY(box.minY);
+        const y1 = this.cellY(box.maxY);
+        // Ids are assigned in insert order, so the earliest entry is the lowest id.
+        let blocker = -1;
+        for (let y = y0; y <= y1; y++) {
+            for (let x = x0; x <= x1; x++) {
+                for (const id of this.cells[y * this.xCells + x]) {
+                    if (blocker !== -1 && id >= blocker)
+                        continue;
+                    if (overlapAllowed(overlap, this.modes[id]))
+                        continue;
+                    const at = id * 4;
+                    if (box.minX < this.boxes[at + 2] &&
+                        box.maxX > this.boxes[at] &&
+                        box.minY < this.boxes[at + 3] &&
+                        box.maxY > this.boxes[at + 1]) {
+                        blocker = id;
+                    }
+                }
+            }
+        }
+        return blocker === -1 ? undefined : blocker;
+    }
+    /**
+     * Adds a box, so that later tests see it.
+     *
+     * Separate from {@link blockerOf} because asking whether a box is blocked and claiming its room are
+     * different questions: a group tests its padded union and inserts its plain one, and maplibre
+     * separates `placeCollisionBox` from `insertCollisionBox` for the same reason.
+     *
+     * Only insert a box that {@link intersects} accepted: one wholly outside the indexed area would be
+     * clamped into an edge cell, and relies on the exact comparison in {@link blockerOf} to stay
+     * harmless.
+     * @param box - The box to add.
+     * @param overlap - How the def competes.
+     * @returns The entry's id: the number of entries inserted before it since the last reset.
+     */
+    insert(box, overlap) {
+        const id = this.count++;
+        const at = id * 4;
+        this.boxes[at] = box.minX;
+        this.boxes[at + 1] = box.minY;
+        this.boxes[at + 2] = box.maxX;
+        this.boxes[at + 3] = box.maxY;
+        this.modes[id] = overlap;
+        const x0 = this.cellX(box.minX);
+        const x1 = this.cellX(box.maxX);
+        const y0 = this.cellY(box.minY);
+        const y1 = this.cellY(box.maxY);
+        for (let y = y0; y <= y1; y++) {
+            for (let x = x0; x <= x1; x++) {
+                const index = y * this.xCells + x;
+                const cell = this.cells[index];
+                if (cell.length === 0)
+                    this.filled.push(index);
+                cell.push(id);
+            }
+        }
+        return id;
+    }
+    /**
+     * Reads back the box an entry was inserted with.
+     * @param id - The entry's id, as {@link insert} returned it since the last reset.
+     * @param out - The box to write into.
+     * @returns `out`.
+     */
+    boxOf(id, out) {
+        const at = id * 4;
+        out.minX = this.boxes[at];
+        out.minY = this.boxes[at + 1];
+        out.maxX = this.boxes[at + 2];
+        out.maxY = this.boxes[at + 3];
+        return out;
+    }
+    /**
+     * Which cell column a CSS x lands in, clamped into the index.
+     * @param x - The coordinate.
+     * @returns The column.
+     */
+    cellX(x) {
+        const cell = Math.floor((x + GRID_MARGIN_PX) / GRID_CELL_PX);
+        return Math.min(Math.max(cell, 0), this.xCells - 1);
+    }
+    /**
+     * Which cell row a CSS y lands in, clamped into the index.
+     * @param y - The coordinate.
+     * @returns The row.
+     */
+    cellY(y) {
+        const cell = Math.floor((y + GRID_MARGIN_PX) / GRID_CELL_PX);
+        return Math.min(Math.max(cell, 0), this.yCells - 1);
+    }
+}
+/**
+ * How wide one cell is, in CSS pixels. More cells means fewer boxes to compare per cell, and more
+ * cells for one box to be filed under. Maplibre uses 25 against symbols a few pixels across; our
+ * pins are 32, so one pin usually touches one cell.
+ */
+export const GRID_CELL_PX = 32;
+/**
+ * How far past the canvas the index reaches, in CSS pixels.
+ *
+ * Maplibre's `viewportPadding`, for its reason: a def crossing the edge of the screen decides off
+ * screen, so the flicker that a crossing causes happens where nobody sees it.
+ */
+export const GRID_MARGIN_PX = 100;

package/dist/events/placement/index.d.ts

@@ -0,0 +1,2 @@
+export { createPlacement, type Placement, type PlacementContext } from './pass';
+//# sourceMappingURL=index.d.ts.map

package/dist/events/placement/index.js

@@ -0,0 +1 @@
+export { createPlacement } from './pass';

package/dist/events/placement/pass.d.ts

@@ -0,0 +1,70 @@
+import { type Camera } from 'three';
+import { type Space } from '../../space/Space';
+import { type Cluster, type ClusterOptions, type ImageDef, type LayerDef, type RenderableDef, type TextDef } from '../../types/defs';
+/** What one placement pass needs to know about the frame it runs for. */
+export interface PlacementContext {
+    /** The scene's space, for the projection. */
+    space: Space;
+    /** The camera in use. */
+    camera: Camera;
+    /** Plan units per CSS pixel. */
+    pixelSize: number;
+    /** The canvas width in CSS pixels. */
+    width: number;
+    /** The canvas height in CSS pixels. */
+    height: number;
+}
+/**
+ * The renderer's placement pass: which screen-space defs win room on screen, and which stand down.
+ *
+ * One object per renderer, holding the grid and the verdict each def was last given. A pass is
+ * synchronous and complete, so there is no partial index for anything to read: the cost of that is
+ * paid by running the pass at most a few times a second rather than every frame, which is the
+ * driver's business rather than this object's.
+ */
+export interface Placement {
+    /**
+     * Runs a whole pass and reports the defs whose verdict changed, and the clusters of each scope
+     * whose set changed.
+     *
+     * The registered arrays are bucketed into **collision scopes** first: one per
+     * {@link LayerDef.collisionGroup} key, and one per layer that names none. A def competes for room
+     * with the defs of its own scope and with nothing else, so each scope starts from an empty grid.
+     *
+     * Order is the argument's own iteration and nothing else: the scopes in the order their first array
+     * was registered, within a scope its arrays in registration order, and each array in the order
+     * its defs were authored. First come, first served, as maplibre does it, so a caller ranks its defs
+     * by ordering its layers and its children.
+     *
+     * A scope where any layer declares {@link LayerDef.clustering} **clusters**: a participant that
+     * collides hides together with the one it collided with, which becomes the seed of a cluster that
+     * later colliders join. A seed's verdict is therefore revised after it was decided, so nothing is
+     * reported during the walk. Once a scope's walk ends, each cluster's marker box absorbs the
+     * placed units it overlaps and merges with the clusters whose marker boxes it overlaps, until
+     * nothing changes (see {@link ClusterOptions.marker}). Only then are its flips reported, first,
+     * in walk order, and then its cluster set, to every clustering layer in it.
+     * @param entries - Each registered def array with the layer that registered it, in registration
+     *   order. The registry's own map entries, so calling this allocates nothing.
+     * @param context - What the camera shows this pass.
+     * @param onFlip - Called for each def whose verdict differs from the one it last had.
+     * @param onCluster - Called once per clustering layer of a scope whose cluster set differs from
+     *   the one last reported for it, with a fresh array each time; also with the current set for a
+     *   clustering layer that joined a scope after its last report, and with an empty array for each
+     *   layer that was told of clusters and has since left: its scope is no longer registered, the
+     *   layer is no longer in it, or it no longer declares `clustering`. The third argument is the
+     *   {@link ClusterOptions} the layer was told under, which is the one to call even where the
+     *   layer has dropped it since.
+     */
+    run(entries: Iterable<readonly [readonly RenderableDef[], LayerDef]>, context: PlacementContext, onFlip: (def: ImageDef | TextDef, placed: boolean) => void, onCluster?: (layer: LayerDef, clusters: readonly Cluster[], clustering: ClusterOptions) => void): void;
+    /**
+     * Drops a def's verdict, so that registering the same object again reports its verdict afresh.
+     * @param def - The def to forget.
+     */
+    forget(def: RenderableDef): void;
+}
+/**
+ * Builds a renderer's placement pass.
+ * @returns The pass.
+ */
+export declare function createPlacement(): Placement;
+//# sourceMappingURL=pass.d.ts.map