@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/fx/billboard.js

@@ -0,0 +1,702 @@
+import { auxSuffix, motionVariant, ScenePipelineCache, sceneVariant, velocityLocation, } from '../render/scene-pipelines.js';
+import { createShaderModule } from '../render/wgsl.js';
+import { BB_FLAG_BAR, BB_FLAG_PX, BB_FLAG_TEXTURED, BB_FLAG_YAW, BILLBOARD_BYTES, BILLBOARD_FLOATS, BILLBOARD_WGSL, billboardWgsl, } from './billboard-wgsl.js';
+import { TextAtlas } from './text-atlas.js';
+const WHITE = [1, 1, 1, 1];
+const ZERO3 = [0, 0, 0];
+const F = BILLBOARD_FLOATS;
+/** Added to the sort key of `depth: 'always'` quads so they draw after every `'test'` one. */
+const ALWAYS_KEY = 1e9;
+const ALPHA_BLEND = {
+    color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+    alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+};
+/**
+ * World units a span of `px` logical px covers at `viewDistance` from a camera whose projection
+ * is `projection` (column-major; `projection[5]` is the vertical scale) on a viewport
+ * `viewportPx` logical px tall. The shader applies the same ratio in clip space for `{ px }`
+ * sizes; use this on the CPU to size something in world units to match a px plate.
+ */
+export function pxToWorld(px, viewDistance, projection, viewportPx) {
+    const scale = projection[5] ?? 1;
+    const w = Math.abs(projection[11] ?? 0) > 0 ? viewDistance : 1;
+    return ((px / viewportPx) * 2 * w) / scale;
+}
+/**
+ * One billboard, returned by `Billboards.add`. Setters change it in place; it is `alive` until
+ * `remove` or its `life` runs out, after which the setters do nothing.
+ */
+export class BillboardHandle {
+    owner;
+    /** @internal slot in the owner's arrays, -1 when dead. */
+    slot = -1;
+    constructor(owner) {
+        this.owner = owner;
+    }
+    get alive() {
+        return this.slot >= 0;
+    }
+    set position(p) {
+        if (this.slot >= 0)
+            this.owner.setPosition(this.slot, p);
+    }
+    set offset(o) {
+        if (this.slot >= 0)
+            this.owner.setOffset(this.slot, o);
+    }
+    set color(c) {
+        if (this.slot >= 0)
+            this.owner.setColor(this.slot, c);
+    }
+    set size(s) {
+        if (this.slot >= 0)
+            this.owner.setSize(this.slot, s);
+    }
+    set region(r) {
+        if (this.slot >= 0)
+            this.owner.setRegion(this.slot, r);
+    }
+    /** The text plate's text (`desc.text`, `setText`); null when not a plate. */
+    get text() {
+        return this.slot >= 0 ? this.owner.plateText(this.slot) : null;
+    }
+    /**
+     * Change a text plate's text (ws/fx-4). Re-rasterised into the plate's own atlas cell when it
+     * fits (no new region, no new texture), else into a wider cell: the quad's height stays and
+     * its width grows with the cell, so the glyphs keep their scale. A handle that is not a plate
+     * becomes one, in the default style, at its current size.
+     */
+    setText(text) {
+        if (this.slot >= 0)
+            this.owner.setText(this.slot, text);
+    }
+    /** The filled share of a bar quad, 0..1. */
+    set fraction(f) {
+        if (this.slot >= 0)
+            this.owner.setFraction(this.slot, f);
+    }
+}
+/**
+ * World-anchored, camera-facing quads in one batch: name plates, damage numbers, health bars,
+ * markers. Each shows a region of the shared text atlas or a solid colour, is sized in world
+ * units or in screen px, optionally fades out over `life` and drifts by `velocity`. Alpha
+ * blended, depth tested without writing (or drawn over everything with `depth: 'always'`),
+ * sorted back to front each `update`. Draw with `frame.drawable(billboards)`.
+ *
+ * ```ts
+ * const bb = createBillboards(renderer);
+ * const plate = bb.add({ position: hero.position, offset: [0, 2, 0], size: { px: [160, 40] },
+ *                        region: bb.text('Hero', { size: 28, stroke: '#000', strokeWidth: 4 }) });
+ * bb.add({ position: hero.position, offset: [0, 2.3, 0], size: [1, 0.12], life: 0.9,
+ *          velocity: [0, 1.2, 0], region: bb.text('-37', { color: '#f44' }) });
+ * bb.update(dt, camera);        // ages, drifts, sorts
+ * frame.drawable(bb);           // inside the scene's render
+ * ```
+ *
+ * Nothing allocates per frame once the buffers are big enough; `add` past `capacity` doubles
+ * them.
+ */
+export class Billboards {
+    /** The atlas canvas as a texture, uploaded when the atlas changed (once per frame at most). */
+    atlasTexture;
+    /** The text atlas behind `text()`. */
+    atlas;
+    /** Draw calls the last `draw` issued (0, 1 or 2: one per depth mode in use). */
+    draws = 0;
+    renderer;
+    device;
+    label;
+    capacity;
+    n = 0;
+    // Per slot, CPU side.
+    anchor;
+    tracked;
+    offset;
+    velocity;
+    /** age, life (life <= 0: immortal). */
+    life;
+    rgba;
+    mode;
+    regions;
+    /** A text plate's text (its region an owned atlas cell); null when not a plate. */
+    plates;
+    handles;
+    /** Instance data per slot, in `BILLBOARD_WGSL`'s layout. */
+    inst;
+    // Per frame.
+    order;
+    keys;
+    upload;
+    /**
+     * Motion (ws/render-11): per slot the anchor its quad was last drawn at (`xyz`, `w` = 1 once
+     * drawn), and the previous anchors in sorted order for `prevBuffer` (binding 3), which the
+     * velocity build of the shader reads. Kept only once a view with a velocity attachment drew
+     * the batch (`motion`); until then the buffer holds zeros, read as "unknown" (no motion).
+     */
+    drawn;
+    prevUpload;
+    prevBuffer;
+    motion = false;
+    /** The velocity builds of the shader, by fragment location (2 or 3), made on first use. */
+    motionModules = [];
+    testCount = 0;
+    alwaysCount = 0;
+    uploadDirty = false;
+    buffer;
+    group;
+    groupLayout;
+    pipelineDesc;
+    /**
+     * Pipelines per depth format (null: none) × the view target's aux key, made on first use
+     * from `renderer.sceneTargets` (ws/render-10): `testPipelines` depth-test (and hold the
+     * depthless one), `alwaysPipelines` ignore depth.
+     */
+    testPipelines = new ScenePipelineCache();
+    alwaysPipelines = new ScenePipelineCache();
+    constructor(renderer, opts = {}) {
+        const device = renderer.device;
+        this.renderer = renderer;
+        this.device = device;
+        this.label = opts.label ?? 'billboards';
+        const cap = Math.max(16, Math.floor(opts.capacity ?? 1024));
+        this.capacity = cap;
+        this.anchor = new Float32Array(cap * 3);
+        this.tracked = new Array(cap).fill(null);
+        this.offset = new Float32Array(cap * 3);
+        this.velocity = new Float32Array(cap * 3);
+        this.life = new Float32Array(cap * 2);
+        this.rgba = new Float32Array(cap * 4);
+        this.mode = new Uint8Array(cap);
+        this.regions = new Array(cap).fill(null);
+        this.plates = new Array(cap).fill(null);
+        this.handles = new Array(cap);
+        this.inst = new Float32Array(cap * F);
+        this.order = new Uint32Array(cap);
+        this.keys = new Float32Array(cap);
+        this.upload = new Float32Array(cap * F);
+        this.drawn = new Float32Array(cap * 4);
+        this.prevUpload = new Float32Array(cap * 4);
+        this.motion = (renderer.target.auxKey & 2) !== 0;
+        this.atlas = new TextAtlas(opts.atlas);
+        this.atlasTexture = renderer.createTexture({
+            width: this.atlas.size,
+            height: this.atlas.size,
+            format: 'rgba8unorm-srgb',
+            label: `${this.label}-atlas`,
+        });
+        this.groupLayout = device.createBindGroupLayout({
+            label: `${this.label}-layout`,
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.VERTEX, buffer: { type: 'read-only-storage' } },
+                { binding: 1, visibility: GPUShaderStage.FRAGMENT, sampler: {} },
+                { binding: 2, visibility: GPUShaderStage.FRAGMENT, texture: {} },
+                { binding: 3, visibility: GPUShaderStage.VERTEX, buffer: { type: 'read-only-storage' } },
+            ],
+        });
+        this.buffer = this.makeBuffer(cap);
+        this.prevBuffer = this.makePrevBuffer(cap);
+        this.group = this.makeGroup();
+        const mod = createShaderModule(device, BILLBOARD_WGSL, this.label);
+        this.pipelineDesc = {
+            label: this.label,
+            layout: device.createPipelineLayout({
+                bindGroupLayouts: [renderer.globalsLayout, this.groupLayout],
+            }),
+            vertex: { module: mod, entryPoint: 'vs' },
+            fragment: {
+                module: mod,
+                entryPoint: 'fs',
+                targets: renderer.sceneTargets(ALPHA_BLEND),
+            },
+            primitive: { topology: 'triangle-list' },
+        };
+        this.pipelineFor(null, renderer.target.auxKey, false);
+    }
+    /** Live billboards. */
+    get count() {
+        return this.n;
+    }
+    /** Share of the atlas canvas in use, 0..1. */
+    get atlasUsed() {
+        return this.atlas.used;
+    }
+    makeBuffer(cap) {
+        return this.device.createBuffer({
+            label: this.label,
+            size: cap * BILLBOARD_BYTES,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+    }
+    makePrevBuffer(cap) {
+        return this.device.createBuffer({
+            label: `${this.label}-prev`,
+            size: cap * 16,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        });
+    }
+    makeGroup() {
+        return this.device.createBindGroup({
+            label: this.label,
+            layout: this.groupLayout,
+            entries: [
+                { binding: 0, resource: { buffer: this.buffer } },
+                { binding: 1, resource: this.renderer.samplers['linear-clamp'] },
+                { binding: 2, resource: this.atlasTexture.view },
+                { binding: 3, resource: { buffer: this.prevBuffer } },
+            ],
+        });
+    }
+    /** Double every array and the GPU buffer (only when `add` finds the batch full). */
+    grow() {
+        const cap = this.capacity * 2;
+        const copy = (old, per) => {
+            const out = new old.constructor(cap * per);
+            out.set(old);
+            return out;
+        };
+        this.anchor = copy(this.anchor, 3);
+        this.offset = copy(this.offset, 3);
+        this.velocity = copy(this.velocity, 3);
+        this.life = copy(this.life, 2);
+        this.rgba = copy(this.rgba, 4);
+        this.mode = copy(this.mode, 1);
+        this.inst = copy(this.inst, F);
+        this.order = copy(this.order, 1);
+        this.keys = copy(this.keys, 1);
+        this.upload = new Float32Array(cap * F);
+        this.drawn = copy(this.drawn, 4);
+        this.prevUpload = new Float32Array(cap * 4);
+        this.tracked.length = cap;
+        this.regions.length = cap;
+        this.plates.length = cap;
+        this.handles.length = cap;
+        for (let i = this.capacity; i < cap; i++) {
+            this.tracked[i] = null;
+            this.regions[i] = null;
+            this.plates[i] = null;
+        }
+        this.capacity = cap;
+        this.buffer.destroy();
+        this.buffer = this.makeBuffer(cap);
+        this.prevBuffer.destroy();
+        this.prevBuffer = this.makePrevBuffer(cap);
+        this.group = this.makeGroup();
+    }
+    /** Add a billboard; the handle changes or removes it later. */
+    add(desc) {
+        if (this.n === this.capacity)
+            this.grow();
+        const i = this.n++;
+        const h = new BillboardHandle(this);
+        h.slot = i;
+        this.handles[i] = h;
+        this.setPosition(i, desc.position);
+        this.setOffset(i, desc.offset ?? ZERO3);
+        const v = desc.velocity ?? ZERO3;
+        this.velocity[i * 3] = v[0];
+        this.velocity[i * 3 + 1] = v[1];
+        this.velocity[i * 3 + 2] = v[2];
+        this.life[i * 2] = 0;
+        this.life[i * 2 + 1] = desc.life ?? 0;
+        this.drawn[i * 4 + 3] = 0;
+        this.mode[i] = desc.depth === 'always' ? 1 : 0;
+        const o = i * F;
+        const inst = this.inst;
+        inst.fill(0, o, o + F);
+        inst[o + 3] = desc.facing === 'cameraY' ? BB_FLAG_YAW : 0;
+        this.setSize(i, desc.size);
+        this.plates[i] = null;
+        this.regions[i] = null;
+        if (desc.text !== undefined)
+            this.makePlate(i, desc.text, desc.textStyle);
+        else
+            this.setRegion(i, desc.region ?? null);
+        this.setColor(i, desc.color ?? WHITE);
+        const bar = desc.bar;
+        if (bar) {
+            inst[o + 3] = (inst[o + 3] | BB_FLAG_BAR) >>> 0;
+            inst[o + 6] = bar.fraction;
+            inst[o + 16] = bar.bg[0];
+            inst[o + 17] = bar.bg[1];
+            inst[o + 18] = bar.bg[2];
+            inst[o + 19] = bar.bg[3] ?? 1;
+        }
+        return h;
+    }
+    /** Remove a billboard now (a no-op for one already gone). */
+    remove(handle) {
+        const i = handle.slot;
+        if (i < 0 || this.handles[i] !== handle)
+            return;
+        this.removeAt(i);
+    }
+    /** Remove every billboard. Atlas text stays cached; text plates give their cells back. */
+    clear() {
+        for (let i = 0; i < this.n; i++) {
+            this.handles[i].slot = -1;
+            this.releasePlate(i);
+            this.tracked[i] = null;
+            this.regions[i] = null;
+        }
+        this.n = 0;
+        this.testCount = 0;
+        this.alwaysCount = 0;
+        this.uploadDirty = true;
+    }
+    /** Swap-remove slot `i`: the last slot moves into it. */
+    removeAt(i) {
+        const last = --this.n;
+        this.handles[i].slot = -1;
+        this.releasePlate(i);
+        if (i !== last) {
+            const h = this.handles[last];
+            h.slot = i;
+            this.handles[i] = h;
+            this.tracked[i] = this.tracked[last];
+            this.regions[i] = this.regions[last];
+            this.plates[i] = this.plates[last];
+            this.mode[i] = this.mode[last];
+            this.anchor.copyWithin(i * 3, last * 3, last * 3 + 3);
+            this.offset.copyWithin(i * 3, last * 3, last * 3 + 3);
+            this.velocity.copyWithin(i * 3, last * 3, last * 3 + 3);
+            this.life.copyWithin(i * 2, last * 2, last * 2 + 2);
+            this.rgba.copyWithin(i * 4, last * 4, last * 4 + 4);
+            this.inst.copyWithin(i * F, last * F, last * F + F);
+            this.drawn.copyWithin(i * 4, last * 4, last * 4 + 4);
+        }
+        this.drawn[last * 4 + 3] = 0;
+        this.tracked[last] = null;
+        this.regions[last] = null;
+        this.plates[last] = null;
+    }
+    /**
+     * The atlas region for `text` in `style`, rasterised on first use and cached (text + style).
+     * Throws when the string is larger than the whole atlas canvas.
+     */
+    text(text, style) {
+        const r = this.atlas.text(text, style);
+        if (!r)
+            throw new Error(`billboards: "${text}" does not fit a ${this.atlas.size}px atlas`);
+        return r;
+    }
+    /**
+     * A health bar in one quad, `fraction` (0..1) of its width in `fg` and the rest in `bg`:
+     * spread it into `add` with a `position`, then set `handle.fraction`.
+     */
+    bar(fraction, size, fg, bg) {
+        return { size, color: fg, region: null, bar: { fraction, bg } };
+    }
+    /** @internal */
+    setPosition(i, p) {
+        if (p instanceof Float32Array) {
+            this.tracked[i] = p;
+        }
+        else {
+            this.tracked[i] = null;
+            this.anchor[i * 3] = p[0];
+            this.anchor[i * 3 + 1] = p[1];
+            this.anchor[i * 3 + 2] = p[2];
+        }
+    }
+    /** @internal */
+    setOffset(i, o) {
+        this.offset[i * 3] = o[0];
+        this.offset[i * 3 + 1] = o[1];
+        this.offset[i * 3 + 2] = o[2];
+    }
+    /** @internal */
+    setColor(i, c) {
+        const o = i * 4;
+        this.rgba[o] = c[0];
+        this.rgba[o + 1] = c[1];
+        this.rgba[o + 2] = c[2];
+        this.rgba[o + 3] = c[3] ?? 1;
+    }
+    /** @internal */
+    setSize(i, s) {
+        const o = i * F;
+        const inst = this.inst;
+        const flags = inst[o + 3] & ~BB_FLAG_PX;
+        if ('px' in s) {
+            inst[o + 3] = flags | BB_FLAG_PX;
+            inst[o + 4] = s.px[0];
+            inst[o + 5] = s.px[1];
+        }
+        else {
+            inst[o + 3] = flags;
+            inst[o + 4] = s[0];
+            inst[o + 5] = s[1];
+        }
+    }
+    /**
+     * The width and height, in atlas px, a text plate of `text` in `style` gets (its cell): size
+     * a plate's quad to this aspect.
+     */
+    measure(text, style) {
+        return this.atlas.cellSize(text, style);
+    }
+    /** @internal */
+    plateText(i) {
+        return this.plates[i] ?? null;
+    }
+    /** @internal */
+    setText(i, text) {
+        const old = this.regions[i];
+        if (this.plates[i] === null || !old) {
+            this.makePlate(i, text);
+            return;
+        }
+        const r = this.atlas.rewrite(old, text);
+        if (!r)
+            throw new Error(`billboards: "${text}" does not fit a ${this.atlas.size}px atlas`);
+        if (r !== old) {
+            // A wider cell: keep the height and the glyph scale.
+            this.inst[i * F + 4] *= r.width / old.width;
+            this.regions[i] = null;
+            this.writeRegion(i, r);
+        }
+        this.plates[i] = text;
+    }
+    makePlate(i, text, style) {
+        const r = this.atlas.cell(text, style);
+        if (!r)
+            throw new Error(`billboards: "${text}" does not fit a ${this.atlas.size}px atlas`);
+        this.setRegion(i, r);
+        this.plates[i] = text;
+    }
+    releasePlate(i) {
+        if (this.plates[i] === null)
+            return;
+        const r = this.regions[i];
+        if (r)
+            this.atlas.release(r);
+        this.plates[i] = null;
+    }
+    /** @internal */
+    setRegion(i, r) {
+        if (this.regions[i] !== r)
+            this.releasePlate(i);
+        this.writeRegion(i, r);
+    }
+    writeRegion(i, r) {
+        const o = i * F;
+        const inst = this.inst;
+        this.regions[i] = r;
+        const flags = inst[o + 3] & ~BB_FLAG_TEXTURED;
+        if (r) {
+            inst[o + 3] = flags | BB_FLAG_TEXTURED;
+            inst[o + 8] = r.u0;
+            inst[o + 9] = r.v0;
+            inst[o + 10] = r.u1;
+            inst[o + 11] = r.v1;
+        }
+        else {
+            inst[o + 3] = flags;
+        }
+    }
+    /** @internal */
+    setFraction(i, f) {
+        this.inst[i * F + 6] = f;
+    }
+    /**
+     * Age and drift every billboard, remove the ones past their `life`, resolve anchors and fades
+     * into the instance data and sort back to front for `camera` (without one, submission order).
+     * Call once per update or frame; allocation-free.
+     */
+    update(dt, camera) {
+        const life = this.life;
+        const vel = this.velocity;
+        const anchor = this.anchor;
+        const offset = this.offset;
+        const tracked = this.tracked;
+        const inst = this.inst;
+        const rgba = this.rgba;
+        const keys = this.keys;
+        const order = this.order;
+        const atlas = this.atlas;
+        const view = camera ? camera.view : null;
+        // Expire from the end so swap-removes never skip a slot.
+        for (let i = this.n - 1; i >= 0; i--) {
+            const total = life[i * 2 + 1];
+            if (total <= 0)
+                continue;
+            const age = life[i * 2] + dt;
+            life[i * 2] = age;
+            if (age >= total)
+                this.removeAt(i);
+        }
+        const n = this.n;
+        let test = 0;
+        for (let i = 0; i < n; i++) {
+            const i3 = i * 3;
+            const t = tracked[i];
+            // Velocity moves the copied anchor, or the offset of a tracked one.
+            const dst = t ? offset : anchor;
+            dst[i3] = dst[i3] + vel[i3] * dt;
+            dst[i3 + 1] = dst[i3 + 1] + vel[i3 + 1] * dt;
+            dst[i3 + 2] = dst[i3 + 2] + vel[i3 + 2] * dt;
+            const x = (t ? t[0] : anchor[i3]) + offset[i3];
+            const y = (t ? t[1] : anchor[i3 + 1]) + offset[i3 + 1];
+            const z = (t ? t[2] : anchor[i3 + 2]) + offset[i3 + 2];
+            const o = i * F;
+            inst[o] = x;
+            inst[o + 1] = y;
+            inst[o + 2] = z;
+            const total = life[i * 2 + 1];
+            let fade = 1;
+            if (total > 0) {
+                const left = 1 - life[i * 2] / total;
+                fade = left < 0.5 ? left * 2 : 1;
+            }
+            inst[o + 12] = rgba[i * 4];
+            inst[o + 13] = rgba[i * 4 + 1];
+            inst[o + 14] = rgba[i * 4 + 2];
+            inst[o + 15] = rgba[i * 4 + 3] * fade;
+            const r = this.regions[i];
+            if (r)
+                atlas.touch(r);
+            const z_view = view ? view[2] * x + view[6] * y + view[10] * z + view[14] : 0;
+            const always = this.mode[i] === 1;
+            if (!always)
+                test++;
+            keys[i] = (always ? ALWAYS_KEY : 0) + z_view;
+            order[i] = i;
+        }
+        this.testCount = test;
+        this.alwaysCount = n - test;
+        // Insertion sort by key ascending (farther view z is more negative, so back to front).
+        // Frame-to-frame coherence keeps it near linear.
+        for (let i = 1; i < n; i++) {
+            const idx = order[i];
+            const k = keys[idx];
+            let j = i - 1;
+            while (j >= 0 && keys[order[j]] > k) {
+                order[j + 1] = order[j];
+                j--;
+            }
+            order[j + 1] = idx;
+        }
+        const upload = this.upload;
+        for (let i = 0; i < n; i++) {
+            const src = order[i] * F;
+            upload.set(inst.subarray(src, src + F), i * F);
+        }
+        this.uploadDirty = true;
+    }
+    /**
+     * Upload the instance data, last frame's drawn anchors when the view has velocity and, when
+     * the atlas changed, its canvas. Runs before the pass.
+     */
+    prepare(_encoder, _frame) {
+        if (_frame && (_frame.auxKey & 2) !== 0)
+            this.motion = true;
+        if (this.motion)
+            this.writePrevious();
+        if (this.uploadDirty) {
+            this.uploadDirty = false;
+            if (this.n > 0) {
+                this.device.queue.writeBuffer(this.buffer, 0, this.upload.buffer, 0, this.n * BILLBOARD_BYTES);
+            }
+        }
+        const atlas = this.atlas;
+        if (atlas.dirty) {
+            atlas.markUploaded();
+            this.device.queue.copyExternalImageToTexture({ source: atlas.canvas }, { texture: this.atlasTexture.texture }, [atlas.size, atlas.size]);
+        }
+    }
+    /**
+     * Once per frame with `motion` on: each drawn quad's previous anchor (where it was drawn last
+     * frame, or its current one the first time) into `prevBuffer` in draw order, then remember
+     * the current anchors. Without an `update` since, current equals previous (no motion).
+     */
+    writePrevious() {
+        const n = this.n;
+        if (n === 0)
+            return;
+        const order = this.order;
+        const upload = this.upload;
+        const drawn = this.drawn;
+        const prev = this.prevUpload;
+        for (let i = 0; i < n; i++) {
+            const s = order[i];
+            const u = i * F;
+            const p = i * 4;
+            const d = s * 4;
+            const known = s < n && drawn[d + 3] === 1;
+            prev[p] = known ? drawn[d] : upload[u];
+            prev[p + 1] = known ? drawn[d + 1] : upload[u + 1];
+            prev[p + 2] = known ? drawn[d + 2] : upload[u + 2];
+            prev[p + 3] = 1;
+            if (s < n) {
+                drawn[d] = upload[u];
+                drawn[d + 1] = upload[u + 1];
+                drawn[d + 2] = upload[u + 2];
+                drawn[d + 3] = 1;
+            }
+        }
+        this.device.queue.writeBuffer(this.prevBuffer, 0, prev.buffer, 0, n * 16);
+    }
+    /** Draw inside the scene pass: the `'test'` quads, then the `'always'` ones. */
+    draw(pass, frame) {
+        this.draws = 0;
+        if (this.n === 0)
+            return;
+        const fmt = frame?.depthFormat ?? null;
+        const aux = frame ? frame.auxKey : this.renderer.target.auxKey;
+        // A first velocity view: its prev buffer is still zeros (no motion) until the next prepare.
+        if ((aux & 2) !== 0)
+            this.motion = true;
+        pass.setBindGroup(1, this.group);
+        if (!fmt) {
+            pass.setPipeline(this.pipelineFor(null, aux, false));
+            pass.draw(6, this.n);
+            this.draws = 1;
+            return;
+        }
+        if (this.testCount > 0) {
+            pass.setPipeline(this.pipelineFor(fmt, aux, false));
+            pass.draw(6, this.testCount, 0, 0);
+            this.draws++;
+        }
+        if (this.alwaysCount > 0) {
+            pass.setPipeline(this.pipelineFor(fmt, aux, true));
+            pass.draw(6, this.alwaysCount, 0, this.testCount);
+            this.draws++;
+        }
+    }
+    pipelineFor(format, aux, always) {
+        const cache = always ? this.alwaysPipelines : this.testPipelines;
+        const p = cache.get(format, aux);
+        if (p)
+            return p;
+        const label = `${this.label}${format ? `:${format}` : ''}${always ? ':always' : ''}`;
+        const depth = format
+            ? { format, depthWriteEnabled: false, depthCompare: always ? 'always' : 'less-equal' }
+            : undefined;
+        const targets = this.renderer.sceneTargets(ALPHA_BLEND, aux);
+        const at = velocityLocation(aux);
+        // With a velocity attachment the quads write their own motion (ws/render-11).
+        const desc = at === 0
+            ? sceneVariant(this.pipelineDesc, targets, `${label}${auxSuffix(aux)}`, depth)
+            : motionVariant(this.pipelineDesc, this.motionModule(at), targets, aux, `${label}${auxSuffix(aux)}:motion`, depth);
+        return cache.set(format, aux, this.device.createRenderPipeline(desc));
+    }
+    motionModule(at) {
+        let m = this.motionModules[at];
+        if (!m) {
+            m = createShaderModule(this.device, billboardWgsl(at), `${this.label}-motion`);
+            this.motionModules[at] = m;
+        }
+        return m;
+    }
+    destroy() {
+        this.clear();
+        this.buffer.destroy();
+        this.prevBuffer.destroy();
+        this.atlasTexture.destroy();
+    }
+}
+/** `new Billboards(renderer, opts)`. */
+export function createBillboards(renderer, opts) {
+    return new Billboards(renderer, opts);
+}