@driftengine/ui2d 3.61.0

package/dist/spriteGpu.js

@@ -0,0 +1,201 @@
+/** The WebGPU half of the sprite pass: one pipeline, one instance buffer, a bind group per slot. */
+import { SPRITE_BINDINGS, SPRITE_FRAG_WGSL, SPRITE_VERT_WGSL, } from './shaders/generated/sprite.wgsl.js';
+import { SPRITE_FLOATS } from './spriteBatch.js';
+const VERT = SPRITE_BINDINGS.SPRITE_VERT;
+const FRAG = SPRITE_BINDINGS.SPRITE_FRAG;
+const STRIDE = SPRITE_FLOATS * 4;
+const STAGE_VERTEX = 1; // GPUShaderStage.VERTEX
+const STAGE_FRAGMENT = 2; // GPUShaderStage.FRAGMENT
+const UNIFORM_COPY_DST = 64 | 8; // GPUBufferUsage.UNIFORM | COPY_DST
+const VERTEX_COPY_DST = 32 | 8; // GPUBufferUsage.VERTEX | COPY_DST
+const TEXTURE_USAGE = 4 | 2 | 16; // TEXTURE_BINDING | COPY_DST | RENDER_ATTACHMENT
+export function createGpuSprites(device, format, depthFormat, samples, capacity, slots, label) {
+    const layout = device.createBindGroupLayout({
+        label: `${label}.layout`,
+        entries: [
+            { binding: VERT.uniforms, visibility: STAGE_VERTEX, buffer: { type: 'uniform' } },
+            { binding: FRAG.uniforms, visibility: STAGE_FRAGMENT, buffer: { type: 'uniform' } },
+            {
+                binding: FRAG.textures.uSpriteTexture.texture,
+                visibility: STAGE_FRAGMENT,
+                texture: { sampleType: 'float' },
+            },
+            {
+                binding: FRAG.textures.uSpriteTexture.sampler,
+                visibility: STAGE_FRAGMENT,
+                sampler: { type: 'filtering' },
+            },
+        ],
+    });
+    const pipeline = device.createRenderPipeline({
+        label,
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            module: device.createShaderModule({ label: `${label}.vert`, code: SPRITE_VERT_WGSL }),
+            entryPoint: 'main',
+            buffers: [
+                {
+                    arrayStride: STRIDE,
+                    stepMode: 'instance',
+                    attributes: [
+                        { shaderLocation: 0, offset: 0, format: 'float32x4' },
+                        { shaderLocation: 1, offset: 16, format: 'float32x4' },
+                        { shaderLocation: 2, offset: 32, format: 'float32x4' },
+                        { shaderLocation: 3, offset: 48, format: 'float32x2' },
+                    ],
+                },
+            ],
+        },
+        fragment: {
+            module: device.createShaderModule({ label: `${label}.frag`, code: SPRITE_FRAG_WGSL }),
+            entryPoint: 'main',
+            targets: [
+                {
+                    format,
+                    /* Premultiplied `over`, matching the WebGL2 half exactly. */
+                    blend: {
+                        color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                        alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+                    },
+                },
+            ],
+        },
+        /*
+         * Nothing is culled: a sprite is mirrored by giving it a negative width, which reverses its
+         * winding, and a character facing left is exactly that.
+         */
+        primitive: { topology: 'triangle-list', cullMode: 'none' },
+        multisample: { count: samples },
+        /*
+         * Neither tested nor written. The 2D layer's order *is* its layering — there is no z to sort
+         * by — and a pass that depth-tested would let whatever 3D geometry is in the frame punch holes
+         * in an overlay drawn over it. Declared all the same, because a pipeline in a render pass that
+         * has a depth attachment must name its format.
+         */
+        depthStencil: { format: depthFormat, depthWriteEnabled: false, depthCompare: 'always' },
+    });
+    const vertexUniforms = device.createBuffer({
+        label: `${label}.vertexUniforms`,
+        size: VERT.uniformSize,
+        usage: UNIFORM_COPY_DST,
+    });
+    const fragmentUniforms = device.createBuffer({
+        label: `${label}.fragmentUniforms`,
+        size: FRAG.uniformSize,
+        usage: UNIFORM_COPY_DST,
+    });
+    const instances = device.createBuffer({
+        label: `${label}.instances`,
+        size: capacity * STRIDE,
+        usage: VERTEX_COPY_DST,
+    });
+    const vertexScratch = new ArrayBuffer(VERT.uniformSize);
+    const fragmentScratch = new ArrayBuffer(FRAG.uniformSize);
+    return {
+        pipeline,
+        layout,
+        vertexUniforms,
+        fragmentUniforms,
+        instances,
+        samplers: {
+            nearest: device.createSampler({ label: `${label}.nearest` }),
+            linear: device.createSampler({
+                label: `${label}.linear`,
+                magFilter: 'linear',
+                minFilter: 'linear',
+            }),
+        },
+        slots: new Array(slots).fill(null),
+        vertexScratch,
+        vertexFloats: new Float32Array(vertexScratch),
+        fragmentScratch,
+        fragmentFloats: new Float32Array(fragmentScratch),
+        fragmentInts: new Int32Array(fragmentScratch),
+    };
+}
+export function setGpuSpriteTexture(device, sprites, slot, source, options) {
+    const previous = sprites.slots[slot];
+    if (previous !== null && previous !== undefined)
+        previous.texture.destroy();
+    const texture = device.createTexture({
+        label: `ui2d.sprite.${slot}`,
+        size: [source.width, source.height],
+        format: options.colorSpace === 'linear' ? 'rgba8unorm' : 'rgba8unorm-srgb',
+        usage: TEXTURE_USAGE,
+    });
+    /*
+     * **No flip, matching WebGL2** — `surfaceTexture.ts` carries the whole argument and the bug it
+     * came from: `UNPACK_FLIP_Y_WEBGL` is ignored for an `ImageBitmap` and honoured for a canvas, so
+     * a `flipY: true` here would be self-consistent and disagree with the other backend on exactly
+     * the source type most callers use.
+     */
+    device.queue.copyExternalImageToTexture({ source: source, flipY: false }, { texture }, [source.width, source.height]);
+    const sampler = options.filter === 'linear' ? sprites.samplers.linear : sprites.samplers.nearest;
+    const bindGroup = device.createBindGroup({
+        label: `ui2d.sprite.${slot}.bindGroup`,
+        layout: sprites.layout,
+        entries: [
+            { binding: VERT.uniforms, resource: { buffer: sprites.vertexUniforms } },
+            { binding: FRAG.uniforms, resource: { buffer: sprites.fragmentUniforms } },
+            { binding: FRAG.textures.uSpriteTexture.texture, resource: texture.createView() },
+            { binding: FRAG.textures.uSpriteTexture.sampler, resource: sampler },
+        ],
+    });
+    sprites.slots[slot] = { texture, bindGroup };
+}
+/** The same one white texel, written straight into a texture. See the WebGL2 half for why. */
+export function setGpuWhiteTexture(device, sprites, slot) {
+    const texture = device.createTexture({
+        label: 'ui2d.sprite.white',
+        size: [1, 1],
+        /* Not `-srgb`: 255 is 255 either way, and a linear format says so without a decode. */
+        format: 'rgba8unorm',
+        usage: TEXTURE_USAGE,
+    });
+    device.queue.writeTexture({ texture }, new Uint8Array([255, 255, 255, 255]), { bytesPerRow: 4 }, [1, 1]);
+    const bindGroup = device.createBindGroup({
+        label: 'ui2d.sprite.white.bindGroup',
+        layout: sprites.layout,
+        entries: [
+            { binding: VERT.uniforms, resource: { buffer: sprites.vertexUniforms } },
+            { binding: FRAG.uniforms, resource: { buffer: sprites.fragmentUniforms } },
+            { binding: FRAG.textures.uSpriteTexture.texture, resource: texture.createView() },
+            { binding: FRAG.textures.uSpriteTexture.sampler, resource: sprites.samplers.nearest },
+        ],
+    });
+    sprites.slots[slot] = { texture, bindGroup };
+}
+export function uploadGpuInstances(device, sprites, batch) {
+    if (batch.count === 0)
+        return;
+    device.queue.writeBuffer(sprites.instances, 0, batch.instances.buffer, batch.instances.byteOffset, batch.count * STRIDE);
+}
+export function drawGpuSprites(pass, sprites, batch) {
+    if (batch.count === 0)
+        return;
+    pass.setPipeline(sprites.pipeline);
+    for (let run = 0; run < batch.runCount; run += 1) {
+        const at = run * 3;
+        const slot = sprites.slots[batch.runs[at]];
+        if (slot === null || slot === undefined)
+            continue;
+        const first = batch.runs[at + 1];
+        const count = batch.runs[at + 2];
+        pass.setBindGroup(0, slot.bindGroup);
+        /*
+         * The run's offset goes into the vertex buffer binding rather than into `firstInstance`,
+         * which is the one place the two backends can be made to do the same arithmetic: WebGL2 has
+         * no base-instance call at all and re-points its attributes the same way.
+         */
+        pass.setVertexBuffer(0, sprites.instances, first * STRIDE, count * STRIDE);
+        pass.draw(6, count);
+    }
+}
+export function disposeGpuSprites(sprites) {
+    sprites.vertexUniforms.destroy();
+    sprites.fragmentUniforms.destroy();
+    sprites.instances.destroy();
+    for (const slot of sprites.slots)
+        if (slot !== null)
+            slot.texture.destroy();
+}

package/dist/spritePass.d.ts

@@ -0,0 +1,54 @@
+/** The 2D layer as a pass a consumer registers: one batch of quads, drawn where the caller says. */
+import type { PassDefinition } from '@driftengine/core';
+import type { Affine2D } from './camera2d.ts';
+import type { SpriteBatch } from './spriteBatch.ts';
+import type { SpriteImage, SpriteTextureOptions } from './spriteTexture.ts';
+/** Sprites a frame, if the caller does not say. Four thousand quads is 224 KB of instance data. */
+export declare const DEFAULT_SPRITE_CAPACITY = 4096;
+/**
+ * Texture slots, if the caller does not say.
+ *
+ * Eight is a sheet for the world, one for the interface, and room to spare. It is not a GPU limit
+ * — each slot is its own bind group on WebGPU and its own object on WebGL2 — it is the number
+ * above which a caller should be asking why its 2D layer has that many atlases.
+ */
+export declare const DEFAULT_SPRITE_SLOTS = 8;
+export interface SpritePassOptions {
+    readonly capacity?: number;
+    readonly slots?: number;
+    readonly label?: string;
+}
+export interface SpritePass extends PassDefinition {
+    /**
+     * The quads for this frame. Reset it, fill it with `drawSprite`, then call `drawPass`.
+     *
+     * Held by the pass rather than handed in per frame, because its size is the pass's GPU buffer
+     * and the two must agree.
+     */
+    readonly batch: SpriteBatch;
+    /**
+     * A slot holding one opaque white texel, filled by the pass and not settable.
+     *
+     * White is the identity of the multiply the shader does, so a quad on this slot draws exactly its
+     * tint — which is what a solid rectangle is, and what `fillPanel` in core does with a whole
+     * program of its own. A caller drawing a filled box needs no sheet for it.
+     *
+     * **A background on this slot and an image from a sheet are two runs**, because a slot change is
+     * a run and the order may not be regrouped. A caller with many filled boxes and many images
+     * interleaved should pack a white texel into its *own* sheet and tint a frame of that instead:
+     * then the whole tree is one run. This slot is the convenience, and the sheet is the fast path.
+     */
+    readonly white: number;
+    /** Clear the batch. Call once at the top of a frame. */
+    reset(): void;
+    /**
+     * Where the batch's coordinates are, from `screenToNdc` or `worldToNdc`.
+     *
+     * Copied, so the caller may reuse its array; and read at draw time, so this can be called before
+     * the pass has a device.
+     */
+    setTransform(affine: Affine2D): void;
+    /** Fill a texture slot. Safe before the pass is registered; applied when it gets a device. */
+    setTexture(slot: number, source: SpriteImage, options?: SpriteTextureOptions): void;
+}
+export declare function createSpritePass(options?: SpritePassOptions): SpritePass;

package/dist/spritePass.js

@@ -0,0 +1,142 @@
+/** The 2D layer as a pass a consumer registers: one batch of quads, drawn where the caller says. */
+import { SPRITE_BINDINGS } from './shaders/generated/sprite.wgsl.js';
+import { createAffine2D } from './camera2d.js';
+import { createSpriteBatch, resetSpriteBatch } from './spriteBatch.js';
+import { createWebgl2Sprites, disposeWebgl2Sprites, drawWebgl2Sprites, setWebgl2SpriteTexture, setWebgl2WhiteTexture, uploadWebgl2Instances, } from './spriteGl.js';
+import { createGpuSprites, disposeGpuSprites, drawGpuSprites, setGpuSpriteTexture, setGpuWhiteTexture, uploadGpuInstances, } from './spriteGpu.js';
+import { DEFAULT_SPRITE_TEXTURE_OPTIONS } from './spriteTexture.js';
+const VERT = SPRITE_BINDINGS.SPRITE_VERT;
+const FRAG = SPRITE_BINDINGS.SPRITE_FRAG;
+/** Identity, so a pass that is drawn before it is transformed puts its sprites in clip space. */
+const IDENTITY_CLIP = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+/** Sprites a frame, if the caller does not say. Four thousand quads is 224 KB of instance data. */
+export const DEFAULT_SPRITE_CAPACITY = 4096;
+/**
+ * Texture slots, if the caller does not say.
+ *
+ * Eight is a sheet for the world, one for the interface, and room to spare. It is not a GPU limit
+ * — each slot is its own bind group on WebGPU and its own object on WebGL2 — it is the number
+ * above which a caller should be asking why its 2D layer has that many atlases.
+ */
+export const DEFAULT_SPRITE_SLOTS = 8;
+export function createSpritePass(options = {}) {
+    const capacity = options.capacity ?? DEFAULT_SPRITE_CAPACITY;
+    const slots = options.slots ?? DEFAULT_SPRITE_SLOTS;
+    const label = options.label ?? 'ui2d.sprites';
+    /* One past the caller's slots, so `setTexture` cannot reach it and it cannot be lost. */
+    const white = slots;
+    const batch = createSpriteBatch(capacity);
+    const toNdc = createAffine2D();
+    /* Identity as an affine: ndc = (x, y). A caller that never sets one draws in clip space. */
+    toNdc[0] = 1;
+    toNdc[3] = 1;
+    let gl = null;
+    let context = null;
+    let gpu = null;
+    let device = null;
+    let clipCorrection = IDENTITY_CLIP;
+    const pending = [];
+    const applyTexture = (entry) => {
+        if (gl !== null && context !== null) {
+            setWebgl2SpriteTexture(context, gl, entry.slot, entry.source, entry.options);
+            return;
+        }
+        if (gpu !== null && device !== null) {
+            setGpuSpriteTexture(device, gpu, entry.slot, entry.source, entry.options);
+        }
+    };
+    return {
+        label,
+        batch,
+        white,
+        reset() {
+            resetSpriteBatch(batch);
+        },
+        setTransform(affine) {
+            toNdc.set(affine);
+        },
+        setTexture(slot, source, textureOptions) {
+            if (slot < 0 || slot >= slots) {
+                throw new RangeError(`${label}: slot ${slot} is outside the ${slots} this pass has`);
+            }
+            const entry = {
+                slot,
+                source,
+                options: textureOptions ?? DEFAULT_SPRITE_TEXTURE_OPTIONS,
+            };
+            if (gl === null && gpu === null) {
+                pending.push(entry);
+                return;
+            }
+            applyTexture(entry);
+        },
+        init(passDevice) {
+            /*
+             * The correction the *matrix* carries, because this stage builds its own clip position and
+             * never multiplies by a camera. Without it the generated WGSL's Y negation stands
+             * uncancelled and the whole 2D layer lands mirrored — `panel.ts` in core made the same
+             * mistake once and its comment is where the reason is written out.
+             */
+            clipCorrection = passDevice.clipCorrection;
+            if (passDevice.backend === 'webgl2') {
+                context = passDevice.gl;
+                gl = createWebgl2Sprites(passDevice.gl, capacity, slots + 1, label);
+            }
+            else {
+                device = passDevice.device;
+                gpu = createGpuSprites(passDevice.device, passDevice.format, passDevice.depthFormat, passDevice.samples, capacity, slots + 1, label);
+            }
+            if (gl !== null && context !== null)
+                setWebgl2WhiteTexture(context, gl, white);
+            if (gpu !== null && device !== null)
+                setGpuWhiteTexture(device, gpu, white);
+            for (const entry of pending)
+                applyTexture(entry);
+            pending.length = 0;
+        },
+        draw(ctx) {
+            if (batch.count === 0)
+                return;
+            if (ctx.backend === 'webgl2') {
+                if (gl === null)
+                    return;
+                uploadWebgl2Instances(ctx.gl, gl, batch);
+                drawWebgl2Sprites(ctx.gl, gl, batch, toNdc, clipCorrection, ctx.outputTransform, ctx.outputExposure);
+                return;
+            }
+            if (gpu === null || device === null)
+                return;
+            const f = gpu.vertexFloats;
+            f[VERT.fields.uToNdc0.offset / 4] = toNdc[0];
+            f[VERT.fields.uToNdc0.offset / 4 + 1] = toNdc[1];
+            f[VERT.fields.uToNdc0.offset / 4 + 2] = toNdc[2];
+            f[VERT.fields.uToNdc0.offset / 4 + 3] = toNdc[3];
+            f[VERT.fields.uToNdc1.offset / 4] = toNdc[4];
+            f[VERT.fields.uToNdc1.offset / 4 + 1] = toNdc[5];
+            f.set(clipCorrection, VERT.fields.uClipCorrection.offset / 4);
+            gpu.fragmentInts[FRAG.fields.uOutputTransform.offset / 4] = ctx.outputTransform;
+            gpu.fragmentFloats[FRAG.fields.uOutputExposure.offset / 4] = ctx.outputExposure;
+            /*
+             * Written from inside an open render pass, which is allowed and ordered: a queue write
+             * issued now lands before the command buffer this pass is being recorded into is submitted.
+             * What it does mean is **one `drawPass` a frame per pass** — a second would overwrite the
+             * first's instances before either had executed. A caller that wants the 2D layer in two
+             * places in the frame registers two passes, which is also how two splat captures work.
+             */
+            device.queue.writeBuffer(gpu.vertexUniforms, 0, gpu.vertexScratch);
+            device.queue.writeBuffer(gpu.fragmentUniforms, 0, gpu.fragmentScratch);
+            uploadGpuInstances(device, gpu, batch);
+            drawGpuSprites(ctx.pass, gpu, batch);
+        },
+        dispose() {
+            if (gl !== null && context !== null)
+                disposeWebgl2Sprites(context, gl);
+            if (gpu !== null)
+                disposeGpuSprites(gpu);
+            gl = null;
+            gpu = null;
+            context = null;
+            device = null;
+        },
+    };
+}

package/dist/spriteSheet.d.ts

@@ -0,0 +1,64 @@
+/** A sheet: the rectangles of one texture that each hold a picture, addressed by index or name. */
+import type { UvRect } from './spriteBatch.ts';
+/** A `UvRect` a caller owns and refills, so reading a frame allocates nothing. */
+export interface SpriteFrame {
+    u0: number;
+    v0: number;
+    u1: number;
+    v1: number;
+}
+export declare function createSpriteFrame(): SpriteFrame;
+/** One entry of an atlas, in texels, as a packer emits it. */
+export interface SheetEntry {
+    readonly name: string;
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+/**
+ * The frames of one texture.
+ *
+ * Two flat arrays and a name index rather than an array of objects: reading a frame in a draw loop
+ * is four `Float32Array` reads and no property lookups, and a tilemap does that per tile.
+ */
+export interface SpriteSheet {
+    /** The slot on the pass this sheet's texture was set into. */
+    readonly texture: number;
+    /** The texture's own size, in texels. */
+    readonly width: number;
+    readonly height: number;
+    readonly count: number;
+    /** Four per frame: u0, v0, u1, v1. */
+    readonly uvs: Float32Array;
+    /** Two per frame: width and height in texels, for drawing a frame at its own scale. */
+    readonly sizes: Float32Array;
+    readonly names: ReadonlyMap<string, number>;
+}
+/**
+ * A sheet cut into equal cells, row-major: left to right, then down.
+ *
+ * **A cell that would run off the edge is not emitted.** A sheet 70 texels wide cut into sixteens
+ * has four whole cells and six texels of margin, and a fifth cell reading into that margin is a
+ * frame with a stripe of nothing down one side — which reads as a rendering bug rather than as a
+ * badly measured atlas.
+ *
+ * Frames are named `"0"`, `"1"` and so on, so `frameOf` works on a grid too.
+ */
+export declare function gridSheet(texture: number, width: number, height: number, cellWidth: number, cellHeight: number): SpriteSheet;
+/** A sheet from an atlas description: whatever rectangles a packer put where. */
+export declare function namedSheet(texture: number, width: number, height: number, entries: readonly SheetEntry[]): SpriteSheet;
+/** The index a name has, or `-1`. */
+export declare function frameOf(sheet: SpriteSheet, name: string): number;
+/**
+ * Read a frame into a rectangle the caller owns. Allocates nothing.
+ *
+ * **An index this sheet does not have reads as the whole texture rather than throwing**, because
+ * this is called per sprite per frame and the rule is that nothing throws in the frame loop. What
+ * a caller then sees is the entire atlas drawn where one picture should be, which is unmistakable.
+ */
+export declare function sheetFrame(sheet: SpriteSheet, index: number, out: SpriteFrame): UvRect;
+/** A frame's width in texels, or 0 for an index the sheet does not have. */
+export declare function sheetFrameWidth(sheet: SpriteSheet, index: number): number;
+/** A frame's height in texels, or 0 for an index the sheet does not have. */
+export declare function sheetFrameHeight(sheet: SpriteSheet, index: number): number;

package/dist/spriteSheet.js

@@ -0,0 +1,84 @@
+/** A sheet: the rectangles of one texture that each hold a picture, addressed by index or name. */
+export function createSpriteFrame() {
+    return { u0: 0, v0: 0, u1: 1, v1: 1 };
+}
+function build(texture, width, height, entries) {
+    const uvs = new Float32Array(entries.length * 4);
+    const sizes = new Float32Array(entries.length * 2);
+    const names = new Map();
+    entries.forEach((entry, index) => {
+        uvs[index * 4] = entry.x / width;
+        uvs[index * 4 + 1] = entry.y / height;
+        uvs[index * 4 + 2] = (entry.x + entry.w) / width;
+        uvs[index * 4 + 3] = (entry.y + entry.h) / height;
+        sizes[index * 2] = entry.w;
+        sizes[index * 2 + 1] = entry.h;
+        names.set(entry.name, index);
+    });
+    return { texture, width, height, count: entries.length, uvs, sizes, names };
+}
+/**
+ * A sheet cut into equal cells, row-major: left to right, then down.
+ *
+ * **A cell that would run off the edge is not emitted.** A sheet 70 texels wide cut into sixteens
+ * has four whole cells and six texels of margin, and a fifth cell reading into that margin is a
+ * frame with a stripe of nothing down one side — which reads as a rendering bug rather than as a
+ * badly measured atlas.
+ *
+ * Frames are named `"0"`, `"1"` and so on, so `frameOf` works on a grid too.
+ */
+export function gridSheet(texture, width, height, cellWidth, cellHeight) {
+    const columns = Math.floor(width / cellWidth);
+    const rows = Math.floor(height / cellHeight);
+    const entries = [];
+    for (let row = 0; row < rows; row += 1) {
+        for (let column = 0; column < columns; column += 1) {
+            entries.push({
+                name: String(entries.length),
+                x: column * cellWidth,
+                y: row * cellHeight,
+                w: cellWidth,
+                h: cellHeight,
+            });
+        }
+    }
+    return build(texture, width, height, entries);
+}
+/** A sheet from an atlas description: whatever rectangles a packer put where. */
+export function namedSheet(texture, width, height, entries) {
+    return build(texture, width, height, entries);
+}
+/** The index a name has, or `-1`. */
+export function frameOf(sheet, name) {
+    return sheet.names.get(name) ?? -1;
+}
+/**
+ * Read a frame into a rectangle the caller owns. Allocates nothing.
+ *
+ * **An index this sheet does not have reads as the whole texture rather than throwing**, because
+ * this is called per sprite per frame and the rule is that nothing throws in the frame loop. What
+ * a caller then sees is the entire atlas drawn where one picture should be, which is unmistakable.
+ */
+export function sheetFrame(sheet, index, out) {
+    if (index < 0 || index >= sheet.count) {
+        out.u0 = 0;
+        out.v0 = 0;
+        out.u1 = 1;
+        out.v1 = 1;
+        return out;
+    }
+    const at = index * 4;
+    out.u0 = sheet.uvs[at];
+    out.v0 = sheet.uvs[at + 1];
+    out.u1 = sheet.uvs[at + 2];
+    out.v1 = sheet.uvs[at + 3];
+    return out;
+}
+/** A frame's width in texels, or 0 for an index the sheet does not have. */
+export function sheetFrameWidth(sheet, index) {
+    return index < 0 || index >= sheet.count ? 0 : sheet.sizes[index * 2];
+}
+/** A frame's height in texels, or 0 for an index the sheet does not have. */
+export function sheetFrameHeight(sheet, index) {
+    return index < 0 || index >= sheet.count ? 0 : sheet.sizes[index * 2 + 1];
+}

package/dist/spriteTexture.d.ts

@@ -0,0 +1,36 @@
+/** What a caller hands over as a sprite texture, and what it says about it. */
+/**
+ * The three sources both backends take without a conversion.
+ *
+ * Narrower than `TexImageSource` on purpose. WebGPU's `copyExternalImageToTexture` refuses an
+ * `ImageData` outright, and an `HTMLImageElement` is accepted by only some implementations — so
+ * the union that is honestly portable is a bitmap and the two canvases. A caller with an `<img>`
+ * reaches this through one `createImageBitmap`, which is also where the decode's own orientation
+ * and premultiply options live, and those are decisions worth making in the open.
+ *
+ * All three carry their own `width` and `height`, which is the other reason: nothing here has to
+ * ask the caller how big the image it just handed over is.
+ */
+export type SpriteImage = ImageBitmap | HTMLCanvasElement | OffscreenCanvas;
+export interface SpriteTextureOptions {
+    /**
+     * `srgb` is right for anything painted to be looked at, which is every sprite sheet — the
+     * sampler decodes and the pass's own output transform re-encodes, so the blend happens in
+     * linear light where it belongs. `linear` is for a sheet carrying data rather than colour: a
+     * mask, a height, a flow field.
+     *
+     * The same name and the same two values `SurfaceTexture` already takes, so a consumer that has
+     * uploaded a texture to the mesh path does not meet a second vocabulary here.
+     */
+    readonly colorSpace?: 'linear' | 'srgb';
+    /**
+     * `nearest` by default, and the default is the argument.
+     *
+     * A sprite sheet is usually pixel art, where linear filtering is the thing that makes it look
+     * wrong; and a sheet that is *not* pixel art is normally drawn near its authored size, where
+     * the two filters differ by very little. So the default costs the smooth case almost nothing
+     * and saves the sharp case from a blur nobody asked for.
+     */
+    readonly filter?: 'nearest' | 'linear';
+}
+export declare const DEFAULT_SPRITE_TEXTURE_OPTIONS: SpriteTextureOptions;

package/dist/spriteTexture.js

@@ -0,0 +1,5 @@
+/** What a caller hands over as a sprite texture, and what it says about it. */
+export const DEFAULT_SPRITE_TEXTURE_OPTIONS = {
+    colorSpace: 'srgb',
+    filter: 'nearest',
+};

package/dist/tilemap.d.ts

@@ -0,0 +1,47 @@
+/** A grid of sheet frames, drawn as sprites, culled to what the view can see. */
+import type { SpriteBatch } from './spriteBatch.ts';
+import type { SpriteSheet } from './spriteSheet.ts';
+/** A cell holding nothing. Negative, so it can never be a frame index. */
+export declare const TILE_EMPTY = -1;
+export interface Tilemap {
+    readonly columns: number;
+    readonly rows: number;
+    /** One frame index per cell, row-major. `TILE_EMPTY` for a cell with nothing in it. */
+    readonly tiles: Int32Array;
+    /** How big a cell is, in whatever units the batch's affine maps from. */
+    readonly tileWidth: number;
+    readonly tileHeight: number;
+    /**
+     * Where cell (0, 0)'s corner sits.
+     *
+     * Mutable, because scrolling a map is moving it and the alternative is rebuilding one.
+     */
+    x: number;
+    y: number;
+}
+/** What the view can see, in the same units the map is placed in. */
+export interface ViewRect {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export declare function createTilemap(columns: number, rows: number, tileWidth: number, tileHeight: number): Tilemap;
+/** The frame in a cell, or `TILE_EMPTY` — including for a cell outside the map. */
+export declare function tileAt(map: Tilemap, column: number, row: number): number;
+/** Put a frame in a cell. A cell outside the map is ignored rather than wrapping into another row. */
+export declare function setTile(map: Tilemap, column: number, row: number, tile: number): void;
+/**
+ * Draw the tiles the view can see. Returns how many that was.
+ *
+ * **The cost is the view rather than the map**, which is the whole reason this is a function and
+ * not a loop the caller writes: the visible span is arithmetic on four numbers, so a map of a
+ * million cells costs the few hundred on screen. A walk over every cell testing each against the
+ * view would draw exactly the same picture and be unusable at the size a tilemap exists for.
+ *
+ * **Which way the rows run is the affine's business, not this function's.** A cell's corner is
+ * `y + row * tileHeight`, so in screen space — where y counts down — row 0 is the top row, and in a
+ * 2D world — where y counts up — it is the bottom. That is the same rule `SpritePlacement` states
+ * about its own corner, and having one rule rather than a flag is what keeps the two agreeing.
+ */
+export declare function drawTilemap(batch: SpriteBatch, map: Tilemap, sheet: SpriteSheet, view: ViewRect, tint: ArrayLike<number> | null): number;