@woosh/meep-engine 3.31.0 → 3.33.0

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/DynamicMeshAVBOITChannel.d.ts

@@ -7,7 +7,8 @@
  *
  * - **occupancy** — one world box per mesh, over the triangles that can still put a fragment on
  *   screen (`dynamic_mesh_live_bounds`), marked on the GPU through the particles' own chunks. The
- *   upload of the batch's vertices happens here too, being the first of the three at execution time.
+ *   upload of the batch's vertices and of its draws' constants happens here too, being the first of
+ *   the three at execution time; the splat and the draw read the one upload.
  * - **splat** — the meshes at the volume's resolution, coverage as the vertex and mesh alpha give it.
  * - **draw** — the meshes at internal resolution into the accumulators, straight alpha premultiplied,
  *   fogged, weighted by the transmittance in front, routed by `avboit_premultiplied_contribution`.

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

@@ -1 +1 @@
-{"version":3,"file":"DynamicMeshAVBOITChannel.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/dynamic/DynamicMeshAVBOITChannel.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IA0BI;;OAEG;IACH,qCAKC;IAED;;;;;;;OAOG;IACH,mBAFa,OAAO,CAcnB;IAED;;;;;;;;;;OAUG;IACH;QANwB,KAAK,EAAlB,MAAM;QACO,MAAM,EAAnB,MAAM;QACkB,kBAAkB,EAA1C,UAAU,MAAM,CAAC;QACJ,SAAS,EAAtB,MAAM;QACJ,MAAM,CAsBlB;IAED;;;;;;;;;;OAUG;IACH;QAPwB,KAAK,EAAlB,MAAM;QACO,MAAM,EAAnB,MAAM;QACO,IAAI,EAAjB,MAAM;QACS,gBAAgB,EAA/B,MAAM,EAAE;QACoD,MAAM,EAAlE;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAC;QACnD;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAkBjE;IAED;;;;;;;;;;;;;;OAcG;IACH;QAXwB,KAAK,EAAlB,MAAM;QACmD,QAAQ,EAAjE,OAAO,2BAA2B,EAAE,cAAc;QACrC,MAAM,EAAnB,MAAM;QACO,aAAa,EAA1B,MAAM;QACO,IAAI,EAAjB,MAAM;QACO,QAAQ,EAArB,MAAM;QACO,eAAe,EAA5B,MAAM;QACO,oBAAoB,EAAjC,MAAM;QACoE,YAAY,EAAtF;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAC;QACjE;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAmC/E;IAED;;;;;;OAMG;IACH,6BAFa,OAAO,CAInB;IAED;;;OAGG;IACH,gBAIC;;CAoDJ"}
+{"version":3,"file":"DynamicMeshAVBOITChannel.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/dynamic/DynamicMeshAVBOITChannel.js"],"names":[],"mappings":"AAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IA2BI;;OAEG;IACH,qCAKC;IAED;;;;;;;OAOG;IACH,mBAFa,OAAO,CAcnB;IAED;;;;;;;;;;OAUG;IACH;QANwB,KAAK,EAAlB,MAAM;QACO,MAAM,EAAnB,MAAM;QACkB,kBAAkB,EAA1C,UAAU,MAAM,CAAC;QACJ,SAAS,EAAtB,MAAM;QACJ,MAAM,CAuBlB;IAED;;;;;;;;;;OAUG;IACH;QAPwB,KAAK,EAAlB,MAAM;QACO,MAAM,EAAnB,MAAM;QACO,IAAI,EAAjB,MAAM;QACS,gBAAgB,EAA/B,MAAM,EAAE;QACoD,MAAM,EAAlE;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAC;QACnD;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,CAiBjE;IAED;;;;;;;;;;;;;;OAcG;IACH;QAXwB,KAAK,EAAlB,MAAM;QACmD,QAAQ,EAAjE,OAAO,2BAA2B,EAAE,cAAc;QACrC,MAAM,EAAnB,MAAM;QACO,aAAa,EAA1B,MAAM;QACO,IAAI,EAAjB,MAAM;QACO,QAAQ,EAArB,MAAM;QACO,eAAe,EAA5B,MAAM;QACO,oBAAoB,EAAjC,MAAM;QACoE,YAAY,EAAtF;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAC;QACjE;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAC,CAkC/E;IAED;;;;;;OAMG;IACH,6BAFa,OAAO,CAInB;IAED;;;OAGG;IACH,gBAIC;;CAoDJ"}

package/src/shade/renderer/dynamic/DynamicMeshAVBOITChannel.js

@@ -1,6 +1,7 @@
 import { assert } from "../../../core/assert.js";
 import { aabb3_matrix4_project } from "../../../core/geom/3d/aabb/aabb3_matrix4_project.js";
 import { dynamic_mesh_live_bounds } from "./dynamic_mesh_live_bounds.js";
+import { GPUDynamicMeshDrawList } from "./GPUDynamicMeshDrawList.js";
 import {
     graph_dynamic_mesh_avboit_draw,
     graph_dynamic_mesh_avboit_occupancy,
@@ -25,7 +26,8 @@ const scratch_world = new Float64Array(6);
  *
  * - **occupancy** — one world box per mesh, over the triangles that can still put a fragment on
  *   screen (`dynamic_mesh_live_bounds`), marked on the GPU through the particles' own chunks. The
- *   upload of the batch's vertices happens here too, being the first of the three at execution time.
+ *   upload of the batch's vertices and of its draws' constants happens here too, being the first of
+ *   the three at execution time; the splat and the draw read the one upload.
  * - **splat** — the meshes at the volume's resolution, coverage as the vertex and mesh alpha give it.
  * - **draw** — the meshes at internal resolution into the accumulators, straight alpha premultiplied,
  *   fogged, weighted by the transmittance in front, routed by `avboit_premultiplied_contribution`.
@@ -55,16 +57,17 @@ export class DynamicMeshAVBOITChannel {
 
     /**
      * What {@link avboit_occupancy} decided for the graph it was asked in — the graph, the live
-     * meshes, and a world box for each ({@link DYNAMIC_MESH_AVBOIT_BOX_FLOATS} floats apiece) — for
-     * the splat and the draw of the same graph to take.
+     * meshes, a world box for each ({@link DYNAMIC_MESH_AVBOIT_BOX_FLOATS} floats apiece), and the
+     * list their draws are written into when the occupancy executes — for the splat and the draw of
+     * the same graph to take.
      *
      * **Dropped as soon as the draw is recorded.** The passes carry their own references to the list
      * and the boxes into execution, so the channel keeps nothing of a frame past its recording: a
      * channel that stops being asked — its last mesh faded, its renderer replaced — does not hold a
-     * whole frame graph, and every pass closure in it, reachable. And since each frame's list and
+     * whole frame graph, and every pass closure in it, reachable. And since each frame's lists and
      * boxes are its own, two graphs recorded before either executes cannot see each other's.
      *
-     * @type {{graph: object, live: DynamicMesh[], boxes: Float32Array}|null}
+     * @type {{graph: object, live: DynamicMesh[], boxes: Float32Array, draws: GPUDynamicMeshDrawList}|null}
      */
     #frame = null;
 
@@ -130,6 +133,7 @@ export class DynamicMeshAVBOITChannel {
             residency: this.#residency,
             meshes: frame.live,
             boxes: frame.boxes,
+            draws: frame.draws,
         });
     }
 
@@ -145,9 +149,9 @@ export class DynamicMeshAVBOITChannel {
      * @returns {{extinction: number, overflow: number, dummy: number}} the volume after the write
      */
     avboit_splat({ graph, camera, warp, voxel_resolution, volume }) {
-        const meshes = this.#frame_for(graph).live;
+        const frame = this.#frame_for(graph);
 
-        if (meshes.length === 0) {
+        if (frame.live.length === 0) {
             return volume;
         }
 
@@ -157,8 +161,7 @@ export class DynamicMeshAVBOITChannel {
             warp,
             voxel_resolution,
             volume,
-            residency: this.#residency,
-            meshes,
+            draws: frame.draws,
         });
     }
 
@@ -188,12 +191,12 @@ export class DynamicMeshAVBOITChannel {
                     volumetrics_metadata,
                     accumulators
                 }) {
-        const meshes = this.#frame_for(graph).live;
+        const frame = this.#frame_for(graph);
 
         // the last of the three: the frame is the passes' from here on, and none of the channel's
         this.#frame = null;
 
-        if (meshes.length === 0) {
+        if (frame.live.length === 0) {
             return accumulators;
         }
 
@@ -207,8 +210,7 @@ export class DynamicMeshAVBOITChannel {
             volumetrics_lut,
             volumetrics_metadata,
             accumulators,
-            residency: this.#residency,
-            meshes,
+            draws: frame.draws,
         });
     }
 
@@ -239,7 +241,7 @@ export class DynamicMeshAVBOITChannel {
      * would upload nothing and draw some other frame's list, so it is refused.
      *
      * @param {object} graph
-     * @returns {{graph: object, live: DynamicMesh[], boxes: Float32Array}}
+     * @returns {{graph: object, live: DynamicMesh[], boxes: Float32Array, draws: GPUDynamicMeshDrawList}}
      */
     #frame_for(graph) {
         const frame = this.#frame;
@@ -251,10 +253,10 @@ export class DynamicMeshAVBOITChannel {
 
     /**
      * Find the batch's live meshes, and a world box for each — into a list and a buffer of this
-     * frame's own.
+     * frame's own, beside the draw list the occupancy will write their draws into.
      *
      * @param {object} graph
-     * @returns {{graph: object, live: DynamicMesh[], boxes: Float32Array}}
+     * @returns {{graph: object, live: DynamicMesh[], boxes: Float32Array, draws: GPUDynamicMeshDrawList}}
      */
     #gather(graph) {
         const meshes = this.#batch.meshes;
@@ -281,7 +283,7 @@ export class DynamicMeshAVBOITChannel {
             live.push(mesh);
         }
 
-        return { graph, live, boxes };
+        return { graph, live, boxes, draws: new GPUDynamicMeshDrawList() };
     }
 }
 

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

@@ -0,0 +1,70 @@
+/**
+ * The most draws one chunk of a frame's constants holds — and so the most draws one bind of the
+ * constants' group serves.
+ *
+ * Bounded rather than one table for every mesh the renderer draws: a chunk is one transient buffer
+ * and one write of at most 80 KiB of constants, whatever the frame's mesh count, so the write never
+ * grows with the scene and a chunk's buffer is the pool's ordinary business.
+ *
+ * @type {number}
+ */
+export const DYNAMIC_MESH_DRAWS_PER_CHUNK: number;
+/**
+ * One frame's draws of a set of {@link DynamicMesh}es: which geometry each draws, and its per-draw
+ * constants ({@link DYNAMIC_MESH_DRAW_STRUCT}), written in chunks of up to
+ * {@link DYNAMIC_MESH_DRAWS_PER_CHUNK}.
+ *
+ * **The constants are all written anew every frame**, into transient buffers of the frame's own: a
+ * dynamic mesh's transform and colour are as free to change as its vertices, so nothing is kept for
+ * a mesh from one frame to the next. What the table buys is that the frame pays per *chunk* for the
+ * buffer, the copy and the bind group, where it used to pay per mesh for each. Per draw, what is
+ * left is the geometry's bind group — the same one every frame, while its buffers keep their size —
+ * and the draw, which names its row of the chunk through its `first_instance`.
+ *
+ * Draws keep the order of the meshes they came from, across chunks: the pass over the scene blends,
+ * and composites in that order.
+ *
+ * {@link write} before a render pass is opened on the encoder — the constants go up through copies,
+ * which a command encoder refuses while a pass is open on it — and then {@link draw} into as many
+ * passes of the frame as draw these meshes. The AVBOIT splat and draw read one write.
+ */
+export class GPUDynamicMeshDrawList {
+    /**
+     * How many draws the last {@link write} laid out.
+     *
+     * @returns {number}
+     */
+    get count(): number;
+    /**
+     * Lay out a draw for every visible mesh of `meshes` with triangles resident in `residency`, and
+     * send their constants — as they are now — in one write per chunk. Replaces whatever the list
+     * held.
+     *
+     * The buffers are the encoder's transients, so the list is good for as long as that encoder is
+     * recording and no longer.
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {GPUDynamicMeshResidencyTable} residency brought up to date for `meshes` this frame
+     * @param {DynamicMesh[]} meshes
+     */
+    write(encoder: ShadeGPUCommandContext, residency: GPUDynamicMeshResidencyTable, meshes: DynamicMesh[]): void;
+    /**
+     * Let go of the frame: the geometries it drew and the transient buffers it wrote, which the
+     * encoder hands back when it finishes. For a list that outlives its frame, once its last pass is
+     * recorded.
+     */
+    clear(): void;
+    /**
+     * Record every draw into `render_pass`: the constants' group once per chunk, then per draw the
+     * geometry's group and the draw at its row. The pass's other groups are the caller's to set.
+     *
+     * @param {ShadeGPURenderPassEncoder} render_pass running `pipeline`
+     * @param {GraphicsContext} graphics
+     * @param {RenderPipelineDescriptor} pipeline one of the dynamic-mesh pipelines, whose layout opens
+     * with `DYNAMIC_MESH_RESOURCES`' groups
+     * @param {GPUBuffer} camera
+     */
+    draw(render_pass: ShadeGPURenderPassEncoder, graphics: GraphicsContext, pipeline: RenderPipelineDescriptor, camera: GPUBuffer): void;
+    #private;
+}
+//# sourceMappingURL=GPUDynamicMeshDrawList.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUDynamicMeshDrawList.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/dynamic/GPUDynamicMeshDrawList.js"],"names":[],"mappings":"AASA;;;;;;;;;GASG;AACH,2CAFU,MAAM,CAEiC;AAsEjD;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAgBI;;;;OAIG;IACH,oBAEC;IAED;;;;;;;;;;;OAWG;IACH,wFAFW,aAAa,QAoEvB;IAED;;;;OAIG;IACH,cAGC;IAED;;;;;;;;;OASG;IACH,qIAsBC;;CACJ"}

package/src/shade/renderer/dynamic/GPUDynamicMeshDrawList.js

@@ -0,0 +1,257 @@
+import { assert } from "../../../core/assert.js";
+import { ceilPowerOfTwo } from "../../../core/binary/operations/ceilPowerOfTwo.js";
+import { round_up } from "../../../core/math/round_up.js";
+import {
+    DYNAMIC_MESH_BIND_GROUP_DRAWS,
+    DYNAMIC_MESH_DRAW_STRUCT,
+    DYNAMIC_MESH_RESOURCES
+} from "./shader_dynamic_mesh.js";
+
+/**
+ * The most draws one chunk of a frame's constants holds — and so the most draws one bind of the
+ * constants' group serves.
+ *
+ * Bounded rather than one table for every mesh the renderer draws: a chunk is one transient buffer
+ * and one write of at most 80 KiB of constants, whatever the frame's mesh count, so the write never
+ * grows with the scene and a chunk's buffer is the pool's ordinary business.
+ *
+ * @type {number}
+ */
+export const DYNAMIC_MESH_DRAWS_PER_CHUNK = 1024;
+
+/**
+ * The fewest draws a chunk is sized for. See {@link chunk_capacity}.
+ *
+ * @type {number}
+ */
+const DRAWS_PER_CHUNK_MIN = 64;
+
+/**
+ * Bytes from one draw's constants to the next: the array stride of {@link DYNAMIC_MESH_DRAW_STRUCT}.
+ *
+ * @type {number}
+ */
+const DRAW_STRIDE = round_up(DYNAMIC_MESH_DRAW_STRUCT.size, DYNAMIC_MESH_DRAW_STRUCT.align);
+
+const DRAW_STRIDE_FLOATS = DRAW_STRIDE / 4;
+const MODEL_OFFSET_FLOATS = DYNAMIC_MESH_DRAW_STRUCT.get("model").offset / 4;
+const COLOR_OFFSET_FLOATS = DYNAMIC_MESH_DRAW_STRUCT.get("color").offset / 4;
+
+/**
+ * Where a frame's constants are laid out on the CPU before they are sent. Only ever used for the
+ * length of one {@link GPUDynamicMeshDrawList#write} — the write copies them out before it returns —
+ * so one serves every list.
+ *
+ * @type {Float32Array}
+ */
+let scratch = new Float32Array(DRAW_STRIDE_FLOATS * DRAWS_PER_CHUNK_MIN);
+
+/**
+ * The scratch is given back once it holds more than four times what a write needs and more than this
+ * many bytes: a burst of meshes should not pin its constants' worth of memory for the rest of the
+ * process, and a count that swings within an ordinary range should not reallocate every frame.
+ *
+ * @type {number}
+ */
+const SCRATCH_RETAINED_BYTES = 1024 * 1024;
+
+/**
+ * How many draws' worth of buffer a chunk of `count` draws takes, and writes: the next power of two,
+ * between {@link DRAWS_PER_CHUNK_MIN} and {@link DYNAMIC_MESH_DRAWS_PER_CHUNK}.
+ *
+ * Sized by class rather than to the count because the count is the part of a frame most certain to
+ * change. Buffers of the exact size are a new size whenever one effect appears, and the transient
+ * pool hands out a buffer only for a request close enough to its size — so a count climbing by a
+ * mesh a frame made a new transient buffer every frame. Five sizes cover every chunk; the
+ * price is writing up to twice the bytes of the draws, rows past the last draw holding whatever the
+ * scratch held, which no draw reads.
+ *
+ * @param {number} count draws in the chunk, 1 to {@link DYNAMIC_MESH_DRAWS_PER_CHUNK}
+ * @returns {number}
+ */
+function chunk_capacity(count) {
+    return Math.min(DYNAMIC_MESH_DRAWS_PER_CHUNK, Math.max(DRAWS_PER_CHUNK_MIN, ceilPowerOfTwo(count)));
+}
+
+/**
+ * Rows of scratch that a write of up to `mesh_count` draws can send, padding included.
+ *
+ * @param {number} mesh_count
+ * @returns {number}
+ */
+function scratch_rows(mesh_count) {
+    if (mesh_count <= DYNAMIC_MESH_DRAWS_PER_CHUNK) {
+        return chunk_capacity(mesh_count);
+    }
+
+    return round_up(mesh_count, DYNAMIC_MESH_DRAWS_PER_CHUNK);
+}
+
+/**
+ * One frame's draws of a set of {@link DynamicMesh}es: which geometry each draws, and its per-draw
+ * constants ({@link DYNAMIC_MESH_DRAW_STRUCT}), written in chunks of up to
+ * {@link DYNAMIC_MESH_DRAWS_PER_CHUNK}.
+ *
+ * **The constants are all written anew every frame**, into transient buffers of the frame's own: a
+ * dynamic mesh's transform and colour are as free to change as its vertices, so nothing is kept for
+ * a mesh from one frame to the next. What the table buys is that the frame pays per *chunk* for the
+ * buffer, the copy and the bind group, where it used to pay per mesh for each. Per draw, what is
+ * left is the geometry's bind group — the same one every frame, while its buffers keep their size —
+ * and the draw, which names its row of the chunk through its `first_instance`.
+ *
+ * Draws keep the order of the meshes they came from, across chunks: the pass over the scene blends,
+ * and composites in that order.
+ *
+ * {@link write} before a render pass is opened on the encoder — the constants go up through copies,
+ * which a command encoder refuses while a pass is open on it — and then {@link draw} into as many
+ * passes of the frame as draw these meshes. The AVBOIT splat and draw read one write.
+ */
+export class GPUDynamicMeshDrawList {
+    /**
+     * What each draw draws, in draw order.
+     *
+     * @type {GPUDynamicMeshResidency[]}
+     */
+    #residencies = [];
+
+    /**
+     * One transient storage buffer per chunk, {@link DYNAMIC_MESH_DRAWS_PER_CHUNK} draws apiece and
+     * the rest in the last, each sized by {@link chunk_capacity}.
+     *
+     * @type {GPUBuffer[]}
+     */
+    #chunks = [];
+
+    /**
+     * How many draws the last {@link write} laid out.
+     *
+     * @returns {number}
+     */
+    get count() {
+        return this.#residencies.length;
+    }
+
+    /**
+     * Lay out a draw for every visible mesh of `meshes` with triangles resident in `residency`, and
+     * send their constants — as they are now — in one write per chunk. Replaces whatever the list
+     * held.
+     *
+     * The buffers are the encoder's transients, so the list is good for as long as that encoder is
+     * recording and no longer.
+     *
+     * @param {ShadeGPUCommandContext} encoder
+     * @param {GPUDynamicMeshResidencyTable} residency brought up to date for `meshes` this frame
+     * @param {DynamicMesh[]} meshes
+     */
+    write(encoder, residency, meshes) {
+        assert.defined(encoder, 'encoder');
+        assert.defined(residency, 'residency');
+        assert.isArray(meshes, 'meshes');
+
+        const residencies = this.#residencies;
+        const chunks = this.#chunks;
+
+        residencies.length = 0;
+        chunks.length = 0;
+
+        const mesh_count = meshes.length;
+        const needed = scratch_rows(mesh_count) * DRAW_STRIDE_FLOATS;
+
+        if (scratch.length < needed || (scratch.length > needed * 4 && scratch.byteLength > SCRATCH_RETAINED_BYTES)) {
+            scratch = new Float32Array(needed);
+        }
+
+        const constants = scratch;
+
+        for (let i = 0; i < mesh_count; i++) {
+            const mesh = meshes[i];
+
+            if (!mesh.visible) {
+                continue;
+            }
+
+            const resident = residency.get(mesh.geometry);
+
+            if (resident === undefined || resident.index_count === 0) {
+                // never uploaded, or nothing to draw
+                continue;
+            }
+
+            const row = residencies.length * DRAW_STRIDE_FLOATS;
+
+            // the transform is its own matrix from element 0; `matrix` would hand out a fresh view
+            const transform = mesh.transform;
+            const model = row + MODEL_OFFSET_FLOATS;
+
+            for (let k = 0; k < 16; k++) {
+                constants[model + k] = transform[k];
+            }
+
+            const color = mesh.color;
+            const tint = row + COLOR_OFFSET_FLOATS;
+
+            constants[tint] = color[0];
+            constants[tint + 1] = color[1];
+            constants[tint + 2] = color[2];
+            constants[tint + 3] = color[3];
+
+            residencies.push(resident);
+        }
+
+        const draw_count = residencies.length;
+
+        for (let first = 0; first < draw_count; first += DYNAMIC_MESH_DRAWS_PER_CHUNK) {
+            const bytes = chunk_capacity(Math.min(DYNAMIC_MESH_DRAWS_PER_CHUNK, draw_count - first)) * DRAW_STRIDE;
+
+            const chunk = encoder.allocateTransientBuffer(GPUBufferUsage.STORAGE, bytes);
+
+            encoder.writeBuffer(chunk, 0, constants.buffer, constants.byteOffset + first * DRAW_STRIDE, bytes);
+
+            chunks.push(chunk);
+        }
+    }
+
+    /**
+     * Let go of the frame: the geometries it drew and the transient buffers it wrote, which the
+     * encoder hands back when it finishes. For a list that outlives its frame, once its last pass is
+     * recorded.
+     */
+    clear() {
+        this.#residencies.length = 0;
+        this.#chunks.length = 0;
+    }
+
+    /**
+     * Record every draw into `render_pass`: the constants' group once per chunk, then per draw the
+     * geometry's group and the draw at its row. The pass's other groups are the caller's to set.
+     *
+     * @param {ShadeGPURenderPassEncoder} render_pass running `pipeline`
+     * @param {GraphicsContext} graphics
+     * @param {RenderPipelineDescriptor} pipeline one of the dynamic-mesh pipelines, whose layout opens
+     * with `DYNAMIC_MESH_RESOURCES`' groups
+     * @param {GPUBuffer} camera
+     */
+    draw(render_pass, graphics, pipeline, camera) {
+        const residencies = this.#residencies;
+        const chunks = this.#chunks;
+
+        const draw_count = residencies.length;
+        const group = DYNAMIC_MESH_RESOURCES.groups[DYNAMIC_MESH_BIND_GROUP_DRAWS];
+
+        for (let c = 0; c < chunks.length; c++) {
+            graphics.setPipelineBindGroup(
+                render_pass,
+                pipeline,
+                DYNAMIC_MESH_BIND_GROUP_DRAWS,
+                group.generateBindings({ camera, draws: chunks[c] })
+            );
+
+            const first = c * DYNAMIC_MESH_DRAWS_PER_CHUNK;
+            const end = Math.min(first + DYNAMIC_MESH_DRAWS_PER_CHUNK, draw_count);
+
+            for (let i = first; i < end; i++) {
+                residencies[i].draw(render_pass, graphics, pipeline, i - first);
+            }
+        }
+    }
+}