@expofp/renderer 0.0.0-experimental.cf063fc

package/dist/core/instanced/Instances.js

@@ -0,0 +1,230 @@
+/**
+ * What one instance's entry holds. Ordered so a free instance can never read as visible, which is
+ * what lets the draw test be one comparison against {@link InstanceState.Visible} rather than a
+ * liveness check and a visibility check that have to agree.
+ */
+var InstanceState;
+(function (InstanceState) {
+    /** Deleted, or never handed out — free to hand out again. */
+    InstanceState[InstanceState["Free"] = 0] = "Free";
+    /** Live, but not drawn. */
+    InstanceState[InstanceState["Hidden"] = 1] = "Hidden";
+    /** Live and drawn. */
+    InstanceState[InstanceState["Visible"] = 2] = "Visible";
+})(InstanceState || (InstanceState = {}));
+/**
+ * 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 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.
+     */
+    instanceStates;
+    /** Ids freed by {@link removeInstances}, handed back out newest first. */
+    freeIds = [];
+    onResize;
+    _activeInstancesCount = 0;
+    _addedInstancesCount = 0;
+    /**
+     * @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, onResize) {
+        this.onResize = onResize;
+        this.instanceStates = new Array(capacity).fill(InstanceState.Free);
+    }
+    /**
+     * 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() {
+        return this.instanceStates.length;
+    }
+    /** The number of active instances. */
+    get instancesCount() {
+        return this._activeInstancesCount;
+    }
+    /**
+     * 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() {
+        return this._addedInstancesCount;
+    }
+    /**
+     * 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, onCreation) {
+        // Refill the holes `removeInstances` left before allocating anything new.
+        const freeIds = this.freeIds;
+        if (freeIds.length > 0) {
+            let maxId = -1;
+            // Taken off the tail, so the ids freed most recently are the first ones handed back out.
+            const freeIdsUsed = Math.min(freeIds.length, count);
+            const freeIdsEnd = freeIds.length - freeIdsUsed;
+            for (let i = freeIds.length - 1; i >= freeIdsEnd; i--) {
+                const id = freeIds[i];
+                if (id > maxId)
+                    maxId = id;
+                this.addInstance(id, onCreation);
+            }
+            // Drop what was taken, and charge it against what still has to be allocated.
+            freeIds.length -= freeIdsUsed;
+            count -= freeIdsUsed;
+            // A removal may have pulled the bound in below an id just reused, so push it back out.
+            this._addedInstancesCount = Math.max(maxId + 1, this._addedInstancesCount);
+        }
+        // Whatever the free list could not cover extends the live range, growing the stores if needed.
+        const start = this._addedInstancesCount;
+        const end = start + count;
+        this.setAddedInstancesCount(end);
+        // Everything past the old bound is untouched, so it needs no reuse check.
+        for (let i = start; i < end; i++) {
+            this.addInstance(i, onCreation);
+        }
+    }
+    /**
+     * Removes instances by id, freeing them for reuse.
+     * @param ids - The instances to remove.
+     */
+    removeInstances(...ids) {
+        // Free each live id and hand it to the list. Whatever visibility it held goes with it — the
+        // id's next tenant gets a fresh one from `addInstance`.
+        const freeIds = this.freeIds;
+        for (const id of ids) {
+            // Anything already dead or past the live range is skipped, so removing twice counts once.
+            if (id < this._addedInstancesCount && this.getActiveAt(id)) {
+                this.instanceStates[id] = InstanceState.Free;
+                freeIds.push(id);
+                this._activeInstancesCount--;
+            }
+        }
+        // Pull the live range back past any instances the removal left trailing and dead, so every later
+        // sweep stops sooner. Holes below the last live id stay put for the free list to refill.
+        for (let i = this._addedInstancesCount - 1; i >= 0; i--) {
+            if (this.getActiveAt(i))
+                break;
+            this._addedInstancesCount--;
+        }
+    }
+    /**
+     * 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) {
+        return this.instanceStates[id] === InstanceState.Visible;
+    }
+    /**
+     * 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, visible) {
+        if (this.instanceStates[id] === InstanceState.Free)
+            return;
+        this.instanceStates[id] = visible ? InstanceState.Visible : InstanceState.Hidden;
+    }
+    /**
+     * 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) {
+        return this.instanceStates[id] !== InstanceState.Free;
+    }
+    /**
+     * Adopts another store's instances, for cloning a mesh.
+     * @param source - The store to copy.
+     */
+    copyFrom(source) {
+        // Capacity comes across with the array, since that is where it is read from.
+        this._activeInstancesCount = source._activeInstancesCount;
+        this._addedInstancesCount = source._addedInstancesCount;
+        this.instanceStates = source.instanceStates.slice();
+        this.freeIds.length = 0;
+        this.freeIds.push(...source.freeIds);
+    }
+    /**
+     * 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.
+     */
+    setAddedInstancesCount(count) {
+        if (count < this._addedInstancesCount) {
+            this._addedInstancesCount = count;
+            return;
+        }
+        const capacity = this.capacity;
+        if (count > capacity) {
+            // Grown geometrically, to amortize repeated additions.
+            let newCapacity = capacity + (capacity >> 1) + 512;
+            while (newCapacity < count)
+                newCapacity += (newCapacity >> 1) + 512;
+            this.resize(newCapacity);
+        }
+        this._addedInstancesCount = count;
+    }
+    /**
+     * 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.
+     */
+    addInstance(id, onCreation) {
+        this._activeInstancesCount++;
+        this.instanceStates[id] = InstanceState.Visible;
+        onCreation?.(id);
+    }
+    /**
+     * 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.
+     */
+    resize(newCapacity) {
+        // Growing the array is what raises {@link capacity}, which reads its length. Filled rather than
+        // left as holes for two reasons: `InstanceState.Free` is a value, so an unwritten entry would
+        // read as live rather than free, and a holey array falls back to a dictionary on the sweeps that
+        // read it every frame.
+        const previous = this.instanceStates.length;
+        this.instanceStates.length = newCapacity;
+        this.instanceStates.fill(InstanceState.Free, previous);
+        this.onResize(newCapacity);
+    }
+}

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

@@ -0,0 +1,118 @@
+import { type Intersection, Matrix4, Mesh, type Object3D, type Raycaster, Sphere } from 'three';
+import { type DrawList } from './FrustumCulling';
+import { type Instances } from './Instances';
+/**
+ * What {@link Raycasting} reads off the mesh it tests, beyond what every mesh already has — the
+ * `geometry` each hit is tested against, the `material` without which nothing is testable, and the
+ * `matrixWorld` each instance is placed under.
+ */
+export interface RaycastHost extends Mesh {
+    /** Bounds enclosing every instance, for the whole-batch early-out. */
+    boundingSphere: Sphere | null;
+    /** Whether each instance is frustum-culled, and so whether the draw list is worth trusting. */
+    perObjectFrustumCulled: boolean;
+    /** Fills {@link boundingSphere} when it has been invalidated. */
+    computeBoundingSphere(): void;
+    /**
+     * Reads an instance's transform.
+     * @param id - The instance.
+     * @param matrix - Target for the result.
+     * @returns The transform matrix.
+     */
+    getMatrixAt(id: number, matrix: Matrix4): Matrix4;
+}
+/**
+ * Per-instance picking: walks the instances that could be under the ray and reports a hit for each
+ * one it passes through.
+ *
+ * Ported from three.ez's instanced-mesh `feature/Raycasting.ts`. The BVH branch is dropped, so this
+ * is the linear sweep upstream falls back to.
+ *
+ * Hits are per instance *quad*: an image is picked anywhere inside its bounds, transparent pixels
+ * included, since the atlas region is sampled by the shader and not consulted here.
+ *
+ * **What a subclass changes** is {@link prepareInstance}: the scratch object one instance is tested
+ * through, and where it is placed. Everything around it — the early-out, which instances are
+ * candidates, the visibility test, and the relabeling — holds however they are placed, so a batch
+ * whose instances are not placed by a matrix inherits all of it.
+ *
+ * Departures from upstream:
+ *
+ * - **Everything stays in world space.** Upstream brings the ray into the mesh's space once instead
+ *   of lifting each instance out of it, which sounds cheaper and is not: `Mesh.raycast` inverts its
+ *   object's matrix and transforms the ray per call regardless, so the saving is one matrix multiply
+ *   per candidate against composing the instance's placement here. What it costs is real — hits come
+ *   back measured in the mesh's local units, and R3F sorts intersections from *every* object by
+ *   `distance`, so an instanced mesh under a scaled ancestor would sort against the batched meshes
+ *   as though it were nearer or further than it is. It also puts `near` and `far` in the wrong units,
+ *   which upstream compensates for by dividing them. World space needs none of that, and lets a
+ *   subclass whose per-instance test projects through the camera — a screen-space line test —
+ *   inherit this method rather than replace it.
+ * - **Hits are relabeled in place.** Upstream collects into a scratch array and copies each entry
+ *   over; this appends straight to the caller's array and rewrites the tail it added, which costs
+ *   no second array.
+ * - **The draw list is passed in, and may be absent.** Upstream reads the mesh's index attribute,
+ *   which always exists; a mesh here has no draw list until its first render, and sweeping every
+ *   live instance is the honest answer then rather than finding nothing.
+ * - **No `objectIndex > instancesArrayCount` guard.** Upstream flags it as possibly unnecessary;
+ *   it is, because both id sources here are bounded by the live range.
+ */
+export declare class Raycasting {
+    /**
+     * Whether picking considers only what the last draw left inside the frustum.
+     *
+     * Upstream defaults this off and tests every live instance. On here because picking is pointer
+     * picking, and nothing off-screen can be under the pointer. A mesh with no draw list — one that
+     * has not been drawn since it was built or cloned — falls back to the full sweep.
+     */
+    private readonly raycastOnlyFrustum;
+    /**
+     * Tests a ray against every instance that could be under it, appending a hit for each one it
+     * passes through.
+     * @param host - The mesh being picked.
+     * @param instances - The mesh's instance allocator, which says what is live and visible.
+     * @param drawList - What the last draw culled to, or `null` before the first draw.
+     * @param raycaster - The caster, which is only read.
+     * @param intersects - Receives the hits.
+     */
+    raycast(host: RaycastHost, instances: Instances, drawList: DrawList | null, raycaster: Raycaster, intersects: Intersection[]): void;
+    /**
+     * Whether the ray comes near the mesh at all — the early-out that costs one test for a batch
+     * nowhere near the pointer.
+     * @param host - The mesh being picked.
+     * @param raycaster - The caster.
+     * @returns Whether anything in the mesh can be under the ray.
+     */
+    protected intersectsMesh(host: RaycastHost, raycaster: Raycaster): boolean;
+    /**
+     * Sweeps the candidate instances.
+     * @param host - The mesh being picked.
+     * @param instances - The mesh's instance allocator, which says what is live and visible.
+     * @param drawList - What the last draw culled to, or `null`.
+     * @param raycaster - The caster.
+     * @param intersects - Receives the hits.
+     */
+    protected raycastInstances(host: RaycastHost, instances: Instances, drawList: DrawList | null, raycaster: Raycaster, intersects: Intersection[]): void;
+    /**
+     * Places the scratch object one instance is tested through, and hands it back.
+     *
+     * The seam a subclass changes, because it is the only part of a sweep that knows how an instance
+     * is placed — here, the mesh's geometry moved onto the instance's transform, and that lifted into
+     * world space, where the ray is. A batch whose instances are not placed by a matrix answers with a
+     * scratch of its own.
+     * @param host - The mesh being picked.
+     * @param objectIndex - The instance to place it as.
+     * @returns The object to cast against, standing in for that instance.
+     */
+    protected prepareInstance(host: RaycastHost, objectIndex: number): Object3D;
+    /**
+     * Tests one instance, appending whatever the ray passes through.
+     * @param host - The mesh being picked.
+     * @param instances - The mesh's instance allocator, which says what is live and visible.
+     * @param objectIndex - The instance to test.
+     * @param raycaster - The caster.
+     * @param intersects - Receives the hits.
+     */
+    private checkObjectIntersection;
+}
+//# sourceMappingURL=Raycasting.d.ts.map

package/dist/core/instanced/Raycasting.js

@@ -0,0 +1,134 @@
+import { Matrix4, Mesh, Sphere } from 'three';
+/**
+ * Per-instance picking: walks the instances that could be under the ray and reports a hit for each
+ * one it passes through.
+ *
+ * Ported from three.ez's instanced-mesh `feature/Raycasting.ts`. The BVH branch is dropped, so this
+ * is the linear sweep upstream falls back to.
+ *
+ * Hits are per instance *quad*: an image is picked anywhere inside its bounds, transparent pixels
+ * included, since the atlas region is sampled by the shader and not consulted here.
+ *
+ * **What a subclass changes** is {@link prepareInstance}: the scratch object one instance is tested
+ * through, and where it is placed. Everything around it — the early-out, which instances are
+ * candidates, the visibility test, and the relabeling — holds however they are placed, so a batch
+ * whose instances are not placed by a matrix inherits all of it.
+ *
+ * Departures from upstream:
+ *
+ * - **Everything stays in world space.** Upstream brings the ray into the mesh's space once instead
+ *   of lifting each instance out of it, which sounds cheaper and is not: `Mesh.raycast` inverts its
+ *   object's matrix and transforms the ray per call regardless, so the saving is one matrix multiply
+ *   per candidate against composing the instance's placement here. What it costs is real — hits come
+ *   back measured in the mesh's local units, and R3F sorts intersections from *every* object by
+ *   `distance`, so an instanced mesh under a scaled ancestor would sort against the batched meshes
+ *   as though it were nearer or further than it is. It also puts `near` and `far` in the wrong units,
+ *   which upstream compensates for by dividing them. World space needs none of that, and lets a
+ *   subclass whose per-instance test projects through the camera — a screen-space line test —
+ *   inherit this method rather than replace it.
+ * - **Hits are relabeled in place.** Upstream collects into a scratch array and copies each entry
+ *   over; this appends straight to the caller's array and rewrites the tail it added, which costs
+ *   no second array.
+ * - **The draw list is passed in, and may be absent.** Upstream reads the mesh's index attribute,
+ *   which always exists; a mesh here has no draw list until its first render, and sweeping every
+ *   live instance is the honest answer then rather than finding nothing.
+ * - **No `objectIndex > instancesArrayCount` guard.** Upstream flags it as possibly unnecessary;
+ *   it is, because both id sources here are bounded by the live range.
+ */
+export class Raycasting {
+    /**
+     * Whether picking considers only what the last draw left inside the frustum.
+     *
+     * Upstream defaults this off and tests every live instance. On here because picking is pointer
+     * picking, and nothing off-screen can be under the pointer. A mesh with no draw list — one that
+     * has not been drawn since it was built or cloned — falls back to the full sweep.
+     */
+    raycastOnlyFrustum = true;
+    /**
+     * Tests a ray against every instance that could be under it, appending a hit for each one it
+     * passes through.
+     * @param host - The mesh being picked.
+     * @param instances - The mesh's instance allocator, which says what is live and visible.
+     * @param drawList - What the last draw culled to, or `null` before the first draw.
+     * @param raycaster - The caster, which is only read.
+     * @param intersects - Receives the hits.
+     */
+    raycast(host, instances, drawList, raycaster, intersects) {
+        if (!host.material || instances.addedInstancesCount === 0)
+            return;
+        if (!this.intersectsMesh(host, raycaster))
+            return;
+        this.raycastInstances(host, instances, drawList, raycaster, intersects);
+    }
+    /**
+     * Whether the ray comes near the mesh at all — the early-out that costs one test for a batch
+     * nowhere near the pointer.
+     * @param host - The mesh being picked.
+     * @param raycaster - The caster.
+     * @returns Whether anything in the mesh can be under the ray.
+     */
+    intersectsMesh(host, raycaster) {
+        if (host.boundingSphere === null)
+            host.computeBoundingSphere();
+        _sphere.copy(host.boundingSphere).applyMatrix4(host.matrixWorld);
+        return raycaster.ray.intersectsSphere(_sphere);
+    }
+    /**
+     * Sweeps the candidate instances.
+     * @param host - The mesh being picked.
+     * @param instances - The mesh's instance allocator, which says what is live and visible.
+     * @param drawList - What the last draw culled to, or `null`.
+     * @param raycaster - The caster.
+     * @param intersects - Receives the hits.
+     */
+    raycastInstances(host, instances, drawList, raycaster, intersects) {
+        // Consider only what the last draw left inside the frustum, when there is such a list to read.
+        const useDrawList = this.raycastOnlyFrustum && host.perObjectFrustumCulled && drawList !== null;
+        const checkCount = useDrawList ? drawList.count : instances.addedInstancesCount;
+        for (let i = 0; i < checkCount; i++) {
+            this.checkObjectIntersection(host, instances, useDrawList ? drawList.ids[i] : i, raycaster, intersects);
+        }
+    }
+    /**
+     * Places the scratch object one instance is tested through, and hands it back.
+     *
+     * The seam a subclass changes, because it is the only part of a sweep that knows how an instance
+     * is placed — here, the mesh's geometry moved onto the instance's transform, and that lifted into
+     * world space, where the ray is. A batch whose instances are not placed by a matrix answers with a
+     * scratch of its own.
+     * @param host - The mesh being picked.
+     * @param objectIndex - The instance to place it as.
+     * @returns The object to cast against, standing in for that instance.
+     */
+    prepareInstance(host, objectIndex) {
+        // One scratch mesh stands in for every instance; only its world matrix changes between tests.
+        _mesh.geometry = host.geometry;
+        _mesh.material = host.material;
+        _mesh.matrixWorld.multiplyMatrices(host.matrixWorld, host.getMatrixAt(objectIndex, _matrix));
+        return _mesh;
+    }
+    /**
+     * Tests one instance, appending whatever the ray passes through.
+     * @param host - The mesh being picked.
+     * @param instances - The mesh's instance allocator, which says what is live and visible.
+     * @param objectIndex - The instance to test.
+     * @param raycaster - The caster.
+     * @param intersects - Receives the hits.
+     */
+    checkObjectIntersection(host, instances, objectIndex, raycaster, intersects) {
+        if (!instances.getVisibleAt(objectIndex))
+            return;
+        const before = intersects.length;
+        this.prepareInstance(host, objectIndex).raycast(raycaster, intersects);
+        // The scratch named itself as the hit object; relabel the tail it just appended so the hits
+        // point back at this batch and name the instance that produced them.
+        for (let hit = before; hit < intersects.length; hit++) {
+            intersects[hit].object = host;
+            intersects[hit].instanceId = objectIndex;
+        }
+    }
+}
+// Scratch shared by every mesh's picking pass, each filled and consumed within one synchronous call.
+const _mesh = new Mesh();
+const _matrix = new Matrix4();
+const _sphere = new Sphere();

package/dist/core/instanced/instanced-material.d.ts

@@ -0,0 +1,77 @@
+import { type Material } from 'three';
+import { type InstanceUniforms } from '../InstanceUniforms';
+import { type SquareDataTexture } from '../SquareDataTexture';
+/**
+ * Everything the shader side of instancing needs: the GLSL chunks that make texture-backed
+ * instancing draw, and the material wrap that points a compiling program at one mesh's textures.
+ *
+ * The chunks are ported from three.ez's instanced-mesh
+ * {@link https://github.com/agargaro/instanced-mesh/blob/master/src/shaders/ShaderChunk.ts | ShaderChunk}
+ * and its `chunks/*.glsl`; the wrap from `InstancedMesh2`'s `patchMaterial`, `unpatchMaterial`,
+ * `_onBeforeCompile` and `_customProgramCacheKey`, which upstream keeps as methods on the mesh.
+ * Nothing here holds state, so they are free functions — {@link patchInstancedMaterial} hands back
+ * its own undo rather than parking it on the caller.
+ *
+ * Skinning, morphing and LOD chunks are dropped. Two substantive changes.
+ *
+ * **Where the draw's instance id comes from.** Upstream reads it from a `uint` vertex attribute; here
+ * it is **fetched from a data texture by `gl_InstanceID`**, the way three's own `BatchedMesh` resolves
+ * `gl_DrawID` — so the mesh writes its cull list to a texture it owns and never touches the geometry
+ * it was handed, which is what lets several meshes draw one cached geometry.
+ *
+ * It stays a **float**, not `uint`: the per-instance uniform varyings carry no `flat` qualifier (see
+ * {@link SquareDataTexture}), and GLSL ES 3.00 forbids a non-flat integer varying — so the index that
+ * feeds those varyings has to be float too. `int( instanceIndex )` still addresses the data textures,
+ * exact for every index a Float32 can hold (2^24, far past any instance count).
+ *
+ * **How the GLSL reaches the shader.** Upstream appends its declarations to three's own
+ * `batching_pars_vertex` and `batching_vertex` chunks, which every *stock* material includes — and a
+ * material that includes neither, such as three's hand-written `LineMaterial` or a shader supplied by
+ * a glTF extension, then compiles reads of an `instanceIndex` nothing declared. Here everything but
+ * the color path is injected straight into the source around `main` (see `shader-source`), so the
+ * only thing left on three's chunks is what is genuinely a stock-material concern: the transform
+ * chunks that apply the instance matrix, and `<color_vertex>`, which is where `vColor` is seeded.
+ */
+/** The per-instance textures a patched program fetches from. */
+export interface InstancingTextures {
+    /** The draw list: the instance id each `gl_InstanceID` reads. */
+    indexTexture: SquareDataTexture;
+    /** Per-instance transforms, one `mat4` each, or `null` while none have been written. */
+    matricesTexture: SquareDataTexture | null;
+    /** Per-instance RGBA colors, or `null` while none have been written. */
+    colorsTexture: SquareDataTexture | null;
+    /** Per-instance uniforms, which generate their own GLSL. */
+    uniforms: InstanceUniforms;
+}
+/**
+ * Prepares three's global `ShaderChunk` for indirect instancing, once per process.
+ *
+ * Only what a *stock* material needs, because only a stock material has these chunks to begin with:
+ * the transform chunks that apply the instance matrix, widened to fire under the indirect define as
+ * well, and the color chunk substituted for `<color_vertex>`. Everything else an instanced draw
+ * needs is injected into the one shader being compiled — see the module docs. Nothing here changes
+ * another material's output: the widened branches are inert without `USE_INSTANCING_INDIRECT`, which
+ * only an instanced mesh sets on the material it is drawing with, and the added chunk is reached only
+ * through the substitution below.
+ */
+export declare function patchInstancedShaderChunks(): void;
+/**
+ * Wraps a material so the program it compiles reads one mesh's instancing textures.
+ *
+ * Wraps the material three handed the mesh rather than the mesh's own, because those differ: a scene
+ * with an `overrideMaterial` draws every object with that one instead, and an override that skipped
+ * the wrap would stack every instance on a single transform. Undoing it afterward is what makes
+ * wrapping a material the mesh does not own safe — three tracks whether the program it cached was
+ * built for an instanced draw and rebuilds when the next object disagrees, so the plain meshes
+ * sharing that override compile their own way.
+ *
+ * The one case this does not cover is two instanced meshes sharing a material: both are
+ * `isInstancedMesh`, so three sees nothing to disagree with and the second draws against the
+ * first's textures. Give each mesh its own material.
+ * @param material - The material about to draw.
+ * @param textures - The textures its program should fetch from, read at compile time so a texture
+ *   added later is still picked up.
+ * @returns Restores the material exactly as it arrived. Call it once, after the draw.
+ */
+export declare function patchInstancedMaterial(material: Material, textures: InstancingTextures): () => void;
+//# sourceMappingURL=instanced-material.d.ts.map