melonjs 19.9.1 → 20.1.0

package/build/video/webgl/batchers/batcher.d.ts

@@ -1,10 +1,26 @@
 /**
- * A base WebGL Batcher object that manages shader programs, vertex attribute
- * definitions, and vertex buffer batching for efficient GPU draw calls.
+ * additional import for TypeScript
+ * @import WebGLRenderer from "./../webgl_renderer.js";
+ * @import {Matrix3d} from "../../../math/matrix3d.ts";
+ * @import {VertexFormat} from "../../gpu/vertexformat.ts";
+ * @import {Topology} from "../../gpu/topology.ts";
+ */
+/**
+ * The base WebGL Batcher — manages shader programs, vertex attribute
+ * definitions, and vertex buffer batching for efficient GPU draw calls,
+ * realizing the backend-neutral {@link Batcher} lifecycle on GL state.
+ * Custom WebGL batchers extend this class.
+ * @augments Batcher
  * @category Rendering
  */
-export class Batcher {
+export class WebGLBatcher extends Batcher {
+    /**
+     * @param {WebGLRenderer} renderer - the current WebGL renderer session
+     * @param {object} settings - additional settings to initialize this batcher (see {@link WebGLBatcher#init})
+     */
+    constructor(renderer: WebGLRenderer, settings: object);
     /**
+     * Initialize the batcher (called by the constructor)
      * @param {WebGLRenderer} renderer - the current WebGL renderer session
      * @param {object} settings - additional settings to initialize this batcher
      * @param {object[]} settings.attributes - an array of attributes definition
@@ -20,7 +36,7 @@ export class Batcher {
      * @param {boolean} [settings.indexed=false] - whether this batcher uses an index buffer for indexed drawing (drawElements)
      * @param {string} [settings.projectionUniform="uProjectionMatrix"] - the name of the projection matrix uniform in the shader
      */
-    constructor(renderer: WebGLRenderer, settings: {
+    init(renderer: WebGLRenderer, settings: {
         attributes: {
             name: string;
             size: number;
@@ -35,15 +51,9 @@ export class Batcher {
         maxVertices?: number | undefined;
         indexed?: boolean | undefined;
         projectionUniform?: string | undefined;
-    });
-    /**
-     * Initialize the batcher
-     * @ignore
-     */
-    init(renderer: any, settings: any): void;
-    renderer: any;
+    }): void;
     gl: any;
-    viewMatrix: any;
+    viewMatrix: Matrix3d | undefined;
     /**
      * the default shader created by this batcher
      * @type {GLShader}
@@ -55,28 +65,38 @@ export class Batcher {
      */
     currentShader: GLShader | undefined;
     /**
-     * primitive type to render (gl.POINTS, gl.LINE_STRIP, gl.LINE_LOOP, gl.LINES, gl.TRIANGLE_STRIP, gl.TRIANGLE_FAN, gl.TRIANGLES)
+     * @param {Topology|number} value - a topology name or a GL primitive mode
+     */
+    set mode(value: Topology | number);
+    /**
+     * Primitive type to render, as a GL enum (`gl.TRIANGLES`, `gl.LINES`, …).
+     *
+     * Assignable from either vocabulary — `batcher.mode = "line-list"` and
+     * `batcher.mode = gl.LINES` are equivalent — but always reads back as the
+     * GL enum, so existing comparisons keep working. Read
+     * {@link WebGLBatcher#topology} for the portable name.
      * @type {number}
      * @default gl.TRIANGLES
      */
-    mode: number | undefined;
+    get mode(): number;
+    vertexState: WebGLVertexState | null | undefined;
     /**
      * an array of vertex attribute properties
-     * @see Batcher.addAttribute
+     * @see WebGLBatcher.addAttribute
      * @type {Array.<Object>}
      */
     attributes: Object[] | undefined;
     /**
      * the stride of a single vertex in bytes
      * (will automatically be calculated as attributes definitions are added)
-     * @see Batcher.addAttribute
+     * @see WebGLBatcher.addAttribute
      * @type {number}
      */
     stride: number | undefined;
     /**
      * the size of a single vertex in floats
      * (will automatically be calculated as attributes definitions are added)
-     * @see Batcher.addAttribute
+     * @see WebGLBatcher.addAttribute
      * @type {number}
      */
     vertexSize: number | undefined;
@@ -108,20 +128,49 @@ export class Batcher {
      */
     indexBuffer: WebGLIndexBuffer | null | undefined;
     /**
-     * Reset batcher internal state
+     * The GL buffer this batcher uploads its vertex data into: its own
+     * buffer for indexed (mesh-family) batchers, otherwise the renderer's
+     * shared one.
+     * @type {WebGLBuffer}
      * @ignore
      */
-    reset(): void;
+    get uploadBuffer(): WebGLBuffer;
     /**
-     * called by the WebGL renderer when a batcher becomes the current one
+     * (Re)build this batcher's {@link WebGLVertexState} — the frozen vertex
+     * buffer layout (`attributes` + `stride`) realized as a GL vertex array
+     * object bound to this batcher's upload buffer and, for indexed
+     * batchers, its index buffer.
+     *
+     * Every shader hosted by this batcher must declare a prefix of that
+     * layout, in layout order (see {@link validateShaderLocations}) — the
+     * locations are frozen here at the default shader's mapping.
+     * @ignore
      */
-    bind(): void;
+    createVertexState(): void;
     /**
-     * called by the WebGL renderer when this batcher is being replaced by another.
-     * Disables this batcher's vertex attribute locations so they don't leak across
-     * (otherwise stale stride/offset state can cause INVALID_OPERATION on the next draw).
+     * Validate (once per shader) that a hosted shader's attribute locations
+     * match this batcher's frozen vertex state. The engine's analogue of
+     * WebGPU's pipeline-creation validation: locations are bound in vertex
+     * source declaration order, so every shader hosted by this batcher must
+     * declare a prefix of the batcher's attribute layout, in layout order.
+     * A mismatched shader silently reads wrong vertex data — warn loudly.
+     * @ignore
      */
-    unbind(): void;
+    validateShaderLocations(shader: any): void;
+    validatedShaders: WeakSet<object> | undefined;
+    /**
+     * Ensure the draw about to be recorded runs on THIS batcher's program.
+     * Normally `bind()` guaranteed that, but an `ONCONTEXT_RESTORED`
+     * emission recompiles every live GLShader — each replaying its uniform
+     * snapshot on its OWN program — leaving whichever recompiled last
+     * really bound while the renderer's cache still named another. The
+     * renderer invalidates its program cache on that event, so this
+     * pointer compare re-issues `useProgram` exactly when the drift
+     * happened and costs two loads otherwise. Called by every flush path
+     * (the base and the quad override).
+     * @ignore
+     */
+    syncProgram(): void;
     /**
      * Select the shader to use for compositing
      * @see GLShader
@@ -130,14 +179,57 @@ export class Batcher {
     useShader(shader: GLShader): void;
     currentSamplerUnit: number | undefined;
     /**
-     * add vertex attribute property definition to the batcher
-     * @param {string} name - name of the attribute in the vertex shader
-     * @param {number} size - number of components per vertex attribute. Must be 1, 2, 3, or 4.
-     * @param {GLenum} type - data type of each component in the array
-     * @param {boolean} normalized - whether integer data values should be normalized into a certain range when being cast to a float
-     * @param {number} offset - offset in bytes of the first component in the vertex attribute array
+     * @param {Topology|number} value - a topology name or a GL primitive mode
      */
-    addAttribute(name: string, size: number, type: GLenum, normalized: boolean, offset: number): void;
+    set topology(value: Topology | number);
+    /**
+     * How this batcher assembles vertices into primitives, in the
+     * backend-neutral vocabulary.
+     *
+     * `"line-loop"` and `"triangle-fan"` are engine extensions with no
+     * equivalent in modern GPU APIs — prefer the others for anything that must
+     * survive a backend change.
+     * @type {Topology}
+     * @default "triangle-list"
+     */
+    get topology(): Topology;
+    /**
+     * Add a vertex attribute to this batcher's layout.
+     *
+     * Accepts either vocabulary. The backend-neutral form names the component
+     * type and count in one token, which is what a non-WebGL backend can
+     * consume directly and what lets a layout be written without a live
+     * rendering context:
+     *
+     * ```js
+     * batcher.addAttribute({ name: "aColor", format: "unorm8x4", offset: 20 });
+     * batcher.addAttribute("aColor", "unorm8x4", 20);
+     * ```
+     *
+     * The GL form is supported indefinitely and behaves exactly as before:
+     *
+     * ```js
+     * batcher.addAttribute("aColor", 4, gl.UNSIGNED_BYTE, true, 20);
+     * ```
+     *
+     * Records keep both spellings, so existing readers of `size` / `type` /
+     * `normalized` are unaffected. A GL combination with no portable name —
+     * three-component 8- and 16-bit types, which the neutral vocabulary does
+     * not define — is stored with `format: undefined` rather than an invented
+     * name that a backend could not honour.
+     *
+     * The layout is frozen once `init()` has built the vertex state, and each
+     * record is frozen on insertion: a batcher rebuilds its vertex state from
+     * these records after a context loss, so a later mutation would take
+     * effect at restore time rather than where it was written.
+     * @param {string|object} name - attribute name, or a descriptor object
+     * @param {number|VertexFormat} [size] - component count (GL form), or the format (neutral form)
+     * @param {GLenum|number} [type] - component type (GL form), or the byte offset (neutral form)
+     * @param {boolean} [normalized] - whether integers are scaled into `[0, 1]` / `[-1, 1]` (GL form only)
+     * @param {number} [offset] - byte offset of the attribute within a vertex (GL form)
+     * @throws {Error} when the layout is frozen, the format or GL type is unknown, or a descriptor contradicts itself
+     */
+    addAttribute(name: string | object, size?: number | VertexFormat, type?: GLenum | number, normalized?: boolean, offset?: number, ...args: any[]): void;
     /**
      * set/change the current projection matrix
      * @param {Matrix3d} matrix - the new projection matrix
@@ -154,11 +246,16 @@ export class Batcher {
      * @param {number} [mode=gl.TRIANGLES] - the GL drawing mode
      */
     flush(mode?: number): void;
+    #private;
 }
-export default Batcher;
+export default WebGLBatcher;
+import { Batcher } from "../../gpu/batcher.js";
+import type WebGLRenderer from "./../webgl_renderer.js";
+import type { Matrix3d } from "../../../math/matrix3d.ts";
 import GLShader from "../glshader.js";
+import type { Topology } from "../../gpu/topology.ts";
+import WebGLVertexState from "../buffer/vertexstate.js";
 import VertexArrayBuffer from "../../buffer/vertex.js";
 import WebGLIndexBuffer from "../buffer/index.js";
-import type { Matrix3d } from "../../../math/matrix3d.ts";
-import type WebGLRenderer from "./../webgl_renderer.js";
+import type { VertexFormat } from "../../gpu/vertexformat.ts";
 //# sourceMappingURL=batcher.d.ts.map

package/build/video/webgl/batchers/batcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"batcher.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/batchers/batcher.js"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH;IACC;;;;;;;;;;;;;;;OAeG;IACH,sBAfW,aAAa,YAErB;QAA2B,UAAU,EACrC;YAAoC,IAAI,EAAhC,MAAM;YACsB,IAAI,EAAhC,MAAM;YACsB,IAAI,EAAhC,MAAM;YACuB,UAAU,EAAvC,OAAO;YACqB,MAAM,EAAlC,MAAM;SACd;QAAyB,MAAM,EAC/B;YAAgC,MAAM,EAA9B,MAAM;YACkB,QAAQ,EAAhC,MAAM;SACd;QAA0B,WAAW;QACV,OAAO;QACR,iBAAiB;KAC7C,EAGA;IAED;;;OAGG;IACH,yCA6HC;IA3HA,cAAwB;IAGxB,QAAqB;IAGrB,gBAA2C;IAE3C;;;OAGG;IACH,oCAA8B;IAE9B;;;OAGG;IACH,oCAA8B;IAE9B;;;;OAIG;IACH,yBAA6B;IAE7B;;;;OAIG;IACH,iCAAoB;IAEpB;;;;;OAKG;IACH,2BAAe;IAEf;;;;;OAKG;IACH,+BAAmB;IAEnB;;;OAGG;IACH,0CAAsB;IAqCtB;;;OAGG;IACH,sCAA0E;IAE1E;;;OAGG;IACH,oCAA+C;IAE/C;;;;OAIG;IACH,+CAA0B;IAE1B;;;;OAIG;IACH,iDAAuB;IAUxB;;;OAGG;IACH,cAoBC;IAED;;OAEG;IACH,aAYC;IAED;;;;OAIG;IACH,eAaC;IAED;;;;OAIG;IACH,kBAFW,QAAQ,QA8BlB;IAHE,uCAA4B;IAK/B;;;;;;;OAOG;IACH,mBANW,MAAM,QACN,MAAM,QACN,MAAM,cACN,OAAO,UACP,MAAM,QA+BhB;IAED;;;OAGG;IACH,sBAFW,QAAQ,QAIlB;IAED;;;;OAIG;IACH,oBAFW,MAAM,EAAE,QAOlB;IAED;;;OAGG;IACH,aAFW,MAAM,QAgFhB;CACD;;qBA9ZoB,gBAAgB;8BAFP,wBAAwB;6BACzB,oBAAoB;8BAMtB,2BAA2B;+BADxB,wBAAwB"}
+{"version":3,"file":"batcher.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/batchers/batcher.js"],"names":[],"mappings":"AASA;;;;;;GAMG;AAEH;;;;;;;GAOG;AACH;IAgBC;;;OAGG;IACH,sBAHW,aAAa,YACb,MAAM,EAKhB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,eAfW,aAAa,YAErB;QAA2B,UAAU,EACrC;YAAoC,IAAI,EAAhC,MAAM;YACsB,IAAI,EAAhC,MAAM;YACsB,IAAI,EAAhC,MAAM;YACuB,UAAU,EAAvC,OAAO;YACqB,MAAM,EAAlC,MAAM;SACd;QAAyB,MAAM,EAC/B;YAAgC,MAAM,EAA9B,MAAM;YACkB,QAAQ,EAAhC,MAAM;SACd;QAA0B,WAAW;QACV,OAAO;QACR,iBAAiB;KAC7C,QA+IA;IAzIA,QAAqB;IAGrB,iCAA2C;IAE3C;;;OAGG;IACH,oCAA8B;IAE9B;;;OAGG;IACH,oCAA8B;IA2X/B;;OAEG;IACH,gBAFW,QAAQ,GAAC,MAAM,EASzB;IAxBD;;;;;;;;;OASG;IACH,YAHU,MAAM,CAKf;IA/WC,iDAAuB;IAGxB;;;;OAIG;IACH,iCAAoB;IAEpB;;;;;OAKG;IACH,2BAAe;IAEf;;;;;OAKG;IACH,+BAAmB;IAEnB;;;OAGG;IACH,0CAAsB;IA4CtB;;;OAGG;IACH,sCAA0E;IAE1E;;;OAGG;IACH,oCAA+C;IAE/C;;;;OAIG;IACH,+CAA0B;IAE1B;;;;OAIG;IACH,iDAAuB;IAgBxB;;;;;;OAMG;IACH,oBAHU,WAAW,CAKpB;IAED;;;;;;;;;;OAUG;IACH,0BAiBC;IAyFD;;;;;;;;OAQG;IACH,2CA0BC;IAxBC,8CAAqC;IA0BvC;;;;;;;;;;;OAWG;IACH,oBAaC;IAED;;;;OAIG;IACH,kBAFW,QAAQ,QAuBlB;IAHE,uCAA4B;IAmB/B;;OAEG;IACH,oBAFW,QAAQ,GAAC,MAAM,EAIzB;IAnBD;;;;;;;;;OASG;IACH,gBAHU,QAAQ,CAKjB;IAmCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,mBAPW,MAAM,GAAC,MAAM,SACb,MAAM,GAAC,YAAY,SACnB,MAAM,GAAC,MAAM,eACb,OAAO,WACP,MAAM,wBA4BhB;IAiJD;;;OAGG;IACH,sBAFW,QAAQ,QAIlB;IAED;;;;OAIG;IACH,oBAFW,MAAM,EAAE,QAOlB;IAED;;;OAGG;IACH,aAFW,MAAM,QAqEhB;;CACD;;wBAvwB6C,sBAAsB;+BAUtC,wBAAwB;8BAC3B,2BAA2B;qBAPjC,gBAAgB;8BASV,uBAAuB;6BAVrB,0BAA0B;8BAJzB,wBAAwB;6BAGzB,oBAAoB;kCAUlB,2BAA2B"}

package/build/video/webgl/batchers/lit_mesh_batcher.d.ts

@@ -11,8 +11,22 @@
  * @category Rendering
  */
 export default class LitMeshBatcher extends MeshBatcher {
+    lightBlock: UniformBlock | undefined;
+    _lightBlockProgram: any;
+    /**
+     * Point the active program's `Light3dBlock` at our uniform buffer.
+     *
+     * A block binding is program state, so it has to be re-established
+     * whenever the program changes: a context restore recompiles it, `init`
+     * re-runs on reset, and `useShader` can swap one in without a batcher
+     * transition. Comparing against the program we last bound covers all
+     * three — a pointer compare in the steady state.
+     * @ignore
+     */
+    _bindLightBlock(): void;
     /** push the 12-float lit vertex, appending the mesh's world-space normal. @ignore */
     _pushVertex(vertexData: any, x: any, y: any, z: any, u: any, v: any, color: any, mesh: any, i3: any): void;
 }
 import MeshBatcher from "./mesh_batcher.js";
+import UniformBlock from "../buffer/uniformblock.js";
 //# sourceMappingURL=lit_mesh_batcher.d.ts.map

package/build/video/webgl/batchers/lit_mesh_batcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lit_mesh_batcher.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/batchers/lit_mesh_batcher.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;GAWG;AACH;IAqBC,qFAAqF;IACrF,2GAaC;CA0BD;wBAzFuB,mBAAmB"}
+{"version":3,"file":"lit_mesh_batcher.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/batchers/lit_mesh_batcher.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;GAWG;AACH;IAuBE,qCAIC;IACD,wBAA8B;IAO/B;;;;;;;;;OASG;IACH,wBAQC;IAyCD,qFAAqF;IACrF,2GAaC;CA4DD;wBApMuB,mBAAmB;yBAPlB,2BAA2B"}

package/build/video/webgl/batchers/lit_quad_batcher.d.ts

@@ -6,13 +6,12 @@
  * Lit-aware variant of `QuadBatcher` for the SpriteIlluminator workflow.
  *
  * Adds a 5th vertex attribute (`aNormalTextureId`) so each quad knows
- * which paired normal-map sampler to read, and bundles the per-frame
- * light uniforms (`uLightPos`, `uLightColor`, `uLightHeight`, `uAmbient`)
- * that the lit fragment shader iterates.
+ * which slot its normal map occupies, and owns the per-frame
+ * `Light2dBlock` uniform buffer that the lit fragment shader iterates.
  *
- * Texture-slot capacity is halved relative to `QuadBatcher` because each
- * sprite may need a paired (color, normal) sampler — color goes to unit
- * `n`, normal to unit `maxBatchTextures + n`. The `WebGLRenderer` only
+ * Colors and normal maps share ONE slot pool the same size as `QuadBatcher`'s
+ * (#1585) — a normal map is allocated a unit like any other texture, and
+ * `aNormalTextureId` records which one. The `WebGLRenderer` only
  * dispatches sprites here when the scene actually needs lighting (active
  * `Light2d` AND the sprite has a `normalMap`); unlit sprites stay on
  * `QuadBatcher` and pay nothing.
@@ -36,23 +35,37 @@ export default class LitQuadBatcher extends QuadBatcher {
      * @ignore
      */
     boundNormalVersions: number[] | undefined;
+    normalStore: WebGLTextureStore | undefined;
     /**
-     * Map from a normal-map source image to its uploaded GL texture and the
-     * source `version` it was uploaded at. A source that bumps its `version`
-     * (e.g. an animated {@link NoiseTexture2d}) is re-uploaded on next bind —
-     * the three.js `Texture.needsUpdate` model, scoped to normal maps which
-     * live outside the color `TextureCache`.
-     * @type {Map<HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap, {tex: WebGLTexture, version: number}>}
+     * Which slot in the shared pool each normal-map source currently holds.
+     * Normal maps are not in the color `TextureCache` (they are raw sources
+     * with their own GL textures), so their unit assignment is tracked here
+     * while the unit itself comes from the same allocator the colors use.
+     * @type {Map<HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap, number>}
      * @ignore
      */
-    normalMapTextures: Map<ImageBitmap | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas, {
-        tex: WebGLTexture;
-        version: number;
-    }> | undefined;
+    normalUnits: Map<ImageBitmap | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas, number> | undefined;
+    _cacheEpoch: any;
     _lightCount: number | undefined;
     _maxLights: number | undefined;
+    lightBlock: UniformBlock | undefined;
+    _lightBlockProgram: any;
     _onTexture2dDestroyed: ((source: any) => void) | null | undefined;
-    _normalRangeReserved: boolean | undefined;
+    /**
+     * Point the active program's `Light2dBlock` at our uniform buffer.
+     *
+     * A block binding is *program* state, and the program can change under us
+     * in three ways: a context restore recompiles it, `setBatcher` can host a
+     * {@link ShaderEffect} on this batcher, and `init` re-runs on reset. Rather
+     * than hook each of those, re-bind whenever the program is not the one we
+     * last bound — a pointer compare per `bind`, and self-healing.
+     *
+     * A hosted `ShaderEffect` is a plain unlit ES 1.00 program with no light
+     * block, so `bindTo` reports failure and we simply record it, leaving the
+     * next real lit program to bind normally.
+     * @ignore
+     */
+    _bindLightBlock(): void;
     /**
      * Release the cached GL texture uploaded for the given normal-map source
      * and clear any slot bookkeeping referencing it. Safe to call for images
@@ -61,24 +74,23 @@ export default class LitQuadBatcher extends QuadBatcher {
      */
     evictNormalMap(image: HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageBitmap): void;
     /**
-     * Bind the paired normal sampler uniforms (`uNormalSampler0..N-1`)
-     * to texture units `maxBatchTextures..2*maxBatchTextures-1`. Called
-     * from `init` and `reset`.
-     * @ignore
-     */
-    bindNormalSamplers(): void;
-    /**
-     * Upload per-frame Light2d uniforms used by the lit fragment path.
+     * Upload the per-frame Light2d data used by the lit fragment path.
      * Called once per camera per frame (before the world tree walk).
      * Lights past `MAX_LIGHTS` are silently ignored.
      *
      * Coordinates must be supplied in the same space as the renderer's
      * pre-projection vertex coords (i.e. camera-local / FBO-local),
      * matching `Stage.drawLighting`'s convention.
+     *
+     * The data goes into the `Light2dBlock` uniform buffer, which is
+     * independent of which program is current — so unlike the uniform arrays
+     * this replaced, calling it does not disturb the active shader. The
+     * upload is skipped outright when the packed bytes are unchanged, so a
+     * scene whose lights are static still costs nothing per frame.
      * @param {object} uniforms
      * @param {Float32Array} uniforms.positions - flat array of `[x, y, radius, intensity]` per light, length = 4 * count
      * @param {Float32Array} uniforms.colors - flat array of `[r, g, b]` per light, length = 3 * count
-     * @param {Float32Array} [uniforms.heights] - flat array of per-light height, length = MAX_LIGHTS
+     * @param {Float32Array} [uniforms.heights] - flat array of per-light height, length >= count
      * @param {number} uniforms.count - number of lights to render (clamped to MAX_LIGHTS)
      * @param {number[]} [uniforms.ambient] - `[r, g, b]` ambient floor (0..1 each)
      */
@@ -97,22 +109,35 @@ export default class LitQuadBatcher extends QuadBatcher {
      * but for normal-map textures which live outside the color
      * `TextureCache` (cached per-image in `normalMapTextures`).
      * @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} image - normal-map source
-     * @param {number} unit - GL texture unit (already offset by `maxBatchTextures`)
+     * @param {number} unit - GL texture unit the normal map is resolved to
      */
     bindNormalMap(image: HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageBitmap, unit: number): void;
     /**
-     * Upload a normal-map image to GL and cache the resulting `WebGLTexture`
-     * for future `bindNormalMap` calls. Not meant to be called directly —
-     * `bindNormalMap` invokes this on the first use of a given image.
+     * Drop a normal map's slot claim and hand the unit back to the allocator.
      *
-     * `premultipliedAlpha = false` — normal maps store linear-encoded
-     * surface normals; multiplying through alpha would corrupt the
-     * encoding for any non-opaque texel.
+     * A normal map claims its unit through `allocateTextureUnit()`, which has no
+     * key to release against — so without this the unit stayed marked used for
+     * the rest of the session and the pool drained monotonically as normal maps
+     * came and went, until something forced a full reset.
      * @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} image - normal-map source
-     * @param {number} unit - GL texture unit (already offset by `maxBatchTextures`)
-     * @param {number} [version=0] - the source revision being uploaded
+     * @ignore
+     */
+    releaseNormalUnit(image: HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageBitmap): void;
+    /**
+     * Resolve a normal-map source to its slot in the shared pool, uploading and
+     * binding it if it is not already resident.
+     *
+     * A version-only bump (an animated source re-baking into the same canvas
+     * reference) re-uploads into the same GL handle and needs no flush —
+     * `version` only changes between frames, and the batch is flushed at every
+     * frame/camera boundary, so no in-flight vertex references stale content.
+     * A DIFFERENT source landing on a live slot does need the pending vertices
+     * drawn first.
+     * @param {HTMLImageElement|HTMLCanvasElement|OffscreenCanvas|ImageBitmap} normalMap - the source
+     * @returns {number} the slot to write into `aNormalTextureId`
+     * @ignore
      */
-    uploadNormalMap(image: HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageBitmap, unit: number, version?: number): void;
+    resolveNormalUnit(normalMap: HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageBitmap): number;
     /**
      * Add a textured quad with optional paired normal map.
      * @param {TextureAtlas} texture - Source texture atlas
@@ -131,5 +156,7 @@ export default class LitQuadBatcher extends QuadBatcher {
     addQuad(texture: TextureAtlas, x: number, y: number, w: number, h: number, u0: number, v0: number, u1: number, v1: number, tint: number, reupload?: boolean, normalMap?: HTMLImageElement | HTMLCanvasElement | null): void;
 }
 import QuadBatcher from "./quad_batcher.js";
+import { WebGLTextureStore } from "../texture/store.js";
+import UniformBlock from "../buffer/uniformblock.js";
 import type { TextureAtlas } from "./../../texture/atlas.js";
 //# sourceMappingURL=lit_quad_batcher.d.ts.map

package/build/video/webgl/batchers/lit_quad_batcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lit_quad_batcher.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/batchers/lit_quad_batcher.js"],"names":[],"mappings":"AAMA;;;GAGG;AAEH;;;;;;;;;;;;;;;GAeG;AACH;IAsEE;;;;;;OAMG;IACH,6GAAmD;IAEnD;;;;;;;OAOG;IACH,0CAAqD;IAErD;;;;;;;;OAQG;IACH;aAHoF,YAAY;iBAAW,MAAM;mBAG/E;IAElC,gCAAoB;IACpB,+BAA4B;IAQ3B,kEAEC;IAiCD,0CAAgC;IAoBlC;;;;;OAKG;IACH,sBAFW,gBAAgB,GAAC,iBAAiB,GAAC,eAAe,GAAC,WAAW,QAcxE;IAED;;;;;OAKG;IACH,2BAOC;IA4DD;;;;;;;;;;;;;;OAcG;IACH,2BANG;QAA+B,SAAS,EAAhC,YAAY;QACW,MAAM,EAA7B,YAAY;QACY,OAAO;QACd,KAAK,EAAtB,MAAM;QACc,OAAO;KACrC,QAgBA;IAED;;;;;;;;;OASG;IACH,qBAHW,gBAAgB,GAAC,iBAAiB,GAAC,eAAe,GAAC,WAAW,QAC9D,MAAM,QAiBhB;IAED;;;;;;;;;;;OAWG;IACH,uBAJW,gBAAgB,GAAC,iBAAiB,GAAC,eAAe,GAAC,WAAW,QAC9D,MAAM,YACN,MAAM,QAwBhB;IAED;;;;;;;;;;;;;;OAcG;IACH,iBAbW,YAAY,KACZ,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QACN,MAAM,aACN,OAAO,cACP,gBAAgB,GAAC,iBAAiB,GAAC,IAAI,QAwIjD;CA8DD;wBA1kBoC,mBAAmB;kCAIzB,0BAA0B"}
+{"version":3,"file":"lit_quad_batcher.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/batchers/lit_quad_batcher.js"],"names":[],"mappings":"AAcA;;;GAGG;AAEH;;;;;;;;;;;;;;GAcG;AACH;IA8DE;;;;;;OAMG;IACH,6GAAiD;IAEjD;;;;;;;OAOG;IACH,0CAAmD;IAmBnD,2CAAiD;IAEjD;;;;;;;OAOG;IACH,2GAA4B;IAC5B,iBAAoB;IAEpB,gCAAoB;IACpB,+BAA4B;IAkB5B,qCAIC;IACD,wBAA8B;IAW7B,kEAEC;IAoCH;;;;;;;;;;;;;OAaG;IACH,wBAQC;IAED;;;;;OAKG;IACH,sBAFW,gBAAgB,GAAC,iBAAiB,GAAC,eAAe,GAAC,WAAW,QAaxE;IA8ED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,2BANG;QAA+B,SAAS,EAAhC,YAAY;QACW,MAAM,EAA7B,YAAY;QACY,OAAO;QACd,KAAK,EAAtB,MAAM;QACc,OAAO;KACrC,QAMA;IAED;;;;;;;;;OASG;IACH,qBAHW,gBAAgB,GAAC,iBAAiB,GAAC,eAAe,GAAC,WAAW,QAC9D,MAAM,QAqChB;IAED;;;;;;;;;OASG;IACH,yBAHW,gBAAgB,GAAC,iBAAiB,GAAC,eAAe,GAAC,WAAW,QAaxE;IAED;;;;;;;;;;;;;OAaG;IACH,6BAJW,gBAAgB,GAAC,iBAAiB,GAAC,eAAe,GAAC,WAAW,GAC5D,MAAM,CAsClB;IAED;;;;;;;;;;;;;;OAcG;IACH,iBAbW,YAAY,KACZ,MAAM,KACN,MAAM,KACN,MAAM,KACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,QACN,MAAM,aACN,OAAO,cACP,gBAAgB,GAAC,iBAAiB,GAAC,IAAI,QAsIjD;CA+DD;wBA3qBuB,mBAAmB;kCADT,qBAAqB;yBAT9B,2BAA2B;kCAcrB,0BAA0B"}

package/build/video/webgl/batchers/material_batcher.d.ts

@@ -1,13 +1,9 @@
-/**
- * additional import for TypeScript
- * @import {TextureAtlas} from "./../../texture/atlas.js";
- */
-/**
- * Base class for batchers that manage WebGL textures and material properties.
- * Provides texture creation, binding, uploading, and deletion.
- * @category Rendering
- */
-export class MaterialBatcher extends Batcher {
+export class MaterialBatcher extends WebGLBatcher {
+    /**
+     * Initialize the textured batcher
+     * @ignore
+     */
+    init(renderer: any, settings: any): void;
     set currentTextureUnit(unit: number);
     /**
      * The GL texture unit currently active (`gl.activeTexture`). Tracked on
@@ -27,6 +23,17 @@ export class MaterialBatcher extends Batcher {
      * @ignore
      */
     boundTextures: any[] | undefined;
+    /**
+     * Units whose texture CONTENT changed since the last upload (a
+     * canvas re-bake announced via `CanvasRenderTarget.invalidate`).
+     * Consumed by {@link MaterialBatcher#uploadTexture}, which then
+     * re-uploads INTO the existing texture — with immutable storage a
+     * same-shape re-upload is a pure `texSubImage2D`, so a ticking
+     * Text / gradient re-bake never re-allocates.
+     * @type {Set<number>}
+     * @ignore
+     */
+    dirtyUnits: Set<number> | undefined;
     _onCacheReset: (() => void) | null | undefined;
     /**
      * Drop every cached texture binding after a {@link GPU_TEXTURE_CACHE_RESET}
@@ -37,14 +44,6 @@ export class MaterialBatcher extends Batcher {
      * @ignore
      */
     _onTextureCacheReset(): void;
-    /**
-     * Free resources used by the batcher. Currently unsubscribes the
-     * texture-cache-reset listener so a discarded batcher doesn't keep
-     * accumulating handlers (relevant on context loss / renderer
-     * teardown).
-     * @ignore
-     */
-    destroy(): void;
     /**
      * Create a WebGL texture from an image
      * @param {number} unit - Destination texture unit
@@ -81,7 +80,17 @@ export class MaterialBatcher extends Batcher {
      * @param {number} [unit] - Texture unit to unbind from
      * @returns {number} unit the unit number that was associated with the given texture
      */
-    unbindTexture2D(texture?: WebGLTexture, unit?: number): number;
+    /**
+     * Announce that the SOURCE content behind `unit` changed (same object,
+     * new pixels — a canvas re-bake): the next {@link MaterialBatcher#uploadTexture}
+     * for it re-uploads into the existing texture in place instead of
+     * discarding it. The allocation-preserving counterpart of
+     * {@link MaterialBatcher#unbindTexture2D}.
+     * @param {number} unit - the texture unit whose content is stale
+     * @ignore
+     */
+    markTextureDirty(unit: number): void;
+    unbindTexture2D(texture: any, unit: any): any;
     /**
      * Forget whatever texture this batcher believes is bound to `unit`, so the
      * next bind to it re-issues the GL bind. Used when a GL texture unit is
@@ -112,6 +121,6 @@ export class MaterialBatcher extends Batcher {
      */
     uploadTexture(texture: TextureAtlas | TextureResource, w?: number, h?: number, force?: boolean, flush?: boolean, repeat?: string): any;
 }
-import { Batcher } from "./batcher.js";
+import { WebGLBatcher } from "./batcher.js";
 import type { TextureAtlas } from "./../../texture/atlas.js";
 //# sourceMappingURL=material_batcher.d.ts.map

package/build/video/webgl/batchers/material_batcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"material_batcher.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/batchers/material_batcher.js"],"names":[],"mappings":"AAIA;;;GAGG;AAEH;;;;GAIG;AACH;IA6EC,6BAPU,MAAM,EASf;IAlBD;;;;;;;;;;;OAWG;IACH,0BAHU,MAAM,CAKf;IA/DA;;;OAGG;IACH,iCAAuB;IAwBtB,+CAEC;IAKH;;;;;;;OAOG;IACH,6BAIC;IAsBD;;;;;;OAMG;IACH,gBAKC;IAmBD;;;;;;;;;;;OAWG;IACH,sBAVW,MAAM,WACN,8DAAM,iBAAiB,GAAC,SAAS,GAAC,UAAU,EAAE,GAAC,YAAY,EAAE,UAC7D,MAAM,WACN,MAAM,MACN,MAAM,MACN,MAAM,uBACN,OAAO,WACP,OAAO,kCACL,YAAY,CAmKxB;IAED;;;OAGG;IACH,yBAFW,YAAY,GAAC,YAAY,QAgCnC;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACJ,YAAY,CAIxB;IAED;;;;OAIG;IACH,uBAHW,YAAY,QACZ,MAAM,yBAsBhB;IAED;;;;;OAKG;IACH,0BAJW,YAAY,SACZ,MAAM,GACJ,MAAM,CAalB;IAED;;;;;;;;;;;OAWG;IACH,qBAHW,MAAM,QAQhB;IAED;;;;;;;;;;;;;;OAcG;IACH,uBAbW,YAAY,GAAC,eAAe,MAC5B,MAAM,MAGN,MAAM,UACN,OAAO,UACP,OAAO,WACP,MAAM,OAsDhB;CACD;wBAzduB,cAAc;kCAIP,0BAA0B"}
+{"version":3,"file":"material_batcher.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/batchers/material_batcher.js"],"names":[],"mappings":"AAgCA;IACC;;;OAGG;IACH,yCAoDC;IAiCD,6BAPU,MAAM,EASf;IAlBD;;;;;;;;;;;OAWG;IACH,0BAHU,MAAM,CAKf;IA5EA;;;OAGG;IACH,iCAAuB;IAEvB;;;;;;;;;OASG;IACH,oCAA2B;IAwB1B,+CAEC;IAKH;;;;;;;OAOG;IACH,6BAKC;IAsDD;;;;;;;;;;;OAWG;IACH,sBAVW,MAAM,WACN,8DAAM,iBAAiB,GAAC,SAAS,GAAC,UAAU,EAAE,GAAC,YAAY,EAAE,UAC7D,MAAM,WACN,MAAM,MACN,MAAM,MACN,MAAM,uBACN,OAAO,WACP,OAAO,kCACL,YAAY,CAoKxB;IAED;;;OAGG;IACH,yBAFW,YAAY,GAAC,YAAY,QAuCnC;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACJ,YAAY,CAIxB;IAED;;;;OAIG;IACH,uBAHW,YAAY,QACZ,MAAM,yBAsBhB;IAED;;;;;OAKG;IACH;;;;;;;;OAQG;IACH,uBAHW,MAAM,QAKhB;IAED,8CAWC;IAED;;;;;;;;;;;OAWG;IACH,qBAHW,MAAM,QAQhB;IAED;;;;;;;;;;;;;;OAcG;IACH,uBAbW,YAAY,GAAC,eAAe,MAC5B,MAAM,MAGN,MAAM,UACN,OAAO,UACP,OAAO,WACP,MAAM,OA2GhB;CACD;6BApkB4B,cAAc;kCAIZ,0BAA0B"}