@expofp/renderer 0.0.0-experimental.cf063fc

package/dist/core/batch/BatchedMesh.js

@@ -0,0 +1,155 @@
+import { extend } from '@react-three/fiber';
+import { BatchedMesh as BatchedMeshBase, } from 'three';
+import { InstanceUniforms } from '../InstanceUniforms';
+import { openMain } from '../shader-source';
+/**
+ * Three's `BatchedMesh` with per-instance uniforms, backed by a {@link SquareDataTexture}.
+ *
+ * Ported from three.ez's batched-mesh-extensions, which supplies this as prototype patches over
+ * `BatchedMesh` rather than a subclass:
+ * {@link https://github.com/agargaro/batched-mesh-extensions/blob/master/src/core/feature/Uniforms.ts | Uniforms}
+ * and
+ * {@link https://github.com/agargaro/batched-mesh-extensions/blob/master/src/patch/PatchBatchedMeshMaterial.ts | PatchBatchedMeshMaterial}.
+ * Only the uniform feature is taken: BVH, raycasting, LOD and per-object frustum culling are left
+ * behind, since the 2D layers draw every instance and pick through their own tables.
+ *
+ * Two departures from upstream:
+ *
+ * - **Uniforms are added, not initialized once** — see {@link addUniforms} and
+ *   {@link InstanceUniforms}.
+ * - **Bounds invalidate themselves.** Every mutation that can move the mesh's extents nulls the
+ *   cached bounds, so callers cannot forget; three's frustum test recomputes a null one on demand.
+ */
+export class BatchedMeshImpl extends BatchedMeshBase {
+    /** Per-instance uniform store, shared with {@link InstancedMeshImpl}. */
+    uniforms = new InstanceUniforms();
+    /** The material whose `onBeforeCompile` is already wrapped, so it is wrapped exactly once. */
+    patchedMaterial = null;
+    /**
+     * Declares per-instance uniforms, merging with any already declared and rebuilding the backing
+     * texture (existing values carried across). See {@link InstanceUniforms.add}.
+     * @param schema - The uniforms to add.
+     */
+    addUniforms(schema) {
+        this.uniforms.add(schema, this.maxInstanceCount);
+        // The generated GLSL changed shape, so whatever was compiled against the old layout is stale.
+        if (this.patchedMaterial)
+            this.patchedMaterial.needsUpdate = true;
+    }
+    /**
+     * Reads one instance's uniform.
+     * @param id - The instance to read.
+     * @param name - The uniform's name.
+     * @param target - Receives the result; unused for a `float`, which is returned directly.
+     * @returns The value.
+     */
+    getUniformAt(id, name, target) {
+        return this.uniforms.get(id, name, target);
+    }
+    /**
+     * Writes one instance's uniform and marks its row for upload.
+     * @param id - The instance to write.
+     * @param name - The uniform's name.
+     * @param value - The value to write.
+     */
+    setUniformAt(id, name, value) {
+        this.uniforms.set(id, name, value);
+    }
+    raycast(raycaster, intersects) {
+        const before = intersects.length;
+        super.raycast(raycaster, intersects);
+        // three names the instance it hit as `batchId` and leaves `instanceId` unset — but `instanceId`
+        // is what R3F keys hover state and hit dedup by, so without this every instance in a batch shares
+        // one identity: `onPointerOut` never fires between two touching shapes, and overlapping hits in
+        // one batch collapse to a single entry. Copying it costs nothing and makes a batch's members as
+        // distinguishable to R3F as an instanced mesh's already are.
+        for (let hit = before; hit < intersects.length; hit++) {
+            intersects[hit].instanceId = intersects[hit].batchId;
+        }
+    }
+    onBeforeRender(renderer, scene, camera, geometry, material, group) {
+        super.onBeforeRender(renderer, scene, camera, geometry, material, group);
+        // Only meshes that declared uniforms touch the material or a texture; a plain shape batch that
+        // never called `addUniforms` leaves its material exactly as it found it.
+        if (!this.uniforms.texture)
+            return;
+        // Both before the program is built for this draw: the patch supplies the GLSL the compile needs,
+        // and the texture flushes whatever changed since the last frame.
+        this.patchMaterial();
+        this.uniforms.texture.update(renderer);
+    }
+    addInstance(geometryId) {
+        const instanceId = super.addInstance(geometryId);
+        this.invalidateBounds();
+        return instanceId;
+    }
+    deleteInstance(instanceId) {
+        super.deleteInstance(instanceId);
+        this.invalidateBounds();
+        return this;
+    }
+    setMatrixAt(instanceId, matrix) {
+        super.setMatrixAt(instanceId, matrix);
+        this.invalidateBounds();
+        return this;
+    }
+    setInstanceCount(maxInstanceCount) {
+        super.setInstanceCount(maxInstanceCount);
+        // The uniform texture is sized per instance, so it has to grow with the mesh.
+        this.uniforms.resize(maxInstanceCount);
+    }
+    dispose() {
+        super.dispose();
+        this.uniforms.dispose();
+    }
+    /**
+     * Nulls the cached bounds so the next frustum test recomputes them. Kept here rather than at the
+     * call sites: every mutation that moves an instance goes through one of the overrides above.
+     */
+    invalidateBounds() {
+        this.boundingBox = null;
+        this.boundingSphere = null;
+    }
+    /**
+     * Wraps the current material's `onBeforeCompile` so compiled programs can read the uniform
+     * texture, once per material.
+     *
+     * Deferred to render time rather than done when uniforms are declared, because the material is
+     * usually attached after the mesh is constructed — R3F mounts it as a child element.
+     */
+    patchMaterial() {
+        const material = this.material;
+        if (Array.isArray(material) || material === this.patchedMaterial)
+            return;
+        // The shader identifier for the name of the index.
+        const batchIndex = 'batchIndex';
+        // GLSL declaring the per-instance index from three's batching. `getIndirectIndex` resolves the
+        // draw to an instance; the half-pixel offset keeps `int()` truncation on the right side of the
+        // boundary, because the varying carrying the index is interpolated rather than flat
+        // (see SquareDataTexture), so a value arriving a hair below its integer would otherwise
+        // truncate to the previous instance.
+        const batchIndexGlsl = /* glsl */ `float ${batchIndex} = getIndirectIndex( gl_DrawID ) + 0.5;`;
+        this.patchedMaterial = material;
+        const onBeforeCompileBase = material.onBeforeCompile.bind(material);
+        // three caches a compiled program under this key alone and compares no source. The prologue
+        // below changes the GLSL, and the schema decides how, so both have to reach the key. Without
+        // it, two batches whose schemas differ share one program and the second draws against the
+        // first's layout. Bound rather than saved raw, because this patch is one-shot and never undone.
+        const cacheKeyBase = material.customProgramCacheKey.bind(material);
+        material.customProgramCacheKey = () => `efpBatched_${this.uniforms.shaderKey}_${cacheKeyBase()}`;
+        material.onBeforeCompile = (shader, renderer) => {
+            if (this.uniforms.patchShader(shader, batchIndex)) {
+                // Declares the index the prologue just injected reads. Written after it precisely so it runs
+                // before it — see `openMain`.
+                shader.vertexShader = openMain(shader.vertexShader, batchIndexGlsl);
+            }
+            onBeforeCompileBase(shader, renderer);
+        };
+        material.needsUpdate = true;
+    }
+}
+/**
+ * Registers the class as an R3F element, by value so the generated key cannot collide with the
+ * `BatchedMesh` three already puts in the catalog when the canvas mounts.
+ */
+export const BatchedMesh = extend(BatchedMeshImpl);

package/dist/core/instanced/FrustumCulling.d.ts

@@ -0,0 +1,141 @@
+import { type Camera, type Material, type Mesh, Sphere } from 'three';
+import { type CustomSortFn } from './InstancedMesh';
+import { type Instances } from './Instances';
+/**
+ * The instances to draw, in draw order. Reused across frames, so read it before the next pass rather
+ * than holding on to it.
+ */
+export interface DrawList {
+    /** The instance each `gl_InstanceID` reads; only the first {@link count} entries are meaningful. */
+    ids: Float32Array;
+    /** How many entries the last pass wrote. */
+    count: number;
+}
+/**
+ * What {@link FrustumCulling} reads off the mesh it culls, beyond the `matrixWorld` every mesh has,
+ * which the camera and frustum are brought into.
+ */
+export interface CullingHost extends Mesh {
+    /** Orders the render list, or `null` to sort by depth. */
+    customSort: CustomSortFn | null;
+    /** Whether each instance is frustum-culled individually. */
+    perObjectFrustumCulled: boolean;
+    /** Whether instances are depth-sorted before drawing. */
+    sortObjects: boolean;
+    /**
+     * Encloses one instance, in the mesh's own space — what the frustum tests, and what depth sorting
+     * measures from.
+     * @param id - The instance.
+     * @param target - Receives the result.
+     * @returns The bounds.
+     */
+    getBoundingSphereAt(id: number, target: Sphere): Sphere;
+}
+/**
+ * Builds the draw list for one draw: every drawable instance, culled and ordered per the host's
+ * {@link CullingHost.perObjectFrustumCulled} and {@link CullingHost.sortObjects}.
+ *
+ * Ported from three.ez's instanced-mesh `feature/FrustumCulling.ts`, with `utils/SortingUtils.ts`
+ * and `utils/InstancedRenderList.ts` folded in — the latter as a pair of module arrays rather than a
+ * class, since nothing outside this file pushes to it. BVH culling and every LOD path are dropped;
+ * `linearCulling` keeps the seam they sat beside, so porting them later is additive.
+ *
+ * Departures from upstream:
+ *
+ * - **It returns a list rather than writing the mesh's buffer.** Upstream fills the mesh's
+ *   `instanceIndex` attribute in place and flags it for upload from here. This hands back a
+ *   {@link DrawList} and leaves both the write-out and the upload to the caller, so no path can
+ *   produce a list that never reaches the GPU.
+ * - **The host encloses its own instances.** Upstream moves the geometry's bounding sphere onto each
+ *   instance's matrix, which assumes every instance is *placed* by one. A line batch is not: a
+ *   segment is placed by its two endpoints, and no matrix maps the template onto it, because the
+ *   quad is expanded after projection in screen space. Asking the host for the sphere costs the same
+ *   and holds for both.
+ * - **The count always resets** (see {@link performFrustumCulling}).
+ * - **The material is passed in** rather than read off the mesh, so a mesh drawing an array of them
+ *   orders each group by its own. Upstream reads `this.material`, which is the whole array.
+ */
+export declare class FrustumCulling {
+    /** The draw list handed back each pass, reused so a frame allocates nothing. */
+    private list;
+    /**
+     * The camera and frustum for the pass in flight, in the mesh's own space — derived once by
+     * {@link frustumCulling} and read by the gather it delegates to.
+     *
+     * Held here rather than at module scope, which is where upstream keeps them, because upstream
+     * patches culling onto the prototype and has nowhere else to put them. They are state for the
+     * length of a pass, not scratch: what makes the module-level values below safe to share between
+     * meshes is that each is filled and consumed within a single statement, and these are not.
+     */
+    private readonly frustum;
+    private readonly cameraPos;
+    private readonly forward;
+    /**
+     * Rebuilds the draw list for one draw.
+     * @param host - The mesh being drawn.
+     * @param instances - The mesh's instance allocator, which says what is live and visible.
+     * @param camera - The camera to cull and sort against.
+     * @param material - The material about to draw, which picks the default sort direction.
+     * @returns The instances to draw, in draw order.
+     */
+    performFrustumCulling(host: CullingHost, instances: Instances, camera: Camera, material: Material): DrawList;
+    /**
+     * Picks the gather-and-order path the host's flags call for.
+     * @param host - The mesh being drawn.
+     * @param instances - The mesh's instance allocator, which says what is live and visible.
+     * @param camera - The camera to cull and sort against.
+     * @param material - The material about to draw.
+     */
+    private frustumCulling;
+    /**
+     * Lists every drawable instance in id order, for the path that neither culls nor sorts.
+     * @param instances - The mesh's instance allocator, which says what is live and visible.
+     */
+    private updateIndexArray;
+    /**
+     * Measures every drawable instance into the sort list, for the path that sorts without culling.
+     * @param host - The mesh being drawn.
+     * @param instances - The mesh's instance allocator, which says what is live and visible.
+     * @param camera - The camera being culled against, which {@link instanceSphere} may measure from.
+     */
+    private updateRenderList;
+    /**
+     * Frustum-tests every drawable instance one at a time, listing or measuring the survivors.
+     * @param host - The mesh being drawn.
+     * @param instances - The mesh's instance allocator, which says what is live and visible.
+     * @param camera - The camera being culled against, which {@link instanceSphere} may measure from.
+     */
+    private linearCulling;
+    /**
+     * What the frustum is tested against for one instance — the bounds the host encloses it with.
+     *
+     * A seam, because *what could be on screen* is not always the same question as *where the instance
+     * is*: a line is drawn as a ribbon expanded around its segment after projection, so a batch of them
+     * culls against something wider than the host's own bounds. That difference belongs to the pass —
+     * it depends on the camera, which the host's bounds do not know about — rather than to the host.
+     * @param host - The mesh being drawn.
+     * @param id - The instance.
+     * @param camera - The camera being culled against. Unused here, because the host's own bounds are
+     *   the whole answer for an instance placed by a matrix; passed because a subclass measuring what
+     *   an instance *covers* needs to know where it is being looked at from.
+     * @param target - Receives the result.
+     * @returns The bounds to test.
+     */
+    protected instanceSphere(host: CullingHost, id: number, camera: Camera, target: Sphere): Sphere;
+    /**
+     * How far along the camera's forward axis an instance sits — what the default sorts order by.
+     *
+     * Measured from the center of what encloses the instance, which is where the culled path always
+     * measured it; the non-culled path used to take the instance matrix's translation instead, so two
+     * meshes differing only in `perObjectFrustumCulled` could disagree about the order of a geometry
+     * whose origin is not its center.
+     *
+     * Reads the pass's camera basis, so it is a method: as a free function it would have looked like
+     * arithmetic over its argument while depending on two module variables some earlier call had to
+     * have filled.
+     * @param sphere - The instance's bounds, in the mesh's space.
+     * @returns The depth.
+     */
+    private depthOf;
+}
+//# sourceMappingURL=FrustumCulling.d.ts.map

package/dist/core/instanced/FrustumCulling.js

@@ -0,0 +1,246 @@
+import { Frustum, Matrix4, Sphere, Vector3 } from 'three';
+/**
+ * Builds the draw list for one draw: every drawable instance, culled and ordered per the host's
+ * {@link CullingHost.perObjectFrustumCulled} and {@link CullingHost.sortObjects}.
+ *
+ * Ported from three.ez's instanced-mesh `feature/FrustumCulling.ts`, with `utils/SortingUtils.ts`
+ * and `utils/InstancedRenderList.ts` folded in — the latter as a pair of module arrays rather than a
+ * class, since nothing outside this file pushes to it. BVH culling and every LOD path are dropped;
+ * `linearCulling` keeps the seam they sat beside, so porting them later is additive.
+ *
+ * Departures from upstream:
+ *
+ * - **It returns a list rather than writing the mesh's buffer.** Upstream fills the mesh's
+ *   `instanceIndex` attribute in place and flags it for upload from here. This hands back a
+ *   {@link DrawList} and leaves both the write-out and the upload to the caller, so no path can
+ *   produce a list that never reaches the GPU.
+ * - **The host encloses its own instances.** Upstream moves the geometry's bounding sphere onto each
+ *   instance's matrix, which assumes every instance is *placed* by one. A line batch is not: a
+ *   segment is placed by its two endpoints, and no matrix maps the template onto it, because the
+ *   quad is expanded after projection in screen space. Asking the host for the sphere costs the same
+ *   and holds for both.
+ * - **The count always resets** (see {@link performFrustumCulling}).
+ * - **The material is passed in** rather than read off the mesh, so a mesh drawing an array of them
+ *   orders each group by its own. Upstream reads `this.material`, which is the whole array.
+ */
+export class FrustumCulling {
+    /** The draw list handed back each pass, reused so a frame allocates nothing. */
+    list = { ids: new Float32Array(0), count: 0 };
+    /**
+     * The camera and frustum for the pass in flight, in the mesh's own space — derived once by
+     * {@link frustumCulling} and read by the gather it delegates to.
+     *
+     * Held here rather than at module scope, which is where upstream keeps them, because upstream
+     * patches culling onto the prototype and has nowhere else to put them. They are state for the
+     * length of a pass, not scratch: what makes the module-level values below safe to share between
+     * meshes is that each is filled and consumed within a single statement, and these are not.
+     */
+    frustum = new Frustum();
+    cameraPos = new Vector3();
+    forward = new Vector3();
+    /**
+     * Rebuilds the draw list for one draw.
+     * @param host - The mesh being drawn.
+     * @param instances - The mesh's instance allocator, which says what is live and visible.
+     * @param camera - The camera to cull and sort against.
+     * @param material - The material about to draw, which picks the default sort direction.
+     * @returns The instances to draw, in draw order.
+     */
+    performFrustumCulling(host, instances, camera, material) {
+        // The list can never hold more than one entry per live instance, so capacity bounds it.
+        if (this.list.ids.length < instances.capacity)
+            this.list.ids = new Float32Array(instances.capacity);
+        // Upstream resets only when culling or sorting, which leaves a mesh whose instances were all
+        // removed drawing the previous pass's list. Resetting unconditionally is a fix, not a port.
+        this.list.count = 0;
+        if (instances.addedInstancesCount === 0)
+            return this.list;
+        this.frustumCulling(host, instances, camera, material);
+        return this.list;
+    }
+    /**
+     * Picks the gather-and-order path the host's flags call for.
+     * @param host - The mesh being drawn.
+     * @param instances - The mesh's instance allocator, which says what is live and visible.
+     * @param camera - The camera to cull and sort against.
+     * @param material - The material about to draw.
+     */
+    frustumCulling(host, instances, camera, material) {
+        const sortObjects = host.sortObjects;
+        const perObjectFrustumCulled = host.perObjectFrustumCulled;
+        // Neither culling nor ordering: the list is every drawable instance, in id order.
+        if (!perObjectFrustumCulled && !sortObjects) {
+            this.updateIndexArray(instances);
+            return;
+        }
+        // Depth is measured in the mesh's own space, so bring the camera into it once up front.
+        if (sortObjects) {
+            _invMatrixWorld.copy(host.matrixWorld).invert();
+            this.cameraPos.setFromMatrixPosition(camera.matrixWorld).applyMatrix4(_invMatrixWorld);
+            this.forward
+                .set(0, 0, -1)
+                .transformDirection(camera.matrixWorld)
+                .transformDirection(_invMatrixWorld);
+        }
+        // Gather the candidates: every drawable instance, or only those the frustum keeps.
+        if (!perObjectFrustumCulled) {
+            this.updateRenderList(host, instances, camera);
+        }
+        else {
+            _projScreenMatrix
+                .multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse)
+                .multiply(host.matrixWorld);
+            this.frustum.setFromProjectionMatrix(_projScreenMatrix);
+            this.linearCulling(host, instances, camera);
+        }
+        // Order what was gathered, then flatten it into the ids the draw reads.
+        if (sortObjects) {
+            const customSort = host.customSort;
+            const list = _renderList;
+            if (customSort === null) {
+                list.sort(material.transparent ? sortTransparent : sortOpaque);
+            }
+            else {
+                customSort(list);
+            }
+            const ids = this.list.ids;
+            const count = list.length;
+            for (let i = 0; i < count; i++) {
+                ids[i] = list[i].index;
+            }
+            this.list.count = count;
+            list.length = 0;
+        }
+    }
+    /**
+     * Lists every drawable instance in id order, for the path that neither culls nor sorts.
+     * @param instances - The mesh's instance allocator, which says what is live and visible.
+     */
+    updateIndexArray(instances) {
+        const ids = this.list.ids;
+        const addedInstancesCount = instances.addedInstancesCount;
+        let count = 0;
+        for (let i = 0; i < addedInstancesCount; i++) {
+            if (instances.getVisibleAt(i)) {
+                ids[count++] = i;
+            }
+        }
+        this.list.count = count;
+    }
+    /**
+     * Measures every drawable instance into the sort list, for the path that sorts without culling.
+     * @param host - The mesh being drawn.
+     * @param instances - The mesh's instance allocator, which says what is live and visible.
+     * @param camera - The camera being culled against, which {@link instanceSphere} may measure from.
+     */
+    updateRenderList(host, instances, camera) {
+        const addedInstancesCount = instances.addedInstancesCount;
+        for (let i = 0; i < addedInstancesCount; i++) {
+            if (instances.getVisibleAt(i)) {
+                pushRenderItem(this.depthOf(this.instanceSphere(host, i, camera, _sphere)), i);
+            }
+        }
+    }
+    /**
+     * Frustum-tests every drawable instance one at a time, listing or measuring the survivors.
+     * @param host - The mesh being drawn.
+     * @param instances - The mesh's instance allocator, which says what is live and visible.
+     * @param camera - The camera being culled against, which {@link instanceSphere} may measure from.
+     */
+    linearCulling(host, instances, camera) {
+        const ids = this.list.ids;
+        const addedInstancesCount = instances.addedInstancesCount;
+        const sortObjects = host.sortObjects;
+        let count = 0;
+        for (let i = 0; i < addedInstancesCount; i++) {
+            if (!instances.getVisibleAt(i))
+                continue;
+            // What the frustum sees of this instance is whatever encloses it.
+            const sphere = this.instanceSphere(host, i, camera, _sphere);
+            if (this.frustum.intersectsSphere(sphere)) {
+                if (sortObjects) {
+                    pushRenderItem(this.depthOf(sphere), i);
+                }
+                else {
+                    ids[count++] = i;
+                }
+            }
+        }
+        // Only the unordered path finished the list here; the ordered one hands off to the sort.
+        if (!sortObjects)
+            this.list.count = count;
+    }
+    /**
+     * What the frustum is tested against for one instance — the bounds the host encloses it with.
+     *
+     * A seam, because *what could be on screen* is not always the same question as *where the instance
+     * is*: a line is drawn as a ribbon expanded around its segment after projection, so a batch of them
+     * culls against something wider than the host's own bounds. That difference belongs to the pass —
+     * it depends on the camera, which the host's bounds do not know about — rather than to the host.
+     * @param host - The mesh being drawn.
+     * @param id - The instance.
+     * @param camera - The camera being culled against. Unused here, because the host's own bounds are
+     *   the whole answer for an instance placed by a matrix; passed because a subclass measuring what
+     *   an instance *covers* needs to know where it is being looked at from.
+     * @param target - Receives the result.
+     * @returns The bounds to test.
+     */
+    instanceSphere(host, id, camera, target) {
+        return host.getBoundingSphereAt(id, target);
+    }
+    /**
+     * How far along the camera's forward axis an instance sits — what the default sorts order by.
+     *
+     * Measured from the center of what encloses the instance, which is where the culled path always
+     * measured it; the non-culled path used to take the instance matrix's translation instead, so two
+     * meshes differing only in `perObjectFrustumCulled` could disagree about the order of a geometry
+     * whose origin is not its center.
+     *
+     * Reads the pass's camera basis, so it is a method: as a free function it would have looked like
+     * arithmetic over its argument while depending on two module variables some earlier call had to
+     * have filled.
+     * @param sphere - The instance's bounds, in the mesh's space.
+     * @returns The depth.
+     */
+    depthOf(sphere) {
+        return _position.subVectors(sphere.center, this.cameraPos).dot(this.forward);
+    }
+}
+/**
+ * Adds an entry to the sort list, writing through the pooled object that sits at that position.
+ *
+ * The two arrays are what make the reuse work, and are why upstream keeps both: sorting reorders
+ * {@link _renderList}, so its own instances cannot be addressed by push order afterwards, while
+ * {@link _renderPool} is never reordered and always hands back the same object for a given
+ * position. Every field is overwritten here before the entry is pushed, so whatever the last pass
+ * left in it is irrelevant.
+ * @param depth - Depth along the camera's forward axis.
+ * @param index - The instance id.
+ */
+function pushRenderItem(depth, index) {
+    const item = (_renderPool[_renderList.length] ??= { depth, index });
+    item.depth = depth;
+    item.index = index;
+    _renderList.push(item);
+}
+function sortOpaque(a, b) {
+    return a.depth - b.depth;
+}
+function sortTransparent(a, b) {
+    return b.depth - a.depth;
+}
+// Scratch shared by every mesh's culling pass. Each is filled and consumed within one statement or
+// the next, which is what makes sharing them safe — anything a pass has to keep for longer than that
+// is a field of the pass instead.
+const _projScreenMatrix = new Matrix4();
+const _invMatrixWorld = new Matrix4();
+const _position = new Vector3();
+const _sphere = new Sphere();
+/** The entries one pass collected, truncated at the end of it and re-pushed by the next. */
+const _renderList = [];
+/**
+ * Every entry ever handed out, in push order and never truncated — so a sorted pass refills objects
+ * rather than allocating one per visible instance. It settles at the most instances ever sorted at
+ * once and stays there.
+ */
+const _renderPool = [];