@expofp/renderer 0.0.0-experimental.2d6c681

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

@@ -0,0 +1,302 @@
+import { Box3, type BufferGeometry, type Camera, Color, type ColorRepresentation, type Group, InstancedBufferAttribute, type Intersection, type Material, Matrix4, Mesh, type Object3DEventMap, type Raycaster, type Scene, Sphere, type Vector4, type WebGLRenderer } from 'three';
+import { type UniformSchemaShader } from '../InstanceUniforms';
+import { type UniformValue, type UniformValueObj } from '../SquareDataTexture';
+import { FrustumCulling } from './FrustumCulling';
+import { Raycasting } from './Raycasting';
+/** Constructor options for {@link InstancedMeshImpl}. */
+export interface InstancedMeshImplParams {
+    /** Initial instance capacity; the buffers grow past it on demand. */
+    capacity?: number;
+}
+/** An entry in the sort list: an instance id and its depth along the view direction. */
+export interface InstancedRenderItem {
+    /** The instance id. */
+    index: number;
+    /** Depth along the camera's forward axis. */
+    depth: number;
+}
+/** A custom sorting function for render items. */
+export type CustomSortFn = (list: InstancedRenderItem[]) => void;
+/**
+ * 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 `BatchedMeshImpl`.
+ * - **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 `BatchedMeshImpl` 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 declare class InstancedMeshImpl extends Mesh<BufferGeometry, Material | Material[], Object3DEventMap & {
+    dispose: object;
+}> {
+    /**
+     * The number of instances rendered in the last frame.
+     * @default 0
+     */
+    count: number;
+    /** Marks this for three's instanced-draw path, which reads {@link count}. */
+    readonly isInstancedMesh = true;
+    /** Placeholder three's instanced path dereferences; the real matrices live in a texture. */
+    readonly instanceMatrix: InstancedBufferAttribute;
+    /** Unused; present because three's instanced path reads it. */
+    readonly 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`.
+     */
+    readonly morphTexture: null;
+    /** Sorts the render list into draw order; assigned through the `customSort` JSX prop. */
+    customSort: CustomSortFn | null;
+    /** Whether each instance is frustum-culled individually. */
+    perObjectFrustumCulled: boolean;
+    /** Whether instances are depth-sorted (via {@link customSort}) before drawing. */
+    sortObjects: boolean;
+    /** Bounding box enclosing every instance; nulled on mutation and recomputed on demand. */
+    boundingBox: Box3 | null;
+    /** Bounding sphere enclosing every instance; nulled on mutation and recomputed on demand. */
+    boundingSphere: Sphere | 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}.
+     */
+    protected raycasting: Raycasting;
+    /**
+     * Builds the draw list each draw. Assigned by a subclass whose instances cover more than their own
+     * bounds; see {@link FrustumCulling.instanceSphere}.
+     */
+    protected culling: FrustumCulling;
+    /** Indirect rendering texture, for each `gl_InstanceID` stores indices of matrix/color/uniforms textures */
+    private 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.
+     */
+    private matricesTexture;
+    /** Per-instance RGBA colors, or `null` until the first {@link setColorAt}. */
+    private colorsTexture;
+    private uniforms;
+    /** Which instances are live, visible and free to hand out. */
+    private instances;
+    /** What the last draw culled to, or `null` before the first — what raycasting tests against. */
+    private drawList;
+    /** Puts back what {@link patchInstancedMaterial} wrapped; null between draws. */
+    private _unpatchMaterial;
+    constructor(params?: InstancedMeshImplParams);
+    /**
+     * The instance capacity the textures currently hold.
+     */
+    get capacity(): number;
+    /**
+     * The number of active instances.
+     */
+    get instancesCount(): number;
+    /**
+     * 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: UniformSchemaShader): void;
+    /**
+     * 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: number, name: string, target?: UniformValueObj): UniformValue;
+    /**
+     * 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: number, name: string, value: UniformValue): void;
+    /**
+     * 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: number, onCreation?: (id: number) => void): 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: number[]): this;
+    /**
+     * Gets the visibility of a specific instance.
+     * @param id - The index of the instance.
+     * @returns Whether it is visible.
+     */
+    getVisibleAt(id: number): boolean;
+    /**
+     * Sets the visibility of a specific instance.
+     * @param id - The index of the instance.
+     * @param visible - Whether it should be visible.
+     */
+    setVisibleAt(id: number, visible: boolean): void;
+    /**
+     * 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: number, matrix?: Matrix4): Matrix4;
+    /**
+     * Writes an instance's transform.
+     * @param id - The index of the instance.
+     * @param matrix - The transform matrix.
+     * @returns `this`.
+     */
+    setMatrixAt(id: number, matrix: Matrix4): this;
+    /**
+     * Reads an instance's color, filling alpha from the fourth channel when handed a `Vector4`.
+     * Tolerates a read before any color was written — an unwritten instance reads opaque white — as
+     * `BatchedMesh` does and the compare-and-skip write helpers rely on.
+     * @param id - The instance.
+     * @param target - Receives the result; pass a `Vector4` to also read alpha.
+     * @returns `target`.
+     */
+    getColorAt(id: number): Color;
+    getColorAt<T extends Color | Vector4>(id: number, target: T): T;
+    /**
+     * 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: number, color: ColorRepresentation | Vector4): this;
+    /**
+     * Computes the bounding box that encloses all instances, and updates the `boundingBox` attribute.
+     */
+    computeBoundingBox(): void;
+    /**
+     * Computes the bounding sphere that encloses all instances, and updates the `boundingSphere` attribute.
+     */
+    computeBoundingSphere(): void;
+    /**
+     * 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: number, target: Sphere): Sphere;
+    /**
+     * 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: number, target: Box3): Box3;
+    /** Frees the data textures, which this mesh allocated rather than three. */
+    dispose(): void;
+    /**
+     * 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.
+     */
+    protected resetInstance(id: number): void;
+    /**
+     * 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.
+     */
+    protected patchMaterial(material: Material): () => void;
+    /**
+     * 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.
+     */
+    protected invalidateBounds(): void;
+    onBeforeRender(renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry, material: Material, group: Group): void;
+    onAfterRender(renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry, material: Material, group: Group): void;
+    onBeforeShadow(renderer: WebGLRenderer, scene: Scene, camera: Camera, shadowCamera: Camera, geometry: BufferGeometry, depthMaterial: Material, group: Group): void;
+    onAfterShadow(renderer: WebGLRenderer, scene: Scene, camera: Camera, shadowCamera: Camera, geometry: BufferGeometry, depthMaterial: Material, group: Group): void;
+    clone(recursive?: boolean): this;
+    copy(source: this, recursive?: boolean): this;
+    raycast(raycaster: Raycaster, intersects: Intersection[]): void;
+    /**
+     * 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.
+     */
+    private resizeCapacity;
+    private initMatricesTexture;
+    private initColorsTexture;
+    /** Flags the material(s) for recompilation, e.g. after a texture is added. */
+    private materialsNeedUpdate;
+}
+/**
+ * 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 declare const InstancedMesh: import("react").ExoticComponent<import("@react-three/fiber/dist/declarations/src/core/utils").Mutable<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<Partial<import("@react-three/fiber/dist/declarations/src/core/utils").Overwrite<InstancedMeshImpl, import("@react-three/fiber").MathProps<InstancedMeshImpl> & import("@react-three/fiber").ReactProps<InstancedMeshImpl> & Partial<import("@react-three/fiber").EventHandlers>>>, Omit<import("@react-three/fiber").InstanceProps<InstancedMeshImpl, typeof InstancedMeshImpl>, "object">>>>;
+//# sourceMappingURL=InstancedMesh.d.ts.map