@expofp/renderer 3.44.8 → 3.45.0

package/dist/events/placement/pass.js

@@ -0,0 +1,617 @@
+import { isImageDef, isPlacementTarget } from '../../types/guards';
+import { createLogger } from '../../utils/logging';
+import { paddedBox, screenBoxOf, spriteBoxAt } from './box';
+import { overlaps, PlacementGrid } from './grid';
+/**
+ * Builds a renderer's placement pass.
+ * @returns The pass.
+ */
+export function createPlacement() {
+    const grid = new PlacementGrid(0, 0);
+    /**
+     * What each participant was last told, as `2 * pass + (placed ? 1 : 0)`, where `pass` is the pass
+     * that told it.
+     *
+     * The stamp is what lets one walk do two jobs. A pass records every participant it visits, and
+     * afterwards drops the entries it did not visit: a def that lost its `placement`, stopped being
+     * screen-space, or left the registry without {@link Placement.forget}. Defs that never
+     * participated have no entry and cost nothing here, which matters because a registry holds every
+     * booth label and dot. A `Map` rather than a `WeakMap` because it has to be iterated to sweep, and
+     * the sweep is also what frees an unmounted def. `forget` still exists because a def can
+     * unregister and re-register as the same object between passes, where a stale verdict would
+     * suppress its first report.
+     */
+    const verdicts = new Map();
+    let pass = 0;
+    /** Defs already warned about, so a flat participant says so once rather than every pass. */
+    const warned = new WeakSet();
+    /**
+     * What each clustering scope last reported, and to which layers. Keyed like the scopes, and
+     * dropped for a scope that stops clustering or stops being registered.
+     */
+    const reported = new Map();
+    return {
+        run(entries, context, onFlip, onCluster = ignoreClusters) {
+            const start = performance.now();
+            const mine = ++pass;
+            let tested = 0;
+            let flips = 0;
+            /**
+             * Stamps a participant's verdict and reports it when it flipped.
+             *
+             * One closure per pass, which at ten passes a second is nothing. Recording before reporting
+             * is what keeps a handler that mutates its def from making this pass report that def twice.
+             * @param def - The participant.
+             * @param placed - Its verdict.
+             */
+            const record = (def, placed) => {
+                const before = verdicts.get(def);
+                verdicts.set(def, 2 * mine + (placed ? 1 : 0));
+                if (before !== undefined && before % 2 === (placed ? 1 : 0))
+                    return;
+                flips++;
+                onFlip(def, placed);
+            };
+            const scopes = scopesOf(entries);
+            for (const [scopeKey, scope] of scopes) {
+                // Once per scope, never once per pass: a scope that inherited the previous one's boxes
+                // would let collision cross the boundary the scope exists to draw. Deliberately not
+                // protected against re-entry, unlike `decided` and `index` below: a nested `run` would
+                // reset this grid out from under the outer pass. Unreachable today, because the contract
+                // forbids `update()` from `onPlace`, which is the only way to start a nested pass.
+                grid.reset(context.width, context.height);
+                const clustering = scope.layers.some((layer) => layer.clustering !== undefined);
+                /**
+                 * Every verdict this scope's walk reached, in walk order. Nothing is reported until the walk
+                 * ends, because a seed placed early is hidden by a def the walk reaches later. A `Map` keeps
+                 * a key's first position when it is set again, so a revised seed still reports where the
+                 * walk first decided it.
+                 */
+                const pending = new Map();
+                /**
+                 * The defs each grid entry stands for, indexed by the entry's id: one def, or every member of
+                 * the group whose union the entry is. Filled only in a clustering scope, which is the only
+                 * one that needs to know whom a blocker stands for, and whom a marker absorbs; an entry
+                 * whose unit has joined a cluster is emptied after the walk.
+                 */
+                const placedDefs = [];
+                /** Each cluster's members, seed first, keyed by the seed's grid entry. */
+                const seeded = new Map();
+                /**
+                 * Settles one unit, a lone def or a whole group, against the grid.
+                 * @param unit - The unit's defs.
+                 * @param test - The box it asks for, or `undefined` when nothing of it could be measured
+                 *   on the grid, or it does not compete: then it is placed, and it is in no cluster.
+                 * @param store - The box it occupies once placed, inserted when `test` is clear.
+                 * @param overlap - How it competes.
+                 */
+                const settle = (unit, test, store, overlap) => {
+                    const blocker = test === undefined ? undefined : grid.blockerOf(test, overlap);
+                    if (blocker === undefined) {
+                        // An always def is drawn without competing and is not inserted, so it blocks nobody.
+                        if (test !== undefined && overlap !== 'always') {
+                            const id = grid.insert(store, overlap);
+                            if (clustering)
+                                placedDefs[id] = unit;
+                        }
+                        for (const def of unit)
+                            pending.set(def, true);
+                        return;
+                    }
+                    for (const def of unit)
+                        pending.set(def, false);
+                    // Without clustering the blocker keeps the room and the verdict it had.
+                    if (!clustering)
+                        return;
+                    let members = seeded.get(blocker);
+                    if (members === undefined) {
+                        // The blocker becomes a seed: it stays in the grid, so a later def colliding with it
+                        // joins this cluster rather than starting one, and it hides with its first joiner.
+                        members = [...placedDefs[blocker]];
+                        for (const def of members)
+                            pending.set(def, false);
+                        seeded.set(blocker, members);
+                    }
+                    for (const def of unit)
+                        members.push(def);
+                };
+                /**
+                 * The group keys this scope has already decided.
+                 *
+                 * Run-local, like `index` below, rather than closure state cleared at the top of each pass: a
+                 * `run` re-entered from an `onPlace` handler would clear a shared set mid-walk, and the outer
+                 * walk would then decide the later members of a group it had already settled. A `const` here
+                 * cannot be reached by an inner pass at all.
+                 *
+                 * Per scope rather than per pass, because a key is resolved per scope: members of one key in
+                 * two scopes are two groups, and each has to be decided in its own scope or it would never be
+                 * decided at all.
+                 *
+                 * A group is decided when the walk reaches its **first** member, which makes the first
+                 * member's position the whole group's priority. Every later member is skipped, because it
+                 * already has its verdict. Deciding at the last member instead would let a def walked between
+                 * two members take room from the first, which is not what first come, first served means.
+                 */
+                const decided = new Set();
+                /**
+                 * Every grouped participant of this scope by its key, in walk order. Built on the first
+                 * grouped def the walk reaches and not before, so a scope with no groups is walked exactly
+                 * once.
+                 */
+                let index;
+                for (const defs of scope.defs) {
+                    for (const def of defs) {
+                        const options = def.placement;
+                        if (options === undefined)
+                            continue;
+                        if (!isPlacementTarget(def)) {
+                            if (!warned.has(def)) {
+                                warned.add(def);
+                                logger.warn('placement is not supported for a flat def yet; set screenSpace to place it %O', def);
+                            }
+                            continue;
+                        }
+                        const key = options.group;
+                        if (key !== undefined) {
+                            if (decided.has(key))
+                                continue;
+                            decided.add(key);
+                            index ??= indexGroups(scope.defs);
+                            const members = index.get(key);
+                            // Only absent when a handler moved a def into this group mid-pass, after the index was
+                            // built, which the `onPlace` contract rules out.
+                            if (members === undefined)
+                                continue;
+                            tested += members.length;
+                            // A folded member's padded box is on the grid, so the padded union that contains it
+                            // is too, and needs no `intersects` of its own.
+                            const folded = unionOf(members, grid, context);
+                            settle(members, folded ? _grownUnion : undefined, _union, 'never');
+                            continue;
+                        }
+                        tested++;
+                        const overlap = options.overlap ?? 'never';
+                        const box = screenBoxOf(def, context.space, context.camera, context.pixelSize, _box);
+                        // The grown box is tested and the plain extent is stored, so a def's padding is the room
+                        // it asks of the others, and is not asked of it again by each of them. A box that did not
+                        // project, or that the grid cannot hold, is placed and competes with nobody: a failed
+                        // measurement is not a collision, and in a clustering scope a def must never be hidden
+                        // without being counted.
+                        const grown = box === undefined ? undefined : paddedBox(def, box, _grown);
+                        const test = grown !== undefined && grid.intersects(grown) ? grown : undefined;
+                        settle([def], test, _box, overlap);
+                    }
+                }
+                const next = clustering
+                    ? converge(seeded, placedDefs, grid, markerOf(scope), context, pending)
+                    : [];
+                const last = reported.get(scopeKey);
+                const changed = clustering && !sameMembers(next, last?.members ?? NO_CLUSTERS);
+                for (const [def, placed] of pending)
+                    record(def, placed);
+                // A layer told of clusters that is no longer a clustering layer here hears the empty set,
+                // or its last markers would stay on screen. Before the rest, so a caller that moved the
+                // layer's role elsewhere clears before it redraws.
+                if (last !== undefined && last.members.length > 0) {
+                    for (const [layer, options] of last.told) {
+                        if (layer.clustering === undefined || !scope.layers.includes(layer)) {
+                            onCluster(layer, [], options);
+                        }
+                    }
+                }
+                if (!clustering) {
+                    reported.delete(scopeKey);
+                    continue;
+                }
+                // An unchanged set still goes to a clustering layer that joined the scope since the last
+                // report, which has never been told it. An empty one goes to nobody new: never having been
+                // told anything is already the truth.
+                if (!changed && (last === undefined || last.members.length === 0))
+                    continue;
+                let clusters;
+                const told = [];
+                for (const layer of scope.layers) {
+                    const options = layer.clustering;
+                    if (options === undefined)
+                        continue;
+                    told.push([layer, options]);
+                    if (!changed && last.told.some(([was]) => was === layer))
+                        continue;
+                    clusters ??= next.map(clusterOf);
+                    onCluster(layer, [...clusters], options);
+                }
+                reported.set(scopeKey, { members: next, told });
+            }
+            // A scope no longer registered, because its layers' participants all left, takes its clusters
+            // with it: each layer that was told of some hears the empty set, or it would go on drawing
+            // them. Then the record goes, so that the scope reports afresh if it comes back.
+            if (reported.size > 0) {
+                for (const [key, { members, told }] of reported) {
+                    if (scopes.has(key))
+                        continue;
+                    reported.delete(key);
+                    if (members.length === 0)
+                        continue;
+                    for (const [layer, options] of told)
+                        onCluster(layer, [], options);
+                }
+            }
+            // Drop what this pass did not visit. Only a stamp older than this pass goes: a pass a handler
+            // started from inside this one has stamped its own defs newer, and those stay.
+            if (verdicts.size > tested) {
+                for (const [def, stamp] of verdicts) {
+                    if (stamp < 2 * mine)
+                        verdicts.delete(def);
+                }
+            }
+            if (flips > 0 && logger.debug.enabled) {
+                const took = (performance.now() - start).toFixed(2);
+                logger.debug(`placed ${tested} defs, ${flips} flipped, in ${took}ms`);
+            }
+        },
+        forget(def) {
+            verdicts.delete(def);
+        },
+    };
+}
+/**
+ * Buckets the registered def arrays into collision scopes, keyed on the layer's
+ * {@link LayerDef.collisionGroup} or, when it names none, on the layer itself.
+ *
+ * Keyed on the layer object, never on its `name`: two layers that happen to share a name are still
+ * two scopes. A `Map` keeps insertion order, so the scopes come out in the order their first array
+ * was registered, and each scope's arrays in registration order.
+ * @param entries - Each registered def array with the layer that registered it, in registration
+ *   order.
+ * @returns The scopes, in walk order.
+ */
+function scopesOf(entries) {
+    const scopes = new Map();
+    for (const [defs, layer] of entries) {
+        const key = layer.collisionGroup ?? layer;
+        const scope = scopes.get(key);
+        if (scope === undefined) {
+            scopes.set(key, { layers: [layer], defs: [defs] });
+            continue;
+        }
+        if (!scope.layers.includes(layer))
+            scope.layers.push(layer);
+        scope.defs.push(defs);
+    }
+    return scopes;
+}
+/**
+ * Collects every grouped participant of one scope by its key, in the walk's own order.
+ *
+ * A flat def carrying a group is left out: it is not a participant, and the main walk is where it
+ * is warned about. Rebuilt for every scope of every pass, which is what keeps it current as defs
+ * join and leave; a scope holds a handful of arrays, so the second walk is not worth a cache.
+ * @param groups - The scope's def arrays, in registration order.
+ * @returns The participants of each group, keyed by `PlacementOptions.group`.
+ */
+function indexGroups(groups) {
+    const index = new Map();
+    for (const defs of groups) {
+        for (const def of defs) {
+            const key = def.placement?.group;
+            if (key === undefined || !isPlacementTarget(def))
+                continue;
+            const members = index.get(key);
+            if (members === undefined)
+                index.set(key, [def]);
+            else
+                members.push(def);
+        }
+    }
+    return index;
+}
+/**
+ * Folds one group's boxes into one, so the group is tested and inserted as one unit.
+ *
+ * The unit's box is the **union** of its members' boxes, each grown by its own padding before the
+ * fold, so one box is tested and one box is inserted, and a group's members can never block each
+ * other or disagree. The plain extents are folded alongside into {@link _union}, and the padded
+ * ones into {@link _grownUnion}, because the grid stores what a def occupies and tests what it asks
+ * for.
+ *
+ * A member is folded only when it produced a box the grid's area covers. One that did not, and one
+ * that is `always`, is left out of the union, because a failed measurement is not a collision and
+ * an `always` member competes with nobody; both still take the unit's verdict.
+ *
+ * When nothing was folded there is nothing to test, and the unit is placed and is in no cluster,
+ * which is what a lone def that could not be measured gets. Either way a group of one behaves
+ * exactly like that def ungrouped.
+ * @param members - The group's participants, in walk order.
+ * @param grid - The pass's grid.
+ * @param context - What the camera shows this pass.
+ * @returns Whether any member was folded, so that the two scratch unions hold the unit's boxes.
+ */
+function unionOf(members, grid, context) {
+    let folded = 0;
+    for (const def of members) {
+        if ((def.placement?.overlap ?? 'never') === 'always')
+            continue;
+        const extent = screenBoxOf(def, context.space, context.camera, context.pixelSize, _box);
+        if (extent === undefined)
+            continue;
+        const grown = paddedBox(def, extent, _grown);
+        if (!grid.intersects(grown))
+            continue;
+        if (folded++ === 0) {
+            copyBox(extent, _union);
+            copyBox(grown, _grownUnion);
+            continue;
+        }
+        foldBox(extent, _union);
+        foldBox(grown, _grownUnion);
+    }
+    return folded > 0;
+}
+/**
+ * Lets each cluster's marker absorb what it overlaps, until nothing changes, and lists the clusters
+ * that remain.
+ *
+ * Runs after a clustering scope's walk and before anything is reported. Each cluster's marker box
+ * stands at the cluster's anchor, which is what the caller is handed. A placed unit whose stored
+ * box it overlaps joins the cluster, every member hidden; a cluster whose marker box it overlaps is
+ * merged into whichever of the two has the earlier seed. Either way the cluster's anchor moves, so
+ * its box is measured again and tested again; a cluster that did not change is not, since it can
+ * find nothing new. Every change removes a unit or a cluster from what is left to test, so the loop
+ * ends; members never leave.
+ *
+ * Brute force, both ways: a scope holds a few hundred participants at most, and the clusters only
+ * a fraction of that. Clusters are visited in seed order and units in grid entry order, which is
+ * walk order, so the answer depends on nothing but the registration and the camera.
+ * @param seeded - Each cluster's members, seed first, by the seed's grid entry.
+ * @param placedDefs - The defs each grid entry stands for. A seed's entry and an absorbed unit's
+ *   are emptied here.
+ * @param grid - The scope's grid, holding each placed unit's box.
+ * @param marker - The scope's declared marker, or nothing to take each cluster's first member's.
+ * @param context - What the camera shows this pass.
+ * @param pending - The scope's verdicts so far, where an absorbed unit's members are hidden.
+ * @returns The clusters' members, in seed order, each cluster's seed first and each unit whole.
+ */
+function converge(seeded, placedDefs, grid, marker, context, pending) {
+    const ids = [...seeded.keys()].sort(byId);
+    const clusters = ids.map((id) => seeded.get(id));
+    if (clusters.length === 0)
+        return clusters;
+    // A seed belongs to its cluster now, so what is left in `placedDefs` is the lone placed units.
+    for (const id of ids)
+        placedDefs[id] = undefined;
+    const boxes = [];
+    const measured = [];
+    const alive = [];
+    /**
+     * Whether a cluster can find anything new when it is next visited: it changed, or a cluster that
+     * changed now overlaps it. The lone units' boxes never move, so nothing else can give a visit
+     * work, and skipping every other cluster gives exactly the answer of re-testing all of them.
+     */
+    const dirty = [];
+    for (const members of clusters) {
+        const box = { minX: 0, minY: 0, maxX: 0, maxY: 0 };
+        boxes.push(box);
+        measured.push(markerBoxOf(members, marker, context, box) !== undefined);
+        alive.push(true);
+        dirty.push(true);
+    }
+    /**
+     * Marks a cluster whose box was just measured again, and every live cluster its box now overlaps.
+     * @param k - The cluster that changed.
+     */
+    const touch = (k) => {
+        dirty[k] = true;
+        if (!measured[k])
+            return;
+        for (let e = 0; e < clusters.length; e++) {
+            if (e !== k && alive[e] && measured[e] && overlaps(boxes[k], boxes[e]))
+                dirty[e] = true;
+        }
+    };
+    for (let changed = true; changed;) {
+        changed = false;
+        for (let c = 0; c < clusters.length; c++) {
+            if (!alive[c] || !dirty[c])
+                continue;
+            dirty[c] = false;
+            // A marker that did not project covers nothing, and nothing can be said to overlap it.
+            for (let id = 0; id < placedDefs.length && measured[c]; id++) {
+                const unit = placedDefs[id];
+                if (unit === undefined || !overlaps(boxes[c], grid.boxOf(id, _entry)))
+                    continue;
+                placedDefs[id] = undefined;
+                for (const def of unit) {
+                    pending.set(def, false);
+                    clusters[c].push(def);
+                }
+                measured[c] = markerBoxOf(clusters[c], marker, context, boxes[c]) !== undefined;
+                touch(c);
+                changed = true;
+            }
+            for (let d = 0; d < clusters.length && measured[c]; d++) {
+                if (d === c || !alive[d] || !measured[d] || !overlaps(boxes[c], boxes[d]))
+                    continue;
+                // The earlier seed stays the seed, so the merged cluster keeps its place in seed order.
+                const keep = Math.min(c, d);
+                const gone = Math.max(c, d);
+                for (const def of clusters[gone])
+                    clusters[keep].push(def);
+                alive[gone] = false;
+                measured[keep] = markerBoxOf(clusters[keep], marker, context, boxes[keep]) !== undefined;
+                touch(keep);
+                changed = true;
+                // Merged into an earlier cluster, this one is gone; the survivor is tested next sweep.
+                if (gone === c)
+                    break;
+            }
+        }
+    }
+    return clusters.filter((_, c) => alive[c]);
+}
+/**
+ * The marker a scope's clusters are drawn with: the one declared by the scope's first clustering
+ * layer, in registration order, so that one scope has one answer however many layers declare one.
+ * @param scope - The scope.
+ * @returns The declared marker, or nothing to take each cluster's first member's box.
+ */
+function markerOf(scope) {
+    return scope.layers.find((layer) => layer.clustering !== undefined)?.clustering?.marker;
+}
+/**
+ * The screen box of a cluster's marker, standing at the cluster's anchor.
+ *
+ * A declared marker gives the size and origin. Without one the box takes the size, origin and
+ * rotation of the cluster's first member, skipping an `always` member, which competes with nobody,
+ * and one with no extent, measured as the walk measures it.
+ * @param members - The cluster's members, seed first.
+ * @param marker - The scope's declared marker, if any.
+ * @param context - What the camera shows this pass.
+ * @param out - The box to write into.
+ * @returns The box, or nothing when the anchor does not project or nothing has an extent.
+ */
+function markerBoxOf(members, marker, context, out) {
+    const { x, y, elevation } = centroidOf(members, _centroid);
+    const { space, camera, pixelSize } = context;
+    if (marker !== undefined) {
+        const { width, height, origin } = marker;
+        return spriteBoxAt(x, y, elevation, width, height, origin, 0, space, camera, out);
+    }
+    if (!Number.isFinite(pixelSize) || pixelSize <= 0)
+        return undefined;
+    for (const def of members) {
+        if ((def.placement?.overlap ?? 'never') === 'always')
+            continue;
+        const { size, rotation } = def.bounds;
+        const width = size.x / pixelSize;
+        const height = size.y / pixelSize;
+        if (!(width > 0) || !(height > 0))
+            continue;
+        const origin = isImageDef(def) ? def.origin : undefined;
+        return spriteBoxAt(x, y, elevation, width, height, origin, rotation, space, camera, out);
+    }
+    return undefined;
+}
+/**
+ * Builds the cluster a pass reports from one cluster's members.
+ *
+ * The members are folded into **units** first: one per `placement.group` key, one per member
+ * carrying none. A group's members are contiguous here, because a unit joins a cluster whole, so
+ * a run of one key is one unit. A unit's anchor is its own `bounds.center`, or for a group the mean
+ * of its members'; the cluster's anchor is the mean of the units', so a group holding more defs
+ * does not pull it further. The elevation is the greatest of the members', so what stands for the
+ * cluster clears the tallest thing it covers.
+ * @param members - The cluster's members, seed first, each unit whole.
+ * @returns The cluster.
+ */
+function clusterOf(members) {
+    return centroidOf(members, { unitCount: 0, x: 0, y: 0, elevation: 0 });
+}
+/**
+ * Folds one cluster's members into its unit count, anchor and elevation, as {@link clusterOf}
+ * describes, into an object the caller owns.
+ * @param members - The cluster's members, seed first, each unit whole.
+ * @param out - Where to write the totals.
+ * @returns `out`.
+ */
+function centroidOf(members, out) {
+    let unitCount = 0;
+    let x = 0;
+    let y = 0;
+    let elevation = -Infinity;
+    for (let i = 0; i < members.length;) {
+        const key = members[i].placement?.group;
+        let sumX = 0;
+        let sumY = 0;
+        let count = 0;
+        do {
+            const { bounds } = members[i];
+            sumX += bounds.center.x;
+            sumY += bounds.center.y;
+            elevation = Math.max(elevation, bounds.elevation);
+            count++;
+            i++;
+        } while (key !== undefined && i < members.length && members[i].placement?.group === key);
+        unitCount++;
+        x += sumX / count;
+        y += sumY / count;
+    }
+    out.unitCount = unitCount;
+    out.x = x / unitCount;
+    out.y = y / unitCount;
+    out.elevation = elevation;
+    return out;
+}
+/**
+ * Whether two cluster sets hold the same members in the same order: the cluster count, then each
+ * cluster's member count, then each member's identity. Order counts, because the seed is part of
+ * the answer even where the numbers a caller is handed come out the same.
+ * @param next - This pass's clusters.
+ * @param last - The clusters last reported.
+ * @returns Whether nothing changed.
+ */
+function sameMembers(next, last) {
+    if (next.length !== last.length)
+        return false;
+    for (let c = 0; c < next.length; c++) {
+        const a = next[c];
+        const b = last[c];
+        if (a.length !== b.length)
+            return false;
+        for (let m = 0; m < a.length; m++) {
+            if (a[m] !== b[m])
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * Orders grid entry ids ascending, which is insert order, which is walk order.
+ * @param a - One id.
+ * @param b - The other.
+ * @returns Their difference.
+ */
+function byId(a, b) {
+    return a - b;
+}
+/** The `onCluster` a caller that clusters nothing passes by omitting it. */
+function ignoreClusters() {
+    // Nothing to report to.
+}
+/**
+ * Copies one box's edges into another.
+ * @param from - The box to copy.
+ * @param out - The box to write into.
+ */
+function copyBox(from, out) {
+    out.minX = from.minX;
+    out.minY = from.minY;
+    out.maxX = from.maxX;
+    out.maxY = from.maxY;
+}
+/**
+ * Grows a box to cover another.
+ * @param box - The box to cover.
+ * @param out - The running union, grown in place.
+ */
+function foldBox(box, out) {
+    out.minX = Math.min(out.minX, box.minX);
+    out.minY = Math.min(out.minY, box.minY);
+    out.maxX = Math.max(out.maxX, box.maxX);
+    out.maxY = Math.max(out.maxY, box.maxY);
+}
+const logger = createLogger('placement');
+/** The set a scope has before it ever reported one: no clusters. */
+const NO_CLUSTERS = [];
+// Scratch for the one box a pass measures at a time, and its padded twin. Each is filled and
+// consumed within one non-re-entrant pass, across all `Placement` instances, since both are module
+// scope.
+const _box = { minX: 0, minY: 0, maxX: 0, maxY: 0 };
+const _grown = { minX: 0, minY: 0, maxX: 0, maxY: 0 };
+// Scratch for a group's union: its members' plain extents and their padded boxes, folded in
+// step. Filled and consumed within one non-re-entrant pass, like the two boxes above.
+const _union = { minX: 0, minY: 0, maxX: 0, maxY: 0 };
+const _grownUnion = { minX: 0, minY: 0, maxX: 0, maxY: 0 };
+// Scratch for the merge loop after a clustering scope's walk: a placed unit's box read back from
+// the grid, and the anchor a marker box is measured around. Filled and consumed within one call.
+const _entry = { minX: 0, minY: 0, maxX: 0, maxY: 0 };
+const _centroid = { unitCount: 0, x: 0, y: 0, elevation: 0 };

package/dist/objects/images/ImageInstance.js

@@ -24,6 +24,7 @@ export const ImageInstance = memo(function ImageInstance(props) {
         const tile = tileRect(packed);
         writeImageMatrix(container, slot, def, tile);
         writeImageAnchor(container, slot, def, tile);
+        container.setOpacityAt(slot, def.opacity);
         // Checked on every sync rather than behind the write, because screenSpace is an ordinary def
         // field. Flipping it reaches this instance and stops there, so this is where a mesh learns that
         // it holds something it should not. The atlas re-filters, which never touches the packing.

package/dist/objects/images/Images.js

@@ -8,7 +8,7 @@ import { createLogger } from '../../utils/logging';
 import { defKey, useContainer } from '../containers';
 import { TextureMaterial } from '../materials/TextureMaterial';
 import { packAtlases, } from './atlas-packer';
-import { ImageContainer, UV_OFFSET_UNIFORM } from './image-container';
+import { ImageContainer, OPACITY_UNIFORM, UV_OFFSET_UNIFORM } from './image-container';
 import { ImageInstance } from './ImageInstance';
 import { contextOf, createAtlasCanvas } from './pack-sources';
 import { TextureBudgetContext, useResizeFactor } from './texture-budget';
@@ -211,7 +211,7 @@ function AtlasMesh(props) {
     // args is a frozen snapshot, so R3F never rebuilds the mesh. The ref arrow, rather than
     // ref={container.bind}, keeps the React Compiler from inferring container itself as a ref and
     // rejecting its render reads.
-    const mesh = kind === 'sprite' ? (_jsx(BatchedSprites, { args: container.args, ref: (instance) => container.bind(instance), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, renderOrder: renderOrder, children: _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM }) })) : (_jsxs(InstancedMesh, { args: container.args, ref: (instance) => container.bind(instance), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, renderOrder: renderOrder, children: [_jsx("planeGeometry", {}), _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM })] }));
+    const mesh = kind === 'sprite' ? (_jsx(BatchedSprites, { args: container.args, ref: (instance) => container.bind(instance), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, renderOrder: renderOrder, children: _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM, opacityUniform: OPACITY_UNIFORM }) })) : (_jsxs(InstancedMesh, { args: container.args, ref: (instance) => container.bind(instance), sortObjects: true, customSort: container.customSort, perObjectFrustumCulled: true, renderOrder: renderOrder, children: [_jsx("planeGeometry", {}), _jsx(TextureMaterial, { map: texture, uvOffset: UV_OFFSET_UNIFORM, opacityUniform: OPACITY_UNIFORM })] }));
     return (_jsxs(_Fragment, { children: [mesh, placements.slice(0, mounted).map((packed) => (_jsx(ImageInstance, { def: packed.def, packed: packed, container: container }, `${defKey(packed.def)}:${packed.uv.u0}:${packed.uv.v0}`)))] }));
 }
 /**

package/dist/objects/images/image-container.d.ts

@@ -10,6 +10,12 @@ import { type PackedImage } from './atlas-packer';
  * `uv * zw + xy` maps the quad's unit uv onto the region.
  */
 export declare const UV_OFFSET_UNIFORM = "uvOffset";
+/**
+ * The per-instance uniform each atlas mesh reads its opacity from. The container owns the name and
+ * hands it to the mesh's `TextureMaterial` as the `opacityUniform` prop, so the material patches its shader
+ * without knowing the name itself.
+ */
+export declare const OPACITY_UNIFORM = "instanceOpacity";
 /**
  * The constructor tuple R3F builds one atlas's mesh from, passed as `<instancedMesh args={…}>`.
  * R3F diffs `args` element-wise and rebuilds the object when any element changes, so this is
@@ -56,6 +62,12 @@ export declare class ImageContainer extends SlotContainer<PackedImage, Instanced
      * @returns Whether this container holds a sprite batch.
      */
     get facesCamera(): boolean;
+    /**
+     * Writes a def's opacity into its slot, clamped, treating an absent value as fully opaque.
+     * @param slot - The instance's slot.
+     * @param opacity - The def's opacity, or `undefined` for the default.
+     */
+    setOpacityAt(slot: number, opacity: number | undefined): void;
     protected addInstance(packed: PackedImage): number;
     protected removeInstance(slot: number): void;
 }