@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/render/shadow.js

@@ -0,0 +1,208 @@
+import { mat4 } from '../core/math.js';
+import { Camera } from './camera.js';
+import { DEFAULT_SHADOW_BIAS } from './lights.js';
+import { INSTANCE_BUFFER_LAYOUT } from './material.js';
+import { createShaderModule, materialPrelude } from './wgsl.js';
+/** Depth format of the sun's shadow map (and of the 1×1 placeholder bound without one). */
+export const SHADOW_FORMAT = 'depth32float';
+/** Shadow map side in texels when `SunShadow.size` is not given. */
+export const DEFAULT_SHADOW_SIZE = 2048;
+const UP = new Float32Array([0, 1, 0]);
+const UP_Z = new Float32Array([0, 0, 1]);
+/**
+ * The sun's shadow map: one `depth32float` texture, a comparison sampler, a 1×1 placeholder
+ * depth texture (what every view binds at `@group(0) @binding(3)` until a shadow pass has
+ * rendered) and a depth-only pipeline per vertex layout. The renderer owns one and, for each
+ * `render` whose `frame.lights.sun.shadow` is set, encodes a shadow pass through `sunCamera`
+ * (an orthographic `Camera` placed by `place`) over the view's opaque shadow-casting draws. A
+ * caster whose material has a `shadowFragmentEntry` (alpha mask, dissolve) draws through that
+ * material's `shadowPipelineFor` instead, so its holes show in the shadow.
+ * Engine-internal; games set `Lights.sun.shadow`.
+ */
+export class ShadowMap {
+    /** Comparison sampler (`less-equal`: a receiver at or in front of the stored depth is lit). */
+    sampler;
+    /** 1×1 depth view bound in place of the map (and in the shadow pass itself). */
+    placeholder;
+    /** The orthographic camera the shadow pass renders through; `place` sets it. */
+    sunCamera = new Camera();
+    /** What `Lights.writeBlock` needs for the view this map was rendered for. */
+    uniforms;
+    /** Side of the current map in texels, 0 before the first shadow pass. */
+    size = 0;
+    /** Bumped every time the map texture is (re)created, so bind groups can follow it. */
+    generation = 0;
+    texture = null;
+    /** Maps replaced this frame (passes already encoded may still read them); see `flush`. */
+    retired = [];
+    mapView;
+    placeholderTex;
+    device;
+    pipelineLayout;
+    pipelines = new Map();
+    /** Skinned layouts: one pipeline per material bind group layout (the palette is group 1). */
+    skinnedPipelines = new Map();
+    globalsLayout;
+    viewM = mat4.create();
+    projM = mat4.create();
+    eye = new Float32Array(3);
+    target = new Float32Array(3);
+    depthAtt;
+    /** The shadow pass descriptor; its attachment view follows `view`. */
+    passDesc;
+    constructor(device, globalsLayout) {
+        this.device = device;
+        this.globalsLayout = globalsLayout;
+        this.sampler = device.createSampler({
+            label: 'engine-shadow-sampler',
+            compare: 'less-equal',
+            magFilter: 'linear',
+            minFilter: 'linear',
+            addressModeU: 'clamp-to-edge',
+            addressModeV: 'clamp-to-edge',
+        });
+        this.placeholderTex = device.createTexture({
+            label: 'engine-shadow-placeholder',
+            size: [1, 1],
+            format: SHADOW_FORMAT,
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT,
+        });
+        this.placeholder = this.placeholderTex.createView({ label: 'engine-shadow-placeholder' });
+        this.mapView = this.placeholder;
+        this.pipelineLayout = device.createPipelineLayout({
+            label: 'engine-shadow-layout',
+            bindGroupLayouts: [globalsLayout],
+        });
+        this.depthAtt = {
+            view: this.placeholder,
+            depthClearValue: 1,
+            depthLoadOp: 'clear',
+            depthStoreOp: 'store',
+        };
+        this.passDesc = {
+            label: 'shadow',
+            colorAttachments: [],
+            depthStencilAttachment: this.depthAtt,
+        };
+        this.uniforms = { viewProj: this.sunCamera.viewProjection, bias: 0, texelSize: 0 };
+        this.sunCamera.depthTest = true;
+        this.sunCamera.depthWrite = true;
+    }
+    /** The map's view when one has been rendered, else `placeholder`. */
+    get view() {
+        return this.mapView;
+    }
+    /**
+     * Make sure the map is `size` texels square (creating or replacing the texture; bumps
+     * `generation` when it does). Returns whether the texture changed.
+     */
+    ensure(size) {
+        if (this.texture && this.size === size)
+            return false;
+        if (this.texture)
+            this.retired.push(this.texture);
+        this.texture = this.device.createTexture({
+            label: 'engine-shadow-map',
+            size: [size, size],
+            format: SHADOW_FORMAT,
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT,
+        });
+        this.mapView = this.texture.createView({ label: 'engine-shadow-map' });
+        this.depthAtt.view = this.mapView;
+        this.size = size;
+        this.generation++;
+        return true;
+    }
+    /**
+     * Point `sunCamera` along `sunDir` through an orthographic box centred on `center` (the
+     * rendering camera's position): half-width `shadow.extent`, depth `near..far` along the
+     * light measured from `center` (defaults `-extent..extent`). Fills `uniforms` for a map of
+     * `size` texels. No allocation.
+     */
+    place(center, sunDir, shadow, size) {
+        const dx = sunDir[0] ?? 0;
+        const dy = sunDir[1] ?? 0;
+        const dz = sunDir[2] ?? 0;
+        const len = Math.hypot(dx, dy, dz) || 1;
+        const e = this.eye;
+        const t = this.target;
+        e[0] = center[0] ?? 0;
+        e[1] = center[1] ?? 0;
+        e[2] = center[2] ?? 0;
+        t[0] = e[0] + dx / len;
+        t[1] = e[1] + dy / len;
+        t[2] = e[2] + dz / len;
+        // A sun straight up or down has no stable +y "up"; use +z then.
+        const up = Math.abs(dy / len) > 0.999 ? UP_Z : UP;
+        mat4.lookAt(this.viewM, e, t, up);
+        const extent = shadow.extent;
+        const near = shadow.near ?? -extent;
+        const far = shadow.far ?? extent;
+        mat4.ortho(this.projM, -extent, extent, -extent, extent, near, far);
+        this.sunCamera.setView(this.viewM);
+        this.sunCamera.setProjection(this.projM);
+        const u = this.uniforms;
+        u.viewProj = this.sunCamera.viewProjection;
+        u.bias = shadow.bias ?? DEFAULT_SHADOW_BIAS;
+        u.texelSize = 1 / size;
+    }
+    /**
+     * The depth-only pipeline for meshes in `layout`: the engine prelude's `vs_main` (so the same
+     * `engine_vertex` path as the scene pass), no fragment stage, `SHADOW_FORMAT` depth with
+     * writes on. Built on first use and cached. A skinned layout with `bindingsLayout` (the
+     * material's group 1, which holds the joint palette) gets a pipeline layout of both groups.
+     */
+    pipelineFor(layout, bindingsLayout) {
+        const skinned = layout.skinned === true && bindingsLayout !== undefined;
+        let byGroup;
+        if (skinned) {
+            byGroup = this.skinnedPipelines.get(layout);
+            if (!byGroup) {
+                byGroup = new Map();
+                this.skinnedPipelines.set(layout, byGroup);
+            }
+            const hit = byGroup.get(bindingsLayout);
+            if (hit)
+                return hit;
+        }
+        else {
+            const hit = this.pipelines.get(layout);
+            if (hit)
+                return hit;
+        }
+        const module = createShaderModule(this.device, materialPrelude(layout), `engine-shadow:${layout.name}`);
+        const pipeline = this.device.createRenderPipeline({
+            label: `engine-shadow:${layout.name}`,
+            layout: skinned
+                ? this.device.createPipelineLayout({
+                    label: `engine-shadow-layout:${layout.name}`,
+                    bindGroupLayouts: [this.globalsLayout, bindingsLayout],
+                })
+                : this.pipelineLayout,
+            vertex: { module, entryPoint: 'vs_main', buffers: [layout.buffer, INSTANCE_BUFFER_LAYOUT] },
+            primitive: { topology: 'triangle-list', cullMode: 'none' },
+            depthStencil: { format: SHADOW_FORMAT, depthWriteEnabled: true, depthCompare: 'less' },
+        });
+        if (byGroup)
+            byGroup.set(bindingsLayout, pipeline);
+        else
+            this.pipelines.set(layout, pipeline);
+        return pipeline;
+    }
+    /** Destroy maps replaced since the last call; the renderer calls it after each submit. */
+    flush() {
+        if (this.retired.length === 0)
+            return;
+        for (const t of this.retired)
+            t.destroy();
+        this.retired.length = 0;
+    }
+    destroy() {
+        this.flush();
+        this.texture?.destroy();
+        this.texture = null;
+        this.placeholderTex.destroy();
+        this.pipelines.clear();
+        this.skinnedPipelines.clear();
+    }
+}

package/dist/render/skin.d.ts

@@ -0,0 +1,112 @@
+import type { InstanceParams } from './frame.js';
+/**
+ * GPU skinning: a `SkinPalette` is the storage buffer of joint matrices that a material
+ * drawing `VERTEX_LAYOUT_SKINNED` meshes reads (`WGSL_SKIN` / `engine_skin` in the prelude).
+ *
+ * - One joint matrix is 12 floats (`JOINT_FLOATS`): a 3×4 row-major affine matrix, rows
+ *   `r0 r1 r2` of four floats, the same layout as the instance matrix and as `anim`'s
+ *   `skinMatrices` output (world × inverse bind, per joint).
+ * - The palette holds `instances × joints` of them, instance after instance, after a 16-byte
+ *   header (`joints`, `instances`) the shader reads to find an instance's block.
+ * - A draw names its block with the palette slot in `InstanceParams.params[3]` (`params.w`,
+ *   read as `u32`); the other three `params` stay the material's. Several draws may share one
+ *   slot.
+ * - `set(slot, matrices)` copies one instance's matrices into CPU staging and marks it dirty;
+ *   `flush()` uploads the dirty range in one `writeBuffer`, once per frame, allocating nothing.
+ *
+ * Bind it to a material with `buffers: [palette.buffer]` (`BindingDesc.buffers`, binding 16).
+ * A palette is one material's; two skinned materials take two palettes, or one shared buffer
+ * passed to both.
+ */
+export interface SkinPaletteDesc {
+    /** Joints per instance (the skeleton's joint count). */
+    joints: number;
+    /** Instances (palette slots) the buffer holds. Default 1. */
+    instances?: number;
+    label?: string;
+    /**
+     * Keep last frame's matrices too (ws/render-4): the buffer holds `[header][current]
+     * [previous]` and the prelude's `engine_skin_previous` reads the previous block, so a
+     * skinned draw into a target with a velocity attachment writes its own motion. `flush()`
+     * settles it: a slot set this frame keeps what it held before as "previous"; one left alone
+     * reads the same matrices both frames (zero motion). Default false (velocity reads zero).
+     */
+    history?: boolean;
+}
+/** Floats in one joint matrix: 3 rows × 4 (row-major 3×4 affine). */
+export declare const JOINT_FLOATS = 12;
+/** Floats of the palette header before the first joint row (`joints`, `instances`, `history`, pad). */
+export declare const SKIN_PALETTE_HEADER_FLOATS = 4;
+export declare class SkinPalette {
+    private readonly device;
+    readonly label: string;
+    readonly joints: number;
+    readonly instances: number;
+    /** The storage buffer (`STORAGE | COPY_DST`), sized at creation; bind it as `buffers[0]`. */
+    readonly buffer: GPUBuffer;
+    /** Floats per instance block (`joints × JOINT_FLOATS`). */
+    readonly instanceFloats: number;
+    /** `SkinPaletteDesc.history`: the buffer carries last frame's matrices after the current. */
+    readonly history: boolean;
+    private readonly data;
+    /** Dirty instance range, inclusive; `lo > hi` means clean. */
+    private dirtyLo;
+    private dirtyHi;
+    /** With history: the flush each slot was last written in (0 = never); `flushes` counts them. */
+    private readonly stamp;
+    private flushes;
+    /** `write(i)` views, made on first use. */
+    private views;
+    /** `params(i)` objects, made on first use. */
+    private slotParams;
+    /** With history: slots whose previous block must follow their current one at the next flush. */
+    private settleLo;
+    private settleHi;
+    constructor(device: GPUDevice, desc: SkinPaletteDesc);
+    /**
+     * Joints per instance (ws/render-11): `joints`, the count each slot's block holds and the
+     * most a skeleton posed into it (`skinPose`, `skinMatrices`) may have.
+     */
+    get jointCount(): number;
+    /** Float offset of `instance`'s first joint row inside the buffer (tests, custom writers). */
+    offsetOf(instance: number): number;
+    /** Float offset of `instance`'s previous-frame block (`history` palettes only; else -1). */
+    previousOffsetOf(instance: number): number;
+    /**
+     * Copy `joints × 12` floats from `matrices` (starting at float `offset`) into palette slot
+     * `instance`. The upload happens in `flush()`. No allocation.
+     */
+    set(instance: number, matrices: ArrayLike<number>, offset?: number): void;
+    /**
+     * Slot `instance`'s `joints × 12` floats to write in place (ws/api-render), for example
+     * `skinMatrices(skeleton, world, palette.write(0))` with no staging array of your own. Marks
+     * the slot for the next `flush()` (and, with `history`, keeps its current block as the
+     * previous one first), so call it each frame you write the slot, before writing. The view is
+     * made once per slot; no allocation after that.
+     */
+    write(instance: number): Float32Array<ArrayBuffer>;
+    /**
+     * The `InstanceParams` that draw with slot `instance` (ws/api-render): `params` is
+     * `[0, 0, 0, instance]`, the slot in `params[SKIN_PARAM]`. One object per slot, made on first
+     * use; pass it to `frame.mesh(mesh, material, transform, palette.params(i))`.
+     */
+    params(instance: number): InstanceParams;
+    /** Reset every joint of slot `instance` to the identity (the mesh's bind pose). */
+    setIdentity(instance: number): void;
+    /** Upload the slots written since the last flush in one `writeBuffer`; nothing when clean. */
+    flush(): void;
+    /** With history: the first write to a slot in a frame keeps its current block as previous. */
+    private capture;
+    /** True when a `flush()` would upload something. */
+    get isDirty(): boolean;
+    destroy(): void;
+    private check;
+    private dirty;
+}
+/**
+ * Write the joints and weights of vertex `vertex` of a `VERTEX_LAYOUT_SKINNED` buffer, through
+ * `bytes`, a `Uint8Array` over the vertex data (`new Uint8Array(vertices.buffer)`). Weights are
+ * normalised to sum to 1 and quantised to unorm8 so the four bytes add up to 255. Up to four
+ * joints; missing entries read joint 0 with weight 0.
+ */
+export declare function setVertexSkin(bytes: Uint8Array, vertex: number, joints: ArrayLike<number>, weights: ArrayLike<number>): void;

package/dist/render/skin.js

@@ -0,0 +1,240 @@
+import { SKIN_JOINTS_BYTE_OFFSET, SKIN_WEIGHTS_BYTE_OFFSET, VERTEX_SKINNED_STRIDE } from './mesh.js';
+/** Floats in one joint matrix: 3 rows × 4 (row-major 3×4 affine). */
+export const JOINT_FLOATS = 12;
+/** Floats of the palette header before the first joint row (`joints`, `instances`, `history`, pad). */
+export const SKIN_PALETTE_HEADER_FLOATS = 4;
+export class SkinPalette {
+    device;
+    label;
+    joints;
+    instances;
+    /** The storage buffer (`STORAGE | COPY_DST`), sized at creation; bind it as `buffers[0]`. */
+    buffer;
+    /** Floats per instance block (`joints × JOINT_FLOATS`). */
+    instanceFloats;
+    /** `SkinPaletteDesc.history`: the buffer carries last frame's matrices after the current. */
+    history;
+    data;
+    /** Dirty instance range, inclusive; `lo > hi` means clean. */
+    dirtyLo = 0;
+    dirtyHi = -1;
+    /** With history: the flush each slot was last written in (0 = never); `flushes` counts them. */
+    stamp;
+    flushes = 1;
+    /** `write(i)` views, made on first use. */
+    views = [];
+    /** `params(i)` objects, made on first use. */
+    slotParams = [];
+    /** With history: slots whose previous block must follow their current one at the next flush. */
+    settleLo = 0;
+    settleHi = -1;
+    constructor(device, desc) {
+        this.device = device;
+        const joints = Math.floor(desc.joints);
+        const instances = Math.floor(desc.instances ?? 1);
+        if (!(joints >= 1))
+            throw new Error(`SkinPalette: joints must be ≥ 1, got ${desc.joints}`);
+        if (!(instances >= 1)) {
+            throw new Error(`SkinPalette: instances must be ≥ 1, got ${desc.instances}`);
+        }
+        this.label = desc.label ?? 'skin-palette';
+        this.joints = joints;
+        this.instances = instances;
+        this.instanceFloats = joints * JOINT_FLOATS;
+        this.history = desc.history === true;
+        const blocks = this.history ? 2 : 1;
+        this.data = new Float32Array(SKIN_PALETTE_HEADER_FLOATS + blocks * instances * this.instanceFloats);
+        this.stamp = new Uint32Array(this.history ? instances : 0);
+        const header = new Uint32Array(this.data.buffer, 0, SKIN_PALETTE_HEADER_FLOATS);
+        header[0] = joints;
+        header[1] = instances;
+        header[2] = this.history ? 1 : 0;
+        this.buffer = device.createBuffer({
+            label: `${this.label}-buffer`,
+            size: this.data.byteLength,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+        // Identity everywhere, so an unset slot draws the mesh in its bind pose.
+        for (let i = 0; i < instances; i++)
+            this.setIdentity(i);
+        if (this.history) {
+            const n = instances * this.instanceFloats;
+            this.data.copyWithin(SKIN_PALETTE_HEADER_FLOATS + n, SKIN_PALETTE_HEADER_FLOATS, SKIN_PALETTE_HEADER_FLOATS + n);
+        }
+        // The header goes up with the first flush (the whole buffer is dirty).
+        this.device.queue.writeBuffer(this.buffer, 0, this.data.buffer, 0, SKIN_PALETTE_HEADER_FLOATS * 4);
+    }
+    /**
+     * Joints per instance (ws/render-11): `joints`, the count each slot's block holds and the
+     * most a skeleton posed into it (`skinPose`, `skinMatrices`) may have.
+     */
+    get jointCount() {
+        return this.joints;
+    }
+    /** Float offset of `instance`'s first joint row inside the buffer (tests, custom writers). */
+    offsetOf(instance) {
+        return SKIN_PALETTE_HEADER_FLOATS + instance * this.instanceFloats;
+    }
+    /** Float offset of `instance`'s previous-frame block (`history` palettes only; else -1). */
+    previousOffsetOf(instance) {
+        return this.history ? this.offsetOf(this.instances + instance) : -1;
+    }
+    /**
+     * Copy `joints × 12` floats from `matrices` (starting at float `offset`) into palette slot
+     * `instance`. The upload happens in `flush()`. No allocation.
+     */
+    set(instance, matrices, offset = 0) {
+        this.check(instance);
+        const n = this.instanceFloats;
+        if (offset + n > matrices.length) {
+            throw new Error(`${this.label}: slot ${instance} needs ${n} floats from ${offset}, got ${matrices.length}`);
+        }
+        const d = this.data;
+        const o = this.offsetOf(instance);
+        this.capture(instance);
+        for (let i = 0; i < n; i++)
+            d[o + i] = matrices[offset + i];
+        this.dirty(instance);
+    }
+    /**
+     * Slot `instance`'s `joints × 12` floats to write in place (ws/api-render), for example
+     * `skinMatrices(skeleton, world, palette.write(0))` with no staging array of your own. Marks
+     * the slot for the next `flush()` (and, with `history`, keeps its current block as the
+     * previous one first), so call it each frame you write the slot, before writing. The view is
+     * made once per slot; no allocation after that.
+     */
+    write(instance) {
+        this.check(instance);
+        let v = this.views[instance];
+        if (!v) {
+            const o = this.offsetOf(instance);
+            v = this.data.subarray(o, o + this.instanceFloats);
+            this.views[instance] = v;
+        }
+        this.capture(instance);
+        this.dirty(instance);
+        return v;
+    }
+    /**
+     * The `InstanceParams` that draw with slot `instance` (ws/api-render): `params` is
+     * `[0, 0, 0, instance]`, the slot in `params[SKIN_PARAM]`. One object per slot, made on first
+     * use; pass it to `frame.mesh(mesh, material, transform, palette.params(i))`.
+     */
+    params(instance) {
+        this.check(instance);
+        let p = this.slotParams[instance];
+        if (!p) {
+            p = { params: [0, 0, 0, instance] };
+            this.slotParams[instance] = p;
+        }
+        return p;
+    }
+    /** Reset every joint of slot `instance` to the identity (the mesh's bind pose). */
+    setIdentity(instance) {
+        this.check(instance);
+        const d = this.data;
+        let o = this.offsetOf(instance);
+        this.capture(instance);
+        for (let j = 0; j < this.joints; j++) {
+            d.fill(0, o, o + JOINT_FLOATS);
+            d[o] = 1;
+            d[o + 5] = 1;
+            d[o + 10] = 1;
+            o += JOINT_FLOATS;
+        }
+        this.dirty(instance);
+    }
+    /** Upload the slots written since the last flush in one `writeBuffer`; nothing when clean. */
+    flush() {
+        const lo = this.dirtyLo;
+        const hi = this.dirtyHi;
+        if (this.history) {
+            // Slots written last flush but not this one move on: previous := current.
+            const sLo = Math.max(this.settleLo, 0);
+            const sHi = this.settleHi;
+            const n = this.instanceFloats;
+            for (let i = sLo; i <= sHi; i++) {
+                if (this.stamp[i] === this.flushes)
+                    continue;
+                const cur = this.offsetOf(i);
+                this.data.copyWithin(this.previousOffsetOf(i), cur, cur + n);
+            }
+            const uLo = lo > hi ? sLo : sHi < sLo ? lo : Math.min(lo, sLo);
+            const uHi = lo > hi ? sHi : Math.max(hi, sHi);
+            this.settleLo = lo;
+            this.settleHi = hi;
+            this.flushes++;
+            this.dirtyLo = this.instances;
+            this.dirtyHi = -1;
+            if (uLo > uHi)
+                return;
+            const first = this.offsetOf(uLo) * 4;
+            const bytes = (uHi - uLo + 1) * n * 4;
+            this.device.queue.writeBuffer(this.buffer, first, this.data.buffer, first, bytes);
+            const pFirst = this.previousOffsetOf(uLo) * 4;
+            this.device.queue.writeBuffer(this.buffer, pFirst, this.data.buffer, pFirst, bytes);
+            return;
+        }
+        if (lo > hi)
+            return;
+        this.dirtyLo = this.instances;
+        this.dirtyHi = -1;
+        const first = this.offsetOf(lo) * 4;
+        const bytes = (hi - lo + 1) * this.instanceFloats * 4;
+        this.device.queue.writeBuffer(this.buffer, first, this.data.buffer, first, bytes);
+    }
+    /** With history: the first write to a slot in a frame keeps its current block as previous. */
+    capture(instance) {
+        if (!this.history || this.stamp[instance] === this.flushes)
+            return;
+        this.stamp[instance] = this.flushes;
+        const cur = this.offsetOf(instance);
+        this.data.copyWithin(this.previousOffsetOf(instance), cur, cur + this.instanceFloats);
+    }
+    /** True when a `flush()` would upload something. */
+    get isDirty() {
+        return this.dirtyLo <= this.dirtyHi;
+    }
+    destroy() {
+        this.buffer.destroy();
+    }
+    check(instance) {
+        if (instance < 0 || instance >= this.instances || !Number.isInteger(instance)) {
+            throw new Error(`${this.label}: slot ${instance} out of range (0..${this.instances - 1})`);
+        }
+    }
+    dirty(instance) {
+        if (instance < this.dirtyLo)
+            this.dirtyLo = instance;
+        if (instance > this.dirtyHi)
+            this.dirtyHi = instance;
+    }
+}
+/**
+ * Write the joints and weights of vertex `vertex` of a `VERTEX_LAYOUT_SKINNED` buffer, through
+ * `bytes`, a `Uint8Array` over the vertex data (`new Uint8Array(vertices.buffer)`). Weights are
+ * normalised to sum to 1 and quantised to unorm8 so the four bytes add up to 255. Up to four
+ * joints; missing entries read joint 0 with weight 0.
+ */
+export function setVertexSkin(bytes, vertex, joints, weights) {
+    const base = vertex * VERTEX_SKINNED_STRIDE;
+    let sum = 0;
+    for (let k = 0; k < 4; k++)
+        sum += k < weights.length ? Math.max(0, weights[k]) : 0;
+    const scale = sum > 0 ? 255 / sum : 0;
+    let used = 0;
+    let largest = 0;
+    for (let k = 0; k < 4; k++) {
+        const j = k < joints.length ? joints[k] : 0;
+        const w = k < weights.length ? Math.round(Math.max(0, weights[k]) * scale) : 0;
+        bytes[base + SKIN_JOINTS_BYTE_OFFSET + k] = j;
+        bytes[base + SKIN_WEIGHTS_BYTE_OFFSET + k] = w;
+        used += w;
+        if (w > bytes[base + SKIN_WEIGHTS_BYTE_OFFSET + largest])
+            largest = k;
+    }
+    // Rounding may leave the bytes short of (or past) 255: settle it on the heaviest weight.
+    if (sum > 0 && used !== 255) {
+        bytes[base + SKIN_WEIGHTS_BYTE_OFFSET + largest] += 255 - used;
+    }
+}

package/dist/render/snapshot.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Offscreen snapshots: a second `Renderer` on the same GPU device that draws one frame into an
+ * `OffscreenCanvas` and hands it back as an `ImageBitmap`. Use it to bake still images (icons,
+ * thumbnails, previews) with the real materials and post stack, then show them in the DOM.
+ *
+ * ```ts
+ * const shot = new SnapshotRenderer(renderer.device, renderer.format, { width: 512, height: 256 });
+ * shot.renderer.post = new PostStack(shot.renderer);            // optional
+ * const mat = shot.renderer.createMaterial({ … });              // materials belong to shot.renderer
+ * const bmp = shot.capture((frame) => frame.sprite(mat, { x: 128, y: 128, w: 200, h: 200 }));
+ * ctx2d.drawImage(bmp, 0, 0, 256, 256, 0, 0, 256, 256);        // slice cells out of the sheet
+ * ```
+ *
+ * The logical space equals the pixel size, so a draw at (x, y) lands on that pixel.
+ */
+import type { Frame } from './frame.js';
+import { Renderer } from './renderer.js';
+export interface SnapshotOptions {
+    /** Output size in pixels (also the logical size). */
+    width: number;
+    height: number;
+}
+export declare class SnapshotRenderer {
+    readonly renderer: Renderer;
+    readonly width: number;
+    readonly height: number;
+    private readonly canvas;
+    private readonly context;
+    constructor(device: GPUDevice, format: GPUTextureFormat, opts: SnapshotOptions);
+    /**
+     * Draw one frame (`draw` records into it) and return the result. `time` feeds
+     * `globals.time`, so animated materials can be frozen at a chosen moment.
+     */
+    capture(draw: (frame: Frame) => void, time?: number): ImageBitmap;
+    destroy(): void;
+}

package/dist/render/snapshot.js

@@ -0,0 +1,34 @@
+import { Renderer } from './renderer.js';
+export class SnapshotRenderer {
+    renderer;
+    width;
+    height;
+    canvas;
+    context;
+    constructor(device, format, opts) {
+        this.width = Math.max(1, Math.floor(opts.width));
+        this.height = Math.max(1, Math.floor(opts.height));
+        this.canvas = new OffscreenCanvas(this.width, this.height);
+        const context = this.canvas.getContext('webgpu');
+        if (!context)
+            throw new Error('SnapshotRenderer: no webgpu context on OffscreenCanvas');
+        context.configure({ device, format, alphaMode: 'opaque' });
+        this.context = context;
+        this.renderer = new Renderer({ device, context, format }, { logicalWidth: this.width, logicalHeight: this.height, initialInstances: 64 });
+        this.renderer.resize(this.width, this.height);
+    }
+    /**
+     * Draw one frame (`draw` records into it) and return the result. `time` feeds
+     * `globals.time`, so animated materials can be frozen at a chosen moment.
+     */
+    capture(draw, time = 0) {
+        const frame = this.renderer.beginFrame(time, 1 / 60);
+        draw(frame);
+        this.renderer.endFrame();
+        return this.canvas.transferToImageBitmap();
+    }
+    destroy() {
+        this.renderer.destroy();
+        this.context.unconfigure();
+    }
+}