melonjs 19.9.1 → 20.1.0

package/build/video/webgl/buffer/vertexstate.d.ts

@@ -0,0 +1,101 @@
+/**
+ * A WebGL Vertex State — a Vertex Array Object owning a frozen vertex
+ * buffer layout: one `vertexAttribPointer` / `enableVertexAttribArray` per
+ * attribute against a given vertex buffer, plus the ELEMENT_ARRAY_BUFFER
+ * binding when the geometry is indexed.
+ *
+ * This is the engine's `GPUVertexState` analogue, and the layout it is built
+ * from is a `GPUVertexBufferLayout[]`: a list of buffer groups, each with its
+ * own buffer, `arrayStride` and `stepMode`. Attributes in a `"vertex"` group
+ * advance once per vertex (the ordinary case); attributes in an
+ * `"instance"` group advance once per *instance*, which is what
+ * `drawElementsInstanced` reads to stamp out N copies of one geometry.
+ * The layout is immutable once built, exactly like a vertex layout baked
+ * into a render pipeline.
+ *
+ * Attribute divisors are vertex-array state, so a fresh VAO starts with every
+ * divisor at 0 and `build()` creates one each time — an instanced layout can
+ * therefore never leak its divisors into an unrelated vertex state, and the
+ * single-buffer path issues no `vertexAttribDivisor` calls at all.
+ *
+ * Every method that mutates GL binding state saves and restores the live
+ * bindings itself, so building or rebuilding one vertex state can never
+ * disturb whichever one is mid-frame. Callers never touch
+ * `bindVertexArray` directly.
+ * @ignore
+ */
+export default class WebGLVertexState {
+    /**
+     * Accepts either shape — the single-buffer one (`attributes` + `stride` +
+     * `buffer`) or a list of buffer groups (`buffers`). They are equivalent;
+     * the former is the latter with one `"vertex"` group.
+     * @param {WebGL2RenderingContext} gl - the WebGL context
+     * @param {object} descriptor - the vertex layout to realize
+     * @param {object[]} [descriptor.attributes] - attribute definitions (`name`, `size`, `type`, `normalized`, `offset`)
+     * @param {number} [descriptor.stride] - size of a single vertex in bytes (`arrayStride`)
+     * @param {WebGLBuffer} [descriptor.buffer] - the vertex buffer the attribute pointers read from
+     * @param {object[]} [descriptor.buffers] - buffer groups, each `{buffer, stride, attributes, stepMode}` where `stepMode` is `"vertex"` (default) or `"instance"`
+     * @param {Function} descriptor.resolveLocation - maps an attribute name to its shader location (`-1` when absent)
+     * @param {WebGLIndexBuffer} [descriptor.indexBuffer] - index buffer to capture, for indexed geometry
+     */
+    constructor(gl: WebGL2RenderingContext, descriptor: {
+        attributes?: object[] | undefined;
+        stride?: number | undefined;
+        buffer?: WebGLBuffer | undefined;
+        buffers?: object[] | undefined;
+        resolveLocation: Function;
+        indexBuffer?: any;
+    });
+    gl: WebGL2RenderingContext;
+    descriptor: {
+        attributes?: object[] | undefined;
+        stride?: number | undefined;
+        buffer?: WebGLBuffer | undefined;
+        buffers?: object[] | undefined;
+        resolveLocation: Function;
+        indexBuffer?: WebGLIndexBuffer;
+    };
+    /**
+     * the underlying GL vertex array object
+     * @type {WebGLVertexArrayObject}
+     */
+    handle: WebGLVertexArrayObject;
+    /**
+     * (Re)build the vertex array object from this state's descriptor,
+     * replacing any previous one. Called on construction and from every
+     * buffer-recreation path — a vertex state referencing a deleted buffer
+     * keeps it alive per the GL spec and draws stale data.
+     * @param {object} [changes] - descriptor fields to replace first (e.g. recreated `buffer` / `buffers` / `indexBuffer`)
+     */
+    build(changes?: object): void;
+    /**
+     * Capture an ELEMENT_ARRAY_BUFFER binding into this vertex state.
+     * Used when an index buffer is (re)created after the state was built —
+     * the quad batchers' static pattern buffer — since that binding is
+     * vertex-array state and would otherwise land in whichever state
+     * happens to be bound.
+     * @param {WebGLIndexBuffer} indexBuffer - the index buffer to capture
+     * @param {Function} [fill] - optional work to run with this state bound (buffer creation/upload)
+     */
+    captureIndexBuffer(indexBuffer: WebGLIndexBuffer, fill?: Function): void;
+    /**
+     * Make this vertex state current. One call restores the entire frozen
+     * layout — the WebGL analogue of `setPipeline` + `setVertexBuffer` +
+     * `setIndexBuffer`.
+     */
+    bind(): void;
+    /**
+     * Delete the underlying vertex array object, if any. Idempotent, and
+     * safe on a lost context: deleting an object belonging to a lost
+     * context would queue `INVALID_OPERATION` (deletion counts as *using*
+     * it — only the `is*` queries are exempt), so probe first.
+     */
+    release(): void;
+    /**
+     * Release the vertex array object. The vertex state must not be used
+     * after calling destroy.
+     */
+    destroy(): void;
+    #private;
+}
+//# sourceMappingURL=vertexstate.d.ts.map

package/build/video/webgl/buffer/vertexstate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vertexstate.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/buffer/vertexstate.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IACC;;;;;;;;;;;;OAYG;IACH,gBATW,sBAAsB,cAE9B;QAA8B,UAAU;QACZ,MAAM;QACD,MAAM;QACT,OAAO;QACR,eAAe;QACN,WAAW;KACnD,EAUA;IARA,2BAAY;IACZ;;;;;;sBAJU,gBAAgB;MAIE;IAC5B;;;OAGG;IACH,QAFU,sBAAsB,CAEd;IAyBnB;;;;;;OAMG;IACH,gBAFW,MAAM,QA4EhB;IAED;;;;;;;;OAQG;IACH,gCAHW,gBAAgB,yBAa1B;IAED;;;;OAIG;IACH,aAEC;IAED;;;;;OAKG;IACH,gBAOC;IAED;;;OAGG;IACH,gBAGC;;CACD"}

package/build/video/webgl/glshader.d.ts

@@ -1,12 +1,40 @@
 /**
- * a base GL Shader object
+ * a complete custom shader program. Historically a WebGL-only GLSL
+ * program (the class keeps its name for compatibility), since 20.0 it can
+ * carry one realization per GPU backend — a `{vertex, fragment}` GLSL
+ * pair for the WebGL renderer and/or a complete `wgsl` module for the
+ * WebGPU renderer — mirroring how {@link ShaderEffect} carries one body
+ * per shading language. The {@link GLShader#isWebGL} / {@link GLShader#isWebGPU}
+ * flags report which realizations exist; a renderer hosts the one it
+ * speaks and anything else degrades to the built-in shading (never fatal).
+ *
+ * ### The WGSL module contract (custom `Mesh` shaders)
+ *
+ * The `wgsl` source is a complete module hosted by the mesh batchers:
+ * entry points must be named **`vertex_main`** (`@vertex`) and
+ * **`fragment_main`** (`@fragment`), over the frozen mesh vertex layout —
+ * `@location(0) aVertex : vec3f`, `@location(1) aRegion : vec2f`,
+ * `@location(2) aColor : vec4f`, plus `@location(3) aNormal : vec3f` on
+ * the 48-byte `lit` layout. Bind groups (declare only what is read):
+ * group 0 `FrameUniforms {projection : mat4x4<f32>, lineWidth : f32}`,
+ * group 1 the mesh texture + sampler, group 2 the `Light3dBlock` (lit
+ * host only), group 3 `MeshUniforms {model, view : mat4x4<f32>,
+ * tint, params, emissive : vec4f}` (`params.x` = alpha cutout). The
+ * vertex stage owns the projection (`projection * view * model`) and must
+ * remap the GL-convention clip z: `(clip.z + clip.w) * 0.5`. WGSL
+ * validation is asynchronous and never throws — a failing module logs its
+ * errors once and the mesh falls back to the built-in shading.
  * @category Rendering
  */
 export default class GLShader {
     /**
-     * @param {WebGLRenderingContext} gl - the current WebGL rendering context
-     * @param {string} vertex - a string containing the GLSL source code to set
-     * @param {string} fragment - a string containing the GLSL source code to set
+     * @param {WebGLRenderingContext} [gl] - the current WebGL rendering
+     * context (`renderer.gl` — undefined on non-WebGL renderers, which
+     * simply skips the GLSL realization)
+     * @param {string|object} vertex - a string containing the GLSL vertex
+     * source, OR a sources object `{vertex, fragment, wgsl, precision,
+     * label}` carrying one realization per backend (any omittable)
+     * @param {string} [fragment] - a string containing the GLSL fragment source
      * @param {string} [precision=auto detected] - float precision ('lowp', 'mediump' or 'highp').
      * @see https://developer.mozilla.org/en-US/docs/Games/Techniques/3D_on_the_web/GLSL_Shaders
      * @example
@@ -29,13 +57,51 @@ export default class GLShader {
      *  )
      * // use the shader
      * myShader.bind();
+     * @example
+     * // a dual-backend custom mesh shader: the same object hosts on
+     * // whichever GPU renderer is active (gl is undefined on WebGPU)
+     * myMesh.shader = new me.GLShader(app.renderer.gl, {
+     *     vertex: toonVertexGLSL,
+     *     fragment: toonFragmentGLSL,
+     *     wgsl: toonModuleWGSL,
+     * });
      */
-    constructor(gl: WebGLRenderingContext, vertex: string, fragment: string, precision?: string);
+    constructor(gl?: WebGLRenderingContext, vertex: string | object, fragment?: string, precision?: string);
     /**
      * the active gl rendering context
      * @type {WebGLRenderingContext}
      */
     gl: WebGLRenderingContext;
+    /**
+     * `true` when this shader carries a WebGL realization: a
+     * `{vertex, fragment}` GLSL pair compiled against a live context.
+     * @type {boolean}
+     * @readonly
+     */
+    readonly isWebGL: boolean;
+    /**
+     * `true` when this shader carries a WebGPU realization: a complete
+     * `wgsl` module (see the class docs for the module contract).
+     * @type {boolean}
+     * @readonly
+     */
+    readonly isWebGPU: boolean;
+    /**
+     * the complete WGSL module source, when {@link GLShader#isWebGPU}
+     * @type {string|undefined}
+     */
+    wgsl: string | undefined;
+    /**
+     * optional debug label, carried onto the GPU shader module (shows
+     * up in browser GPU error messages and profilers)
+     * @type {string|undefined}
+     */
+    label: string | undefined;
+    wgslValid: boolean;
+    _wgslRegistrations: {
+        epoch: number;
+        keys: Map<any, any>;
+    };
     /**
      * `true` once {@link destroy} has been called. After this flag is
      * `true`, every method on the shader is a silent no-op — callers
@@ -68,8 +134,8 @@ export default class GLShader {
      * @readonly
      */
     readonly suspended: boolean;
-    _sourceVertex: string;
-    _sourceFragment: string;
+    _sourceVertex: string | object;
+    _sourceFragment: string | undefined;
     _precision: string | undefined;
     _uniformCache: any;
     program: WebGLProgram;
@@ -118,7 +184,15 @@ export default class GLShader {
      */
     setUniform(name: string, value: object | Float32Array): void;
     /**
-     * activate the given vertex attribute for this shader
+     * activate the given vertex attribute for this shader.
+     *
+     * Note: since 20.0 the engine no longer calls this per frame — each
+     * {@link WebGLBatcher} captures its attribute layout once into an immutable
+     * vertex-state object (VAO) at init (see `WebGLBatcher.createVertexState`).
+     * Kept public for custom callers managing their own vertex setup.
+     * Custom shaders hosted by a built-in batcher must declare that
+     * batcher's attributes first, in layout order — attribute locations
+     * are bound in declaration order and the vertex state is frozen.
      * @param {WebGLRenderingContext} gl - the current WebGL rendering context
      * @param {object[]} attributes - an array of vertex attributes
      * @param {number} stride - the size of a single vertex in bytes
@@ -142,6 +216,25 @@ export default class GLShader {
      * @returns {GLShader} a new, caller-owned shader (`shared === false`)
      */
     clone(): GLShader;
+    /**
+     * Register this shader's WGSL module as a pipeline family for one
+     * hosting mesh batcher, against that host's positional group-layout
+     * list and frozen vertex layout. Registered once per host per device
+     * generation; the module text is namespaced by the host key so the
+     * same shader yields distinct families (distinct pipeline layouts) on
+     * the unlit and lit hosts. Asynchronous WGSL validation errors flip
+     * {@link GLShader#wgslValid} and the host falls back to its built-in
+     * shading (warn-and-degrade, never fatal).
+     * @param {object} cache - the WebGPU renderer's pipeline cache
+     * @param {string} host - the hosting family's vertex-layout key
+     * @param {GPUBindGroupLayout[]} bindGroupLayouts - the host's group list
+     * @param {string} vertexLayoutKey - the host's registered vertex layout
+     * @returns {string|null} the family key to pass to the pipeline cache's
+     *   `get`, or null when the module failed validation on this device
+     *   generation (the host then uses its built-in family)
+     * @ignore
+     */
+    registerWGSL(cache: object, host: string, bindGroupLayouts: GPUBindGroupLayout[], vertexLayoutKey: string): string | null;
     /**
      * destroy this shader objects resources (program, attributes, uniforms).
      * Idempotent — calling destroy twice (or after a context-lost suspend)

package/build/video/webgl/glshader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"glshader.d.ts","sourceRoot":"","sources":["../../../src/video/webgl/glshader.js"],"names":[],"mappings":"AAYA;;;GAGG;AACH;IACC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,gBA1BW,qBAAqB,UACrB,MAAM,YACN,MAAM,cACN,MAAM,EAqFhB;IA7DA;;;OAGG;IACH,IAFU,qBAAqB,CAEnB;IAEZ;;;;;;;OAOG;IACH,oBAHU,OAAO,CAGK;IAEtB;;;;;;;;;OASG;IACH,QAHU,OAAO,CAGE;IAEnB;;;;;;;;;;OAUG;IACH,oBAHU,OAAO,CAGK;IAGtB,sBAA2B;IAC3B,wBAA+B;IAC/B,+BAA2B;IAG3B,mBAAwC;IAKvC,sBAAmB;IACnB,iBAAoB;IACpB,qBAAsB;IASxB;;;;;;OAMG;IACH,iBA0CC;IAzCA,YAGC;IACD,cAGC;IAoCF;;;;;OAKG;IACH,uBAgBC;IAED;;;;;OAKG;IACH,2BAMC;IAED;;OAEG;IACH,aAKC;IAED;;;;OAIG;IACH,wBAHW,MAAM,GACJ,KAAK,CAYjB;IAED;;;;;;OAMG;IACH,iBALW,MAAM,SACN,MAAM,GAAC,YAAY,QA0C7B;IAED;;;;;OAKG;IACH,wBAJW,qBAAqB,cACrB,MAAM,EAAE,UACR,MAAM,QAmBhB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,SAFa,QAAQ,CAyBpB;IAED;;;;;OAKG;IACH,gBA2BC;CACD"}
+{"version":3,"file":"glshader.d.ts","sourceRoot":"","sources":["../../../src/video/webgl/glshader.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IACC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH,iBAtCW,qBAAqB,UAGrB,MAAM,GAAC,MAAM,aAGb,MAAM,cACN,MAAM,EAiKhB;IArHA;;;OAGG;IACH,IAFU,qBAAqB,CAEnB;IAEZ;;;;;OAKG;IACH,kBAHU,OAAO,CAIwD;IAEzE;;;;;OAKG;IACH,mBAHU,OAAO,CAGuB;IAExC;;;OAGG;IACH,MAFU,MAAM,GAAC,SAAS,CAEV;IAEhB;;;;OAIG;IACH,OAFU,MAAM,GAAC,SAAS,CAER;IAIlB,mBAAqB;IAKrB;;;MAAwD;IAWxD;;;;;;;OAOG;IACH,oBAHU,OAAO,CAGK;IAEtB;;;;;;;;;OASG;IACH,QAHU,OAAO,CAGE;IAEnB;;;;;;;;;;OAUG;IACH,oBAHU,OAAO,CAGK;IAGtB,+BAA2B;IAC3B,oCAA+B;IAC/B,+BAA2B;IAG3B,mBAAwC;IAMtC,sBAAmB;IACnB,iBAAoB;IACpB,qBAAsB;IAgBzB;;;;;;OAMG;IACH,iBA0CC;IAzCA,YAGC;IACD,cAGC;IAoCF;;;;;OAKG;IACH,uBAgBC;IAED;;;;;OAKG;IACH,2BAMC;IAED;;OAEG;IACH,aAMC;IAED;;;;OAIG;IACH,wBAHW,MAAM,GACJ,KAAK,CAcjB;IAED;;;;;;OAMG;IACH,iBALW,MAAM,SACN,MAAM,GAAC,YAAY,QA4C7B;IAED;;;;;;;;;;;;;OAaG;IACH,wBAJW,qBAAqB,cACrB,MAAM,EAAE,UACR,MAAM,QAmBhB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,SAFa,QAAQ,CA8BpB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,oBATW,MAAM,QACN,MAAM,oBACN,kBAAkB,EAAE,mBACpB,MAAM,GACJ,MAAM,GAAC,IAAI,CAgFvB;IAED;;;;;OAKG;IACH,gBAkCC;CACD"}

package/build/video/webgl/lighting/constants.d.ts

@@ -1,13 +1,25 @@
 /**
- * Constants shared between the lit fragment shader (`multitexture-lit.js`),
- * the lit batcher (`LitQuadBatcher`), and the uniform packer (`pack.ts`).
- * Kept in a tiny standalone module so the three consumers don't depend on
- * each other transitively for a single integer.
+ * Constants shared between the lit fragment shaders
+ * (`multitexture-lit.js`, `mesh-lit.frag`), the lit batchers
+ * (`LitQuadBatcher`, `LitMeshBatcher`), the uniform packers (`pack.ts`,
+ * `pack3d.ts`) and the std140 writer (`std140.ts`). Kept in a tiny
+ * standalone module so the consumers don't depend on each other
+ * transitively for a couple of integers.
  */
 /**
- * Maximum number of `Light2d` instances the lit fragment shader supports
- * concurrently per draw call. Lights past this index are ignored. Sized
- * to keep the GLSL uniform arrays comfortably within WebGL1 limits.
+ * Maximum number of lights the lit fragment shaders support concurrently
+ * per draw call. Lights past this index are ignored.
+ *
+ * The data travels in a uniform buffer, so this is an allocation rather
+ * than a compatibility question: 32 lights cost 1056 bytes against
+ * `MAX_UNIFORM_BLOCK_SIZE`, which is at least 16 KB everywhere. Uniform
+ * _arrays_, the previous transport, are charged against the much smaller
+ * `MAX_FRAGMENT_UNIFORM_VECTORS` — shared with every other uniform the
+ * shader declares — which is what held this at 8.
+ *
+ * It is not a statement about what a device can afford to _shade_: the
+ * fragment loop still runs once per pixel per live light. Unused capacity
+ * is free — the loop bound is the live count — but filling it is not.
  */
-export declare const MAX_LIGHTS = 8;
+export declare const MAX_LIGHTS = 32;
 //# sourceMappingURL=constants.d.ts.map

package/build/video/webgl/lighting/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/lighting/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,eAAO,MAAM,UAAU,IAAI,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/lighting/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU,KAAK,CAAC"}

package/build/video/webgl/lighting/pack.d.ts

@@ -58,7 +58,7 @@ interface ColorLike {
  * the lit fragment's `lightPos - vWorldPos` math lines up with the
  * camera's view.
  *
- * Lights past `MAX_LIGHTS` (8) are silently dropped. Unused slots are
+ * Lights past `MAX_LIGHTS` are silently dropped. Unused slots are
  * zero-filled so stale data from a previous frame can't leak into the
  * shader.
  *

package/build/video/webgl/lighting/pack3d.d.ts

@@ -4,26 +4,42 @@ import type { Light3d } from "../../../lighting/light3d.ts";
  * @ignore
  */
 export interface PackedMeshLighting {
-    /** number of active directional lights, clamped to `MAX_LIGHTS`. */
+    /** number of active shaded lights, clamped to `MAX_LIGHTS`. */
     count: number;
-    /** `MAX_LIGHTS × 3` surface→light directions (already negated, normalized). */
-    directions: Float32Array;
-    /** `MAX_LIGHTS × 3` directional light colors premultiplied by intensity. */
-    colors: Float32Array;
+    /**
+     * `MAX_LIGHTS × 4` — `[x, y, z, range]` per light; `range` is `-1` for
+     * directional lights (the shader's type sentinel).
+     */
+    posRange: Float32Array;
+    /**
+     * `MAX_LIGHTS × 4` — `[dx, dy, dz, cos(outerConeAngle)]` per light;
+     * `cosOuter` is `-1` when no cone applies (directional carries the
+     * pre-negated surface→light vector, point carries no direction).
+     */
+    dirCone: Float32Array;
+    /**
+     * `MAX_LIGHTS × 4` — `[r, g, b, cos(innerConeAngle)]` per light,
+     * color premultiplied by intensity.
+     */
+    colorInner: Float32Array;
     /** the summed ambient color (RGB, 0..1+). */
     ambient: Float32Array;
 }
 /**
  * Pack an iterable of {@link Light3d} (e.g. the active `Stage`'s 3D-light set)
- * into the uniform arrays the mesh-lit shader reads:
- * - **directional** lights contribute a surface→light direction (negated travel
- *   direction, normalized) + a color premultiplied by intensity, up to
- *   `MAX_LIGHTS`. Re-normalized here so a direction mutated at runtime without
+ * into the std140-ready arrays the mesh-lit shader reads:
+ * - **directional** lights contribute a surface→light direction (negated
+ *   travel direction, normalized) + a color premultiplied by intensity.
+ *   Re-normalized here so a direction mutated at runtime without
  *   re-normalizing still shades correctly.
+ * - **point** lights contribute their world position, `range` (quadratic
+ *   falloff over the range — the Light2d model) and premultiplied color.
+ * - **spot** lights add their travel direction and the cone cosines
+ *   (`innerConeAngle` clamped just inside `outerConeAngle`, so the
+ *   smoothstep denominator never collapses).
  * - **ambient** lights are summed into a single flat ambient color.
  *
- * Other types (`"point"`) are skipped — not shaded yet. The same buffers are
- * returned each call (overwritten in place).
+ * The same buffers are returned each call (overwritten in place).
  * @param lights - iterable of lights, or `null`/`undefined` (treated as empty)
  * @returns the packed lighting (reused instance)
  * @ignore

package/build/video/webgl/lighting/pack3d.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pack3d.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/lighting/pack3d.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAG5D;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,UAAU,EAAE,YAAY,CAAC;IACzB,4EAA4E;IAC5E,MAAM,EAAE,YAAY,CAAC;IACrB,6CAA6C;IAC7C,OAAO,EAAE,YAAY,CAAC;CACtB;AAcD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAC1C,kBAAkB,CAuCpB"}
+{"version":3,"file":"pack3d.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/lighting/pack3d.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAG5D;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,EAAE,YAAY,CAAC;IACvB;;;;OAIG;IACH,OAAO,EAAE,YAAY,CAAC;IACtB;;;OAGG;IACH,UAAU,EAAE,YAAY,CAAC;IACzB,6CAA6C;IAC7C,OAAO,EAAE,YAAY,CAAC;CACtB;AAgBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAC1C,kBAAkB,CAuFpB"}

package/build/video/webgl/lighting/std140.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Header, occupying two `vec4`s before the light array begins.
+ *
+ * ```glsl
+ * int  count;     // offset 0
+ * vec3 ambient;   // offset 16 — a vec3 aligns to 16, so it cannot share
+ * ```
+ *
+ * `count` is written as a float and read back with `int(...)` in the
+ * shader. Declaring it `int` in the block would be tidier, but mixing int
+ * and float members means the staging buffer can no longer be a single
+ * `Float32Array` view, and the cast is free on every GPU that matters.
+ * @ignore
+ */
+export declare const HEADER_FLOATS: number;
+/**
+ * floats occupied by one light: two `vec4`s
+ * @ignore
+ */
+export declare const LIGHT_FLOATS: number;
+/**
+ * total floats in a light block, header included
+ * @ignore
+ */
+export declare const BLOCK_FLOATS: number;
+/**
+ * total bytes in a light block
+ * @ignore
+ */
+export declare const BLOCK_BYTES: number;
+/**
+ * Lay out 2D (`Light2d`) data.
+ *
+ * ```glsl
+ * struct Light2dData {
+ *   vec4 posRadiusIntensity;  // x, y, radius, intensity
+ *   vec4 colorHeight;         // r, g, b, lightHeight
+ * };
+ * ```
+ * @param out - staging buffer, at least `BLOCK_FLOATS` long
+ * @param packed - what {@link packLights} produced
+ * @param packed.count - number of live lights, clamped to `MAX_LIGHTS`
+ * @param packed.positions - `[x, y, radius, intensity]` per light
+ * @param packed.colors - `[r, g, b]` per light, 0..1 per channel
+ * @param packed.heights - per-light height; absent means 0
+ * @param packed.ambient - `[r, g, b]` ambient floor; absent means black
+ * @returns how many floats of `out` are live, for a partial upload
+ * @ignore
+ */
+export declare function writeLight2dBlock(out: Float32Array, packed: {
+    count: number;
+    positions: Float32Array;
+    colors: Float32Array;
+    heights?: Float32Array;
+    ambient?: ArrayLike<number>;
+}): number;
+/**
+ * floats occupied by one 3D light: three `vec4`s. The 3D block grew from
+ * two when point/spot shading landed (#1536) — a spot light needs position
+ * + range + direction + both cone cosines + color, which cannot fold into
+ * two vec4s' padding. The 2D block keeps its two-vec4 stride.
+ * @ignore
+ */
+export declare const LIGHT3D_FLOATS: number;
+/**
+ * total floats in a 3D light block, header included
+ * @ignore
+ */
+export declare const BLOCK3D_FLOATS: number;
+/**
+ * total bytes in a 3D light block
+ * @ignore
+ */
+export declare const BLOCK3D_BYTES: number;
+/**
+ * Lay out 3D (`Light3d`) data.
+ *
+ * ```glsl
+ * struct Light3dData {
+ *   vec4 posRange;    // x, y, z = world position · w = range;
+ *                     //   w < 0 marks a DIRECTIONAL light (xyz unused)
+ *   vec4 dirCone;     // x, y, z = direction · w = cos(outerConeAngle);
+ *                     //   w = -1 marks "no cone" (directional dir is the
+ *                     //   pre-negated surface→light vector; a point light
+ *                     //   carries no direction)
+ *   vec4 colorInner;  // r, g, b = color × intensity · w = cos(innerConeAngle)
+ * };
+ * ```
+ *
+ * The type is inferred from the sentinels rather than a tag slot:
+ * `posRange.w < 0` → directional; otherwise positional, with a cone
+ * applied when `dirCone.w > -1`.
+ * @param out - staging buffer, at least `BLOCK3D_FLOATS` long
+ * @param packed - what {@link packMeshLights} produced
+ * @param packed.count - number of live lights, clamped to `MAX_LIGHTS`
+ * @param packed.posRange - `[x, y, z, range]` per light (range -1 for directional)
+ * @param packed.dirCone - `[dx, dy, dz, cosOuter]` per light (cosOuter -1 for none)
+ * @param packed.colorInner - `[r, g, b, cosInner]` per light
+ * @param packed.ambient - `[r, g, b]` ambient floor; absent means black
+ * @returns how many floats of `out` are live, for a partial upload
+ * @ignore
+ */
+export declare function writeLight3dBlock(out: Float32Array, packed: {
+    count: number;
+    posRange: Float32Array;
+    dirCone: Float32Array;
+    colorInner: Float32Array;
+    ambient?: ArrayLike<number>;
+}): number;
+//# sourceMappingURL=std140.d.ts.map

package/build/video/webgl/lighting/std140.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"std140.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/lighting/std140.ts"],"names":[],"mappings":"AAsCA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,QAAW,CAAC;AAEtC;;;GAGG;AACH,eAAO,MAAM,YAAY,QAAW,CAAC;AAErC;;;GAGG;AACH,eAAO,MAAM,YAAY,QAA4C,CAAC;AAEtE;;;GAGG;AACH,eAAO,MAAM,WAAW,QAAgD,CAAC;AA0BzE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAChC,GAAG,EAAE,YAAY,EACjB,MAAM,EAAE;IACP,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,YAAY,CAAC;IACxB,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,OAAO,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;CAC5B,GACC,MAAM,CAkCR;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,QAAW,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,cAAc,QAA8C,CAAC;AAE1E;;;GAGG;AACH,eAAO,MAAM,aAAa,QAAkD,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAChC,GAAG,EAAE,YAAY,EACjB,MAAM,EAAE;IACP,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,YAAY,CAAC;IACzB,OAAO,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;CAC5B,GACC,MAAM,CA4BR"}

package/build/video/webgl/shaders/multitexture-lit.d.ts

@@ -7,17 +7,21 @@
  * unlit fast path inside this same shader (sample color, multiply by
  * vertex color, return) so lit and unlit sprites can share the lit batch
  * when they coexist with active lights. The cost vs the truly-unlit
- * `QuadBatcher` shader is one varying read + one comparison per fragment.
+ * `QuadBatcher` shader is one interpolated read + one comparison per
+ * fragment.
  *
  * The light's "height above the sprite plane" is encoded as a small
  * fraction of the light's radius (default `0.075`) so that lights
  * exactly at a fragment's screen position don't produce degenerate
  * flat shading.
+ *
+ * GLSL ES 3.00, because the light data arrives in a uniform block and
+ * blocks do not exist in ES 1.00 (see #1552). The paired vertex shader
+ * `quad-multi-lit.vert` is on the same version — both stages of a program
+ * must agree.
  * @param {number} maxTextures - the number of color/normal texture units to support
  * @returns {string} GLSL fragment shader source
  * @ignore
  */
 export function buildLitMultiTextureFragment(maxTextures: number): string;
-export { MAX_LIGHTS };
-import { MAX_LIGHTS } from "../lighting/constants.ts";
 //# sourceMappingURL=multitexture-lit.d.ts.map

package/build/video/webgl/shaders/multitexture-lit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"multitexture-lit.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/shaders/multitexture-lit.js"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;GAkBG;AACH,0DAJW,MAAM,GACJ,MAAM,CAiFlB;;2BAjI0B,0BAA0B"}
+{"version":3,"file":"multitexture-lit.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/shaders/multitexture-lit.js"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,0DAJW,MAAM,GACJ,MAAM,CAsGlB"}

package/build/video/webgl/texture/store.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The WebGL realization of {@link TextureStore}.
+ *
+ * The shared base owns the policy — source → record, the reuse-or-upload
+ * decision, generation and lifetime bookkeeping. This subclass owns the GL
+ * calls, and nothing else. Mirrors the `Batcher` / `WebGLBatcher` /
+ * `WebGPUBatcher` arrangement: one neutral base, one realization per backend.
+ *
+ * Two instances exist per renderer: the colour store, which every batcher
+ * shares through `WebGLRenderer.textureStore`, and the lit batcher's
+ * normal-map store — normal maps live outside the colour `TextureCache`, so
+ * their handles are that batcher's to own, but the policy is identical.
+ * @augments TextureStore
+ * @ignore
+ */
+export class WebGLTextureStore extends TextureStore {
+    /**
+     * @param {WebGL2RenderingContext} gl - the owning context
+     * @ignore
+     */
+    constructor(gl: WebGL2RenderingContext);
+    gl: WebGL2RenderingContext;
+    /**
+     * @returns {WebGLTexture} a fresh texture object
+     * @ignore
+     */
+    onCreate(): WebGLTexture;
+    /**
+     * Push the source's pixels.
+     *
+     * Delegated to a per-call closure rather than implemented here, because a
+     * GL upload needs the *batcher's* `createTexture2D`: it binds the target
+     * unit, tracks immutable-storage shape, and swaps the texture object when
+     * the shape changes. None of that is residency, and moving it into the
+     * store would drag the batcher's unit bookkeeping along with it.
+     * @param {WebGLTexture} handle - the existing texture object
+     * @param {object} source - the image/canvas being uploaded
+     * @param {object} record - the resident record
+     * @param {object} options - carries `upload(handle)`
+     * @returns {WebGLTexture} the handle actually used, which may be a
+     * replacement when immutable storage had to be respecified
+     * @ignore
+     */
+    onUpload(handle: WebGLTexture, source: object, record: object, options: object): WebGLTexture;
+    /**
+     * @param {WebGLTexture} handle - the texture object to release
+     * @ignore
+     */
+    onDestroy(handle: WebGLTexture): void;
+}
+import { TextureStore } from "./../../gpu/texturestore.js";
+//# sourceMappingURL=store.d.ts.map

package/build/video/webgl/texture/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/texture/store.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH;IACC;;;OAGG;IACH,gBAHW,sBAAsB,EAMhC;IADA,2BAAY;IAGb;;;OAGG;IACH,YAHa,YAAY,CAKxB;IAED;;;;;;;;;;;;;;;OAeG;IACH,iBARW,YAAY,UACZ,MAAM,UACN,MAAM,WACN,MAAM,GACJ,YAAY,CAMxB;IAED;;;OAGG;IACH,kBAHW,YAAY,QAKtB;CACD;6BA9D4B,6BAA6B"}

package/build/video/webgl/utils/maxtextures.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Resolve the texture-unit pool this renderer will use.
+ *
+ * Clamping happens ONCE, at renderer construction, before the batchers and the
+ * `TextureCache` are built — every consumer derives from the result, so the
+ * batchers' sampler counts and the cache's capacity cannot disagree. A setting
+ * above what the device reports is clamped down rather than honoured: declaring
+ * more `sampler2D` uniforms than the device has units fails to link, and a link
+ * failure at startup is not a useful way to learn about a typo.
+ * @param {number} deviceMax - the device's `MAX_TEXTURE_IMAGE_UNITS`
+ * @param {"auto"|number} [setting="auto"] - the `maxTextures` application setting
+ * @returns {number} the pool size, at least 1 and never above `deviceMax`
+ * @ignore
+ */
+export function resolveMaxTextures(deviceMax: number, setting?: "auto" | number): number;
+/**
+ * Default ceiling applied when `maxTextures` is `"auto"`.
+ *
+ * There is no spec maximum to defer to — WebGL 2 / GLES 3.0 only set a
+ * *minimum* of 16 for `MAX_TEXTURE_IMAGE_UNITS`, and an implementation may
+ * report any value at or above it. What actually limits us is that the
+ * multi-texture fragment shader unrolls one sampler and one branch per unit
+ * (see `buildMultiTextureFragment`), so a very wide pool costs compile time
+ * and register pressure, and historically some drivers mis-compile the widest
+ * ladders. 32 covers current desktop and mobile hardware while staying a
+ * conservative default; raise or lower it with the `maxTextures` setting.
+ * @ignore
+ */
+export const AUTO_MAX_TEXTURES: 32;
+/**
+ * Smallest pool the engine will resolve to. A lit quad occupies a colour slot
+ * and a normal-map slot simultaneously, so anything narrower makes the two ids
+ * collide and the sprite samples its own albedo as a normal map.
+ * @ignore
+ */
+export const MIN_MAX_TEXTURES: 2;
+//# sourceMappingURL=maxtextures.d.ts.map

package/build/video/webgl/utils/maxtextures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maxtextures.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/utils/maxtextures.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;GAaG;AACH,8CALW,MAAM,YACN,MAAM,GAAC,MAAM,GACX,MAAM,CAgBlB;AAlDD;;;;;;;;;;;;GAYG;AACH,gCAAiC,EAAE,CAAC;AAEpC;;;;;GAKG;AACH,+BAAgC,CAAC,CAAC"}