@woosh/meep-engine 3.31.0 → 3.32.0

package/src/shade/renderer/buffer/GPUBufferStagingAllocator.js

@@ -8,8 +8,13 @@ import { binarySearchHighIndex } from "../../../core/collection/array/binarySear
 let id_count = 0;
 
 /**
- * Provides staging buffers for pushing data from CPU to GPU.
+ * Mapped `MAP_WRITE | COPY_SRC` buffers for pushing data from the CPU to the GPU, one per upload.
  *
+ * A buffer comes out mapped; its holder fills it, unmaps it, copies out of it and gives it back, and
+ * the pool maps it again — a round trip through the GPU — before it can come out again. For bytes
+ * that is the cheaper road; for thousands of small writes a frame the round trips are the cost, which
+ * is why a {@link ShadeGPUCommandContext} brings only its large writes here (see
+ * `MAPPED_UPLOAD_THRESHOLD`).
  */
 export class GPUBufferStagingAllocator {
 
@@ -24,6 +29,39 @@ export class GPUBufferStagingAllocator {
      */
     #ready = [];
 
+    /**
+     * Bytes in {@link #ready}.
+     *
+     * @type {number}
+     */
+    #ready_byte_size = 0;
+
+    /**
+     * Bytes in buffers handed out and not back in {@link #ready} yet: with their holder, or on their
+     * way back through a mapping. They are memory like any other, and a GPU running behind holds a
+     * frame's worth of them for every frame it is behind.
+     *
+     * @type {number}
+     */
+    #held_byte_size = 0;
+
+    /**
+     * Buffers handed out and not given back yet. Only these are taken back: a buffer given back
+     * twice, or one this pool never made, would otherwise go into {@link #ready} twice and come out
+     * to two holders at once.
+     *
+     * @type {Set<GPUBuffer>}
+     */
+    #held = new Set();
+
+    /**
+     * Set by {@link destroy}. A buffer whose mapping comes back after that is destroyed, not pooled —
+     * the pool it would go into is gone.
+     *
+     * @type {boolean}
+     */
+    #destroyed = false;
+
     /**
      *
      * @param {GPUDevice} device
@@ -35,17 +73,13 @@ export class GPUBufferStagingAllocator {
     }
 
     /**
+     * Bytes in every buffer this pool has made and not destroyed: free, handed out, or on the way
+     * back.
      *
      * @returns {number}
      */
     get gpu_memory_usage() {
-        let r = 0;
-
-        for (const b of this.#ready) {
-            r += b.size;
-        }
-
-        return r;
+        return this.#ready_byte_size + this.#held_byte_size;
     }
 
 
@@ -78,8 +112,13 @@ export class GPUBufferStagingAllocator {
                 mappedAtCreation: true,
             });
 
+        } else {
+            this.#ready_byte_size -= result.size;
         }
 
+        this.#held_byte_size += result.size;
+        this.#held.add(result);
+
         assert.greaterThanOrEqual(result.size, min_size_bytes, 'result.size < min_size_bytes');
         assert.equal(result.mapState, "mapped", 'result.mapState !== "mapped"');
 
@@ -113,38 +152,81 @@ export class GPUBufferStagingAllocator {
 
         this.#ready.splice(index, 0, buffer);
 
+        this.#ready_byte_size += buffer.size;
+
         return true;
     }
 
     /**
      *
      * @param {GPUBuffer} buffer
+     * @returns {boolean} whether it was taken back: false for a buffer given back already, or one
+     * this pool did not hand out
      */
     release(buffer) {
+        if (!this.#held.delete(buffer)) {
+            return false;
+        }
+
         const state = buffer.mapState;
 
-        // TODO have a cleanup mechanism to prevent memory leak
+        // TODO the ready list never shrinks: a burst's buffers stay until destroy()
 
         if (state === "mapped") {
             // release directly
-            this.#add_to_ready(buffer);
+            this.#take_back(buffer);
         } else if (state === "unmapped") {
             buffer.mapAsync(GPUMapMode.WRITE)
                 .then(
-                    () => this.#add_to_ready(buffer),
-                    console.error
+                    () => this.#take_back(buffer),
+                    () => this.#give_up(buffer)
                 );
         } else {
             throw new Error(`Invalid map state: ${state}`);
         }
+
+        return true;
+    }
+
+    /**
+     * A buffer back and mapped, to be handed out again.
+     *
+     * @param {GPUBuffer} buffer
+     */
+    #take_back(buffer) {
+        this.#held_byte_size -= buffer.size;
+
+        if (this.#destroyed) {
+            buffer.destroy();
+
+            return;
+        }
+
+        this.#add_to_ready(buffer);
+    }
+
+    /**
+     * A mapping that failed — the buffer or its device is gone — brings nothing back to reuse. It
+     * used to be logged and dropped: never destroyed, so whatever was left of it waited for the
+     * garbage collector.
+     *
+     * @param {GPUBuffer} buffer
+     */
+    #give_up(buffer) {
+        this.#held_byte_size -= buffer.size;
+
+        buffer.destroy();
     }
 
     destroy() {
+        this.#destroyed = true;
+
         for (const b of this.#ready) {
             b.destroy();
         }
 
         // drop data
         this.#ready.splice(0, this.#ready.length);
+        this.#ready_byte_size = 0;
     }
-}
+}

package/src/shade/renderer/buffer/GPUBufferUploadAllocator.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Uploads of this many bytes or more go through a mapped staging buffer of their own
+ * ({@link GraphicsContext#buffer_allocator_staging}); smaller ones through upload blocks.
+ *
+ * The two ways cost differently. A mapping is a round trip per upload, which thousands of small
+ * uniforms a frame cannot afford: 1 KiB uploads moved 8–10 MiB/s mapped against 430–470 MiB/s
+ * through blocks. Bytes, though, travel better mapped — filled in place and copied once, where a
+ * block's are copied into it, sent with a queue write and copied again on the GPU — and 1 MiB
+ * uploads moved 3,350–3,560 MiB/s mapped against 1,480–1,640 through blocks. The two crossed between
+ * 24 and 32 KiB (RTX 4090, Chrome 154, 4 MiB per submission in uploads of one size, 2026-09-26).
+ *
+ * @type {number}
+ */
+export const MAPPED_UPLOAD_THRESHOLD: number;
+/**
+ * Size of every upload block. Everything that comes here is smaller than
+ * {@link MAPPED_UPLOAD_THRESHOLD}, so any empty block holds any write, and a frame's uniforms — a
+ * few thousand at the heavy end, tens of bytes each — fill one or two.
+ *
+ * @type {number}
+ */
+export const UPLOAD_BLOCK_SIZE: number;
+/**
+ * Upload memory for {@link ShadeGPUCommandContext}'s small writes: pooled {@link GPUUploadBlock}s,
+ * all {@link UPLOAD_BLOCK_SIZE} bytes, each a `COPY_SRC | COPY_DST` buffer paired with CPU memory of
+ * the same size.
+ *
+ * A block is a transient in {@link TransientResourcePool}'s sense and is reused as soon as it is
+ * given back, for the reason `ShadeGPUCommandContext#send_uploads` sets out. It is a pool of its own,
+ * not {@link GraphicsContext#buffer_allocator_main}, because the frame graph aliases that pool's
+ * buffers within a submission, and a queue write — which lands ahead of the whole submission — into
+ * an aliased buffer would overwrite what an earlier pass in it still needs. Nothing aliases a block.
+ */
+export class GPUBufferUploadAllocator extends TransientResourcePool {
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device: GPUDevice);
+    /**
+     * An empty block. Give it back with {@link release}.
+     *
+     * @returns {GPUUploadBlock}
+     */
+    get(): GPUUploadBlock;
+    /**
+     * @param {GPUUploadBlock} block
+     * @returns {boolean}
+     */
+    release(block: GPUUploadBlock): boolean;
+    find(): number;
+    compare(a: any, b: any): number;
+    sizeOf(block: any): any;
+    make(): GPUUploadBlock;
+    destroyResource(block: any): void;
+    afterAcquire(block: any): void;
+    #private;
+}
+import { TransientResourcePool } from "../pool/TransientResourcePool.js";
+import { GPUUploadBlock } from "./GPUUploadBlock.js";
+//# sourceMappingURL=GPUBufferUploadAllocator.d.ts.map

package/src/shade/renderer/buffer/GPUBufferUploadAllocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUBufferUploadAllocator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/GPUBufferUploadAllocator.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;GAYG;AACH,sCAFU,MAAM,CAEqC;AAErD;;;;;;GAMG;AACH,gCAFU,MAAM,CAEgC;AAShD;;;;;;;;;;GAUG;AACH;IAeI;;OAEG;IACH,+BAMC;IAED;;;;OAIG;IACH,OAFa,cAAc,CAI1B;IAkBD;;;OAGG;IACH,eAHW,cAAc,GACZ,OAAO,CAMnB;IAED,eAYC;IAED,gCAIC;IAED,wBAEC;IAED,uBAkDC;IAED,kCAEC;IAED,+BAEC;;CASJ;sCArMqC,kCAAkC;+BACzC,qBAAqB"}

package/src/shade/renderer/buffer/GPUBufferUploadAllocator.js

@@ -0,0 +1,202 @@
+import { assert } from "../../../core/assert.js";
+import { KILOBYTE } from "../../../core/science/units/memory/KILOBYTE.js";
+import { MEGABYTE } from "../../../core/science/units/memory/MEGABYTE.js";
+import { warn_limited } from "../../util/warn_limited.js";
+import { TransientResourcePool } from "../pool/TransientResourcePool.js";
+import { GPUUploadBlock } from "./GPUUploadBlock.js";
+
+/**
+ * Uploads of this many bytes or more go through a mapped staging buffer of their own
+ * ({@link GraphicsContext#buffer_allocator_staging}); smaller ones through upload blocks.
+ *
+ * The two ways cost differently. A mapping is a round trip per upload, which thousands of small
+ * uniforms a frame cannot afford: 1 KiB uploads moved 8–10 MiB/s mapped against 430–470 MiB/s
+ * through blocks. Bytes, though, travel better mapped — filled in place and copied once, where a
+ * block's are copied into it, sent with a queue write and copied again on the GPU — and 1 MiB
+ * uploads moved 3,350–3,560 MiB/s mapped against 1,480–1,640 through blocks. The two crossed between
+ * 24 and 32 KiB (RTX 4090, Chrome 154, 4 MiB per submission in uploads of one size, 2026-09-26).
+ *
+ * @type {number}
+ */
+export const MAPPED_UPLOAD_THRESHOLD = 32 * KILOBYTE;
+
+/**
+ * Size of every upload block. Everything that comes here is smaller than
+ * {@link MAPPED_UPLOAD_THRESHOLD}, so any empty block holds any write, and a frame's uniforms — a
+ * few thousand at the heavy end, tens of bytes each — fill one or two.
+ *
+ * @type {number}
+ */
+export const UPLOAD_BLOCK_SIZE = 256 * KILOBYTE;
+
+assert.greaterThan(UPLOAD_BLOCK_SIZE, MAPPED_UPLOAD_THRESHOLD, 'a block must hold the largest write routed to it');
+
+/**
+ * @type {number}
+ */
+let id_counter = 0;
+
+/**
+ * Upload memory for {@link ShadeGPUCommandContext}'s small writes: pooled {@link GPUUploadBlock}s,
+ * all {@link UPLOAD_BLOCK_SIZE} bytes, each a `COPY_SRC | COPY_DST` buffer paired with CPU memory of
+ * the same size.
+ *
+ * A block is a transient in {@link TransientResourcePool}'s sense and is reused as soon as it is
+ * given back, for the reason `ShadeGPUCommandContext#send_uploads` sets out. It is a pool of its own,
+ * not {@link GraphicsContext#buffer_allocator_main}, because the frame graph aliases that pool's
+ * buffers within a submission, and a queue write — which lands ahead of the whole submission — into
+ * an aliased buffer would overwrite what an earlier pass in it still needs. Nothing aliases a block.
+ */
+export class GPUBufferUploadAllocator extends TransientResourcePool {
+    /**
+     * Pooled bytes above which idle blocks are reclaimed. Counted once, but a block holds its size
+     * twice — on the GPU, and on the CPU for as long as it lives — so this is kept lower than the
+     * general pool's.
+     *
+     * @type {number}
+     */
+    param_soft_byte_budget = 16 * MEGABYTE;
+
+    /**
+     * @type {GPUDevice|undefined}
+     */
+    #device;
+
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device) {
+        super();
+
+        assert.defined(device, 'device');
+
+        this.#device = device;
+    }
+
+    /**
+     * An empty block. Give it back with {@link release}.
+     *
+     * @returns {GPUUploadBlock}
+     */
+    get() {
+        return super.get(UPLOAD_BLOCK_SIZE);
+    }
+
+    /**
+     * When each pooled block was given back, counting releases. The pool keeps its blocks in this
+     * order and hands out the latest, so a frame that needs one block gets the same one every time
+     * and the rest go idle long enough to be reclaimed. With no order at all, the pool's sorted
+     * insert put each block given back in the middle and the one handed out came from the end: after
+     * a burst, a one-block frame cycled through three blocks for good, none ever idle.
+     *
+     * @type {WeakMap<GPUUploadBlock, number>}
+     */
+    #given_back = new WeakMap();
+
+    /**
+     * @type {number}
+     */
+    #release_count = 0;
+
+    /**
+     * @param {GPUUploadBlock} block
+     * @returns {boolean}
+     */
+    release(block) {
+        this.#given_back.set(block, ++this.#release_count);
+
+        return super.release(block);
+    }
+
+    find() {
+        const records = this.records;
+
+        // the latest given back that the device did not refuse: a refused block is never handed out
+        // again, and sits idle until update() reclaims it like any other
+        for (let i = records.length - 1; i >= 0; i--) {
+            if (!records[i].resource.refused) {
+                return i;
+            }
+        }
+
+        return -1;
+    }
+
+    compare(a, b) {
+        const given_back = this.#given_back;
+
+        return given_back.get(a.resource) - given_back.get(b.resource);
+    }
+
+    sizeOf(block) {
+        return block.size;
+    }
+
+    make() {
+        // the CPU half first: it is the one that can throw, and a buffer made before it would leak
+        const data = new ArrayBuffer(UPLOAD_BLOCK_SIZE);
+
+        const device = this.#device;
+
+        /*
+         WebGPU does not throw for a buffer it cannot back. It reports the failure through the error
+         scopes, later, and hands back a buffer that fails everything it is used in — here, the whole
+         submission of every context that takes the block. The scopes are how the block finds out,
+         so the pool can stop handing it out; they also keep the error from reaching the page's
+         uncapturederror handler, so it is reported here instead — a few times, not once a frame
+         for as long as the device stays out of memory.
+        */
+
+        /**
+         * Assigned before either scope can answer: they answer on a later turn.
+         * @type {GPUUploadBlock|null}
+         */
+        let block = null;
+
+        const on_scope = error => {
+            if (error !== null && block !== null && !block.refused) {
+                block.refused = true;
+
+                warn_limited(`GPUBufferUploadAllocator: an upload block could not be created and will not be used again: ${error.message}`, 8);
+            }
+        };
+
+        device.pushErrorScope('out-of-memory');
+        device.pushErrorScope('validation');
+
+        let buffer;
+
+        try {
+            buffer = device.createBuffer({
+                label: `upload ${id_counter++}`,
+                size: UPLOAD_BLOCK_SIZE,
+                usage: GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+            });
+        } finally {
+            // popped whatever happens, innermost first: a scope left open would take every error
+            // the device raised from then on, for anyone
+            device.popErrorScope().then(on_scope, console.error);
+            device.popErrorScope().then(on_scope, console.error);
+        }
+
+        block = new GPUUploadBlock(buffer, data);
+
+        return block;
+    }
+
+    destroyResource(block) {
+        block.buffer.destroy();
+    }
+
+    afterAcquire(block) {
+        block.used = 0;
+    }
+
+    destroy() {
+        super.destroy();
+
+        // as GPUBufferAllocator does: a block asked for after teardown would otherwise be made, and
+        // nothing would ever destroy it
+        this.#device = undefined;
+    }
+}

package/src/shade/renderer/buffer/GPUUploadBlock.d.ts

@@ -0,0 +1,68 @@
+/**
+ * One piece of upload memory: a GPU buffer, and the bytes it is to be given, held on the CPU until
+ * they are sent.
+ *
+ * A {@link ShadeGPUCommandContext} fills regions of {@link data} as it records, and copies each
+ * region to its destination with a `copyBufferToBuffer` out of {@link buffer} recorded where the
+ * write was made; the part in use reaches {@link buffer} in one queue write just before the context
+ * submits. Why the block can go back to its pool as soon as the context finishes is set out once,
+ * at `ShadeGPUCommandContext#send_uploads`.
+ *
+ * Both halves live as long as the block does — the CPU half is not given up once sent — so a block
+ * costs its size twice for as long as its pool keeps it.
+ */
+export class GPUUploadBlock {
+    /**
+     * @param {GPUBuffer} buffer
+     * @param {ArrayBuffer} data
+     */
+    constructor(buffer: GPUBuffer, data: ArrayBuffer);
+    /**
+     * `COPY_SRC | COPY_DST`, never mapped.
+     *
+     * @type {GPUBuffer}
+     */
+    buffer: GPUBuffer;
+    /**
+     * What {@link buffer} is to hold, the same size as it. Past {@link used} it holds whatever the
+     * last use left.
+     *
+     * @type {ArrayBuffer}
+     */
+    data: ArrayBuffer;
+    /**
+     * Bytes handed out, from the start. A multiple of 4, so every region starts on one: WebGPU's
+     * buffer copies work in whole 4-byte words, on both offsets and the size.
+     *
+     * @type {number}
+     */
+    used: number;
+    /**
+     * Whether the device refused to back {@link buffer} — out of memory, in practice.
+     *
+     * WebGPU says so through its error scopes, after the fact, and hands back a buffer object either
+     * way. By the time this is set the context that took the block has recorded copies out of an
+     * invalid buffer and its submission is lost with them; what this prevents is the same loss on
+     * every frame after, which is what a pool that kept handing the block out would cause.
+     *
+     * @type {boolean}
+     */
+    refused: boolean;
+    /**
+     * @returns {number} bytes
+     */
+    get size(): number;
+    /**
+     * @param {number} size bytes
+     * @returns {boolean} whether a region of `size` bytes is still free
+     */
+    fits(size: number): boolean;
+    /**
+     * Take the next `size` bytes.
+     *
+     * @param {number} size bytes; the region taken is rounded up to a whole number of 4-byte words
+     * @returns {number} byte offset of the region in {@link data} and {@link buffer}
+     */
+    allocate(size: number): number;
+}
+//# sourceMappingURL=GPUUploadBlock.d.ts.map

package/src/shade/renderer/buffer/GPUUploadBlock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUUploadBlock.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/GPUUploadBlock.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH;IAoCI;;;OAGG;IACH,qCAFW,WAAW,EASrB;IA9CD;;;;OAIG;IACH,kBAAO;IAEP;;;;;OAKG;IACH,MAFU,WAAW,CAEhB;IAEL;;;;;OAKG;IACH,MAFU,MAAM,CAEP;IAET;;;;;;;;;OASG;IACH,SAFU,OAAO,CAED;IAehB;;OAEG;IACH,mBAEC;IAED;;;OAGG;IACH,WAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;OAKG;IACH,eAHW,MAAM,GACJ,MAAM,CAWlB;CACJ"}

package/src/shade/renderer/buffer/GPUUploadBlock.js

@@ -0,0 +1,97 @@
+import { assert } from "../../../core/assert.js";
+import { align_4 } from "../../../core/binary/align_4.js";
+
+/**
+ * One piece of upload memory: a GPU buffer, and the bytes it is to be given, held on the CPU until
+ * they are sent.
+ *
+ * A {@link ShadeGPUCommandContext} fills regions of {@link data} as it records, and copies each
+ * region to its destination with a `copyBufferToBuffer` out of {@link buffer} recorded where the
+ * write was made; the part in use reaches {@link buffer} in one queue write just before the context
+ * submits. Why the block can go back to its pool as soon as the context finishes is set out once,
+ * at `ShadeGPUCommandContext#send_uploads`.
+ *
+ * Both halves live as long as the block does — the CPU half is not given up once sent — so a block
+ * costs its size twice for as long as its pool keeps it.
+ */
+export class GPUUploadBlock {
+    /**
+     * `COPY_SRC | COPY_DST`, never mapped.
+     *
+     * @type {GPUBuffer}
+     */
+    buffer;
+
+    /**
+     * What {@link buffer} is to hold, the same size as it. Past {@link used} it holds whatever the
+     * last use left.
+     *
+     * @type {ArrayBuffer}
+     */
+    data;
+
+    /**
+     * Bytes handed out, from the start. A multiple of 4, so every region starts on one: WebGPU's
+     * buffer copies work in whole 4-byte words, on both offsets and the size.
+     *
+     * @type {number}
+     */
+    used = 0;
+
+    /**
+     * Whether the device refused to back {@link buffer} — out of memory, in practice.
+     *
+     * WebGPU says so through its error scopes, after the fact, and hands back a buffer object either
+     * way. By the time this is set the context that took the block has recorded copies out of an
+     * invalid buffer and its submission is lost with them; what this prevents is the same loss on
+     * every frame after, which is what a pool that kept handing the block out would cause.
+     *
+     * @type {boolean}
+     */
+    refused = false;
+
+    /**
+     * @param {GPUBuffer} buffer
+     * @param {ArrayBuffer} data
+     */
+    constructor(buffer, data) {
+        assert.defined(buffer, 'buffer');
+        assert.defined(data, 'data');
+        assert.equal(data.byteLength, buffer.size, 'data.byteLength !== buffer.size');
+
+        this.buffer = buffer;
+        this.data = data;
+    }
+
+    /**
+     * @returns {number} bytes
+     */
+    get size() {
+        return this.data.byteLength;
+    }
+
+    /**
+     * @param {number} size bytes
+     * @returns {boolean} whether a region of `size` bytes is still free
+     */
+    fits(size) {
+        return this.used + size <= this.data.byteLength;
+    }
+
+    /**
+     * Take the next `size` bytes.
+     *
+     * @param {number} size bytes; the region taken is rounded up to a whole number of 4-byte words
+     * @returns {number} byte offset of the region in {@link data} and {@link buffer}
+     */
+    allocate(size) {
+        assert.isNonNegativeInteger(size, 'size');
+        assert.ok(this.fits(size), 'does not fit');
+
+        const offset = this.used;
+
+        this.used = offset + align_4(size);
+
+        return offset;
+    }
+}

package/src/shade/renderer/dynamic/GPUDynamicMeshRenderer.d.ts

@@ -24,17 +24,27 @@ export class GPUDynamicMeshRenderer {
      * Set before the first draw. Changing it later rebuilds the pipeline, which is cheap but not
      * free, and the whole batch moves together — this is a property of the pass, not of a mesh.
      *
+     * Solid content belongs at `FramePhase.AfterLighting`, with the depth {@link graph_draw} hands
+     * back published: transparency runs after that phase and tests against that depth, so glass in
+     * front of the batch covers it. At `AfterTransparency` the glass is already resolved, and the
+     * batch is drawn over it.
+     *
      * @type {boolean}
      */
     opaque: boolean;
     /**
      * Record the draws into `graph`, over the colour it is given.
      *
-     * When {@link opaque} is set the pass writes the depth it is given. That write lands in the
-     * same physical texture the handle names — a written handle is a renamed clone of one resource,
-     * not a second one — so a later pass reading the handle the caller still holds sees the depth
-     * this pass left. Only the colour is threaded back, because that is what an injected pass is
-     * allowed to replace.
+     * **Both handles come back, and the caller publishes both** — into `SceneColor` and
+     * `ViewTextures` from an extension. The colour is always replaced. The depth is replaced when
+     * {@link opaque} is set, since the pass writes it; otherwise it comes back as it was given.
+     *
+     * A written handle is a renamed clone of the same texture, so a pass that goes on reading the
+     * depth handle it held before this draw is reading a version this pass has superseded.
+     * `FrameGraph.validate` refuses that, and the frame fails to compile in a development build.
+     * A stripped build reads the right contents only because passes run in the order they were
+     * recorded. So every reader of the scene depth after this draw has to be handed the new handle:
+     * depth of field, motion blur, the NSS upscaler, the next extension along.
      *
      * @param {object} args
      * @param {FrameGraph} args.graph
@@ -42,7 +52,7 @@ export class GPUDynamicMeshRenderer {
      * @param {number} args.color colour resource handle to draw over
      * @param {number} args.depth scene depth, written when {@link opaque} and otherwise only tested
      * @param {GPUBuffer} args.camera
-     * @returns {number} the colour handle after the draws
+     * @returns {{color: number, depth: number}} the colour and depth handles after the draws
      */
     graph_draw({ graph, batch, color, depth, camera }: {
         graph: FrameGraph;
@@ -50,7 +60,10 @@ export class GPUDynamicMeshRenderer {
         color: number;
         depth: number;
         camera: GPUBuffer;
-    }): number;
+    }): {
+        color: number;
+        depth: number;
+    };
     /**
      * Release the GPU buffers held for `geometry`. A dynamic mesh that is gone for good should say
      * so — residency deliberately survives removal from the batch, so nothing else will free it.

package/src/shade/renderer/dynamic/GPUDynamicMeshRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUDynamicMeshRenderer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/dynamic/GPUDynamicMeshRenderer.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;GAWG;AACH;IACI;;;;;;;;;;;;;;OAcG;IACH,QAFU,OAAO,CAEF;IAiBf;;;;;;;;;;;;;;;;OAgBG;IACH;QAP4B,KAAK;QACC,KAAK;QACf,KAAK,EAAlB,MAAM;QACO,KAAK,EAAlB,MAAM;QACU,MAAM;QACpB,MAAM,CAuBlB;IAqHD;;;;;;OAMG;IACH,6BAFa,OAAO,CAInB;IAED,gBAEC;;CACJ"}
+{"version":3,"file":"GPUDynamicMeshRenderer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/dynamic/GPUDynamicMeshRenderer.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;GAWG;AACH;IACI;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAFU,OAAO,CAEF;IAiBf;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH;QAP4B,KAAK;QACC,KAAK;QACf,KAAK,EAAlB,MAAM;QACO,KAAK,EAAlB,MAAM;QACU,MAAM;QACpB;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CA0B1C;IAqHD;;;;;;OAMG;IACH,6BAFa,OAAO,CAInB;IAED,gBAEC;;CACJ"}