melonjs 19.9.1 → 20.1.0

package/build/video/gpu/primitives.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Primitive-batcher geometry assembly shared by both backends — pure CPU
+ * code, no GPU references (the `meshchunk.ts` / `meshvertex.ts`
+ * precedent). The vertex layout is the primitive tier's 6-float
+ * `x, y, z, nx, ny, packed-color` stream on both backends.
+ * @ignore
+ */
+/** the minimal vertex-buffer surface this module writes — `@ignore` */
+interface PrimitiveVertexData {
+    push(x: number, y: number, z: number, nx: number, ny: number, color: number): void;
+    isFull(count: number): boolean;
+}
+/** a 4×4 column-major transform (Matrix3d-shaped) — `@ignore` */
+interface MatrixLike {
+    val: Float32Array;
+    isIdentity(): boolean;
+}
+interface PointLike {
+    x: number;
+    y: number;
+}
+/**
+ * Push `verts[start..end)` into the vertex buffer, transformed by the
+ * given view matrix. The caller guarantees the range fits.
+ *
+ * The transform includes the z column (m[8] / m[9] / m[10] / m[14]) so
+ * Camera3d's view matrix (X/Y-axis rotation) actually rotates the
+ * primitive in 3D. For 2D matrices those slots are identity, so output
+ * (x, y, z) is bit-identical to the legacy 2D-only multiply.
+ * @ignore
+ */
+export declare function pushPrimitiveRange(vertexData: PrimitiveVertexData, viewMatrix: MatrixLike, verts: PointLike[], start: number, end: number, colorUint32: number, z: number): void;
+/**
+ * Expand line pairs into triangles with perpendicular normals. The vertex
+ * shader offsets each vertex by `aNormal * uLineWidth * 0.5`, producing
+ * thick lines without manual geometry expansion in the renderer. The
+ * caller has already switched its draw mode to triangles.
+ *
+ * Each line pair expands to 2 triangles (6 vertices) — capacity is
+ * checked per pair through the `flush` callback, so a dashed/long
+ * thick-line path larger than the whole buffer flushes mid-shape instead
+ * of silently dropping the out-of-range writes (pairs are independent
+ * quads, so a mid-shape flush is invisible).
+ *
+ * The view matrix is applied (z column included) without mutating the
+ * inputs. Note: the perpendicular normal is computed in pre-projection
+ * world space, which appears non-perpendicular under perspective — a
+ * known limitation shared by both backends.
+ * @param vertexData - destination vertex stream
+ * @param viewMatrix - the current view matrix
+ * @param verts - line vertices in pairs [from, to, from, to, ...]
+ * @param vertexCount - number of vertices to consume
+ * @param colorUint32 - packed line color
+ * @param z - the current renderer depth
+ * @param flush - drains the vertex buffer when a pair no longer fits
+ * @ignore
+ */
+export declare function expandLinesToTriangles(vertexData: PrimitiveVertexData, viewMatrix: MatrixLike, verts: PointLike[], vertexCount: number, colorUint32: number, z: number, flush: () => void): void;
+export {};
+//# sourceMappingURL=primitives.d.ts.map

package/build/video/gpu/primitives.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../../src/video/gpu/primitives.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,uEAAuE;AACvE,UAAU,mBAAmB;IAC5B,IAAI,CACH,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,GACX,IAAI,CAAC;IACR,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B;AAED,iEAAiE;AACjE,UAAU,UAAU;IACnB,GAAG,EAAE,YAAY,CAAC;IAClB,UAAU,IAAI,OAAO,CAAC;CACtB;AAED,UAAU,SAAS;IAClB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACV;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CACjC,UAAU,EAAE,mBAAmB,EAC/B,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,SAAS,EAAE,EAClB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,CAAC,EAAE,MAAM,GACP,IAAI,CAsBN;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,sBAAsB,CACrC,UAAU,EAAE,mBAAmB,EAC/B,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,SAAS,EAAE,EAClB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,CAAC,EAAE,MAAM,EACT,KAAK,EAAE,MAAM,IAAI,GACf,IAAI,CAuDN"}

package/build/video/gpu/quadcorners.d.ts

@@ -0,0 +1,11 @@
+import type { Matrix3d } from "../../math/matrix3d.ts";
+import { Vector3d } from "../../math/vector3d.ts";
+/**
+ * Set the four corners of an axis-aligned quad and transform them by `m`
+ * (skipped when `m` is null/identity — the common untransformed case).
+ * Returns the shared corner pool, valid until the next call:
+ * `[topLeft, topRight, bottomLeft, bottomRight]`.
+ * @ignore
+ */
+export declare function transformQuadCorners(m: Matrix3d | null | undefined, x: number, y: number, w: number, h: number, z: number): Vector3d[];
+//# sourceMappingURL=quadcorners.d.ts.map

package/build/video/gpu/quadcorners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quadcorners.d.ts","sourceRoot":"","sources":["../../../src/video/gpu/quadcorners.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAyBlD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CACnC,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,EAC9B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACP,QAAQ,EAAE,CAYZ"}

package/build/video/gpu/textureslots.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Backend-neutral texture slot assignment.
+ *
+ * Both GPU backends solve the same problem — "many textures, one draw call" —
+ * by giving each texture a small integer slot that the fragment shader selects
+ * on per-vertex. Only the *resource* differs: a WebGL texture unit, or an entry
+ * in a WebGPU material bind group. The assignment policy (who gets a slot, what
+ * happens when they run out, what is dropped) is identical, and used to be
+ * written twice — `TextureCache.allocateTextureUnit` on one side,
+ * `WebGPUQuadBatcher.segmentSlotFor` on the other — which is how the two drifted.
+ *
+ * This class owns that policy and nothing else. It never touches a GL unit or a
+ * bind group; the caller supplies the binding through the callbacks. That keeps
+ * it pure, so the same test suite proves both backends behave alike.
+ * @ignore
+ */
+export class TextureSlotTable {
+    /**
+     * @param {object} options - table configuration
+     * @param {number} options.capacity - number of slots, `[0, capacity)`
+     * @param {Function} [options.onOverflow] - called when a new key arrives with
+     * no slot free. The caller must turn the pending work into GPU work (flush)
+     * before the table reassigns slots out from under it.
+     * @param {Function} [options.onEvict] - called with each slot index as it is
+     * dropped, so the caller can forget its binding for that slot
+     * @param {Function} [options.isReserved] - optional predicate; a slot it
+     * approves is held out of assignment entirely (WebGL parks `ShaderEffect`
+     * extra samplers on high units this way). Reservations survive a reset.
+     * @ignore
+     */
+    constructor({ capacity, onOverflow, onEvict, isReserved }?: {
+        capacity: number;
+        onOverflow?: Function | undefined;
+        onEvict?: Function | undefined;
+        isReserved?: Function | undefined;
+    });
+    /** @type {Map<string, number>} key → slot */
+    slots: Map<string, number>;
+    /** @type {Set<number>} occupied slot indices */
+    used: Set<number>;
+    capacity: number;
+    onOverflow: Function | undefined;
+    onEvict: Function | undefined;
+    isReserved: Function | undefined;
+    /**
+     * How many slots are currently taken.
+     *
+     * Occupancy, NOT the key map: slots claimed through {@link claim} carry no
+     * key at all (the WebGL cache allocates that way), so counting keys would
+     * report an empty table while every unit was in use.
+     * @returns {number} the number of occupied slots
+     * @ignore
+     */
+    get size(): number;
+    /**
+     * Resize the table. Shrinking evicts every assignment at or above the new
+     * capacity; growing keeps everything. Called on context restore / device
+     * change, where the resolved limit can differ from the previous one.
+     * @param {number} capacity - the new slot count
+     * @ignore
+     */
+    setCapacity(capacity: number): void;
+    /**
+     * The slot this key already holds, without assigning one. Use when a miss
+     * should not trigger an overflow (probing, debug, bookkeeping).
+     * @param {string} key - the slot key
+     * @returns {number|undefined} the assigned slot, or `undefined`
+     * @ignore
+     */
+    peek(key: string): number | undefined;
+    /**
+     * The lowest assignable slot, or `-1` when every one is taken or reserved.
+     * Bounded by `capacity` on purpose: a caller that reserves every slot must
+     * get an answer rather than an infinite scan.
+     * @returns {number} a free slot index, or -1
+     * @ignore
+     */
+    freeSlot(): number;
+    /**
+     * Resolve a key to its slot, assigning one if needed.
+     *
+     * On exhaustion this calls `onOverflow` (the caller flushes) and then drops
+     * every assignment, so the incoming key starts a fresh set — the behaviour
+     * both backends already had. The eviction step is deliberately the only
+     * policy here: replacing this wipe with something finer (see #1586) changes
+     * both backends at once, which is the point of sharing it.
+     * @param {string} key - identifies the texture *and* the sampling state it
+     * needs, since two draws of one image under different filter/wrap settings
+     * cannot share a slot
+     * @returns {number} the slot to write into the vertex stream
+     * @ignore
+     */
+    slotFor(key: string): number;
+    /**
+     * Take a slot without associating a key with it.
+     *
+     * The WebGL cache resolves textures to units through its own source-keyed
+     * index (a source can hold one unit per wrap mode it was sampled with), so
+     * it needs the *policy* — free-slot search honoring reservations, and the
+     * flush-then-evict behaviour on exhaustion — without the key map. WebGPU's
+     * batcher keys directly and goes through {@link slotFor}, which is this plus
+     * the mapping. Both therefore overflow on the same rule.
+     * @returns {number} the claimed slot
+     * @ignore
+     */
+    claim(): number;
+    /**
+     * Drop a single assignment, freeing its slot. Reservations are untouched —
+     * they are owned by whoever reserved them, not by the table.
+     * @param {string} key - the slot key to release
+     * @returns {boolean} whether the key held a slot
+     * @ignore
+     */
+    release(key: string): boolean;
+    /**
+     * Drop every assignment. `onEvict` fires once per slot that was live, so a
+     * caller tracking bindings per slot can forget exactly those.
+     * @ignore
+     */
+    reset(): void;
+}
+//# sourceMappingURL=textureslots.d.ts.map

package/build/video/gpu/textureslots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textureslots.d.ts","sourceRoot":"","sources":["../../../src/video/gpu/textureslots.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH;IACC;;;;;;;;;;;;OAYG;IACH,4DAXG;QAAwB,QAAQ,EAAxB,MAAM;QACa,UAAU;QAGV,OAAO;QAEP,UAAU;KAGrC,EAWF;IARA,6CAA6C;IAC7C,OADW,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CACR;IACtB,gDAAgD;IAChD,MADW,GAAG,CAAC,MAAM,CAAC,CACD;IACrB,iBAA6B;IAC7B,iCAA4B;IAC5B,8BAAsB;IACtB,iCAA4B;IAG7B;;;;;;;;OAQG;IACH,YAHa,MAAM,CAKlB;IAED;;;;;;OAMG;IACH,sBAHW,MAAM,QAoBhB;IAED;;;;;;OAMG;IACH,UAJW,MAAM,GACJ,MAAM,GAAC,SAAS,CAK5B;IAED;;;;;;OAMG;IACH,YAHa,MAAM,CAUlB;IAED;;;;;;;;;;;;;OAaG;IACH,aANW,MAAM,GAGJ,MAAM,CAWlB;IAED;;;;;;;;;;;OAWG;IACH,SAHa,MAAM,CAsBlB;IAED;;;;;;OAMG;IACH,aAJW,MAAM,GACJ,OAAO,CAYnB;IAED;;;;OAIG;IACH,cAQC;CACD"}

package/build/video/gpu/texturestore.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Backend-neutral texture residency.
+ *
+ * There are two separate questions about a texture, and conflating them is
+ * what makes a GPU renderer re-upload work it already has:
+ *
+ * - **which slot is it in, for this draw?** — transient, per-batch, bounded by
+ *   the shader's sampler count. That is {@link TextureSlotTable}.
+ * - **does it exist on the GPU, and is its content current?** — persistent,
+ *   per-source, bounded by disposal. That is this class.
+ *
+ * The WebGL backend used to answer both with one field (`boundTextures[unit]`),
+ * so dropping a slot assignment destroyed the texture handle and the next draw
+ * rebuilt it from scratch — a full re-upload and mip regeneration per quad,
+ * once past the batching limit.
+ *
+ * This class owns the source → record index, the reuse-or-upload decision, and
+ * the lifetime bookkeeping. It touches no GL or WebGPU API: each backend
+ * supplies `onCreate` / `onUpload` / `onDestroy`, exactly as the slot table
+ * takes its binding through callbacks. That keeps the decision logic identical
+ * on both backends and testable without a device.
+ * @ignore
+ */
+export class TextureStore {
+    /**
+     * @param {object} [options] - store configuration
+     * @param {Function} [options.onCreate] - `(source, options) => handle`, allocate
+     * the backing GPU texture for a source seen for the first time
+     * @param {Function} [options.onUpload] - `(handle, source, record, options) => handle`,
+     * push the source's current content. May return a *replacement* handle when
+     * the shape changed and the old one cannot be respecified (immutable
+     * storage); returning nothing keeps the existing handle.
+     * @param {Function} [options.onDestroy] - `(handle, source)`, release the
+     * GPU texture. Called exactly once per handle.
+     * @ignore
+     */
+    constructor({ onCreate, onUpload, onDestroy }?: {
+        onCreate?: Function | undefined;
+        onUpload?: Function | undefined;
+        onDestroy?: Function | undefined;
+    });
+    /** @type {Map<object, {handle: *, version: number, generation: number}>} */
+    records: Map<object, {
+        handle: any;
+        version: number;
+        generation: number;
+    }>;
+    /**
+     * Allocate the backing GPU texture for a source seen for the first time.
+     * @param {object} source - the image/canvas/resource
+     * @param {object} options - the resolve options
+     * @returns {*} the new handle
+     * @ignore
+     */
+    onCreate(source: object, options: object): any;
+    /**
+     * Push the source's current content. May return a REPLACEMENT handle when
+     * the shape changed and the old one cannot be respecified.
+     * @param {*} handle - the existing handle
+     * @param {object} source - the image/canvas/resource
+     * @param {object} record - the resident record
+     * @param {object} options - the resolve options
+     * @returns {*} a replacement handle, or nothing to keep the existing one
+     * @ignore
+     */
+    onUpload(handle: any, source: object, record: object, options: object): any;
+    /**
+     * Release a GPU texture. Called exactly once per handle.
+     * @param {*} handle - the handle to release
+     * @param {object} source - the source it belonged to
+     * @ignore
+     */
+    onDestroy(handle: any, source: object): void;
+    generation: number;
+    /**
+     * how many sources are currently resident
+     * @returns {number} the record count
+     * @ignore
+     */
+    get size(): number;
+    /**
+     * The live record for a source, uploading only when it is genuinely needed:
+     * the source has never been seen, its content changed, its handle predates
+     * the current context, or the caller forced it.
+     *
+     * A texture that merely moved to a different slot is NOT a reason to upload
+     * — that is the whole point of separating residency from slot assignment.
+     * @param {object} source - the image/canvas/resource backing the texture
+     * @param {object} [options] - resolution options
+     * @param {number} [options.version=0] - the source's content revision; a
+     * change from the recorded value forces a re-upload
+     * @param {boolean} [options.force=false] - re-upload regardless
+     * @returns {{handle: *, version: number, generation: number, uploaded: boolean}}
+     * the record, with `uploaded` reporting whether this call did GPU work
+     * @ignore
+     */
+    getResidentRecord(source: object, options?: {
+        version?: number | undefined;
+        force?: boolean | undefined;
+    }): {
+        handle: any;
+        version: number;
+        generation: number;
+        uploaded: boolean;
+    };
+    /**
+     * The record for a source without resolving one, for callers that must not
+     * trigger GPU work (bookkeeping, debug, invalidation checks).
+     * @param {object} source - the source to look up
+     * @returns {object|undefined} the record, or `undefined`
+     * @ignore
+     */
+    peek(source: object): object | undefined;
+    /**
+     * Release the GPU texture for one source. Driven by the source going away
+     * — never by a slot being reassigned, which is exactly the coupling this
+     * class exists to break.
+     * @param {object} source - the disposed source
+     * @returns {boolean} whether a record was held
+     * @ignore
+     */
+    destroyTexture(source: object): boolean;
+    /**
+     * Drop every record and bump the generation. Called on context or device
+     * loss.
+     *
+     * This CLEARS the store in place — callers must never respond to a restore
+     * by constructing a replacement store. Doing so orphans every handle the
+     * old one was tracking, so the *second* loss leaks everything it had
+     * accumulated since the first. Both WebGL batchers re-run `init()` on
+     * restore, which is precisely how that mistake gets made here.
+     * @param {boolean} [destroy=false] - whether to release the handles first.
+     * Leave `false` for a lost context (the GPU objects are already gone);
+     * pass `true` for an orderly teardown.
+     * @ignore
+     */
+    releaseAll(destroy?: boolean): void;
+}
+//# sourceMappingURL=texturestore.d.ts.map

package/build/video/gpu/texturestore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texturestore.d.ts","sourceRoot":"","sources":["../../../src/video/gpu/texturestore.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IACC;;;;;;;;;;;OAWG;IACH,gDAVG;QAA2B,QAAQ;QAER,QAAQ;QAIR,SAAS;KAEpC,EAuBF;IApBA,4EAA4E;IAC5E,SADW,GAAG,CAAC,MAAM,EAAE;QAAC,MAAM,EAAE,GAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,CAChD;IAqBzB;;;;;;OAMG;IACH,iBALW,MAAM,WACN,MAAM,GACJ,GAAC,CAOb;IAED;;;;;;;;;OASG;IACH,iBAPW,GAAC,UACD,MAAM,UACN,MAAM,WACN,MAAM,GACJ,GAAC,CASb;IAED;;;;;OAKG;IACH,kBAJW,GAAC,UACD,MAAM,QAMhB;IA3CA,mBAAmB;IA6CpB;;;;OAIG;IACH,YAHa,MAAM,CAKlB;IAED;;;;;;;;;;;;;;;OAeG;IACH,0BATW,MAAM,YAEd;QAAyB,OAAO;QAEN,KAAK;KAC/B,GAAU;QAAC,MAAM,EAAE,GAAC,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAC,CAqC/E;IAED;;;;;;OAMG;IACH,aAJW,MAAM,GACJ,MAAM,GAAC,SAAS,CAK5B;IAED;;;;;;;OAOG;IACH,uBAJW,MAAM,GACJ,OAAO,CAanB;IAED;;;;;;;;;;;;;OAaG;IACH,qBALW,OAAO,QAejB;CACD"}

package/build/video/gpu/topology.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Backend-neutral primitive topologies.
+ *
+ * Names how a stream of vertices is assembled into primitives, in the GPU
+ * vocabulary rather than the GL one. Like {@link VertexFormat}, this lets a
+ * draw be described without a live rendering context, and lets a backend read
+ * the description directly instead of translating enums.
+ *
+ * This module holds no GL references, so a non-WebGL backend can import it
+ * without pulling in the WebGL layer.
+ */
+/**
+ * How vertices are assembled into primitives.
+ *
+ * Five of these are portable across backends. `"line-loop"` and
+ * `"triangle-fan"` are **engine extensions** with no modern GPU-API
+ * equivalent — they exist because the primitive batcher has always accepted
+ * them, and a future backend will have to emulate them (a line loop is a line
+ * strip plus a closing segment, which is already how the WebGL path draws it).
+ * Prefer {@link PORTABLE_TOPOLOGIES} for anything that must survive a backend
+ * change.
+ */
+export type Topology = "point-list" | "line-list" | "line-strip" | "line-loop" | "triangle-list" | "triangle-strip" | "triangle-fan";
+/**
+ * The topologies with a direct equivalent in modern GPU APIs.
+ *
+ * `"line-loop"` and `"triangle-fan"` are deliberately absent — see
+ * {@link Topology}.
+ */
+export declare const PORTABLE_TOPOLOGIES: readonly ["point-list", "line-list", "line-strip", "triangle-list", "triangle-strip"];
+/**
+ * Whether a value is a supported topology name.
+ * @param value - the value to test
+ * @returns `true` when `value` names a topology
+ */
+export declare function isTopology(value: unknown): value is Topology;
+/**
+ * Whether a topology has a direct equivalent in modern GPU APIs.
+ * @param topology - the topology to test
+ * @returns `false` for the two engine extensions, which a non-WebGL backend must emulate
+ */
+export declare function isPortableTopology(topology: Topology): boolean;
+//# sourceMappingURL=topology.d.ts.map

package/build/video/gpu/topology.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topology.d.ts","sourceRoot":"","sources":["../../../src/video/gpu/topology.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GACjB,YAAY,GACZ,WAAW,GACX,YAAY,GACZ,WAAW,GACX,eAAe,GACf,gBAAgB,GAChB,cAAc,CAAC;AAElB;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,uFAMQ,CAAC;AAgBzC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAE9D"}

package/build/video/gpu/vertexformat.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Backend-neutral vertex attribute formats.
+ *
+ * A vertex format names a component type and a component count in one token:
+ * `"float32x3"` is three 32-bit floats, `"unorm8x4"` is four unsigned bytes
+ * normalized to `[0, 1]`. That is everything a backend needs to interpret a
+ * slice of an interleaved vertex buffer, which is why it replaces the
+ * `size` + `type` + `normalized` triple the WebGL API works in.
+ *
+ * Naming follows the GPU vocabulary rather than the GL one, because the
+ * translation only runs one way: `"unorm8x4"` gives you `4` +
+ * `UNSIGNED_BYTE` + `normalized`, whereas `UNSIGNED_BYTE` alone cannot tell
+ * you the component count or whether it is normalized. Declaring the format
+ * also means a layout no longer needs a live rendering context to be written
+ * down — the GL enums are only resolved when a backend consumes it.
+ *
+ * This module holds no GL references at all, so a non-WebGL backend can
+ * import it without pulling in the WebGL layer.
+ * @see {@link Batcher#addAttribute}
+ */
+/**
+ * The scalar component type underlying a {@link VertexFormat}.
+ * @ignore
+ */
+export type VertexScalar = "float32" | "uint8" | "sint8" | "unorm8" | "snorm8" | "uint16" | "sint16" | "unorm16" | "snorm16" | "uint32" | "sint32";
+/**
+ * A vertex attribute format: component type and count.
+ *
+ * The set is deliberately narrower than the full GPU vocabulary — see the
+ * module notes for what is excluded and why. Layouts that cannot be spelled
+ * here (three-component 8- and 16-bit types, for instance) remain expressible
+ * with the {@link Batcher#addAttribute} GL-enum form, which is supported
+ * indefinitely.
+ */
+export type VertexFormat = "float32" | "float32x2" | "float32x3" | "float32x4" | "uint8" | "uint8x2" | "uint8x4" | "sint8" | "sint8x2" | "sint8x4" | "unorm8" | "unorm8x2" | "unorm8x4" | "snorm8" | "snorm8x2" | "snorm8x4" | "uint16" | "uint16x2" | "uint16x4" | "sint16" | "sint16x2" | "sint16x4" | "unorm16" | "unorm16x2" | "unorm16x4" | "snorm16" | "snorm16x2" | "snorm16x4" | "uint32" | "uint32x2" | "uint32x3" | "uint32x4" | "sint32" | "sint32x2" | "sint32x3" | "sint32x4";
+/**
+ * What a {@link VertexFormat} resolves to.
+ * @ignore
+ */
+export interface VertexFormatInfo {
+    /** number of components (1, 2, 3 or 4) */
+    components: 1 | 2 | 3 | 4;
+    /** total size of the attribute in bytes */
+    bytes: number;
+    /** whether integer values are scaled into `[0, 1]` / `[-1, 1]` when read by a shader */
+    normalized: boolean;
+    /** the underlying scalar type */
+    scalar: VertexScalar;
+}
+/**
+ * Every supported format, resolved.
+ *
+ * `bytes` is computed as `components × scalar size`, which is the same
+ * arithmetic the GL-enum path has always used — so a layout expressed either
+ * way produces an identical stride.
+ * @ignore
+ */
+export declare const VERTEX_FORMATS: Record<VertexFormat, VertexFormatInfo>;
+/**
+ * Whether a value is a supported vertex format name.
+ * @param value - the value to test
+ * @returns `true` when `value` names a format in {@link VERTEX_FORMATS}
+ */
+export declare function isVertexFormat(value: unknown): value is VertexFormat;
+/**
+ * Resolve a vertex format to its component count, size and normalization.
+ * @param format - the format to resolve
+ * @returns the resolved description
+ * @throws {Error} when `format` is not a supported format name
+ */
+export declare function resolveVertexFormat(format: VertexFormat): VertexFormatInfo;
+//# sourceMappingURL=vertexformat.d.ts.map

package/build/video/gpu/vertexformat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vertexformat.d.ts","sourceRoot":"","sources":["../../../src/video/gpu/vertexformat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;GAGG;AACH,MAAM,MAAM,YAAY,GACrB,SAAS,GACT,OAAO,GACP,OAAO,GACP,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,SAAS,GACT,QAAQ,GACR,QAAQ,CAAC;AAEZ;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAErB,SAAS,GACT,WAAW,GACX,WAAW,GACX,WAAW,GAEX,OAAO,GACP,SAAS,GACT,SAAS,GACT,OAAO,GACP,SAAS,GACT,SAAS,GAET,QAAQ,GACR,UAAU,GACV,UAAU,GACV,QAAQ,GACR,UAAU,GACV,UAAU,GAEV,QAAQ,GACR,UAAU,GACV,UAAU,GACV,QAAQ,GACR,UAAU,GACV,UAAU,GAEV,SAAS,GACT,WAAW,GACX,WAAW,GACX,SAAS,GACT,WAAW,GACX,WAAW,GAEX,QAAQ,GACR,UAAU,GACV,UAAU,GACV,UAAU,GACV,QAAQ,GACR,UAAU,GACV,UAAU,GACV,UAAU,CAAC;AAEd;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAChC,0CAA0C;IAC1C,UAAU,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC1B,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,UAAU,EAAE,OAAO,CAAC;IACpB,iCAAiC;IACjC,MAAM,EAAE,YAAY,CAAC;CACrB;AA0DD;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,YAAY,EAAE,gBAAgB,CA0CjE,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,GAAG,gBAAgB,CAS1E"}

package/build/video/gradient.d.ts

@@ -77,17 +77,26 @@ export class Gradient {
      */
     toCanvasGradient(context: CanvasRenderingContext2D): CanvasGradient;
     /**
-     * Render the gradient onto a canvas matching the given draw rect.
-     * Uses the original gradient coordinates so the result matches Canvas 2D behavior.
-     * @param {CanvasRenderer|WebGLRenderer} renderer - the active renderer (used to invalidate GPU texture)
+     * Render the gradient into the fixed-resolution shared bake target for
+     * the given draw rect. Uses the original gradient coordinates so the
+     * result matches Canvas 2D behavior. Rects larger than the bake target
+     * are rasterized scaled-down; the destination quad stretches them back,
+     * which is visually equivalent (linear stop interpolation × linear
+     * texture filtering). The returned `width`/`height` describe the region
+     * of the canvas the caller must use as the drawImage SOURCE rect.
+     * @param {CanvasRenderer|WebGLRenderer} renderer - the active renderer (used to invalidate the GPU texture)
      * @param {number} x - draw rect x
      * @param {number} y - draw rect y
      * @param {number} width - draw rect width
      * @param {number} height - draw rect height
-     * @returns {HTMLCanvasElement|OffscreenCanvas} the rendered gradient canvas
+     * @returns {{canvas: HTMLCanvasElement|OffscreenCanvas, width: number, height: number}} the shared gradient canvas + the used source-rect size
      * @ignore
      */
-    toCanvas(renderer: CanvasRenderer | WebGLRenderer, x: number, y: number, width: number, height: number): HTMLCanvasElement | OffscreenCanvas;
+    toCanvas(renderer: CanvasRenderer | WebGLRenderer, x: number, y: number, width: number, height: number): {
+        canvas: HTMLCanvasElement | OffscreenCanvas;
+        width: number;
+        height: number;
+    };
     /**
      * Get the interpolated color at a given position along the gradient.
      * Useful for procedural effects like trails that need per-segment colors.

package/build/video/gradient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gradient.d.ts","sourceRoot":"","sources":["../../src/video/gradient.js"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH;IACC;;;OAGG;IACH,kBAHW,QAAQ,GAAC,QAAQ,UACjB,MAAM,EAAE,EAqDlB;IAlDA;;;OAGG;IACH,cAAc;IACd,YAA2B;IAE3B,0BAAgB;IAEhB;;;;OAIG;IACH,QAHU,MAAM,EAAE,CAGE;IAEpB;;;;OAIG;IACH,YAHU,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAAC,CAG5B;IAEpB;;;;OAIG;IACH,iBAHU,cAAc,GAAC,SAAS,CAGF;IAEhC;;;;OAIG;IACH,eAHU,kBAAkB,GAAC,SAAS,CAGR;IAE9B;;;;OAIG;IACH,QAHU,OAAO,CAGC;IAElB;;;;OAIG;IACH,cAHU;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAC,EAAE,GAAC,IAAI,CAGvB;IAGzB;;;;;;;;;OASG;IACH,qBARW,MAAM,SACN,KAAK,GAAC,MAAM,GACV,QAAQ,CA0BpB;IAED;;;;;OAKG;IACH,0BAJW,wBAAwB,GACtB,cAAc,CAiC1B;IAED;;;;;;;;;;OAUG;IACH,mBARW,cAAc,GAAC,aAAa,KAC5B,MAAM,KACN,MAAM,SACN,MAAM,UACN,MAAM,GACJ,iBAAiB,GAAC,eAAe,CAwE7C;IAED;;;;;;;;;;;OAWG;IACH,qBATW,MAAM,OACN,KAAK,GACH,KAAK,CA+CjB;IAED;;;OAGG;IACH,0BAWC;IAED;;OAEG;IACH,gBAOC;CACD;+BAtT8B,sCAAsC;2BAH7C,kBAAkB"}
+{"version":3,"file":"gradient.d.ts","sourceRoot":"","sources":["../../src/video/gradient.js"],"names":[],"mappings":"AAiCA;;;;GAIG;AACH;IACC;;;OAGG;IACH,kBAHW,QAAQ,GAAC,QAAQ,UACjB,MAAM,EAAE,EAqDlB;IAlDA;;;OAGG;IACH,cAAc;IACd,YAA2B;IAE3B,0BAAgB;IAEhB;;;;OAIG;IACH,QAHU,MAAM,EAAE,CAGE;IAEpB;;;;OAIG;IACH,YAHU,KAAK,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAAC,CAG5B;IAEpB;;;;OAIG;IACH,iBAHU,cAAc,GAAC,SAAS,CAGF;IAEhC;;;;OAIG;IACH,eAHU,kBAAkB,GAAC,SAAS,CAGR;IAE9B;;;;OAIG;IACH,QAHU,OAAO,CAGC;IAElB;;;;OAIG;IACH,cAHU;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAC,EAAE,GAAC,IAAI,CAGvB;IAGzB;;;;;;;;;OASG;IACH,qBARW,MAAM,SACN,KAAK,GAAC,MAAM,GACV,QAAQ,CA0BpB;IAED;;;;;OAKG;IACH,0BAJW,wBAAwB,GACtB,cAAc,CAiC1B;IAED;;;;;;;;;;;;;;;OAeG;IACH,mBARW,cAAc,GAAC,aAAa,KAC5B,MAAM,KACN,MAAM,SACN,MAAM,UACN,MAAM,GACJ;QAAC,MAAM,EAAE,iBAAiB,GAAC,eAAe,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,CAwFtF;IAED;;;;;;;;;;;OAWG;IACH,qBATW,MAAM,OACN,KAAK,GACH,KAAK,CA+CjB;IAED;;;OAGG;IACH,0BAWC;IAED;;OAEG;IACH,gBAOC;CACD;+BA1V8B,sCAAsC;2BAF7C,kBAAkB"}