@driftengine/ui2d 3.61.0

package/dist/shaders/generated/sprite.wgsl.js

@@ -0,0 +1,60 @@
+/*
+ * Generated from ../sprite.ts by `npm run wgsl`. Do not edit.
+ *
+ * The GLSL beside this file is the source of truth. A hand edit here is discarded by
+ * the next generation, and `npm run wgsl:check` fails the build when this is stale.
+ */
+export const SPRITE_FRAG_WGSL = "struct Uniforms {\n    uOutputTransform: i32,\n    uOutputExposure: f32,\n}\n\n@group(0) @binding(1) \nvar<uniform> unnamed: Uniforms;\n@group(0) @binding(32) \nvar uSpriteTexture_t: texture_2d<f32>;\n@group(0) @binding(33) \nvar uSpriteTexture_s: sampler;\nvar<private> vUv_1: vec2<f32>;\nvar<private> vTint_1: vec4<f32>;\nvar<private> fragColor: vec4<f32>;\n\nfn linearToSrgb_u0028_vf3_u003b(c: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var low: vec3<f32>;\n    var high: vec3<f32>;\n\n    let _e55 = (*c);\n    low = (_e55 * 12.92f);\n    let _e57 = (*c);\n    high = ((pow(max(_e57, vec3<f32>(0f, 0f, 0f)), vec3<f32>(0.41666666f, 0.41666666f, 0.41666666f)) * 1.055f) - vec3(0.055f));\n    let _e63 = high;\n    let _e64 = low;\n    let _e65 = (*c);\n    return mix(_e63, _e64, step(_e65, vec3<f32>(0.0031308f, 0.0031308f, 0.0031308f)));\n}\n\nfn rrtAndOdtFit_u0028_vf3_u003b(v: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var a: vec3<f32>;\n    var b: vec3<f32>;\n\n    let _e55 = (*v);\n    let _e56 = (*v);\n    a = ((_e55 * (_e56 + vec3(0.0245786f))) - vec3(0.000090537f));\n    let _e62 = (*v);\n    let _e63 = (*v);\n    b = ((_e62 * ((_e63 * 0.983729f) + vec3(0.432951f))) + vec3(0.238081f));\n    let _e70 = a;\n    let _e71 = b;\n    return (_e70 / _e71);\n}\n\nfn acesFilmic_u0028_vf3_u003b(x: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var param: vec3<f32>;\n\n    let _e55 = unnamed.uOutputExposure;\n    let _e56 = (*x);\n    (*x) = (_e56 * _e55);\n    let _e58 = (*x);\n    param = (mat3x3<f32>(vec3<f32>(0.59719f, 0.076f, 0.0284f), vec3<f32>(0.35458f, 0.90834f, 0.13383f), vec3<f32>(0.04823f, 0.01566f, 0.83777f)) * _e58);\n    let _e60 = rrtAndOdtFit_u0028_vf3_u003b((&param));\n    return clamp((mat3x3<f32>(vec3<f32>(1.60475f, -0.10208f, -0.00327f), vec3<f32>(-0.53108f, 1.10813f, -0.07276f), vec3<f32>(-0.07367f, -0.00605f, 1.07602f)) * _e60), vec3(0f), vec3(1f));\n}\n\nfn applyOutputTransform_u0028_vf3_u003b(c_1: ptr<function, vec3<f32>>) -> vec3<f32> {\n    var param_1: vec3<f32>;\n    var param_2: vec3<f32>;\n\n    let _e56 = unnamed.uOutputTransform;\n    if (_e56 == 0i) {\n        let _e58 = (*c_1);\n        return _e58;\n    }\n    let _e60 = unnamed.uOutputTransform;\n    if (_e60 == 2i) {\n        let _e62 = (*c_1);\n        param_1 = _e62;\n        let _e63 = acesFilmic_u0028_vf3_u003b((&param_1));\n        (*c_1) = _e63;\n    }\n    let _e64 = (*c_1);\n    param_2 = _e64;\n    let _e65 = linearToSrgb_u0028_vf3_u003b((&param_2));\n    return _e65;\n}\n\nfn main_1() {\n    var texel: vec4<f32>;\n    var colour: vec4<f32>;\n    var param_3: vec3<f32>;\n\n    let _e55 = vUv_1;\n    let _e56 = textureSample(uSpriteTexture_t, uSpriteTexture_s, _e55);\n    texel = _e56;\n    let _e57 = texel;\n    let _e58 = vTint_1;\n    colour = (_e57 * _e58);\n    let _e61 = colour[3u];\n    if (_e61 < 0.00392157f) {\n        discard;\n    }\n    let _e63 = colour;\n    param_3 = _e63.xyz;\n    let _e65 = applyOutputTransform_u0028_vf3_u003b((&param_3));\n    let _e66 = colour;\n    colour = vec4<f32>(_e65.x, _e65.y, _e65.z, _e66.w);\n    let _e72 = colour;\n    let _e75 = colour[3u];\n    let _e76 = (_e72.xyz * _e75);\n    let _e78 = colour[3u];\n    fragColor = vec4<f32>(_e76.x, _e76.y, _e76.z, _e78);\n    return;\n}\n\n@fragment \nfn main(@location(0) vUv: vec2<f32>, @location(1) vTint: vec4<f32>) -> @location(0) vec4<f32> {\n    vUv_1 = vUv;\n    vTint_1 = vTint;\n    main_1();\n    let _e5 = fragColor;\n    return _e5;\n}\n";
+export const SPRITE_VERT_WGSL = "struct Uniforms {\n    uToNdc0_: vec4<f32>,\n    uToNdc1_: vec4<f32>,\n    uClipCorrection: mat4x4<f32>,\n}\n\nstruct gl_PerVertex {\n    @builtin(position) gl_Position: vec4<f32>,\n    gl_PointSize: f32,\n}\n\nstruct VertexOutput {\n    @location(0) member: vec2<f32>,\n    @location(1) member_1: vec4<f32>,\n    @builtin(position) gl_Position: vec4<f32>,\n}\n\nvar<private> gl_VertexIndex_1: i32;\nvar<private> aOrigin_1: vec2<f32>;\nvar<private> aEdges_1: vec4<f32>;\n@group(0) @binding(0) \nvar<uniform> unnamed: Uniforms;\nvar<private> vUv: vec2<f32>;\nvar<private> aUv_1: vec4<f32>;\nvar<private> vTint: vec4<f32>;\nvar<private> aTint_1: vec4<f32>;\nvar<private> unnamed_1: gl_PerVertex = gl_PerVertex(vec4<f32>(0f, 0f, 0f, 1f), 1f);\n\nfn main_1() {\n    var corner: vec2<f32>;\n    var indexable: array<vec2<f32>, 6>;\n    var p: vec2<f32>;\n    var ndc: vec2<f32>;\n\n    let _e28 = gl_VertexIndex_1;\n    indexable = array<vec2<f32>, 6>(vec2<f32>(0f, 0f), vec2<f32>(1f, 0f), vec2<f32>(0f, 1f), vec2<f32>(0f, 1f), vec2<f32>(1f, 0f), vec2<f32>(1f, 1f));\n    let _e30 = indexable[_e28];\n    corner = _e30;\n    let _e31 = aOrigin_1;\n    let _e32 = aEdges_1;\n    let _e35 = corner[0u];\n    let _e38 = aEdges_1;\n    let _e41 = corner[1u];\n    p = ((_e31 + (_e32.xy * _e35)) + (_e38.zw * _e41));\n    let _e46 = unnamed.uToNdc0_[0u];\n    let _e48 = p[0u];\n    let _e52 = unnamed.uToNdc0_[2u];\n    let _e54 = p[1u];\n    let _e59 = unnamed.uToNdc1_[0u];\n    let _e63 = unnamed.uToNdc0_[1u];\n    let _e65 = p[0u];\n    let _e69 = unnamed.uToNdc0_[3u];\n    let _e71 = p[1u];\n    let _e76 = unnamed.uToNdc1_[1u];\n    ndc = vec2<f32>((((_e46 * _e48) + (_e52 * _e54)) + _e59), (((_e63 * _e65) + (_e69 * _e71)) + _e76));\n    let _e79 = aUv_1;\n    let _e81 = aUv_1;\n    let _e83 = corner;\n    vUv = mix(_e79.xy, _e81.zw, _e83);\n    let _e85 = aTint_1;\n    vTint = _e85;\n    let _e87 = unnamed.uClipCorrection;\n    let _e88 = ndc;\n    unnamed_1.gl_Position = (_e87 * vec4<f32>(_e88.x, _e88.y, 0f, 1f));\n    return;\n}\n\n@vertex \nfn main(@builtin(vertex_index) gl_VertexIndex: u32, @location(3) aOrigin: vec2<f32>, @location(0) aEdges: vec4<f32>, @location(1) aUv: vec4<f32>, @location(2) aTint: vec4<f32>) -> VertexOutput {\n    gl_VertexIndex_1 = i32(gl_VertexIndex);\n    aOrigin_1 = aOrigin;\n    aEdges_1 = aEdges;\n    aUv_1 = aUv;\n    aTint_1 = aTint;\n    main_1();\n    let _e16 = unnamed_1.gl_Position.y;\n    unnamed_1.gl_Position.y = -(_e16);\n    let _e18 = vUv;\n    let _e19 = vTint;\n    let _e20 = unnamed_1.gl_Position;\n    return VertexOutput(_e18, _e19, _e20);\n}\n";
+/**
+ * What the transform assigned, so the renderer binds the same numbers.
+ *
+ * A permuted shader has one entry per variant, keyed as `FLAT_FRAG_WGSL` is.
+ */
+export const SPRITE_BINDINGS = {
+    "SPRITE_FRAG": {
+        "uniforms": 1,
+        "uniformSize": 16,
+        "fields": {
+            "uOutputTransform": {
+                "offset": 0,
+                "size": 4,
+                "type": "int"
+            },
+            "uOutputExposure": {
+                "offset": 4,
+                "size": 4,
+                "type": "float"
+            }
+        },
+        "textures": {
+            "uSpriteTexture": {
+                "texture": 32,
+                "sampler": 33,
+                "type": "sampler2D"
+            }
+        }
+    },
+    "SPRITE_VERT": {
+        "uniforms": 0,
+        "uniformSize": 96,
+        "fields": {
+            "uToNdc0": {
+                "offset": 0,
+                "size": 16,
+                "type": "vec4"
+            },
+            "uToNdc1": {
+                "offset": 16,
+                "size": 16,
+                "type": "vec4"
+            },
+            "uClipCorrection": {
+                "offset": 32,
+                "size": 64,
+                "type": "mat4"
+            }
+        },
+        "textures": {}
+    }
+};

package/dist/shaders/sprite.d.ts

@@ -0,0 +1,3 @@
+/** The sprite program: one textured, tinted quad per instance, blended in submission order. */
+export declare const SPRITE_VERT = "#version 300 es\n\n/**\n * The two edge vectors of the quad, in the space the affine below maps from.\n *\n * Edge vectors rather than a size and an angle: the rotation is resolved on the CPU once per\n * sprite, where it costs one sine, and the vertex stage does two multiplies and an add. A sprite\n * batch is vertex-bound at four thousand quads and this is the whole of its vertex work.\n */\nlayout(location = 0) in vec4 aEdges;\n/** The frame this sprite reads, as (u0, v0) and (u1, v1). */\nlayout(location = 1) in vec4 aUv;\n/** Straight, not premultiplied. The fragment stage premultiplies after the texture fetch. */\nlayout(location = 2) in vec4 aTint;\n/** The corner the two edges grow from. */\nlayout(location = 3) in vec2 aOrigin;\n\n/**\n * The affine to normalised device coordinates, as (a, b, c, d) and (e, f).\n *\n * Two `vec4`s rather than a `mat3`, because a `mat3` in a uniform block is three\n * sixteen-byte rows for nine useful floats and this is read once per vertex.\n */\nuniform vec4 uToNdc0;\nuniform vec4 uToNdc1;\n/**\n * Clip space, as the backend drawing this defines it. Identity on WebGL2.\n *\n * The same correction `panel.ts` carries and for the same reason: this stage builds its own clip\n * position and never multiplies by a camera, so the generated vertex shader's Y negation would\n * stand uncancelled and the whole 2D layer would land mirrored about the middle of the frame.\n */\nuniform mat4 uClipCorrection;\n\nout vec2 vUv;\nout vec4 vTint;\n\n/**\n * Two triangles, wound so that either winding draws: this pass culls nothing.\n *\n * A sprite is flipped by giving it a negative width, which reverses the winding \u2014 so a cull mode\n * would silently drop every mirrored sprite, which is what a character facing left is.\n */\nconst vec2 CORNERS[6] = vec2[6](\n  vec2(0.0, 0.0), vec2(1.0, 0.0), vec2(0.0, 1.0),\n  vec2(0.0, 1.0), vec2(1.0, 0.0), vec2(1.0, 1.0)\n);\n\nvoid main() {\n  vec2 corner = CORNERS[gl_VertexID];\n  vec2 p = aOrigin + aEdges.xy * corner.x + aEdges.zw * corner.y;\n  vec2 ndc = vec2(\n    uToNdc0.x * p.x + uToNdc0.z * p.y + uToNdc1.x,\n    uToNdc0.y * p.x + uToNdc0.w * p.y + uToNdc1.y\n  );\n  vUv = mix(aUv.xy, aUv.zw, corner);\n  vTint = aTint;\n  /* z is 0 and nothing depth-tests here: the order sprites were submitted in is the layering. */\n  gl_Position = uClipCorrection * vec4(ndc, 0.0, 1.0);\n}\n";
+export declare const SPRITE_FRAG: string;

package/dist/shaders/sprite.js

@@ -0,0 +1,98 @@
+/** The sprite program: one textured, tinted quad per instance, blended in submission order. */
+import { OUTPUT_TRANSFORM_GLSL } from '@driftengine/core';
+/**
+ * Below this the fragment is thrown away rather than blended.
+ *
+ * Half of one eight-bit step. A sprite sheet's transparent margin is exactly zero and costs
+ * nothing to reject; what this buys is the *soft* edge of an antialiased glyph or a feathered
+ * particle, whose outermost ring blends a texture fetch and a blend for a contribution no frame
+ * can show. It is a fill saving and not a correctness rule, which is why it is this low: a cutout
+ * threshold that shaved visible alpha would put a hard edge on every soft one.
+ */
+const ALPHA_FLOOR = 1.0 / 255.0;
+export const SPRITE_VERT = `#version 300 es
+
+/**
+ * The two edge vectors of the quad, in the space the affine below maps from.
+ *
+ * Edge vectors rather than a size and an angle: the rotation is resolved on the CPU once per
+ * sprite, where it costs one sine, and the vertex stage does two multiplies and an add. A sprite
+ * batch is vertex-bound at four thousand quads and this is the whole of its vertex work.
+ */
+layout(location = 0) in vec4 aEdges;
+/** The frame this sprite reads, as (u0, v0) and (u1, v1). */
+layout(location = 1) in vec4 aUv;
+/** Straight, not premultiplied. The fragment stage premultiplies after the texture fetch. */
+layout(location = 2) in vec4 aTint;
+/** The corner the two edges grow from. */
+layout(location = 3) in vec2 aOrigin;
+
+/**
+ * The affine to normalised device coordinates, as (a, b, c, d) and (e, f).
+ *
+ * Two \`vec4\`s rather than a \`mat3\`, because a \`mat3\` in a uniform block is three
+ * sixteen-byte rows for nine useful floats and this is read once per vertex.
+ */
+uniform vec4 uToNdc0;
+uniform vec4 uToNdc1;
+/**
+ * Clip space, as the backend drawing this defines it. Identity on WebGL2.
+ *
+ * The same correction \`panel.ts\` carries and for the same reason: this stage builds its own clip
+ * position and never multiplies by a camera, so the generated vertex shader's Y negation would
+ * stand uncancelled and the whole 2D layer would land mirrored about the middle of the frame.
+ */
+uniform mat4 uClipCorrection;
+
+out vec2 vUv;
+out vec4 vTint;
+
+/**
+ * Two triangles, wound so that either winding draws: this pass culls nothing.
+ *
+ * A sprite is flipped by giving it a negative width, which reverses the winding — so a cull mode
+ * would silently drop every mirrored sprite, which is what a character facing left is.
+ */
+const vec2 CORNERS[6] = vec2[6](
+  vec2(0.0, 0.0), vec2(1.0, 0.0), vec2(0.0, 1.0),
+  vec2(0.0, 1.0), vec2(1.0, 0.0), vec2(1.0, 1.0)
+);
+
+void main() {
+  vec2 corner = CORNERS[gl_VertexID];
+  vec2 p = aOrigin + aEdges.xy * corner.x + aEdges.zw * corner.y;
+  vec2 ndc = vec2(
+    uToNdc0.x * p.x + uToNdc0.z * p.y + uToNdc1.x,
+    uToNdc0.y * p.x + uToNdc0.w * p.y + uToNdc1.y
+  );
+  vUv = mix(aUv.xy, aUv.zw, corner);
+  vTint = aTint;
+  /* z is 0 and nothing depth-tests here: the order sprites were submitted in is the layering. */
+  gl_Position = uClipCorrection * vec4(ndc, 0.0, 1.0);
+}
+`;
+export const SPRITE_FRAG = `#version 300 es
+precision highp float;
+
+uniform sampler2D uSpriteTexture;
+
+in vec2 vUv;
+in vec4 vTint;
+out vec4 fragColor;
+
+${OUTPUT_TRANSFORM_GLSL}
+
+void main() {
+  /*
+   * No branch reaches this fetch, so the implicit derivative is taken in uniform control flow and
+   * a sheet may be mipmapped. The 2026-08-07 rule is about a sample under a branch and there is
+   * none here; adding one later would mean a \`textureLod\`.
+   */
+  vec4 texel = texture(uSpriteTexture, vUv);
+  vec4 colour = texel * vTint;
+  if (colour.a < ${ALPHA_FLOOR.toFixed(8)}) discard;
+  colour.rgb = applyOutputTransform(colour.rgb);
+  /* Premultiplied out, because the blend is (ONE, ONE_MINUS_SRC_ALPHA). */
+  fragColor = vec4(colour.rgb * colour.a, colour.a);
+}
+`;

package/dist/spriteBatch.d.ts

@@ -0,0 +1,78 @@
+/** The CPU side of a sprite draw: quads packed into one instance buffer, in submission order. */
+/**
+ * Floats per instance: two edge vectors, a UV rectangle, a tint, and an origin.
+ *
+ * Fourteen rather than a rounder sixteen because a vertex buffer's stride only has to be a multiple
+ * of four bytes, and two floats a sprite is 8 KB at a four-thousand-sprite batch.
+ */
+export declare const SPRITE_FLOATS = 14;
+/** Where a sprite goes, in whatever space the batch is being drawn in. */
+export interface SpritePlacement {
+    /**
+     * The corner the sprite grows from, and *which* corner depends on the affine.
+     *
+     * In screen space y counts down, so this is the top-left; in a 2D world y counts up, so it is
+     * the bottom-left. The batch does not know which it is in and does not need to: it is the same
+     * arithmetic either way, and `camera2d.ts` is where the two conventions are written down.
+     */
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+    /**
+     * Radians, anticlockwise in the mathematical sense — which reads as clockwise on screen, where y
+     * counts down. Defaults to none.
+     */
+    readonly rotation?: number;
+    /** The point rotation turns about, as a fraction of the sprite. Defaults to its centre. */
+    readonly pivotX?: number;
+    readonly pivotY?: number;
+}
+/** A rectangle of a texture, in the 0..1 the sampler reads. See `spriteSheet.ts`. */
+export interface UvRect {
+    readonly u0: number;
+    readonly v0: number;
+    readonly u1: number;
+    readonly v1: number;
+}
+/**
+ * A run of consecutive instances that share a texture.
+ *
+ * Runs exist because the number to hold down is material changes rather than draws: a tilemap over
+ * one sheet is one run however many thousand tiles it is, and a run boundary is the only place the
+ * pass has to touch the GPU between them.
+ */
+export interface SpriteRun {
+    readonly texture: number;
+    readonly first: number;
+    readonly count: number;
+}
+/**
+ * One frame's worth of sprites.
+ *
+ * Fixed capacity, filled from the front, reset each frame. It grows for nobody: a batch that
+ * reallocated mid-frame would allocate in the hot path, and the failure it is protecting against —
+ * a caller drawing more than it planned for — is one that wants counting rather than absorbing.
+ */
+export interface SpriteBatch {
+    /** `capacity * SPRITE_FLOATS`, filled to `count * SPRITE_FLOATS`. */
+    readonly instances: Float32Array;
+    readonly capacity: number;
+    count: number;
+    /** Three entries a run: texture, first instance, length. */
+    readonly runs: Int32Array;
+    runCount: number;
+    /** Sprites this frame refused for want of room. Zero is the only good value. */
+    dropped: number;
+}
+export declare function createSpriteBatch(capacity: number): SpriteBatch;
+export declare function resetSpriteBatch(batch: SpriteBatch): void;
+/** Read a run back. For tests and diagnostics; the pass reads `runs` directly. */
+export declare function spriteRun(batch: SpriteBatch, index: number): SpriteRun;
+/**
+ * Push one quad. Allocates nothing.
+ *
+ * `source` of `null` is the whole texture and `tint` of `null` is opaque white, because those are
+ * what a caller drawing a plain image wants and neither should cost an object per draw.
+ */
+export declare function drawSprite(batch: SpriteBatch, texture: number, placement: SpritePlacement, source: UvRect | null, tint: ArrayLike<number> | null): void;

package/dist/spriteBatch.js

@@ -0,0 +1,93 @@
+/** The CPU side of a sprite draw: quads packed into one instance buffer, in submission order. */
+/**
+ * Floats per instance: two edge vectors, a UV rectangle, a tint, and an origin.
+ *
+ * Fourteen rather than a rounder sixteen because a vertex buffer's stride only has to be a multiple
+ * of four bytes, and two floats a sprite is 8 KB at a four-thousand-sprite batch.
+ */
+export const SPRITE_FLOATS = 14;
+export function createSpriteBatch(capacity) {
+    return {
+        instances: new Float32Array(capacity * SPRITE_FLOATS),
+        capacity,
+        count: 0,
+        /*
+         * One run per sprite is the worst case — a caller alternating textures every draw — and
+         * allocating for it costs twelve bytes a sprite against the fifty-six the sprite itself costs.
+         * The alternative is a second capacity to overflow, on a path where overflowing means dropping
+         * a draw the caller can see.
+         */
+        runs: new Int32Array(capacity * 3),
+        runCount: 0,
+        dropped: 0,
+    };
+}
+export function resetSpriteBatch(batch) {
+    batch.count = 0;
+    batch.runCount = 0;
+    batch.dropped = 0;
+}
+/** Read a run back. For tests and diagnostics; the pass reads `runs` directly. */
+export function spriteRun(batch, index) {
+    const at = index * 3;
+    return {
+        texture: batch.runs[at],
+        first: batch.runs[at + 1],
+        count: batch.runs[at + 2],
+    };
+}
+/**
+ * Push one quad. Allocates nothing.
+ *
+ * `source` of `null` is the whole texture and `tint` of `null` is opaque white, because those are
+ * what a caller drawing a plain image wants and neither should cost an object per draw.
+ */
+export function drawSprite(batch, texture, placement, source, tint) {
+    if (batch.count >= batch.capacity) {
+        batch.dropped += 1;
+        return;
+    }
+    const rotation = placement.rotation ?? 0;
+    const cos = rotation === 0 ? 1 : Math.cos(rotation);
+    const sin = rotation === 0 ? 0 : Math.sin(rotation);
+    const w = placement.w;
+    const h = placement.h;
+    // The two edge vectors of the quad, turned.
+    const ax = w * cos;
+    const ay = w * sin;
+    const bx = -h * sin;
+    const by = h * cos;
+    const pivotX = placement.pivotX ?? 0.5;
+    const pivotY = placement.pivotY ?? 0.5;
+    // The pivot does not move, so the origin is wherever it has to be for that to hold.
+    const originX = placement.x + w * pivotX - (ax * pivotX + bx * pivotY);
+    const originY = placement.y + h * pivotY - (ay * pivotX + by * pivotY);
+    const at = batch.count * SPRITE_FLOATS;
+    const f = batch.instances;
+    f[at] = ax;
+    f[at + 1] = ay;
+    f[at + 2] = bx;
+    f[at + 3] = by;
+    f[at + 4] = source === null ? 0 : source.u0;
+    f[at + 5] = source === null ? 0 : source.v0;
+    f[at + 6] = source === null ? 1 : source.u1;
+    f[at + 7] = source === null ? 1 : source.v1;
+    f[at + 8] = tint === null ? 1 : tint[0];
+    f[at + 9] = tint === null ? 1 : tint[1];
+    f[at + 10] = tint === null ? 1 : tint[2];
+    f[at + 11] = tint === null ? 1 : tint[3];
+    f[at + 12] = originX;
+    f[at + 13] = originY;
+    const lastRun = (batch.runCount - 1) * 3;
+    if (batch.runCount > 0 && batch.runs[lastRun] === texture) {
+        batch.runs[lastRun + 2] = batch.runs[lastRun + 2] + 1;
+    }
+    else {
+        const run = batch.runCount * 3;
+        batch.runs[run] = texture;
+        batch.runs[run + 1] = batch.count;
+        batch.runs[run + 2] = 1;
+        batch.runCount += 1;
+    }
+    batch.count += 1;
+}

package/dist/spriteGl.d.ts

@@ -0,0 +1,26 @@
+/** The WebGL2 half of the sprite pass: one program, one instance buffer, one texture slot table. */
+import type { SpriteBatch } from './spriteBatch.ts';
+import type { SpriteTextureOptions } from './spriteTexture.ts';
+export interface Webgl2Sprites {
+    readonly program: WebGLProgram;
+    readonly vao: WebGLVertexArrayObject;
+    readonly instances: WebGLBuffer;
+    readonly uniforms: Readonly<Record<string, WebGLUniformLocation | null>>;
+    /** One per slot, `null` until the caller sets it. A run naming an empty slot draws nothing. */
+    readonly textures: (WebGLTexture | null)[];
+}
+export declare function createWebgl2Sprites(gl: WebGL2RenderingContext, capacity: number, slots: number, label: string): Webgl2Sprites;
+/** Replace a texture slot. The previous texture in that slot is deleted. */
+export declare function setWebgl2SpriteTexture(gl: WebGL2RenderingContext, sprites: Webgl2Sprites, slot: number, source: TexImageSource, options: SpriteTextureOptions): void;
+/**
+ * Fill a slot with one opaque white texel, from an array rather than an image.
+ *
+ * **White is the identity of the multiply this shader does**, so a quad on this slot draws exactly
+ * its tint — which is what a solid background is. Built from four bytes rather than from a canvas
+ * because the pass has no DOM to reach for and should not need one: `texImage2D`'s pixel overload
+ * takes the texel directly, and `queue.writeTexture` is its WebGPU twin.
+ */
+export declare function setWebgl2WhiteTexture(gl: WebGL2RenderingContext, sprites: Webgl2Sprites, slot: number): void;
+export declare function uploadWebgl2Instances(gl: WebGL2RenderingContext, sprites: Webgl2Sprites, batch: SpriteBatch): void;
+export declare function drawWebgl2Sprites(gl: WebGL2RenderingContext, sprites: Webgl2Sprites, batch: SpriteBatch, toNdc: Float32Array, clipCorrection: Float32Array, outputTransform: number, outputExposure: number): void;
+export declare function disposeWebgl2Sprites(gl: WebGL2RenderingContext, sprites: Webgl2Sprites): void;

package/dist/spriteGl.js

@@ -0,0 +1,207 @@
+/** The WebGL2 half of the sprite pass: one program, one instance buffer, one texture slot table. */
+import { SPRITE_FRAG, SPRITE_VERT } from './shaders/sprite.js';
+import { SPRITE_FLOATS } from './spriteBatch.js';
+/**
+ * The unit this pass borrows for the length of one draw.
+ *
+ * Fourteen is above every unit `lightBudget.ts` assigns — `COOKIE_ATLAS_TEXTURE_UNIT` is the
+ * highest at thirteen — and below the sixteen WebGL2 guarantees. The pass releases it before it
+ * returns, because a texture left bound to a unit a later pass attaches is a feedback loop rather
+ * than a wrong colour.
+ */
+const SPRITE_UNIT = 14;
+/** Bytes per instance. Fourteen floats; see `SPRITE_FLOATS`. */
+const STRIDE = SPRITE_FLOATS * 4;
+function compile(gl, kind, source, label) {
+    const shader = gl.createShader(kind);
+    if (shader === null)
+        throw new Error(`${label}: createShader failed`);
+    gl.shaderSource(shader, source);
+    gl.compileShader(shader);
+    if (gl.getShaderParameter(shader, gl.COMPILE_STATUS) !== true) {
+        const log = gl.getShaderInfoLog(shader) ?? '';
+        gl.deleteShader(shader);
+        throw new Error(`${label}: ${log}`);
+    }
+    return shader;
+}
+const UNIFORM_NAMES = [
+    'uToNdc0',
+    'uToNdc1',
+    'uClipCorrection',
+    'uSpriteTexture',
+    'uOutputTransform',
+    'uOutputExposure',
+];
+export function createWebgl2Sprites(gl, capacity, slots, label) {
+    const program = gl.createProgram();
+    if (program === null)
+        throw new Error(`${label}: createProgram failed`);
+    const vert = compile(gl, gl.VERTEX_SHADER, SPRITE_VERT, `${label} vertex`);
+    const frag = compile(gl, gl.FRAGMENT_SHADER, SPRITE_FRAG, `${label} fragment`);
+    gl.attachShader(program, vert);
+    gl.attachShader(program, frag);
+    gl.linkProgram(program);
+    gl.deleteShader(vert);
+    gl.deleteShader(frag);
+    if (gl.getProgramParameter(program, gl.LINK_STATUS) !== true) {
+        const log = gl.getProgramInfoLog(program) ?? '';
+        gl.deleteProgram(program);
+        throw new Error(`${label}: ${log}`);
+    }
+    const uniforms = {};
+    for (const name of UNIFORM_NAMES)
+        uniforms[name] = gl.getUniformLocation(program, name);
+    const vao = gl.createVertexArray();
+    const instances = gl.createBuffer();
+    if (vao === null || instances === null)
+        throw new Error(`${label}: buffer allocation failed`);
+    gl.bindVertexArray(vao);
+    gl.bindBuffer(gl.ARRAY_BUFFER, instances);
+    gl.bufferData(gl.ARRAY_BUFFER, capacity * STRIDE, gl.DYNAMIC_DRAW);
+    /*
+     * Four attributes, every one of them per instance: the quad's own corners come from
+     * `gl_VertexID` and cost no buffer at all. Offsets are re-pointed per run, which is how a run
+     * starts partway into the buffer without `baseInstance` — WebGL2 has no such call.
+     */
+    bindAttributes(gl, 0);
+    gl.bindVertexArray(null);
+    gl.bindBuffer(gl.ARRAY_BUFFER, null);
+    return { program, vao, instances, uniforms, textures: new Array(slots).fill(null) };
+}
+/** Point the four instance attributes at instance `first`. The buffer must be bound. */
+function bindAttributes(gl, first) {
+    const base = first * STRIDE;
+    gl.enableVertexAttribArray(0);
+    gl.vertexAttribPointer(0, 4, gl.FLOAT, false, STRIDE, base);
+    gl.vertexAttribDivisor(0, 1);
+    gl.enableVertexAttribArray(1);
+    gl.vertexAttribPointer(1, 4, gl.FLOAT, false, STRIDE, base + 16);
+    gl.vertexAttribDivisor(1, 1);
+    gl.enableVertexAttribArray(2);
+    gl.vertexAttribPointer(2, 4, gl.FLOAT, false, STRIDE, base + 32);
+    gl.vertexAttribDivisor(2, 1);
+    gl.enableVertexAttribArray(3);
+    gl.vertexAttribPointer(3, 2, gl.FLOAT, false, STRIDE, base + 48);
+    gl.vertexAttribDivisor(3, 1);
+}
+/** Replace a texture slot. The previous texture in that slot is deleted. */
+export function setWebgl2SpriteTexture(gl, sprites, slot, source, options) {
+    const previous = sprites.textures[slot];
+    if (previous !== null && previous !== undefined)
+        gl.deleteTexture(previous);
+    const texture = gl.createTexture();
+    if (texture === null)
+        throw new Error('ui2d: createTexture failed');
+    gl.activeTexture(gl.TEXTURE0 + SPRITE_UNIT);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    const internal = options.colorSpace === 'linear' ? gl.RGBA : gl.SRGB8_ALPHA8;
+    gl.texImage2D(gl.TEXTURE_2D, 0, internal, gl.RGBA, gl.UNSIGNED_BYTE, source);
+    const filter = options.filter === 'linear' ? gl.LINEAR : gl.NEAREST;
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);
+    /*
+     * Clamped on both axes, and it is a correctness rule rather than a default. A sheet frame's
+     * edge texel is adjacent to the *next* frame's, so a repeating wrap bleeds one sprite into
+     * another at exactly the seam a caller cannot see in the atlas.
+     */
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    gl.activeTexture(gl.TEXTURE0);
+    sprites.textures[slot] = texture;
+}
+/**
+ * Fill a slot with one opaque white texel, from an array rather than an image.
+ *
+ * **White is the identity of the multiply this shader does**, so a quad on this slot draws exactly
+ * its tint — which is what a solid background is. Built from four bytes rather than from a canvas
+ * because the pass has no DOM to reach for and should not need one: `texImage2D`'s pixel overload
+ * takes the texel directly, and `queue.writeTexture` is its WebGPU twin.
+ */
+export function setWebgl2WhiteTexture(gl, sprites, slot) {
+    const texture = gl.createTexture();
+    if (texture === null)
+        throw new Error('ui2d: createTexture failed');
+    gl.activeTexture(gl.TEXTURE0 + SPRITE_UNIT);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, 1, 1, 0, gl.RGBA, gl.UNSIGNED_BYTE, new Uint8Array([255, 255, 255, 255]));
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    gl.activeTexture(gl.TEXTURE0);
+    sprites.textures[slot] = texture;
+}
+export function uploadWebgl2Instances(gl, sprites, batch) {
+    if (batch.count === 0)
+        return;
+    gl.bindBuffer(gl.ARRAY_BUFFER, sprites.instances);
+    gl.bufferSubData(gl.ARRAY_BUFFER, 0, batch.instances, 0, batch.count * SPRITE_FLOATS);
+    gl.bindBuffer(gl.ARRAY_BUFFER, null);
+}
+export function drawWebgl2Sprites(gl, sprites, batch, toNdc, clipCorrection, outputTransform, outputExposure) {
+    if (batch.count === 0)
+        return;
+    gl.useProgram(sprites.program);
+    gl.bindVertexArray(sprites.vao);
+    gl.bindBuffer(gl.ARRAY_BUFFER, sprites.instances);
+    const u = sprites.uniforms;
+    gl.uniform4f(u['uToNdc0'] ?? null, toNdc[0], toNdc[1], toNdc[2], toNdc[3]);
+    gl.uniform4f(u['uToNdc1'] ?? null, toNdc[4], toNdc[5], 0, 0);
+    gl.uniformMatrix4fv(u['uClipCorrection'] ?? null, false, clipCorrection);
+    gl.uniform1i(u['uOutputTransform'] ?? null, outputTransform);
+    gl.uniform1f(u['uOutputExposure'] ?? null, outputExposure);
+    gl.uniform1i(u['uSpriteTexture'] ?? null, SPRITE_UNIT);
+    const blendWas = gl.getParameter(gl.BLEND);
+    const depthTestWas = gl.getParameter(gl.DEPTH_TEST);
+    const depthMaskWas = gl.getParameter(gl.DEPTH_WRITEMASK);
+    const cullWas = gl.getParameter(gl.CULL_FACE);
+    /*
+     * **Culling off, and the WebGPU pipeline says `cullMode: 'none'` for the same reason**: a sprite
+     * is mirrored by giving it a negative width, which reverses its winding, so a cull mode drops
+     * every flipped sprite — which is what a character facing left is.
+     *
+     * This line is here because the frame that was missing it drew *nothing at all* on WebGL2 while
+     * WebGPU was pixel-perfect, and nothing reported an error. A contributed pass inherits whatever
+     * cull state the last scene draw left on, and the screen-space quad's winding is not the scene's;
+     * WebGPU has no such inheritance, because a pipeline states its own. Every backend difference
+     * this seam has is of that shape: one API carries state between draws and the other does not.
+     */
+    gl.disable(gl.CULL_FACE);
+    gl.enable(gl.BLEND);
+    /* Premultiplied `over`: the fragment stage folds alpha in, so this composes onto opaque pixels. */
+    gl.blendFuncSeparate(gl.ONE, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+    gl.disable(gl.DEPTH_TEST);
+    gl.depthMask(false);
+    gl.activeTexture(gl.TEXTURE0 + SPRITE_UNIT);
+    for (let run = 0; run < batch.runCount; run += 1) {
+        const at = run * 3;
+        const texture = sprites.textures[batch.runs[at]];
+        if (texture === null || texture === undefined)
+            continue;
+        gl.bindTexture(gl.TEXTURE_2D, texture);
+        bindAttributes(gl, batch.runs[at + 1]);
+        gl.drawArraysInstanced(gl.TRIANGLES, 0, 6, batch.runs[at + 2]);
+    }
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.depthMask(depthMaskWas);
+    if (cullWas)
+        gl.enable(gl.CULL_FACE);
+    if (depthTestWas)
+        gl.enable(gl.DEPTH_TEST);
+    if (!blendWas)
+        gl.disable(gl.BLEND);
+    gl.bindBuffer(gl.ARRAY_BUFFER, null);
+    gl.bindVertexArray(null);
+}
+export function disposeWebgl2Sprites(gl, sprites) {
+    gl.deleteProgram(sprites.program);
+    gl.deleteVertexArray(sprites.vao);
+    gl.deleteBuffer(sprites.instances);
+    for (const texture of sprites.textures)
+        if (texture !== null)
+            gl.deleteTexture(texture);
+}

package/dist/spriteGpu.d.ts

@@ -0,0 +1,31 @@
+/** The WebGPU half of the sprite pass: one pipeline, one instance buffer, a bind group per slot. */
+import type { SpriteBatch } from './spriteBatch.ts';
+import type { SpriteImage, SpriteTextureOptions } from './spriteTexture.ts';
+export interface GpuSpriteSlot {
+    readonly texture: GPUTexture;
+    readonly bindGroup: GPUBindGroup;
+}
+export interface GpuSprites {
+    readonly pipeline: GPURenderPipeline;
+    readonly layout: GPUBindGroupLayout;
+    readonly vertexUniforms: GPUBuffer;
+    readonly fragmentUniforms: GPUBuffer;
+    readonly instances: GPUBuffer;
+    readonly samplers: {
+        readonly nearest: GPUSampler;
+        readonly linear: GPUSampler;
+    };
+    readonly slots: (GpuSpriteSlot | null)[];
+    readonly vertexScratch: ArrayBuffer;
+    readonly vertexFloats: Float32Array;
+    readonly fragmentScratch: ArrayBuffer;
+    readonly fragmentFloats: Float32Array;
+    readonly fragmentInts: Int32Array;
+}
+export declare function createGpuSprites(device: GPUDevice, format: GPUTextureFormat, depthFormat: GPUTextureFormat, samples: number, capacity: number, slots: number, label: string): GpuSprites;
+export declare function setGpuSpriteTexture(device: GPUDevice, sprites: GpuSprites, slot: number, source: SpriteImage, options: SpriteTextureOptions): void;
+/** The same one white texel, written straight into a texture. See the WebGL2 half for why. */
+export declare function setGpuWhiteTexture(device: GPUDevice, sprites: GpuSprites, slot: number): void;
+export declare function uploadGpuInstances(device: GPUDevice, sprites: GpuSprites, batch: SpriteBatch): void;
+export declare function drawGpuSprites(pass: GPURenderPassEncoder, sprites: GpuSprites, batch: SpriteBatch): void;
+export declare function disposeGpuSprites(sprites: GpuSprites): void;