@expofp/renderer 3.2.4 → 3.27.0

package/dist/core/instanced/InstancedMesh.js

@@ -0,0 +1,497 @@
+import { extend } from '@react-three/fiber';
+import { Box3, Color, ColorManagement, InstancedBufferAttribute, Matrix4, Mesh, Sphere, } from 'three';
+import { InstanceUniforms } from '../InstanceUniforms';
+import { SquareDataTexture } from '../SquareDataTexture';
+import { FrustumCulling } from './FrustumCulling';
+import { patchInstancedMaterial, patchInstancedShaderChunks } from './instanced-material';
+import { Instances } from './Instances';
+import { Raycasting } from './Raycasting';
+// Prepare three's `ShaderChunk` when this module loads — once, guarded — so a mesh built later finds
+// the stock chunks it compiles against already widened.
+patchInstancedShaderChunks();
+/**
+ * A texture-backed instanced mesh: three's `InstancedMesh` regime, but with per-instance matrices,
+ * colors and uniforms held in data textures instead of vertex attributes — so instances can be
+ * added, removed, hidden, sorted and frustum-culled individually, and the buffers grow on demand.
+ *
+ * Ported from three.ez's instanced-mesh (`InstancedMesh2` and its `feature/*` and `utils/*`
+ * modules,
+ * {@link https://github.com/agargaro/instanced-mesh/tree/master/src/core | source}) as a plain
+ * subclass rather than a re-export of theirs. Only what the 2D layers use is kept: dynamic capacity,
+ * add/remove, per-instance visibility, sorting, linear per-instance frustum culling, and uniforms.
+ * BVH, LOD, skinning, morphing, and the `InstancedEntity` object layer are all dropped.
+ *
+ * Departures from upstream:
+ *
+ * - **Batched-style texture handling.** The data textures bind as ordinary shader uniforms and
+ *   flush through {@link SquareDataTexture.update}, so there is no manual texture-unit binding,
+ *   `updateTextures`/`bindTextures` split, or `PropertiesOverride` — the vendored texture already
+ *   works this way for `BatchedMeshExt`.
+ * - **The draw list is a texture, not a vertex attribute.** Upstream stamps a `uint` index attribute
+ *   onto whatever geometry it is handed; this fetches the instance id by `gl_InstanceID` from a texture of
+ *   its own, the way `BatchedMeshExt` resolves `gl_DrawID`. So the mesh never writes to a geometry it
+ *   does not own — several may draw one cached geometry — and the cull list flushes through
+ *   {@link SquareDataTexture.update} in `onBeforeRender` like every other per-instance buffer, rather
+ *   than needing an attribute that owns its GL buffer to beat three's upload in `projectObject`. It
+ *   is a float for the same reason `BatchedMesh`'s is: see {@link SquareDataTexture}.
+ * - **Merged color/opacity API.** {@link setColorAt}/{@link getColorAt} take and return
+ *   `Color | Vector4`, alpha in the fourth channel, as `BatchedMesh` does — no separate opacity
+ *   methods.
+ * - **Uniforms are added, not initialized once** ({@link addUniforms}, {@link InstanceUniforms}).
+ * - **Bounds invalidate themselves** on every mutation that can move an instance.
+ * - **No caller-supplied geometry or material.** Like `BatchedMesh`, the constructor takes only
+ *   options; it seeds a throwaway geometry and material that R3F's `<planeGeometry>` and
+ *   `<TextureMaterial>` children replace on mount.
+ *
+ * Render it with {@link InstancedMesh}.
+ */
+export class InstancedMeshExt extends Mesh {
+    /**
+     * The number of instances rendered in the last frame.
+     * @default 0
+     */
+    count = 0;
+    /** Marks this for three's instanced-draw path, which reads {@link count}. */
+    isInstancedMesh = true;
+    /** Placeholder three's instanced path dereferences; the real matrices live in a texture. */
+    instanceMatrix = new InstancedBufferAttribute(new Float32Array(0), 16);
+    /** Unused; present because three's instanced path reads it. */
+    instanceColor = null;
+    /**
+     * Unused, but must be `null`, not `undefined`: three enables its instanced-morph shader path on
+     * `isInstancedMesh && morphTexture !== null`, and an undefined field would satisfy that and emit
+     * morph GLSL that references an undeclared `MORPHTARGETS_COUNT`.
+     */
+    morphTexture = null;
+    /** Sorts the render list into draw order; assigned through the `customSort` JSX prop. */
+    customSort = null;
+    /** Whether each instance is frustum-culled individually. */
+    perObjectFrustumCulled = true;
+    /** Whether instances are depth-sorted (via {@link customSort}) before drawing. */
+    sortObjects = false;
+    /** Bounding box enclosing every instance; nulled on mutation and recomputed on demand. */
+    boundingBox = null;
+    /** Bounding sphere enclosing every instance; nulled on mutation and recomputed on demand. */
+    boundingSphere = null;
+    /**
+     * Tests the ray against individual instances. Assigned by a subclass whose instances are placed
+     * some other way, to one that knows how; see {@link Raycasting.prepareInstance}.
+     */
+    raycasting = new Raycasting();
+    /**
+     * Builds the draw list each draw. Assigned by a subclass whose instances cover more than their own
+     * bounds; see {@link FrustumCulling.instanceSphere}.
+     */
+    culling = new FrustumCulling();
+    /** Indirect rendering texture, for each `gl_InstanceID` stores indices of matrix/color/uniforms textures */
+    indexTexture;
+    /**
+     * Per-instance transforms: one `mat4` per instance (4 channels × 4 pixels), or `null` until the
+     * first {@link setMatrixAt} — a mesh whose instances are placed some other way never allocates it,
+     * and the shader reads identity in its absence.
+     */
+    matricesTexture = null;
+    /** Per-instance RGBA colors, or `null` until the first {@link setColorAt}. */
+    colorsTexture = null;
+    uniforms = new InstanceUniforms();
+    /** Which instances are live, visible and free to hand out. */
+    instances;
+    /** What the last draw culled to, or `null` before the first — what raycasting tests against. */
+    drawList = null;
+    /** Puts back what {@link patchInstancedMaterial} wrapped; null between draws. */
+    _unpatchMaterial = null;
+    constructor(params = {}) {
+        super();
+        const capacity = params.capacity && params.capacity > 0 ? params.capacity : DEFAULT_CAPACITY;
+        this.instances = new Instances(capacity, (grown) => this.resizeCapacity(grown));
+        this.indexTexture = new SquareDataTexture(Float32Array, 1, 1, capacity);
+    }
+    /**
+     * The instance capacity the textures currently hold.
+     */
+    get capacity() {
+        return this.instances.capacity;
+    }
+    /**
+     * The number of active instances.
+     */
+    get instancesCount() {
+        return this.instances.instancesCount;
+    }
+    /**
+     * 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.capacity);
+        this.materialsNeedUpdate();
+    }
+    /**
+     * Reads one instance's uniform.
+     * @param id - The index of instance to read.
+     * @param name - The uniform's name.
+     * @param target - Receives the result; unused for a `float`, 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 index of 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);
+    }
+    /**
+     * Adds `count` instances, reusing removed instances first, and reports each new id through
+     * `onCreation` so the caller can capture it. New instances start visible at the identity matrix.
+     * @param count - How many to add.
+     * @param onCreation - Called with each new instance's id.
+     * @returns `this`.
+     */
+    addInstances(count, onCreation) {
+        this.instances.addInstances(count, (id) => {
+            this.resetInstance(id);
+            onCreation?.(id);
+        });
+        return this;
+    }
+    /**
+     * Removes instances by id, freeing their instances for reuse and shrinking the iteration bound past
+     * any now-trailing inactive instances.
+     * @param ids - The instances to remove.
+     * @returns `this`.
+     */
+    removeInstances(...ids) {
+        this.instances.removeInstances(...ids);
+        this.invalidateBounds();
+        return this;
+    }
+    /**
+     * Gets the visibility of a specific instance.
+     * @param id - The index of the instance.
+     * @returns Whether it is visible.
+     */
+    getVisibleAt(id) {
+        return this.instances.getVisibleAt(id);
+    }
+    /**
+     * Sets the visibility of a specific instance.
+     * @param id - The index of the instance.
+     * @param visible - Whether it should be visible.
+     */
+    setVisibleAt(id, visible) {
+        this.instances.setVisibleAt(id, visible);
+        // The bounds still hold — a hidden instance is still live — but the draw list does not: it names
+        // what the last frame drew, and this changes that. See {@link invalidateBounds}.
+        this.drawList = null;
+    }
+    /**
+     * Reads an instance's transform. Tolerates a read before any transform was written — every
+     * instance is then untransformed, which is what the shader draws in the same state.
+     * @param id - The index of the instance.
+     * @param matrix - Target for the result.
+     * @returns The transform matrix.
+     */
+    getMatrixAt(id, matrix = _matrix) {
+        if (!this.matricesTexture)
+            return matrix.identity();
+        return matrix.fromArray(this.matricesTexture.data, id * 16);
+    }
+    /**
+     * Writes an instance's transform.
+     * @param id - The index of the instance.
+     * @param matrix - The transform matrix.
+     * @returns `this`.
+     */
+    setMatrixAt(id, matrix) {
+        if (!this.matricesTexture)
+            this.initMatricesTexture();
+        const texture = this.matricesTexture;
+        matrix.toArray(texture.data, id * 16);
+        texture.enqueueUpdate(id);
+        this.invalidateBounds();
+        return this;
+    }
+    getColorAt(id, target = _color) {
+        if (!this.colorsTexture)
+            return target.setScalar(1);
+        const data = this.colorsTexture.data;
+        return target.fromArray(data, id * 4);
+    }
+    /**
+     * Writes an instance's color, routing a `Vector4`'s alpha to the fourth channel.
+     * @param id - The instance.
+     * @param color - The color; pass a `Vector4` to also set alpha.
+     * @returns `this`.
+     */
+    setColorAt(id, color) {
+        if (!this.colorsTexture)
+            this.initColorsTexture();
+        const data = this.colorsTexture.data;
+        const colorObj = typeof color !== 'object' ? _color.set(color) : color;
+        colorObj.toArray(data, id * 4);
+        this.colorsTexture.enqueueUpdate(id);
+        return this;
+    }
+    /**
+     * Computes the bounding box that encloses all instances, and updates the `boundingBox` attribute.
+     */
+    computeBoundingBox() {
+        const count = this.instances.addedInstancesCount;
+        this.boundingBox ??= new Box3();
+        this.boundingBox.makeEmpty();
+        for (let i = 0; i < count; i++) {
+            if (!this.instances.getActiveAt(i))
+                continue;
+            this.boundingBox.union(this.getBoundingBoxAt(i, _box));
+        }
+    }
+    /**
+     * Computes the bounding sphere that encloses all instances, and updates the `boundingSphere` attribute.
+     */
+    computeBoundingSphere() {
+        const count = this.instances.addedInstancesCount;
+        this.boundingSphere ??= new Sphere();
+        this.boundingSphere.makeEmpty();
+        for (let i = 0; i < count; i++) {
+            if (!this.instances.getActiveAt(i))
+                continue;
+            this.boundingSphere.union(this.getBoundingSphereAt(i, _sphere));
+        }
+    }
+    /**
+     * Encloses one instance, in this mesh's space: the geometry's own sphere, moved onto the
+     * instance's transform.
+     *
+     * The seam frustum culling asks through, so that what encloses an instance is the mesh's business
+     * rather than something derived from a matrix every mesh is assumed to have — see
+     * {@link CullingHost}. Whole-mesh bounds go through it too, so a subclass placing its instances
+     * some other way overrides the one method and both follow.
+     * @param id - The instance.
+     * @param target - Receives the result.
+     * @returns The bounds.
+     */
+    getBoundingSphereAt(id, target) {
+        const geometry = this.geometry;
+        if (!geometry.boundingSphere)
+            geometry.computeBoundingSphere();
+        return target.copy(geometry.boundingSphere).applyMatrix4(this.getMatrixAt(id));
+    }
+    /**
+     * Encloses one instance in a box, in this mesh's space: the geometry's own, moved onto the
+     * instance's transform.
+     *
+     * The seam {@link computeBoundingBox} goes through, for the reason {@link getBoundingSphereAt} is
+     * the one culling asks through — a subclass overrides what encloses *one* instance, and every
+     * sweep over the set follows.
+     * @param id - The instance.
+     * @param target - Receives the result.
+     * @returns The bounds.
+     */
+    getBoundingBoxAt(id, target) {
+        const geometry = this.geometry;
+        if (!geometry.boundingBox)
+            geometry.computeBoundingBox();
+        return target.copy(geometry.boundingBox).applyMatrix4(this.getMatrixAt(id));
+    }
+    /** Frees the data textures, which this mesh allocated rather than three. */
+    dispose() {
+        this.dispatchEvent({ type: 'dispose' });
+        this.indexTexture.dispose();
+        this.matricesTexture?.dispose();
+        this.colorsTexture?.dispose();
+        this.uniforms.dispose();
+    }
+    /**
+     * Clears whatever an instance holds, as it is handed out.
+     *
+     * A new instance may reuse a freed id that still holds the previous tenant's state, and nothing
+     * else will clear it: `onCreation` belongs to the caller, which knows what it is about to write
+     * and not what was there before. A subclass keeping per-instance state of its own overrides this
+     * and clears that too.
+     *
+     * The matrix only when there is a matrices texture — without one every instance already reads
+     * identity, which is exactly what this would write, and writing it would allocate the texture this
+     * mesh has so far done without.
+     * @param id - The instance being handed out.
+     */
+    resetInstance(id) {
+        if (this.matricesTexture)
+            this.setMatrixAt(id, _matrix.identity());
+    }
+    /**
+     * Patches the material three is about to draw with, so the program it compiles reads this mesh's
+     * per-instance state — and hands back the undo.
+     *
+     * Applied and undone around every draw rather than once per material, because the material three
+     * hands over is not always the mesh's own: a scene's `overrideMaterial` is drawn with instead, and
+     * one left patched afterwards would carry this mesh's textures into every other object using it.
+     *
+     * The seam a subclass extends when its members need more of the shader than instancing — it wraps
+     * first, so that its own patch runs *inside* this one and finds the prologue already injected.
+     * @param material - The material about to draw.
+     * @returns Restores the material exactly as it arrived. Called once, after the draw.
+     */
+    patchMaterial(material) {
+        // A snapshot of the textures, which is enough: the patch is reapplied and undone around every
+        // draw, so nothing can swap one out between here and the compile that reads them.
+        return patchInstancedMaterial(material, {
+            indexTexture: this.indexTexture,
+            matricesTexture: this.matricesTexture,
+            colorsTexture: this.colorsTexture,
+            uniforms: this.uniforms,
+        });
+    }
+    /**
+     * Nulls the cached bounds so three's next frustum test recomputes them, and the draw list with
+     * them.
+     *
+     * The draw list describes what the **last frame** drew, and {@link raycast} tests against it — so
+     * any mutation that changes what would draw leaves it lying to the next pointer event. Nulling it
+     * falls back to sweeping every live instance, which is the honest answer until a frame rebuilds
+     * it: an instance added between a mutation and the next draw is otherwise unpickable, which reads
+     * as the pointer having left something it is still sitting on.
+     *
+     * Protected to be *called*, not overridden: a subclass places its instances its own way, so its
+     * own writes are the ones this class cannot know have moved something.
+     */
+    invalidateBounds() {
+        this.boundingBox = null;
+        this.boundingSphere = null;
+        this.drawList = null;
+    }
+    onBeforeRender(renderer, scene, camera, geometry, material, group) {
+        super.onBeforeRender(renderer, scene, camera, geometry, material, group);
+        this._unpatchMaterial = this.patchMaterial(material);
+        // Rebuild the draw list for this draw, then publish it: the ids into the texture the shader
+        // fetches by `gl_InstanceID`, the length into the count three's instanced draw reads.
+        const drawList = this.culling.performFrustumCulling(this, this.instances, camera, material);
+        this.indexTexture.data.set(drawList.ids.subarray(0, drawList.count));
+        // One mark per row the list touched; the texture merges the contiguous run into a single upload.
+        const perRow = this.indexTexture.image.width;
+        for (let i = 0; i < drawList.count; i += perRow)
+            this.indexTexture.enqueueUpdate(i);
+        this.drawList = drawList;
+        this.count = drawList.count;
+        if (this.count === 0)
+            return;
+        // Every per-instance buffer is a data texture, and each flushes what changed since the last
+        // frame — the draw list included, whose rows the write-out above just marked.
+        this.indexTexture.update(renderer);
+        this.matricesTexture?.update(renderer);
+        this.colorsTexture?.update(renderer);
+        this.uniforms.texture?.update(renderer);
+    }
+    onAfterRender(renderer, scene, camera, geometry, material, group) {
+        super.onAfterRender(renderer, scene, camera, geometry, material, group);
+        // Hands the material back exactly as it arrived. Strictly paired with the wrap above: three calls
+        // the two hooks around every draw, including the two-pass draw a transparent double-sided
+        // material takes.
+        this._unpatchMaterial?.();
+        this._unpatchMaterial = null;
+    }
+    onBeforeShadow(renderer, scene, camera, shadowCamera, geometry, depthMaterial, group) {
+        this.onBeforeRender(renderer, scene, shadowCamera, geometry, depthMaterial, group);
+    }
+    onAfterShadow(renderer, scene, camera, shadowCamera, geometry, depthMaterial, group) {
+        this.onAfterRender(renderer, scene, shadowCamera, geometry, depthMaterial, group);
+        // That pass culled to the light's frustum, which is the wrong set to raycast against.
+        this.drawList = null;
+    }
+    clone(recursive) {
+        const Constructor = this.constructor;
+        return new Constructor({ capacity: this.capacity }).copy(this, recursive);
+    }
+    copy(source, recursive) {
+        super.copy(source, recursive);
+        // `Mesh.copy` left the clone sharing the source's geometry. Sharing one is safe — nothing writes
+        // to it — but a clone is expected to be independent, so it gets its own.
+        this.geometry = source.geometry.clone();
+        this.instances.copyFrom(source.instances);
+        // The clone has not been drawn, so it has no draw list of its own yet and its `count` stays 0;
+        // its first render builds both. Until then nothing draws and raycasting falls back to sweeping
+        // every live instance. Neither is worth carrying over — three reads `count` only after
+        // `onBeforeRender`, which sets it, and nothing else here reads it at all.
+        this.drawList = null;
+        this.indexTexture = source.indexTexture.clone();
+        this.matricesTexture = source.matricesTexture ? source.matricesTexture.clone() : null;
+        this.colorsTexture = source.colorsTexture ? source.colorsTexture.clone() : null;
+        this.uniforms.copyFrom(source.uniforms);
+        if (source.boundingBox)
+            this.boundingBox = source.boundingBox.clone();
+        if (source.boundingSphere)
+            this.boundingSphere = source.boundingSphere.clone();
+        return this;
+    }
+    raycast(raycaster, intersects) {
+        this.raycasting.raycast(this, this.instances, this.drawList, raycaster, intersects);
+    }
+    /**
+     * Grows every per-instance texture to a new capacity, keeping what is written. {@link Instances} grows
+     * its own store and then calls this, so nothing here tracks capacity itself.
+     * @param newCapacity - The new capacity, always larger than the current one.
+     */
+    resizeCapacity(newCapacity) {
+        // `SquareDataTexture.resize` disposes each old GPU texture before swapping in the grown one. The
+        // draw list needs nothing carried across: culling rewrites it every frame from the live instances.
+        this.indexTexture.resize(newCapacity);
+        // The room this adds needs no identity fill, unlike the colors below: every instance handed out
+        // has its transform reset as it is created, so the only rows left zeroed are ones no instance
+        // occupies. A color is not reset there, so an instance in the new room would read the zero.
+        this.matricesTexture?.resize(newCapacity);
+        if (this.colorsTexture) {
+            // Measured before the resize, so the fill covers exactly the room it added.
+            const previousLength = this.colorsTexture.data.length;
+            this.colorsTexture.resize(newCapacity);
+            // The instances the grown room just added read opaque white, as the original allocation does.
+            this.colorsTexture.data.fill(1, previousLength);
+        }
+        this.uniforms.resize(newCapacity);
+    }
+    initMatricesTexture() {
+        this.matricesTexture = new SquareDataTexture(Float32Array, 4, 4, this.capacity);
+        // Identity into every row, because a data texture allocates zero-filled and a zero matrix
+        // collapses what it transforms to a point — so the instances added before this existed, whose
+        // reset found no texture to write into, would draw as nothing rather than as untransformed.
+        const data = this.matricesTexture.data;
+        for (let i = 0; i < data.length; i += 16) {
+            data[i] = 1;
+            data[i + 5] = 1;
+            data[i + 10] = 1;
+            data[i + 15] = 1;
+        }
+        this.materialsNeedUpdate();
+    }
+    initColorsTexture() {
+        this.colorsTexture = new SquareDataTexture(Float32Array, 4, 1, this.capacity);
+        this.colorsTexture.colorSpace = ColorManagement.workingColorSpace;
+        this.colorsTexture.data.fill(1);
+        this.materialsNeedUpdate();
+    }
+    /** Flags the material(s) for recompilation, e.g. after a texture is added. */
+    materialsNeedUpdate() {
+        const material = this.material;
+        if (Array.isArray(material)) {
+            for (const one of material)
+                one.needsUpdate = true;
+        }
+        else {
+            material.needsUpdate = true;
+        }
+    }
+}
+/**
+ * Registers the class as an R3F element, by value so the generated key cannot collide with the
+ * `InstancedMesh` three already puts in the catalog when the canvas mounts.
+ */
+export const InstancedMesh = extend(InstancedMeshExt);
+const DEFAULT_CAPACITY = 1000;
+const _matrix = new Matrix4();
+const _color = new Color();
+const _box = new Box3();
+const _sphere = new Sphere();

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

@@ -0,0 +1,119 @@
+/**
+ * The instance allocator: which instances are live, which are visible, which ids are free to hand
+ * out again, and how far the live range extends.
+ *
+ * Ported from three.ez's instanced-mesh — `feature/Instances.ts` for the lifecycle, the availability
+ * accessors from `InstancedMesh2.ts`, and `setInstancesArrayCount` from `feature/Capacity.ts`. The
+ * `InstancedEntity` object layer and the BVH bookkeeping woven through all three are dropped, so an
+ * instance is just an id.
+ *
+ * Upstream reaches these through prototype augmentation on `InstancedMesh2`; here they are a store
+ * the mesh holds, so frustum culling and raycasting can read availability without reaching into the
+ * mesh at all.
+ */
+export declare class Instances {
+    /**
+     * What each instance holds, one entry each — so its length is the capacity, and there is no second
+     * count to keep in step with it. Never sparse; see {@link InstanceState}.
+     * @see `InstancedMesh2.availabilityArray` upstream, a pair of booleans per instance. One value
+     *   cannot express "hidden and free" — which nothing wants, since the only path back to live is
+     *   {@link addInstance}, and it hands the id to a different instance.
+     */
+    private instanceStates;
+    /** Ids freed by {@link removeInstances}, handed back out newest first. */
+    private freeIds;
+    private onResize;
+    private _activeInstancesCount;
+    private _addedInstancesCount;
+    /**
+     * @param capacity - How many instances the stores start out holding.
+     * @param onResize - Grows everything the owner keeps per instance, keeping what is written.
+     *   Called only when adding would overflow what the stores hold.
+     */
+    constructor(capacity: number, onResize: (capacity: number) => void);
+    /**
+     * The number of instances the stores currently hold. Derived rather than tracked, so it cannot
+     * fall out of step with the array it describes.
+     */
+    get capacity(): number;
+    /** The number of active instances. */
+    get instancesCount(): number;
+    /**
+     * One past the highest live id — the bound every per-instance sweep iterates to. Larger than
+     * {@link instancesCount} whenever a removal left a hole, since only trailing dead instances pull
+     * it back in.
+     *
+     * **Pulled back on removal**, unlike the batched text and line classes, whose equivalent is a
+     * pure high-water mark. Both bound a sweep; only this one shrinks. It can afford to because the
+     * textures here are sized by {@link capacity} instead, which only ever grows.
+     * @see `InstancedMesh2._instancesArrayCount` upstream, which this renames: that name reads as a
+     *   count of instances, which is exactly what it is not.
+     */
+    get addedInstancesCount(): number;
+    /**
+     * Adds `count` instances, reusing removed ids first, and reports each new id through `onCreation`
+     * so the caller can capture it. New instances start active and visible.
+     * @param count - How many to add.
+     * @param onCreation - Called with each new instance's id.
+     */
+    addInstances(count: number, onCreation?: (id: number) => void): void;
+    /**
+     * Removes instances by id, freeing them for reuse.
+     * @param ids - The instances to remove.
+     */
+    removeInstances(...ids: number[]): void;
+    /**
+     * Whether an instance draws — live, and not hidden. The test every per-instance sweep applies.
+     * @param id - The index of the instance.
+     * @returns Whether it is visible.
+     * @see `InstancedMesh2.getVisibilityAt` and `getActiveAndVisibilityAt` upstream, which are one
+     *   predicate here: an instance cannot be visible without being live.
+     */
+    getVisibleAt(id: number): boolean;
+    /**
+     * Shows or hides an instance. A freed id stays freed: liveness and visibility are one value, so
+     * writing visibility here would otherwise hand a dead instance back to the draw list.
+     * @param id - The index of the instance.
+     * @param visible - Whether it should be visible.
+     */
+    setVisibleAt(id: number, visible: boolean): void;
+    /**
+     * Whether an instance is live — handed out and not yet removed, hidden or not. What the bounds
+     * sweep to, since a hidden instance still occupies space.
+     * @param id - The index of the instance.
+     * @returns Whether it is active (not deleted).
+     */
+    getActiveAt(id: number): boolean;
+    /**
+     * Adopts another store's instances, for cloning a mesh.
+     * @param source - The store to copy.
+     */
+    copyFrom(source: Instances): void;
+    /**
+     * Moves the live range's bound, growing every store when it would pass what they hold. Shrinking
+     * only moves the bound; the instances past it keep their data until something reuses them.
+     * @param count - One past the highest id the range should cover.
+     * @see `InstancedMesh2.setInstancesArrayCount` upstream, which is `@internal` there for the same
+     *   reason it is private here: only {@link addInstances} has cause to move the bound.
+     */
+    private setAddedInstancesCount;
+    /**
+     * Adds one instance at an id: marks it live and visible, then hands the id to `onCreation` so the
+     * owner can reset what it holds and the caller can fill in the rest.
+     *
+     * One write, so a reused id cannot inherit the hidden state of whatever freed it — the id now
+     * belongs to a different instance.
+     * @param id - The instance.
+     * @param onCreation - Called with the id.
+     */
+    private addInstance;
+    /**
+     * Grows this store and everything the owner keeps per instance.
+     *
+     * Upstream's `resizeBuffers` grows the availability array itself; here the owner has its buffers
+     * and this has the instances, so each grows its own.
+     * @param newCapacity - The new capacity, always larger than the current one.
+     */
+    private resize;
+}
+//# sourceMappingURL=Instances.d.ts.map