@expofp/renderer 3.2.5 → 3.27.0

package/dist/core/SquareDataTexture.d.ts

@@ -0,0 +1,277 @@
+import { type Color, DataTexture, type Matrix3, type Matrix4, type PixelFormat, type TextureDataType, type TypedArray, type TypedArrayConstructor, type Vector2, type Vector3, type Vector4, type WebGLRenderer, WebGLUtils } from 'three';
+/** Represents the number of elements per pixel. */
+export type ChannelSize = 1 | 2 | 3 | 4;
+/** Represents the texture information including its data, size, format, and data type. */
+export interface TextureInfo {
+    /** The allocated typed array. */
+    array: TypedArray;
+    /** The square texture's edge in pixels. */
+    size: number;
+    /** The pixel format. */
+    format: PixelFormat;
+    /** The data type. */
+    type: TextureDataType;
+}
+/** Represents information for updating rows in the texture. */
+export interface UpdateRowInfo {
+    /** The first row of the range. */
+    row: number;
+    /** How many rows the range spans. */
+    count: number;
+}
+/** Defines the possible types of uniforms that can be used in shaders. */
+export type UniformType = 'float' | 'vec2' | 'vec3' | 'vec4' | 'mat3' | 'mat4';
+/** Represents a value that can be used as a uniform. */
+export type UniformValueObj = Vector2 | Vector3 | Vector4 | Matrix3 | Matrix4 | Color;
+/** Defines a uniform value as either a number or a compatible three object. */
+export type UniformValue = number | UniformValueObj;
+/** Represents the schema for a uniform, defining its offset, size, and type. */
+export interface UniformMapType {
+    /** The uniform's element offset within an instance's record. */
+    offset: number;
+    /** How many elements it spans. */
+    size: number;
+    /** Its GLSL type. */
+    type: UniformType;
+}
+/** Represents a map of uniform names to their schema definitions. */
+export type UniformMap = Map<string, UniformMapType>;
+/**
+ * The GLSL one shader stage needs in order to read a texture's uniforms, split by where it goes.
+ *
+ * Split rather than handed over as one string that opens `main` itself, which is what this used to
+ * emit: a prologue carrying its own `void main() {` made every patch that came after it aim at *that*
+ * one instead of the shader's, and the ordering that produced had to be re-explained at each call
+ * site. Both halves now go in through `shader-source`, which owns the anchor.
+ */
+export interface UniformsStageGLSL {
+    /** Samplers and varyings, which belong above `main`. */
+    declarations: string;
+    /** The fetch and the varying traffic, which belong as `main`'s first statements. */
+    body: string;
+}
+/**
+ * Calculates the square texture size based on the capacity and pixels per instance, so the texture
+ * is large enough to store every instance in a square layout.
+ * @param capacity - The maximum number of instances allowed in the texture.
+ * @param pixelsPerInstance - The number of pixels required for each instance.
+ * @returns The size of the square texture needed to store all the instances.
+ */
+export declare function getSquareTextureSize(capacity: number, pixelsPerInstance: number): number;
+/**
+ * Generates texture information (size, format, type) for a square texture.
+ * @param arrayType - The constructor for the TypedArray.
+ * @param channels - The number of channels in the texture.
+ * @param pixelsPerInstance - The number of pixels required for each instance.
+ * @param capacity - The maximum number of instances allowed in the texture.
+ * @returns An object containing the texture's array, size, format, and data type.
+ */
+export declare function getSquareTextureInfo(arrayType: TypedArrayConstructor, channels: ChannelSize, pixelsPerInstance: number, capacity: number): TextureInfo;
+/**
+ * A `DataTexture` laid out as a square grid of per-instance records, with partial row uploads and
+ * per-instance uniforms addressed by instance id.
+ *
+ * Vendored from three.ez, which ships two near-identical copies of this file — one per package —
+ * and we would otherwise bundle both:
+ * - {@link https://github.com/agargaro/batched-mesh-extensions/blob/master/src/core/SquareDataTexture.ts | batched-mesh-extensions}
+ * - {@link https://github.com/agargaro/instanced-mesh/blob/master/src/core/utils/SquareDataTexture.ts | instanced-mesh}
+ *
+ * This is the batched-mesh-extensions version, the later of the two: its `update` hands whole-texture
+ * uploads back to three instead of hand-binding a texture unit, which drops `bindToProgram`,
+ * `getSlot`, `updateFull` and `updatePartial` along with the `?? maxTextures - 1` slot guess the
+ * instanced-mesh copy still carries.
+ *
+ * Three deliberate departures from both originals:
+ *
+ * 1. **No `flat` on the varyings.** With flat shading a fragment takes its value from the
+ *    primitive's *provoking* vertex, and WebGL's default last-vertex convention is the expensive one
+ *    for drivers — which is why upstream wants `WEBGL_provoking_vertex` enabled. Every value here is
+ *    per-instance and therefore identical across a primitive's vertices, so interpolating instead of
+ *    flat-shading yields the same result and needs no extension.
+ * 2. **The index varying is always `float`**, so `getUniformsGLSL` no longer takes an index type.
+ *    It follows from the first: GLSL ES 3.00 requires integer varyings to be `flat`, so an index
+ *    that is not float could not have the qualifier removed. **Callers must therefore hand it a float
+ *    index** — `BatchedMeshExt` does, from three's own `getIndirectIndex( gl_DrawID )`, and
+ *    `InstancedMeshExt` does, from the float index texture that replaced upstream's `uint` attribute.
+ * 3. **`clone` and `copy` produce an independent texture.** See each method.
+ */
+export declare class SquareDataTexture extends DataTexture {
+    /**
+     * Whether to enable partial texture updates by row. If `false`, the entire texture is updated.
+     * @default true
+     */
+    partialUpdate: boolean;
+    /**
+     * The maximum number of update calls per frame. Past it, the whole texture is re-uploaded instead.
+     * @default Infinity
+     */
+    maxUpdateCalls: number;
+    /** Format/type conversion helper, built on first upload. */
+    protected _utils: WebGLUtils | null;
+    /** Whether any row has been marked since the last upload. */
+    protected _needsUpdate: boolean;
+    /** Width at the last upload, used to notice a resize; `null` until the first one. */
+    protected _lastWidth: number | null;
+    /** The typed array backing the texture. */
+    protected _data: TypedArray;
+    /** Elements per pixel. */
+    protected _channels: ChannelSize;
+    /** Pixels each instance occupies. */
+    protected _pixelsPerInstance: number;
+    /** Elements each instance occupies. */
+    protected _stride: number;
+    /** Rows marked dirty for the next partial upload. */
+    protected _rowToUpdate: boolean[];
+    /** Reused pool of dirty-row ranges, refilled each upload so a frame allocates nothing. */
+    protected readonly _rowRanges: UpdateRowInfo[];
+    /** Uniform layout, shared with whoever built the schema. */
+    protected _uniformMap: UniformMap;
+    /** Whether uniforms are fetched in the fragment shader rather than passed as varyings. */
+    protected _fetchUniformsInFragmentShader: boolean;
+    /**
+     * The backing typed array. An instanced mesh reads and writes its matrix and color data through
+     * it directly, the way three's own `InstancedMesh` writes its instance attributes — a per-instance
+     * accessor would be pure overhead on that hot path. Pair a write with {@link enqueueUpdate} so the
+     * row is re-uploaded.
+     * @returns The array.
+     */
+    get data(): TypedArray;
+    /**
+     * @param arrayType - The constructor for the TypedArray.
+     * @param channels - The number of channels in the texture.
+     * @param pixelsPerInstance - The number of pixels required for each instance.
+     * @param capacity - The total number of instances.
+     * @param uniformMap - Optional map for handling uniform values.
+     * @param fetchInFragmentShader - Optional flag that determines if uniform values should be fetched
+     *   in the fragment shader instead of the vertex shader.
+     */
+    constructor(arrayType: TypedArrayConstructor, channels: ChannelSize, pixelsPerInstance: number, capacity: number, uniformMap?: UniformMap, fetchInFragmentShader?: boolean);
+    /**
+     * Resizes the texture to accommodate a new number of instances.
+     * @param count - The new total number of instances.
+     */
+    resize(count: number): void;
+    /**
+     * Marks a row of the texture for update during the next render cycle, so only rows that changed
+     * are re-uploaded.
+     * @param index - The index of the instance to update.
+     */
+    enqueueUpdate(index: number): void;
+    /**
+     * Uploads whatever changed since the last frame, a row range at a time.
+     *
+     * Defers to three's own full upload whenever it is going to happen anyway — before the texture
+     * exists, after a resize, or when the version moved — and whenever the dirty rows are so scattered
+     * that `maxUpdateCalls` would be exceeded.
+     * @param renderer - The renderer to upload through.
+     */
+    update(renderer: WebGLRenderer): void;
+    /**
+     * Sets a uniform value at the specified instance ID in the texture.
+     * @param id - The instance ID to set the uniform for.
+     * @param name - The name of the uniform.
+     * @param value - The value to set for the uniform.
+     */
+    setUniformAt(id: number, name: string, value: UniformValue): void;
+    /**
+     * Retrieves a uniform value at the specified instance ID from the texture.
+     * @param id - The instance ID to retrieve the uniform from.
+     * @param name - The name of the uniform.
+     * @param target - Optional target object to store the uniform value.
+     * @returns The uniform value for the specified instance.
+     */
+    getUniformAt(id: number, name: string, target?: UniformValueObj): UniformValue;
+    /**
+     * Generates the GLSL for reading this texture's uniforms.
+     *
+     * The index varying is `float` and has no index-type parameter, because these varyings carry no
+     * `flat` qualifier — see the class docs. `indexName` must name a float in the shader.
+     * @param textureName - The name of the texture in the GLSL shader.
+     * @param indexName - The name of the index in the GLSL shader.
+     * @returns What each stage declares and what it runs first; see {@link UniformsStageGLSL}.
+     */
+    getUniformsGLSL(textureName: string, indexName: string): {
+        vertex: UniformsStageGLSL;
+        fragment: UniformsStageGLSL;
+    };
+    /**
+     * Copies another texture's pixels and layout, leaving nothing shared between the two.
+     *
+     * Both originals assign `_rowToUpdate` by reference and inherit `Texture.copy`'s by-reference
+     * `source`, so a copy and its original wrote through into each other's pixels and marked each
+     * other's rows dirty. Only `_uniformMap` stays shared, which is safe: it is the layout descriptor
+     * built once from the schema and never mutated.
+     * @param source - The texture to copy.
+     * @returns `this`.
+     */
+    copy(source: SquareDataTexture): this;
+    /**
+     * Duplicates the texture.
+     *
+     * Neither original overrides this, so three's `Texture.clone` ran `new this.constructor()` with no
+     * arguments — and this constructor derives its size, format and typed array from those arguments,
+     * so the inherited clone always threw, taking every `copy` of an owning mesh down with it.
+     * @returns The independent copy.
+     */
+    clone(): this;
+    /**
+     * Groups the dirty rows into contiguous ranges, so neighbors upload in one call. Fills the reused
+     * {@link _rowRanges} pool — growing it only when a frame has more ranges than ever before — rather
+     * than allocating a fresh array and range objects every frame.
+     * @returns How many ranges were written to the pool.
+     */
+    protected collectDirtyRanges(): number;
+    /**
+     * Uploads the given row ranges with `texSubImage2D`.
+     * @param webglTexture - The uploaded texture to write into.
+     * @param renderer - The renderer to upload through.
+     * @param rangeCount - How many of the pooled {@link _rowRanges} to upload.
+     */
+    protected updateRows(webglTexture: WebGLTexture, renderer: WebGLRenderer, rangeCount: number): void;
+    /**
+     * The vertex stage's share: either the whole fetch plus the varyings it feeds, or — when uniforms
+     * are read in the fragment shader — just the index handed across.
+     * @param textureName - The sampler name.
+     * @param indexName - The per-instance index available in the vertex shader; must be a float.
+     * @returns What the stage declares and what it runs first.
+     */
+    protected getUniformsVertexGLSL(textureName: string, indexName: string): UniformsStageGLSL;
+    /**
+     * The fragment stage's share: either the varyings the vertex shader filled, or the fetch itself.
+     * @param textureName - The sampler name.
+     * @param indexName - The per-instance index carried across as a varying.
+     * @returns What the stage declares and what it runs first.
+     */
+    protected getUniformsFragmentGLSL(textureName: string, indexName: string): UniformsStageGLSL;
+    /**
+     * GLSL fetching every texel one instance occupies.
+     * @param textureName - The sampler name.
+     * @param indexName - The instance index expression.
+     * @returns The GLSL statements.
+     */
+    protected texelsFetchGLSL(textureName: string, indexName: string): string;
+    /**
+     * GLSL unpacking each uniform out of the fetched texels.
+     * @returns The GLSL declarations.
+     */
+    protected getFromTexelsGLSL(): string;
+    /**
+     * The varying declarations carrying each uniform from vertex to fragment stage.
+     *
+     * No `flat` qualifier, unlike both originals — see the class docs.
+     * @returns The declaration, assignment and read snippets.
+     */
+    protected getVarying(): {
+        declareVarying: string;
+        assignVarying: string;
+        getVarying: string;
+    };
+    /**
+     * The swizzle selecting a uniform's components out of its texel.
+     * @param offset - The uniform's element offset within an instance.
+     * @param size - How many elements it spans.
+     * @returns The component swizzle, such as `rgb`.
+     */
+    protected getUniformComponents(offset: number, size: number): string;
+}
+//# sourceMappingURL=SquareDataTexture.d.ts.map