@expofp/renderer 0.0.0-experimental.cf063fc

package/dist/core/InstanceUniforms.d.ts

@@ -0,0 +1,108 @@
+import { type WebGLProgramParametersWithUniforms } from 'three';
+import { SquareDataTexture, type UniformType, type UniformValue, type UniformValueObj } from './SquareDataTexture';
+/** The GLSL types a per-instance uniform may take, keyed by the name it gets in the shader. */
+export type UniformSchema = Record<string, UniformType>;
+/** Per-instance uniforms to declare, split by the shader stage that reads them. */
+export interface UniformSchemaShader {
+    /** Uniforms read in the vertex shader. */
+    vertex?: UniformSchema;
+    /** Uniforms read in the fragment shader. */
+    fragment?: UniformSchema;
+}
+/**
+ * The per-instance uniform store shared by all core classes: a {@link SquareDataTexture} plus the schema
+ * describing how uniforms pack into it.
+ *
+ * Ported from the identical uniform code both three.ez packages carry (`Uniforms.ts` in each), with
+ * one change: uniforms are **added**, not declared once. {@link add} merges into whatever is already
+ * there and rebuilds the texture, carrying existing values across — so a material and its container
+ * can each declare what they need without coordinating, and a declaration after instances are
+ * written keeps them. Removal is deliberately unsupported; rebuild the mesh if it is ever needed.
+ *
+ * The shader wiring lives here as well ({@link patchShader}), because every mesh does the same two
+ * things with it: bind the texture, and open `main` with the prologue that fetches from it. What
+ * differs between them — where the per-instance index comes from, and what each adds around the
+ * prologue — is what they pass in.
+ */
+export declare class InstanceUniforms {
+    /** The backing texture, or `null` until {@link add} declares the first uniform. */
+    texture: SquareDataTexture | null;
+    /** Everything declared so far, merged across calls, so a rebuild recomputes the whole layout. */
+    private declared;
+    /** Backs {@link shaderKey}, rebuilt whenever {@link declared} changes. */
+    private key;
+    /**
+     * What the declared uniforms generate, as one string.
+     *
+     * A material that fetches per-instance uniforms compiles different GLSL for every schema, and
+     * three caches a compiled program under `customProgramCacheKey` alone, with no way to compare
+     * source. So every patcher that injects this store's prologue folds this into its own key.
+     * Without it, two meshes whose schemas differ share one program and the second silently draws
+     * against the first's layout.
+     *
+     * Empty while nothing is declared, which is itself a distinct key: that program has no prologue.
+     * @returns The key, stable for as long as the schema is.
+     */
+    get shaderKey(): string;
+    /**
+     * Declares uniforms, merging with any already declared and rebuilding the texture.
+     *
+     * The layout packs every uniform into as few texels as it can, so adding one generally moves the
+     * others — hence the rebuild-and-copy rather than an in-place append. Redeclaring a name with a
+     * different type replaces it.
+     * @param schema - The uniforms to add.
+     * @param capacity - Instances the texture must hold.
+     */
+    add(schema: UniformSchemaShader, capacity: number): void;
+    /**
+     * Reads one instance's uniform.
+     * @param id - The instance to read.
+     * @param name - The uniform's name.
+     * @param target - Receives the result; unused for a `float`, which is returned directly.
+     * @returns The value.
+     */
+    get(id: number, name: string, target?: UniformValueObj): UniformValue;
+    /**
+     * Writes one instance's uniform and marks its row for upload.
+     * @param id - The instance to write.
+     * @param name - The uniform's name.
+     * @param value - The value to write.
+     */
+    set(id: number, name: string, value: UniformValue): void;
+    /**
+     * Grows the texture to a new instance capacity, keeping what is written.
+     * @param capacity - The new capacity.
+     */
+    resize(capacity: number): void;
+    /**
+     * Points a compiling shader at these uniforms: binds the texture, and opens `main` in both stages
+     * with the prologue that fetches this instance's values and brings them into scope under the
+     * names they were declared with.
+     *
+     * Does nothing and answers `false` while no uniform is declared — there is no texture to bind and
+     * nothing to name, so a caller whose own GLSL reads those names has to skip it too.
+     * @param shader - The program parameters to edit.
+     * @param indexName - The per-instance index the fetch addresses by, in shader scope where the
+     *   prologue lands (a float; see {@link SquareDataTexture}). A caller computing it inside `main`
+     *   supplies it with a later {@link openMain}, which lands ahead of this fetch.
+     * @param body - GLSL to run straight after the fetch, in both stages. Where code reading the
+     *   uniforms goes, since nothing ahead of the prologue can see them.
+     * @returns Whether the shader was patched.
+     * @throws {Error} If either stage has no `main` to inject into.
+     */
+    patchShader(shader: WebGLProgramParametersWithUniforms, indexName: string, body?: string): boolean;
+    /**
+     * Adopts another store's schema and an independent copy of its values, for cloning a mesh.
+     * @param source - The store to copy.
+     */
+    copyFrom(source: InstanceUniforms): void;
+    /** Frees the texture. */
+    dispose(): void;
+    /**
+     * The texture, or a readable failure when nothing declared a uniform.
+     * @returns The texture.
+     * @throws {Error} If {@link add} has not been called.
+     */
+    private require;
+}
+//# sourceMappingURL=InstanceUniforms.d.ts.map

package/dist/core/InstanceUniforms.js

@@ -0,0 +1,298 @@
+import { Matrix3, Matrix4, Vector2, Vector3, Vector4, } from 'three';
+import { declareBeforeMain, openMain } from './shader-source';
+import { SquareDataTexture, } from './SquareDataTexture';
+/**
+ * The per-instance uniform store shared by all core classes: a {@link SquareDataTexture} plus the schema
+ * describing how uniforms pack into it.
+ *
+ * Ported from the identical uniform code both three.ez packages carry (`Uniforms.ts` in each), with
+ * one change: uniforms are **added**, not declared once. {@link add} merges into whatever is already
+ * there and rebuilds the texture, carrying existing values across — so a material and its container
+ * can each declare what they need without coordinating, and a declaration after instances are
+ * written keeps them. Removal is deliberately unsupported; rebuild the mesh if it is ever needed.
+ *
+ * The shader wiring lives here as well ({@link patchShader}), because every mesh does the same two
+ * things with it: bind the texture, and open `main` with the prologue that fetches from it. What
+ * differs between them — where the per-instance index comes from, and what each adds around the
+ * prologue — is what they pass in.
+ */
+export class InstanceUniforms {
+    /** The backing texture, or `null` until {@link add} declares the first uniform. */
+    texture = null;
+    /** Everything declared so far, merged across calls, so a rebuild recomputes the whole layout. */
+    declared = {};
+    /** Backs {@link shaderKey}, rebuilt whenever {@link declared} changes. */
+    key = '';
+    /**
+     * What the declared uniforms generate, as one string.
+     *
+     * A material that fetches per-instance uniforms compiles different GLSL for every schema, and
+     * three caches a compiled program under `customProgramCacheKey` alone, with no way to compare
+     * source. So every patcher that injects this store's prologue folds this into its own key.
+     * Without it, two meshes whose schemas differ share one program and the second silently draws
+     * against the first's layout.
+     *
+     * Empty while nothing is declared, which is itself a distinct key: that program has no prologue.
+     * @returns The key, stable for as long as the schema is.
+     */
+    get shaderKey() {
+        return this.key;
+    }
+    /**
+     * Declares uniforms, merging with any already declared and rebuilding the texture.
+     *
+     * The layout packs every uniform into as few texels as it can, so adding one generally moves the
+     * others — hence the rebuild-and-copy rather than an in-place append. Redeclaring a name with a
+     * different type replaces it.
+     * @param schema - The uniforms to add.
+     * @param capacity - Instances the texture must hold.
+     */
+    add(schema, capacity) {
+        const vertex = { ...this.declared.vertex, ...schema.vertex };
+        const fragment = { ...this.declared.fragment, ...schema.fragment };
+        const layout = buildUniformLayout({ vertex, fragment });
+        const texture = new SquareDataTexture(Float32Array, layout.channels, layout.pixelsPerInstance, capacity, layout.uniformMap, layout.fetchInFragmentShader);
+        const previous = this.texture;
+        if (previous) {
+            copyUniforms(previous, texture, declaredTypes(this.declared), capacity);
+            previous.dispose();
+        }
+        this.texture = texture;
+        this.declared = { vertex, fragment };
+        this.key = schemaKey(this.declared);
+    }
+    /**
+     * Reads one instance's uniform.
+     * @param id - The instance to read.
+     * @param name - The uniform's name.
+     * @param target - Receives the result; unused for a `float`, which is returned directly.
+     * @returns The value.
+     */
+    get(id, name, target) {
+        return this.require().getUniformAt(id, name, target);
+    }
+    /**
+     * Writes one instance's uniform and marks its row for upload.
+     * @param id - The instance to write.
+     * @param name - The uniform's name.
+     * @param value - The value to write.
+     */
+    set(id, name, value) {
+        const texture = this.require();
+        texture.setUniformAt(id, name, value);
+        texture.enqueueUpdate(id);
+    }
+    /**
+     * Grows the texture to a new instance capacity, keeping what is written.
+     * @param capacity - The new capacity.
+     */
+    resize(capacity) {
+        this.texture?.resize(capacity);
+    }
+    /**
+     * Points a compiling shader at these uniforms: binds the texture, and opens `main` in both stages
+     * with the prologue that fetches this instance's values and brings them into scope under the
+     * names they were declared with.
+     *
+     * Does nothing and answers `false` while no uniform is declared — there is no texture to bind and
+     * nothing to name, so a caller whose own GLSL reads those names has to skip it too.
+     * @param shader - The program parameters to edit.
+     * @param indexName - The per-instance index the fetch addresses by, in shader scope where the
+     *   prologue lands (a float; see {@link SquareDataTexture}). A caller computing it inside `main`
+     *   supplies it with a later {@link openMain}, which lands ahead of this fetch.
+     * @param body - GLSL to run straight after the fetch, in both stages. Where code reading the
+     *   uniforms goes, since nothing ahead of the prologue can see them.
+     * @returns Whether the shader was patched.
+     * @throws {Error} If either stage has no `main` to inject into.
+     */
+    patchShader(shader, indexName, body = '') {
+        const texture = this.texture;
+        if (!texture)
+            return false;
+        const glsl = texture.getUniformsGLSL(UNIFORMS_TEXTURE, indexName);
+        shader.uniforms[UNIFORMS_TEXTURE] = { value: texture };
+        shader.vertexShader = openMain(declareBeforeMain(shader.vertexShader, glsl.vertex.declarations), `${glsl.vertex.body}\n${body}`);
+        shader.fragmentShader = openMain(declareBeforeMain(shader.fragmentShader, glsl.fragment.declarations), `${glsl.fragment.body}\n${body}`);
+        return true;
+    }
+    /**
+     * Adopts another store's schema and an independent copy of its values, for cloning a mesh.
+     * @param source - The store to copy.
+     */
+    copyFrom(source) {
+        this.declared = {
+            vertex: { ...source.declared.vertex },
+            fragment: { ...source.declared.fragment },
+        };
+        this.key = source.key;
+        this.texture = source.texture ? source.texture.clone() : null;
+    }
+    /** Frees the texture. */
+    dispose() {
+        this.texture?.dispose();
+    }
+    /**
+     * The texture, or a readable failure when nothing declared a uniform.
+     * @returns The texture.
+     * @throws {Error} If {@link add} has not been called.
+     */
+    require() {
+        if (!this.texture) {
+            throw new Error('InstanceUniforms: declare uniforms with "addUniforms" before reading or writing them.');
+        }
+        return this.texture;
+    }
+}
+/**
+ * Packs a schema into texels, largest uniform first so small ones fill the gaps.
+ * @param schema - Every uniform to lay out.
+ * @returns The layout.
+ */
+function buildUniformLayout(schema) {
+    const vertexSchema = schema.vertex ?? {};
+    const fragmentSchema = schema.fragment ?? {};
+    const uniforms = [];
+    let totalSize = 0;
+    // Only when nothing is read in the vertex shader can the fetch move to the fragment shader.
+    let fetchInFragmentShader = true;
+    for (const name in vertexSchema) {
+        const type = vertexSchema[name];
+        const size = uniformSize(type);
+        totalSize += size;
+        uniforms.push({ name, type, size });
+        fetchInFragmentShader = false;
+    }
+    for (const name in fragmentSchema) {
+        if (vertexSchema[name])
+            continue;
+        const type = fragmentSchema[name];
+        const size = uniformSize(type);
+        totalSize += size;
+        uniforms.push({ name, type, size });
+    }
+    uniforms.sort((a, b) => b.size - a.size);
+    const uniformMap = new Map();
+    const filled = [];
+    for (const { name, size, type } of uniforms) {
+        uniformMap.set(name, { offset: uniformOffset(size, filled), size, type });
+    }
+    return {
+        channels: Math.min(totalSize, 4),
+        pixelsPerInstance: Math.ceil(totalSize / 4),
+        uniformMap,
+        fetchInFragmentShader,
+    };
+}
+/**
+ * Places one uniform, reusing a partly filled texel when it fits.
+ * @param size - Elements the uniform spans.
+ * @param filled - Elements used so far in each texel; extended as texels are opened.
+ * @returns The uniform's element offset within an instance's record.
+ */
+function uniformOffset(size, filled) {
+    if (size < 4) {
+        for (let i = 0; i < filled.length; i++) {
+            if (filled[i] + size <= 4) {
+                const offset = i * 4 + filled[i];
+                filled[i] += size;
+                return offset;
+            }
+        }
+    }
+    const offset = filled.length * 4;
+    for (let remaining = size; remaining > 0; remaining -= 4) {
+        filled.push(remaining);
+    }
+    return offset;
+}
+/**
+ * Elements a uniform type occupies.
+ * @param type - The GLSL type.
+ * @returns Its element count.
+ * @throws {Error} If the type is not one this texture can store.
+ */
+function uniformSize(type) {
+    switch (type) {
+        case 'float':
+            return 1;
+        case 'vec2':
+            return 2;
+        case 'vec3':
+            return 3;
+        case 'vec4':
+            return 4;
+        case 'mat3':
+            return 9;
+        case 'mat4':
+            return 16;
+        default:
+            throw new Error(`InstanceUniforms: invalid uniform type "${String(type)}".`);
+    }
+}
+/**
+ * Builds the key that stands for the GLSL a schema generates. See {@link InstanceUniforms.shaderKey}.
+ *
+ * Names, types and the stage each is read in, because all three reach the generated source. Left in
+ * declaration order rather than sorted, since that is the order the layout packs them in, so two
+ * schemas that differ only in order still pack differently and have to compile apart.
+ * @param schema - The declared uniforms.
+ * @returns The key.
+ */
+function schemaKey(schema) {
+    const stage = (prefix, uniforms = {}) => Object.entries(uniforms).map(([name, type]) => `${prefix}${name}:${type}`);
+    return [...stage('v', schema.vertex), ...stage('f', schema.fragment)].join(',');
+}
+/**
+ * Flattens a schema into the name-to-type pairs a rebuild has to carry across.
+ * @param schema - The declared uniforms.
+ * @returns Every uniform, whichever stage reads it.
+ */
+function declaredTypes(schema) {
+    return { ...schema.vertex, ...schema.fragment };
+}
+/**
+ * Carries per-instance values from one layout to the next, so declaring a uniform does not discard
+ * what is already written. Goes through the public accessors, which is what makes it indifferent to
+ * the offsets moving underneath.
+ * @param previous - The texture being replaced.
+ * @param next - The texture replacing it.
+ * @param types - The uniforms to carry, by name.
+ * @param count - Instances to copy.
+ */
+function copyUniforms(previous, next, types, count) {
+    for (const name in types) {
+        // Allocated once per uniform, not per instance, so a rebuild costs a handful of objects however
+        // many instances it carries across.
+        const target = uniformScratch(types[name]);
+        for (let id = 0; id < count; id++) {
+            next.setUniformAt(id, name, previous.getUniformAt(id, name, target));
+        }
+    }
+}
+/**
+ * A target for reading a uniform of the given type.
+ * @param type - The GLSL type.
+ * @returns The scratch object, or `undefined` for a `float`, which is read by value.
+ */
+function uniformScratch(type) {
+    switch (type) {
+        case 'vec2':
+            return new Vector2();
+        case 'vec3':
+            return new Vector3();
+        case 'vec4':
+            return new Vector4();
+        case 'mat3':
+            return new Matrix3();
+        case 'mat4':
+            return new Matrix4();
+        default:
+            return undefined;
+    }
+}
+/**
+ * The sampler name the uniforms texture binds to. Private because both sides of the agreement it
+ * enforces — the generated GLSL and the `shader.uniforms[…]` entry — are set by
+ * {@link InstanceUniforms.patchShader}.
+ */
+const UNIFORMS_TEXTURE = 'uniformsTexture';

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** — `BatchedMeshImpl` does, from three's own `getIndirectIndex( gl_DrawID )`, and
+ *    `InstancedMeshImpl` 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