@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/render/flipbook.js

@@ -0,0 +1,87 @@
+/**
+ * Flipbook (ws/ergo-2d): frame timing over a list of texture sub-rectangles. Pure: no GPU, no
+ * allocation in `update`. A 2D game keeps one per animated sprite, calls `update(dt)` each tick
+ * and hands `uv` to its `DrawParams.uv`.
+ */
+/**
+ * The `UvRect`s of a grid atlas's cells, row-major from the top left (`cols × rows` cells); with
+ * `indices`, only those cells in that order. Throws when `inset` is set without `width` and
+ * `height`. Allocates: call it at load time.
+ */
+export function atlasFrames(atlas, indices) {
+    const { cols, rows } = atlas;
+    const inset = atlas.inset ?? 0;
+    let du = 0;
+    let dv = 0;
+    if (inset !== 0) {
+        const { width, height } = atlas;
+        if (!(width > 0) || !(height > 0)) {
+            throw new Error('atlasFrames: inset needs the atlas width and height in texels');
+        }
+        du = inset / width;
+        dv = inset / height;
+    }
+    const n = indices ? indices.length : cols * rows;
+    const out = [];
+    for (let k = 0; k < n; k++) {
+        const i = indices ? indices[k] : k;
+        const c = i % cols;
+        const r = Math.floor(i / cols);
+        out.push([c / cols + du, r / rows + dv, (c + 1) / cols - du, (r + 1) / rows - dv]);
+    }
+    return out;
+}
+/** Make a `Flipbook` over `frames` at `fps`. */
+export function createFlipbook(opts) {
+    if (opts.frames.length === 0)
+        throw new Error('createFlipbook: no frames');
+    let frames = opts.frames;
+    let time = 0;
+    let index = 0;
+    let done = false;
+    const book = {
+        fps: opts.fps ?? 12,
+        loop: opts.loop ?? true,
+        get frames() {
+            return frames;
+        },
+        get uv() {
+            return frames[index];
+        },
+        get frame() {
+            return index;
+        },
+        get done() {
+            return done;
+        },
+        update(dt) {
+            if (done || !(book.fps > 0))
+                return;
+            time += dt;
+            const total = frames.length / book.fps;
+            if (book.loop) {
+                if (time >= total)
+                    time -= total * Math.floor(time / total);
+            }
+            else if (time >= total) {
+                time = total;
+                done = true;
+            }
+            index = Math.min(frames.length - 1, Math.floor(time * book.fps));
+        },
+        reset() {
+            time = 0;
+            index = 0;
+            done = false;
+        },
+        play(next) {
+            if (next) {
+                if (next.length === 0)
+                    throw new Error('Flipbook.play: no frames');
+                frames = next;
+            }
+            book.reset();
+        },
+    };
+    return book;
+}

package/dist/render/frame.d.ts

@@ -0,0 +1,278 @@
+import type { Camera } from './camera.js';
+import type { InstanceList } from './instance-list.js';
+import { Lights } from './lights.js';
+import { type MeshLod } from './lod.js';
+import type { Material } from './material.js';
+import type { Mesh, MeshBounds, MeshRange } from './mesh.js';
+import type { SceneTarget } from './scene-target.js';
+import { Transform } from './transform.js';
+/**
+ * Floats per instance in `InstanceBatch.params`: the instance format after its 3×4 matrix
+ * (`INSTANCE_FLOATS` − 12): `uvRect` (4), `tint` (4), `params` (4), `emissive`, `flags`,
+ * `size.x`, `size.y`. `writeInstanceParams` fills one from an `InstanceParams`.
+ */
+export declare const INSTANCE_PARAM_FLOATS = 16;
+/**
+ * Many instances of one mesh and material submitted at once (`frame.meshes`): `count` 3×4
+ * row-major world matrices in `matrices` (12 floats each, `Transform.world`'s layout) and,
+ * optionally, their `INSTANCE_PARAM_FLOATS` of params each in `params` (null or absent: the
+ * defaults, white tint, full uv, the mesh's shadow flags, size from the matrix columns). The
+ * renderer copies both straight into its instance upload. `bounds`, when given, is one
+ * world-space sphere for the whole batch: the camera culls the batch with one test and never
+ * per instance; without it each instance is culled by `mesh.bounds` through its matrix. The
+ * batch is one sort key (its `order`, then its first instance's depth) and one draw. An
+ * `InstanceList` is one.
+ */
+export interface InstanceBatch {
+    /** Instances to draw (the first `count` of `matrices` / `params`). */
+    count: number;
+    /** `count` × 12 floats (at least). */
+    matrices: Float32Array;
+    /** `count` × `INSTANCE_PARAM_FLOATS` floats, or null for the defaults. */
+    params?: Float32Array | null;
+    /** One world-space sphere for the batch, or null to cull per instance. */
+    bounds?: MeshBounds | null;
+    /** Layer mask of every instance, matched against `camera.layers`. Default 1. */
+    layerBits?: number;
+    /** Sort key, as `InstanceParams.order`. Default 0. */
+    order?: number;
+    /** Draw into the sun's shadow map; default: the mesh is not in `VERTEX_LAYOUT_2D`. */
+    castShadow?: boolean;
+    /**
+     * Each instance's previous-frame matrix (`count` × 12 floats, index for index with
+     * `matrices`), or null (ws/render-7). Drawn into a target with a velocity attachment by a
+     * material with `aux`, the batch then writes per-instance motion through the renderer's
+     * shared previous-matrix lane; without it the instances report camera motion only. A LOD
+     * `InstanceList` made with `velocity` carries its own.
+     */
+    prevMatrices?: Float32Array | null;
+}
+/**
+ * Write the `INSTANCE_PARAM_FLOATS` of one instance (its fields after the matrix) at float
+ * `o` of `dst` from `p`, with `sizeX`, `sizeY` as its `size` (`VSOut.size`: a transform's
+ * scale.xy). Same defaults as `frame.mesh`: uv 0,0,1,1, white tint, zero params and emissive,
+ * `packInstanceFlags(receiveShadow, layers)`.
+ */
+export declare function writeInstanceParams(dst: Float32Array, o: number, p: InstanceParams, sizeX?: number, sizeY?: number): void;
+/**
+ * Index into `InstanceParams.params` of the skin palette slot (`params.w`): the convention
+ * `engine_skin` reads and the skin harness and glTF skins write. A constant, not a layout change.
+ */
+export declare const SKIN_PARAM = 3;
+/**
+ * Per-draw instance fields other than placement. A draw placed by a `Transform` takes these;
+ * `DrawParams` adds the 2D placement (x, y, w, h, rotation). Reuse the object across frames.
+ */
+export interface InstanceParams {
+    /** Linear RGBA multiplier (HDR allowed). Default white. */
+    tint?: ArrayLike<number>;
+    /** Sub-rectangle of the texture: u0, v0, u1, v1. Default 0,0,1,1. */
+    uv?: ArrayLike<number>;
+    /**
+     * Free per-instance vec4 for custom materials (`in.params`). Convention: a skinned draw names
+     * its `SkinPalette` slot in `params[SKIN_PARAM]` (`params.w`, read as `u32` by `engine_skin`);
+     * the other three stay the material's.
+     */
+    params?: ArrayLike<number>;
+    /** Emissive strength (`in.emissive`); the built-in sprite writes colour × this to bloom. */
+    emissive?: number;
+    /**
+     * Draw this instance into the sun's shadow map when `frame.lights.sun.shadow` is set and the
+     * material is opaque. Default: true for meshes in a 3D vertex layout, false for 2D sprites
+     * and quads (`VERTEX_LAYOUT_2D`), so a 2D scene never renders a shadow pass.
+     */
+    castShadow?: boolean;
+    /**
+     * Set false to mark the instance as not receiving the sun's shadow: instance flag bit 0
+     * (`in.flags & 1u`) is set and a material may skip `engine_shadow` for it. The engine's
+     * `engine_lambert` does not read the flag. Default true (flag bit clear).
+     */
+    receiveShadow?: boolean;
+    /**
+     * This draw's own uniform block (f32s, copied at call time) for a material created with
+     * `perDrawUniforms`. Lets many instances share one material, each with its own uniforms.
+     */
+    uniforms?: ArrayLike<number>;
+    /**
+     * Layer membership mask (u32). The draw is skipped when `layers & camera.layers` is 0.
+     * Default 1. A camera without `layers` sees every layer. Its low `INSTANCE_LAYER_BITS` also
+     * ride the instance flags (bits 1..23), so a light whose `layers` share no bit skips it.
+     */
+    layers?: number;
+    /**
+     * Sort key. Draws render by `order`, then submission order, so leaving it at the default 0
+     * keeps plain submission order. With depth on it is still the first key (see the renderer).
+     */
+    order?: number;
+    /**
+     * Draw only the indices `[first, first + count)` of the mesh (ws/render-4): a sub-mesh of a
+     * file, one of `mesh.ranges`. Instances batch per (mesh, material, range). Indexed meshes
+     * only; ignored by `frame.meshes` batches and lists.
+     */
+    range?: MeshRange;
+}
+/** Parameters for one instanced draw. Reuse the object across frames to avoid garbage. */
+export interface DrawParams extends InstanceParams {
+    /** Position (logical px). For the built-in quad this is the centre. */
+    x: number;
+    y: number;
+    /** Scale. For the quad: size in logical px. Default 1. */
+    w?: number;
+    h?: number;
+    /** Radians, clockwise on screen (y is down). */
+    rotation?: number;
+}
+/**
+ * Something that draws itself inside the scene pass (particles, custom pipelines).
+ * `prepare` runs once per frame before the scene pass (compute work, uploads);
+ * `draw` runs in draw order inside the scene pass, which has the colour targets of
+ * `renderer.sceneTargets(blend, frame.auxKey)` (HDR colour, HDR emissive, then the target's aux
+ * attachments) and `@group(0)` = engine globals.
+ * When the camera asks for depth the pass also has a depth attachment
+ * (`frame.depthFormat`), and the drawable's pipeline must declare a matching `depthStencil`.
+ *
+ * Depth hook (ws/render-hooks): a drawable with `readsDepth` set makes the renderer split the
+ * view's scene pass at the opaque/blended boundary when the camera has `depthTest`: the opaque
+ * draws end their pass, the depth attachment is copied into the target's `depthCopy`, every
+ * hooked drawable's `afterOpaque(encoder, view)` runs (the same encoder, between the passes),
+ * and the blended draws follow in a second pass that loads everything. `readsDepth` is the
+ * flag; a drawable may set it without an `afterOpaque` (it then reads `view.target.depthCopy`
+ * itself in `draw`). Without `depthTest` (`ortho2d`), or on a target whose depth cannot be
+ * copied, nothing splits and `afterOpaque` never fires; the drawable keeps its fallback.
+ */
+export interface Drawable {
+    prepare?(encoder: GPUCommandEncoder, frame: Frame): void;
+    draw(pass: GPURenderPassEncoder, frame: Frame): void;
+    /** Ask for this frame's opaque depth before `draw` (see above). Default off. */
+    readsDepth?: boolean;
+    /** Runs between the opaque and blended passes of each view that split for this drawable. */
+    afterOpaque?(encoder: GPUCommandEncoder, view: ViewInfo): void;
+}
+/**
+ * What `Drawable.afterOpaque` gets: the view's camera and target, the sampleable copy of the
+ * opaque depth (`depthCopy`, `frame.depthFormat`, the whole target; `depthView` is its `'2d'`
+ * view) and the viewport the view draws into (target px). Valid until the view's blended pass
+ * ends; the copy is overwritten by the next view that splits into the same target.
+ */
+export interface ViewInfo {
+    camera: Camera;
+    target: SceneTarget;
+    depthCopy: GPUTexture;
+    depthView: GPUTextureView;
+    viewport: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/** Hooks the renderer exposes to Frame (kept internal). */
+export interface FrameSink {
+    /**
+     * `t` places the draw when given; otherwise `p` is a `DrawParams`. `bounds` is the mesh-space
+     * sphere the draw is frustum-culled by (through its instance matrix), or null for a draw that
+     * is never culled (sprites). `lod` is the chain the renderer picks `mesh` from per view
+     * (`frame.mesh` with a `MeshLod`; `mesh` is then its first level).
+     */
+    pushInstance(material: Material, mesh: Mesh, t: Transform | null, p: DrawParams | InstanceParams, bounds: MeshBounds | null, lod?: MeshLod | null): void;
+    /**
+     * A batch of `mesh` with `material` (`frame.meshes` / `frame.list`); `bounds` is the mesh's
+     * sphere for per-instance culling when the batch gives none. `list` is the retained list
+     * the batch is, if any (its instances live in its own buffer). `lod` is the chain each
+     * instance picks its level from per view (ws/render-6; `mesh` is then its first level).
+     */
+    pushBatch(material: Material, mesh: Mesh, batch: InstanceBatch, bounds: MeshBounds | null, list: InstanceList | null, lod?: MeshLod | null): void;
+    pushDrawable(d: Drawable, order: number, layers: number): void;
+    pushPrePass(fn: (encoder: GPUCommandEncoder) => void): void;
+    readonly defaultSprite: Material;
+    readonly quad: Mesh;
+}
+/**
+ * Per-frame draw recorder. Obtained from `renderer.beginFrame()`; the same object is reused
+ * every frame. Draws render sorted by `order` (default 0), then call order; consecutive draws
+ * with the same material, mesh and uniforms merge into one instanced draw call. `meshes` draws
+ * a typed-array batch and `list` a retained `InstanceList`, each as one unit.
+ */
+export declare class Frame {
+    private readonly sink;
+    readonly logicalWidth: number;
+    readonly logicalHeight: number;
+    /** Seconds since renderer start (or whatever the caller passed to beginFrame). */
+    time: number;
+    /** Seconds since last frame. */
+    dt: number;
+    /** Linear clear colour for the HDR colour target. */
+    readonly clearColor: GPUColorDict;
+    /**
+     * Depth attachment format of this frame's scene pass, or null when the camera has no depth
+     * (the 2D path). Set by the renderer before `prepare`/`draw` run.
+     */
+    depthFormat: GPUTextureFormat | null;
+    /**
+     * Aux key (`SceneTarget.auxKey`: bit 0 rough-metal, bit 1 velocity) of the target this view's
+     * scene pass draws into; 0 for a plain target. Set by the renderer with `depthFormat`. A
+     * drawable keys its pipelines on it and builds them with `renderer.sceneTargets(blend,
+     * frame.auxKey)` (ws/render-10).
+     */
+    auxKey: number;
+    /**
+     * The frame's lights, uploaded as `EngineLights` (`@group(0) @binding(2)`) with every view.
+     * Defaults to an unlit block (ambient 1, no sun, no points), so materials that read it draw
+     * their albedo unchanged until the game sets it. Mutate it or assign another `Lights`; the
+     * object persists across frames (it is not reset by `beginFrame`).
+     */
+    lights: Lights;
+    constructor(sink: FrameSink, logicalWidth: number, logicalHeight: number);
+    clear(r: number, g: number, b: number, a?: number): void;
+    /**
+     * Draw a quad with `material` (default: built-in white sprite), placed by `DrawParams`
+     * (x, y = centre, w, h = size, rotation) or by a `Transform` (the quad spans -0.5..0.5 in
+     * its local space, so the transform's scale is the size).
+     */
+    sprite(material: Material | null, p: DrawParams): void;
+    sprite(material: Material | null, t: Transform, p?: InstanceParams): void;
+    /**
+     * Draw `mesh` with `material`, placed by `DrawParams` (x, y, w, h, rotation) or a `Transform`.
+     * The draw carries `mesh.bounds` through its instance matrix, so a camera with `cull` on
+     * skips it when the sphere is outside the frustum (sprites are never culled).
+     *
+     * Given a `MeshLod` (ws/render-5), each view picks one of its `meshes` for the instance from
+     * the projected height of its sphere (`meshes[0].bounds`) against `thresholdsPx`, times
+     * `camera.lodBias`, with `renderer.lodHysteresis` keyed on the `Transform` (or the
+     * `DrawParams` object), so pass a stable one; instances of a level sort together and draw
+     * as one instanced call per (level, material). `renderer.stats.lodCounts[i]` counts them.
+     *
+     * Placed by a `Transform` with an `aux` material into a velocity target (ws/render-8), the
+     * draw writes the object's own motion: the renderer keeps the transform's world matrix per
+     * view and passes last view's as the previous one (zero motion on its first view).
+     */
+    mesh(mesh: Mesh | MeshLod, material: Material, p: DrawParams): void;
+    mesh(mesh: Mesh | MeshLod, material: Material, t: Transform, p?: InstanceParams): void;
+    /**
+     * Draw `batch.count` instances of `mesh` with `material` from typed arrays (`InstanceBatch`):
+     * the bulk path for many things that change every frame. One sort key and one draw call;
+     * culled as one sphere when `batch.bounds` is given, else per instance by `mesh.bounds`.
+     * Throws when `matrices` or `params` are too short for `count`.
+     *
+     * Given a `MeshLod` (ws/render-6), each instance picks its level per view as `frame.mesh`
+     * does (the sphere of `meshes[0].bounds` through its matrix, the level memory kept per view
+     * and instance index) and the batch draws one instanced call per non-empty level.
+     */
+    meshes(mesh: Mesh | MeshLod, material: Material, batch: InstanceBatch): void;
+    /**
+     * Draw a retained `InstanceList` (`renderer.createInstanceList`): its instances live in their
+     * own GPU buffer, uploaded only where `set` / `remove` changed them since the last frame.
+     * Culled as one sphere (`list.bounds`), one draw call. A list made with a `MeshLod`
+     * (ws/render-6) picks a level per instance and view, and its instances are copied into the
+     * frame's upload bucketed by level (one draw per non-empty level) instead of drawn from its
+     * own buffer.
+     */
+    list(list: InstanceList): void;
+    /**
+     * Insert a custom drawable (e.g. a particle system) at this point in the draw order, with
+     * sort key `order` (default 0) and layer mask `layers` (default 1).
+     */
+    drawable(d: Drawable, order?: number, layers?: number): void;
+    /** Run `fn` before the scene pass (offscreen passes, compute). Pass a stable function. */
+    prePass(fn: (encoder: GPUCommandEncoder) => void): void;
+}

package/dist/render/frame.js

@@ -0,0 +1,174 @@
+import { Lights, packInstanceFlags } from './lights.js';
+import { isMeshLod } from './lod.js';
+import { Transform } from './transform.js';
+/**
+ * Floats per instance in `InstanceBatch.params`: the instance format after its 3×4 matrix
+ * (`INSTANCE_FLOATS` − 12): `uvRect` (4), `tint` (4), `params` (4), `emissive`, `flags`,
+ * `size.x`, `size.y`. `writeInstanceParams` fills one from an `InstanceParams`.
+ */
+export const INSTANCE_PARAM_FLOATS = 16;
+/**
+ * Write the `INSTANCE_PARAM_FLOATS` of one instance (its fields after the matrix) at float
+ * `o` of `dst` from `p`, with `sizeX`, `sizeY` as its `size` (`VSOut.size`: a transform's
+ * scale.xy). Same defaults as `frame.mesh`: uv 0,0,1,1, white tint, zero params and emissive,
+ * `packInstanceFlags(receiveShadow, layers)`.
+ */
+export function writeInstanceParams(dst, o, p, sizeX = 1, sizeY = 1) {
+    const uv = p.uv;
+    dst[o++] = uv ? uv[0] : 0;
+    dst[o++] = uv ? uv[1] : 0;
+    dst[o++] = uv ? uv[2] : 1;
+    dst[o++] = uv ? uv[3] : 1;
+    const t = p.tint;
+    dst[o++] = t ? t[0] : 1;
+    dst[o++] = t ? t[1] : 1;
+    dst[o++] = t ? t[2] : 1;
+    dst[o++] = t ? (t[3] ?? 1) : 1;
+    const q = p.params;
+    dst[o++] = q ? q[0] : 0;
+    dst[o++] = q ? (q[1] ?? 0) : 0;
+    dst[o++] = q ? (q[2] ?? 0) : 0;
+    dst[o++] = q ? (q[3] ?? 0) : 0;
+    dst[o++] = p.emissive ?? 0;
+    dst[o++] = packInstanceFlags(p.receiveShadow !== false, p.layers ?? 1);
+    dst[o++] = sizeX;
+    dst[o] = sizeY;
+}
+/**
+ * Index into `InstanceParams.params` of the skin palette slot (`params.w`): the convention
+ * `engine_skin` reads and the skin harness and glTF skins write. A constant, not a layout change.
+ */
+export const SKIN_PARAM = 3;
+const NO_PARAMS = Object.freeze({});
+/**
+ * Per-frame draw recorder. Obtained from `renderer.beginFrame()`; the same object is reused
+ * every frame. Draws render sorted by `order` (default 0), then call order; consecutive draws
+ * with the same material, mesh and uniforms merge into one instanced draw call. `meshes` draws
+ * a typed-array batch and `list` a retained `InstanceList`, each as one unit.
+ */
+export class Frame {
+    sink;
+    logicalWidth;
+    logicalHeight;
+    /** Seconds since renderer start (or whatever the caller passed to beginFrame). */
+    time = 0;
+    /** Seconds since last frame. */
+    dt = 0;
+    /** Linear clear colour for the HDR colour target. */
+    clearColor = { r: 0, g: 0, b: 0, a: 1 };
+    /**
+     * Depth attachment format of this frame's scene pass, or null when the camera has no depth
+     * (the 2D path). Set by the renderer before `prepare`/`draw` run.
+     */
+    depthFormat = null;
+    /**
+     * Aux key (`SceneTarget.auxKey`: bit 0 rough-metal, bit 1 velocity) of the target this view's
+     * scene pass draws into; 0 for a plain target. Set by the renderer with `depthFormat`. A
+     * drawable keys its pipelines on it and builds them with `renderer.sceneTargets(blend,
+     * frame.auxKey)` (ws/render-10).
+     */
+    auxKey = 0;
+    /**
+     * The frame's lights, uploaded as `EngineLights` (`@group(0) @binding(2)`) with every view.
+     * Defaults to an unlit block (ambient 1, no sun, no points), so materials that read it draw
+     * their albedo unchanged until the game sets it. Mutate it or assign another `Lights`; the
+     * object persists across frames (it is not reset by `beginFrame`).
+     */
+    lights = new Lights();
+    constructor(sink, logicalWidth, logicalHeight) {
+        this.sink = sink;
+        this.logicalWidth = logicalWidth;
+        this.logicalHeight = logicalHeight;
+    }
+    clear(r, g, b, a = 1) {
+        const c = this.clearColor;
+        c.r = r;
+        c.g = g;
+        c.b = b;
+        c.a = a;
+    }
+    sprite(material, a, b) {
+        const m = material ?? this.sink.defaultSprite;
+        const q = this.sink.quad;
+        if (a instanceof Transform)
+            this.sink.pushInstance(m, q, a, b ?? NO_PARAMS, null);
+        else
+            this.sink.pushInstance(m, q, null, a, null);
+    }
+    mesh(mesh, material, a, b) {
+        let lod = null;
+        let m;
+        if (isMeshLod(mesh)) {
+            lod = mesh;
+            const first = mesh.meshes[0];
+            if (!first)
+                throw new Error('frame.mesh: MeshLod has no meshes');
+            m = first;
+        }
+        else {
+            m = mesh;
+        }
+        const bounds = m.bounds;
+        if (a instanceof Transform)
+            this.sink.pushInstance(material, m, a, b ?? NO_PARAMS, bounds, lod);
+        else
+            this.sink.pushInstance(material, m, null, a, bounds, lod);
+    }
+    /**
+     * Draw `batch.count` instances of `mesh` with `material` from typed arrays (`InstanceBatch`):
+     * the bulk path for many things that change every frame. One sort key and one draw call;
+     * culled as one sphere when `batch.bounds` is given, else per instance by `mesh.bounds`.
+     * Throws when `matrices` or `params` are too short for `count`.
+     *
+     * Given a `MeshLod` (ws/render-6), each instance picks its level per view as `frame.mesh`
+     * does (the sphere of `meshes[0].bounds` through its matrix, the level memory kept per view
+     * and instance index) and the batch draws one instanced call per non-empty level.
+     */
+    meshes(mesh, material, batch) {
+        if (batch.count <= 0)
+            return;
+        let lod = null;
+        let m;
+        if (isMeshLod(mesh)) {
+            lod = mesh;
+            const first = mesh.meshes[0];
+            if (!first)
+                throw new Error('frame.meshes: MeshLod has no meshes');
+            m = first;
+        }
+        else {
+            m = mesh;
+        }
+        if (batch.matrices.length < batch.count * 12) {
+            throw new Error(`frame.meshes: matrices holds ${batch.matrices.length} floats for ${batch.count} instances`);
+        }
+        if (batch.params && batch.params.length < batch.count * INSTANCE_PARAM_FLOATS) {
+            throw new Error(`frame.meshes: params holds ${batch.params.length} floats for ${batch.count} instances`);
+        }
+        this.sink.pushBatch(material, m, batch, m.bounds, null, lod);
+    }
+    /**
+     * Draw a retained `InstanceList` (`renderer.createInstanceList`): its instances live in their
+     * own GPU buffer, uploaded only where `set` / `remove` changed them since the last frame.
+     * Culled as one sphere (`list.bounds`), one draw call. A list made with a `MeshLod`
+     * (ws/render-6) picks a level per instance and view, and its instances are copied into the
+     * frame's upload bucketed by level (one draw per non-empty level) instead of drawn from its
+     * own buffer.
+     */
+    list(list) {
+        if (list.count <= 0)
+            return;
+        this.sink.pushBatch(list.material, list.mesh, list, null, list, list.lod);
+    }
+    /**
+     * Insert a custom drawable (e.g. a particle system) at this point in the draw order, with
+     * sort key `order` (default 0) and layer mask `layers` (default 1).
+     */
+    drawable(d, order = 0, layers = 1) {
+        this.sink.pushDrawable(d, order, layers);
+    }
+    /** Run `fn` before the scene pass (offscreen passes, compute). Pass a stable function. */
+    prePass(fn) {
+        this.sink.pushPrePass(fn);
+    }
+}

package/dist/render/fullscreen.d.ts

@@ -0,0 +1,54 @@
+import { type BindingDesc, BindingSet } from './bindings.js';
+import { type RenderBlendMode } from './blend.js';
+import type { TextureLike } from './texture.js';
+export interface FullscreenPassDesc extends BindingDesc {
+    label: string;
+    /**
+     * WGSL appended after the fullscreen prelude. Must define
+     * `@fragment fn fs_main(in: FullscreenIn) -> @location(0) vec4f` (or a struct for MRT).
+     * Bindings live in `@group(0)` following the convention in `bindings.ts`.
+     */
+    wgsl: string;
+    /** Colour target formats. */
+    targets: GPUTextureFormat[];
+    blend?: RenderBlendMode | GPUBlendState;
+    fragmentEntry?: string;
+}
+export interface FullscreenEncodeOptions {
+    /** Clear colour; omit to clear to transparent black, `null` to load existing contents. */
+    clear?: GPUColor | null;
+    /** Use an explicit bind group (see `createBindGroup`) instead of the managed one. */
+    bindGroup?: GPUBindGroup;
+    blendConstant?: GPUColor;
+    /** Timestamp writes for this pass (see `GpuTimer.pass`). */
+    timestampWrites?: GPURenderPassTimestampWrites;
+    /**
+     * Draw into this part of `target` only (texture px): viewport and scissor. Pair it with
+     * `clear: null`, since a clear covers the whole attachment (ws/xr-post: one eye of a layer).
+     */
+    viewport?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * A fragment shader run over a whole render target. Used by the post stack, procedural
+ * texture generation and game passes (e.g. a fluid sim into a render target).
+ */
+export declare class FullscreenPass {
+    readonly label: string;
+    readonly pipeline: GPURenderPipeline;
+    readonly bindings: BindingSet | null;
+    private readonly colorAttachment;
+    private readonly passDesc;
+    constructor(device: GPUDevice, desc: FullscreenPassDesc, sampler: GPUSampler, defaultView: GPUTextureView);
+    setUniforms(data: BufferSource, byteOffset?: number): void;
+    setTexture(slot: number, tex: TextureLike | GPUTextureView): void;
+    /** Create a bind group for a fixed set of input views. Cache the result (e.g. per resize). */
+    createBindGroup(views: readonly GPUTextureView[]): GPUBindGroup;
+    /** Record the pass into `encoder`, drawing into `target` (single colour attachment). */
+    encode(encoder: GPUCommandEncoder, target: GPUTextureView, opts?: FullscreenEncodeOptions): void;
+    destroy(): void;
+}

package/dist/render/fullscreen.js

@@ -0,0 +1,91 @@
+import { BindingSet, hasBindings } from './bindings.js';
+import { blendState } from './blend.js';
+import { createShaderModule, WGSL_FULLSCREEN_PRELUDE } from './wgsl.js';
+/**
+ * A fragment shader run over a whole render target. Used by the post stack, procedural
+ * texture generation and game passes (e.g. a fluid sim into a render target).
+ */
+export class FullscreenPass {
+    label;
+    pipeline;
+    bindings;
+    colorAttachment;
+    passDesc;
+    constructor(device, desc, sampler, defaultView) {
+        this.label = desc.label;
+        this.bindings = hasBindings(desc)
+            ? new BindingSet(device, { ...desc, visibility: GPUShaderStage.FRAGMENT }, sampler, defaultView, `pass:${desc.label}`)
+            : null;
+        const code = `${WGSL_FULLSCREEN_PRELUDE}\n// ---- pass: ${desc.label} ----\n${desc.wgsl}`;
+        const module = createShaderModule(device, code, `pass:${desc.label}`);
+        const blend = typeof desc.blend === 'string' || desc.blend === undefined
+            ? blendState(desc.blend ?? 'opaque')
+            : desc.blend;
+        this.pipeline = device.createRenderPipeline({
+            label: `pass:${desc.label}`,
+            layout: device.createPipelineLayout({
+                bindGroupLayouts: this.bindings ? [this.bindings.layout] : [],
+            }),
+            vertex: { module, entryPoint: 'vs_fullscreen' },
+            fragment: {
+                module,
+                entryPoint: desc.fragmentEntry ?? 'fs_main',
+                targets: desc.targets.map((format) => ({ format, blend })),
+            },
+            primitive: { topology: 'triangle-list' },
+        });
+        this.colorAttachment = {
+            view: defaultView,
+            loadOp: 'clear',
+            storeOp: 'store',
+            clearValue: { r: 0, g: 0, b: 0, a: 0 },
+        };
+        this.passDesc = { label: `pass:${desc.label}`, colorAttachments: [this.colorAttachment] };
+    }
+    setUniforms(data, byteOffset = 0) {
+        if (!this.bindings)
+            throw new Error(`pass ${this.label}: no uniforms declared`);
+        this.bindings.setUniforms(data, byteOffset);
+    }
+    setTexture(slot, tex) {
+        if (!this.bindings)
+            throw new Error(`pass ${this.label}: no textures declared`);
+        this.bindings.setTexture(slot, tex);
+    }
+    /** Create a bind group for a fixed set of input views. Cache the result (e.g. per resize). */
+    createBindGroup(views) {
+        if (!this.bindings)
+            throw new Error(`pass ${this.label}: no bindings declared`);
+        return this.bindings.createGroup(views);
+    }
+    /** Record the pass into `encoder`, drawing into `target` (single colour attachment). */
+    encode(encoder, target, opts = {}) {
+        const ca = this.colorAttachment;
+        ca.view = target;
+        if (opts.clear === null) {
+            ca.loadOp = 'load';
+        }
+        else {
+            ca.loadOp = 'clear';
+            ca.clearValue = opts.clear ?? { r: 0, g: 0, b: 0, a: 0 };
+        }
+        this.passDesc.timestampWrites = opts.timestampWrites;
+        const pass = encoder.beginRenderPass(this.passDesc);
+        pass.setPipeline(this.pipeline);
+        const vp = opts.viewport;
+        if (vp) {
+            pass.setViewport(vp.x, vp.y, vp.width, vp.height, 0, 1);
+            pass.setScissorRect(vp.x, vp.y, vp.width, vp.height);
+        }
+        const group = opts.bindGroup ?? this.bindings?.bindGroup;
+        if (group)
+            pass.setBindGroup(0, group);
+        if (opts.blendConstant)
+            pass.setBlendConstant(opts.blendConstant);
+        pass.draw(3);
+        pass.end();
+    }
+    destroy() {
+        this.bindings?.destroy();
+    }
+}