@woosh/meep-engine 3.32.0 → 3.34.0

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

@@ -1,5 +1,6 @@
 import { assert } from "../../../core/assert.js";
-import { binarySearchHighIndex } from "../../../core/collection/array/binarySearchHighIndex.js";
+import { round_up } from "../../../core/math/round_up.js";
+import { MEGABYTE } from "../../../core/science/units/memory/MEGABYTE.js";
 
 /**
  *
@@ -7,6 +8,84 @@ import { binarySearchHighIndex } from "../../../core/collection/array/binarySear
  */
 let id_count = 0;
 
+/**
+ * A pooled buffer is handed out only for a request it is at most this many times the size of.
+ *
+ * A buffer is mapped whole each time it comes back, and a mapping is paid for by the size of the
+ * buffer, not by what was written into it. With no bound, eight idle 16 MiB buffers left by a burst
+ * took the 80 KiB and 40 KiB draw-constant writes of a 1,500-DynamicMesh frame from then on: 32 MiB
+ * mapped a render for 120 KiB written, and 178–202 renders/s against 244–256 with no burst. The same
+ * 128 MiB mapped and idle outside the pool ran 246–259, so the cost was the handing out, not the
+ * memory (RTX 4090, Chrome 154, paired in one page, 2026-09-27).
+ *
+ * @type {number}
+ */
+const REUSE_LIMIT_SCALE = 2;
+
+/**
+ * Sizes a new staging buffer can be made at within each doubling, evenly spaced: with 4, a buffer
+ * made for a request of more than 16 bytes is never more than a quarter larger than it.
+ *
+ * @type {number}
+ */
+const SIZE_CLASSES_PER_DOUBLING = 4;
+
+/**
+ * The size a new staging buffer for `bytes` is made at: the next of the
+ * {@link SIZE_CLASSES_PER_DOUBLING} sizes in the doubling `bytes` falls in.
+ *
+ * Made at the exact size, a write that grew a little every frame asked for a size no pooled buffer
+ * had, every frame, and got a new buffer every frame. Now one buffer serves it until it grows past a
+ * class.
+ *
+ * @param {number} bytes
+ * @returns {number} a multiple of 4, as a buffer mapped at creation must be
+ */
+function size_class(bytes) {
+    if (bytes <= 16) {
+        return round_up(bytes, 4);
+    }
+
+    // the largest power of two not above `bytes`
+    let doubling = 16;
+
+    while (doubling * 2 <= bytes) {
+        doubling *= 2;
+    }
+
+    return round_up(bytes, doubling / SIZE_CLASSES_PER_DOUBLING);
+}
+
+/**
+ * Where the first buffer of at least `size` bytes is, or would go, in `buffers` sorted by size.
+ *
+ * Both ends of the pool use it: a request takes the buffer there, the smallest that holds it, and a
+ * buffer given back goes in there, ahead of its equals — so of buffers of one size, the one given
+ * back last goes out first. A search that landed anywhere among equals moved a steady writer to
+ * another buffer whenever their count changed, and every buffer it had touched was kept for a
+ * backstop more: a burst of 40 left 3 alive past the backstop where the writer needed 1.
+ *
+ * @param {GPUBuffer[]} buffers
+ * @param {number} size
+ * @returns {number}
+ */
+function first_at_least(buffers, size) {
+    let low = 0;
+    let high = buffers.length;
+
+    while (low < high) {
+        const middle = (low + high) >>> 1;
+
+        if (buffers[middle].size < size) {
+            low = middle + 1;
+        } else {
+            high = middle;
+        }
+    }
+
+    return low;
+}
+
 /**
  * Mapped `MAP_WRITE | COPY_SRC` buffers for pushing data from the CPU to the GPU, one per upload.
  *
@@ -15,9 +94,55 @@ let id_count = 0;
  * 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`).
+ *
+ * A buffer is made up to a quarter larger than asked, so a size that drifts keeps its buffer, and is
+ * handed out again only to requests at least half its size ({@link REUSE_LIMIT_SCALE}), so a burst's
+ * large buffers do not end up mapped whole for every smaller write after it. Of buffers of one size
+ * the one given back last goes out first, so a steady writer keeps one and the rest go idle. What
+ * sits idle is destroyed by {@link update}, as {@link TransientResourcePool#update} does for the
+ * frame's transients: without that, a burst's buffers stayed until the device went.
  */
 export class GPUBufferStagingAllocator {
 
+    // ----- reclaim tuning, as TransientResourcePool's -----
+
+    /**
+     * Idle bytes above which buffers idle for {@link param_over_budget_idle_frames} are destroyed.
+     * The same as the upload blocks' budget.
+     *
+     * @type {number}
+     */
+    param_soft_byte_budget = 16 * MEGABYTE;
+
+    /**
+     * Frames a buffer may sit idle while the pool is over its budget: long enough that a write made
+     * every few frames keeps its buffer, short enough that a burst's go within a second or so.
+     *
+     * @type {number}
+     */
+    param_over_budget_idle_frames = 60;
+
+    /**
+     * An idle buffer is destroyed after this many frames even with the pool under its budget.
+     *
+     * @type {number}
+     */
+    param_backstop_frames = 600;
+
+    /**
+     * Most buffers destroyed by one {@link update}.
+     *
+     * @type {number}
+     */
+    param_max_reclaim_per_frame = 8;
+
+    /**
+     * Most idle buffers one {@link update} looks at.
+     *
+     * @type {number}
+     */
+    param_scan_budget = 16;
+
     /**
      * @type {GPUDevice}
      */
@@ -62,6 +187,27 @@ export class GPUBufferStagingAllocator {
      */
     #destroyed = false;
 
+    /**
+     * Frames counted by {@link increment_time}.
+     *
+     * @type {number}
+     */
+    #frame = 0;
+
+    /**
+     * The frame each buffer in {@link #ready} came back in: how long it has been idle.
+     *
+     * @type {WeakMap<GPUBuffer, number>}
+     */
+    #returned_at = new WeakMap();
+
+    /**
+     * Where in {@link #ready} the next {@link update} starts looking.
+     *
+     * @type {number}
+     */
+    #cursor = 0;
+
     /**
      *
      * @param {GPUDevice} device
@@ -91,29 +237,34 @@ export class GPUBufferStagingAllocator {
     get(min_size_bytes) {
         assert.isNonNegativeInteger(min_size_bytes, 'min_size_bytes');
 
-        const index = this.#get_position(min_size_bytes);
-
         const buffers = this.#ready;
 
+        // the smallest ready buffer that holds the request, unless even that one is too large for it
+        const index = first_at_least(buffers, min_size_bytes);
+
         let result;
-        if (index !== -1) {
+
+        if (index < buffers.length && buffers[index].size <= min_size_bytes * REUSE_LIMIT_SCALE) {
             result = buffers.splice(index, 1)[0];
-        }
 
-        if (result === undefined) {
+            this.#ready_byte_size -= result.size;
+        } else {
+            const device = this.#device;
+
+            // Never rounded past the device's limit for a request that is within it, which would
+            // refuse a write the exact size takes; and a whole number of words below the limit, which
+            // the spec does not require to be one, as a buffer mapped at creation must be.
+            const limit = device.limits.maxBufferSize;
+            const largest = limit - limit % 4;
 
-            // TODO align buffer size?
             const id = id_count++;
 
-            result = this.#device.createBuffer({
+            result = device.createBuffer({
                 label: `staging ${id}`,
-                size: min_size_bytes,
+                size: Math.max(min_size_bytes, Math.min(size_class(min_size_bytes), largest)),
                 usage: GPUBufferUsage.COPY_SRC | GPUBufferUsage.MAP_WRITE,
                 mappedAtCreation: true,
             });
-
-        } else {
-            this.#ready_byte_size -= result.size;
         }
 
         this.#held_byte_size += result.size;
@@ -125,19 +276,6 @@ export class GPUBufferStagingAllocator {
         return result;
     }
 
-    /**
-     *
-     * @param {number} size
-     * @return {number}
-     */
-    #get_position(size) {
-        function by_size(a, b) {
-            return a.size - b.size;
-        }
-
-        return binarySearchHighIndex(this.#ready, { size }, by_size);
-    }
-
     /**
      *
      * @param {GPUBuffer} buffer
@@ -148,7 +286,8 @@ export class GPUBufferStagingAllocator {
         assert.equal(buffer.mapState, "mapped", 'buffer.mapState !== "mapped"');
         assert.equal(buffer.usage, GPUBufferUsage.COPY_SRC | GPUBufferUsage.MAP_WRITE, 'buffer.usage !== GPUBufferUsage.COPY_SRC | GPUBufferUsage.MAP_WRITE');
 
-        const index = this.#get_position(buffer.size);
+        // ahead of its equals: the next request for this size takes it
+        const index = first_at_least(this.#ready, buffer.size);
 
         this.#ready.splice(index, 0, buffer);
 
@@ -170,8 +309,6 @@ export class GPUBufferStagingAllocator {
 
         const state = buffer.mapState;
 
-        // TODO the ready list never shrinks: a burst's buffers stay until destroy()
-
         if (state === "mapped") {
             // release directly
             this.#take_back(buffer);
@@ -203,6 +340,8 @@ export class GPUBufferStagingAllocator {
         }
 
         this.#add_to_ready(buffer);
+
+        this.#returned_at.set(buffer, this.#frame);
     }
 
     /**
@@ -218,6 +357,53 @@ export class GPUBufferStagingAllocator {
         buffer.destroy();
     }
 
+    /**
+     * Advance the pool's frame clock; once a frame, with the other pools'.
+     */
+    increment_time() {
+        this.#frame++;
+    }
+
+    /**
+     * Once-a-frame housekeeping: destroy the buffers nothing has asked for in a while — idle past
+     * {@link param_backstop_frames}, or, while more than {@link param_soft_byte_budget} bytes sit
+     * idle, past {@link param_over_budget_idle_frames}. A bounded sweep from where the last one
+     * stopped, at most {@link param_scan_budget} buffers looked at and
+     * {@link param_max_reclaim_per_frame} destroyed, as {@link TransientResourcePool#update}.
+     */
+    update() {
+        const ready = this.#ready;
+
+        let count = ready.length;
+
+        let over_budget = this.#ready_byte_size - this.param_soft_byte_budget;
+        let reclaim_budget = this.param_max_reclaim_per_frame;
+
+        const sweep = Math.min(count, this.param_scan_budget);
+
+        for (let i = 0; i < sweep && count > 0 && reclaim_budget > 0; i++) {
+            const cursor = this.#cursor % count;
+            const buffer = ready[cursor];
+
+            const idle = this.#frame - this.#returned_at.get(buffer);
+
+            if (idle > this.param_backstop_frames || (over_budget > 0 && idle > this.param_over_budget_idle_frames)) {
+                ready.splice(cursor, 1);
+                count--;
+
+                this.#ready_byte_size -= buffer.size;
+                over_budget -= buffer.size;
+                reclaim_budget--;
+
+                buffer.destroy();
+
+                // the slot now holds the next buffer; the cursor stays where it is
+            } else {
+                this.#cursor = cursor + 1;
+            }
+        }
+    }
+
     destroy() {
         this.#destroyed = true;
 

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"}