@woosh/meep-engine 3.32.0 → 3.33.0

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

@@ -1,240 +1,241 @@
-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";
-
-/**
- * Sizes are rounded up to this when a buffer is created, so that batches whose byte count breathes
- * by a few rows keep landing in the same buffer instead of each size making a new one.
- *
- * @type {number}
- */
-const SIZE_GRANULARITY = 256;
-
-/**
- * How many bytes of *free* readback buffers are kept. Buffers handed out are the holder's to bound;
- * this bounds what an idle pool pins after a spike — one 50k-row batch is ~3 MB, and without a cap
- * it would stay for the life of the process, which is what the ring this replaced did.
- *
- * @type {number}
- */
-const DEFAULT_BUDGET_BYTES = 16 * MEGABYTE;
-
-/**
- * @type {number}
- */
-let id_count = 0;
-
-/**
- * @param {{size: number}} a
- * @param {{size: number}} b
- * @returns {number}
- */
-function by_size(a, b) {
-    return a.size - b.size;
-}
-
-/**
- * Persistent `MAP_READ | COPY_DST` buffers for reading GPU data back — {@link GPUBufferStagingAllocator}
- * run the other way.
- *
- * The same shape on purpose: a size-sorted free list, `get(min_size)` serving the smallest buffer
- * that fits and creating one when none does, `release(buffer)` putting it back. Where the staging
- * pool re-maps a buffer on release because the next writer needs it mapped, this one *unmaps*,
- * because the next copy into it needs it unmapped; the mapping is the holder's, taken after the
- * copy has landed and read at the holder's own apply point.
- *
- * Why not `buffer_allocator_main`: `TransientResourcePool`'s reuse safety rests on transients being
- * GPU-only, and a readback buffer is held by the CPU across frames.
- *
- * Why not a ring: a ring hands out `null` when its slots are busy and leaves the caller to defer a
- * whole frame's work, and growing a slot destroys a perfectly good smaller buffer. A free list makes
- * another buffer and keeps both sizes.
- *
- * @see GPUDatabaseReadback the holder
- */
-export class GPUBufferReadbackAllocator {
-    /**
-     * @type {GPUDevice}
-     */
-    #device;
-
-    /**
-     * Free buffers, ascending by size.
-     * @type {GPUBuffer[]}
-     */
-    #ready = [];
-
-    /**
-     * @type {number}
-     */
-    #ready_byte_size = 0;
-
-    /**
-     * Bytes in buffers handed out and not yet given back.
-     * @type {number}
-     */
-    #held_byte_size = 0;
-
-    /**
-     * @type {number}
-     */
-    #budget_bytes;
-
-    /**
-     * @param {GPUDevice} device
-     * @param {Object} [options]
-     * @param {number} [options.budget_bytes] free bytes kept before the largest free buffers are destroyed
-     */
-    constructor(device, { budget_bytes = DEFAULT_BUDGET_BYTES } = {}) {
-        assert.defined(device, 'device');
-        assert.isNonNegativeInteger(budget_bytes, 'budget_bytes');
-
-        this.#device = device;
-        this.#budget_bytes = budget_bytes;
-    }
-
-    /**
-     * Bytes in every buffer this pool has made and not destroyed, held or free.
-     * @returns {number}
-     */
-    get gpu_memory_usage() {
-        return this.#ready_byte_size + this.#held_byte_size;
-    }
-
-    /**
-     * Bytes sitting in the free list.
-     * @returns {number}
-     */
-    get ready_byte_size() {
-        return this.#ready_byte_size;
-    }
-
-    /**
-     * Bytes in buffers currently handed out.
-     * @returns {number}
-     */
-    get held_byte_size() {
-        return this.#held_byte_size;
-    }
-
-    /**
-     * Free buffers.
-     * @returns {number}
-     */
-    get ready_count() {
-        return this.#ready.length;
-    }
-
-    /**
-     * The smallest free buffer of at least `min_size_bytes`, or a new one. **Unmapped**, ready to be
-     * the destination of a copy. Contents are whatever the last use left.
-     *
-     * @param {number} min_size_bytes
-     * @returns {GPUBuffer}
-     */
-    get(min_size_bytes) {
-        assert.isNonNegativeInteger(min_size_bytes, 'min_size_bytes');
-        assert.greaterThan(min_size_bytes, 0, 'min_size_bytes');
-
-        const ready = this.#ready;
-        const index = binarySearchHighIndex(ready, { size: min_size_bytes }, by_size);
-
-        let result;
-
-        if (index < ready.length) {
-            result = ready[index];
-
-            ready.splice(index, 1);
-
-            this.#ready_byte_size -= result.size;
-        } else {
-            result = this.#device.createBuffer({
-                label: `readback ${id_count++}`,
-                size: round_up(min_size_bytes, SIZE_GRANULARITY),
-                // the only usage pair WebGPU permits alongside MAP_READ
-                usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
-                mappedAtCreation: false,
-            });
-        }
-
-        assert.greaterThanOrEqual(result.size, min_size_bytes, 'result.size < min_size_bytes');
-        assert.equal(result.mapState, "unmapped", 'result.mapState !== "unmapped"');
-
-        this.#held_byte_size += result.size;
-
-        return result;
-    }
-
-    /**
-     * Give a buffer back. A mapped buffer is unmapped here; a buffer whose mapping is still pending
-     * cannot be given back — let the mapping settle, or {@link discard} it.
-     *
-     * @param {GPUBuffer} buffer
-     */
-    release(buffer) {
-        assert.defined(buffer, 'buffer');
-        assert.equal(buffer.usage, GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST, 'buffer.usage !== GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST');
-
-        const state = buffer.mapState;
-
-        if (state === "mapped") {
-            buffer.unmap();
-        } else if (state !== "unmapped") {
-            throw new Error(`Invalid map state: ${state}`);
-        }
-
-        this.#held_byte_size -= buffer.size;
-
-        const ready = this.#ready;
-        const index = binarySearchHighIndex(ready, buffer, by_size);
-
-        ready.splice(index, 0, buffer);
-
-        this.#ready_byte_size += buffer.size;
-
-        this.#trim();
-    }
-
-    /**
-     * Destroy a buffer that was handed out, instead of giving it back — for a holder being torn down
-     * while a mapping is still pending, which WebGPU lets `destroy()` abort but not `unmap()`.
-     *
-     * @param {GPUBuffer} buffer
-     */
-    discard(buffer) {
-        assert.defined(buffer, 'buffer');
-
-        this.#held_byte_size -= buffer.size;
-
-        buffer.destroy();
-    }
-
-    /**
-     * Keep the free list under budget, dropping the largest buffers first: they cost the most, and a
-     * spike is the least likely size to be asked for again.
-     */
-    #trim() {
-        const ready = this.#ready;
-
-        while (this.#ready_byte_size > this.#budget_bytes && ready.length > 0) {
-            const largest = ready.pop();
-
-            this.#ready_byte_size -= largest.size;
-
-            largest.destroy();
-        }
-    }
-
-    destroy() {
-        const ready = this.#ready;
-
-        for (let i = 0; i < ready.length; i++) {
-            ready[i].destroy();
-        }
-
-        ready.length = 0;
-
-        this.#ready_byte_size = 0;
-    }
-}
+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";
+
+/**
+ * Sizes are rounded up to this when a buffer is created, so that batches whose byte count breathes
+ * by a few rows keep landing in the same buffer instead of each size making a new one.
+ *
+ * @type {number}
+ */
+const SIZE_GRANULARITY = 256;
+
+/**
+ * How many bytes of *free* readback buffers are kept. Buffers handed out are the holder's to bound;
+ * this bounds what an idle pool pins after a spike — one 50k-row batch is ~3 MB, and without a cap
+ * it would stay for the life of the process, which is what the ring this replaced did.
+ *
+ * @type {number}
+ */
+const DEFAULT_BUDGET_BYTES = 16 * MEGABYTE;
+
+/**
+ * @type {number}
+ */
+let id_count = 0;
+
+/**
+ * @param {{size: number}} a
+ * @param {{size: number}} b
+ * @returns {number}
+ */
+function by_size(a, b) {
+    return a.size - b.size;
+}
+
+/**
+ * Persistent `MAP_READ | COPY_DST` buffers for reading GPU data back — {@link GPUBufferStagingAllocator}
+ * run the other way.
+ *
+ * The same shape: a size-sorted free list, `get(min_size)` serving the smallest buffer that fits
+ * and creating one when none does, `release(buffer)` putting it back. Where the staging pool re-maps
+ * a buffer on release because the next writer needs it mapped, this one *unmaps*, because the next
+ * copy into it needs it unmapped; the mapping is the holder's, taken after the copy has landed and
+ * read at the holder's own apply point. Unlike the staging pool, this one has no bound on how much
+ * larger than the request a buffer it serves may be, no size classes and no reclaim.
+ *
+ * Why not `buffer_allocator_main`: `TransientResourcePool`'s reuse safety rests on transients being
+ * GPU-only, and a readback buffer is held by the CPU across frames.
+ *
+ * Why not a ring: a ring hands out `null` when its slots are busy and leaves the caller to defer a
+ * whole frame's work, and growing a slot destroys a perfectly good smaller buffer. A free list makes
+ * another buffer and keeps both sizes.
+ *
+ * @see GPUDatabaseReadback the holder
+ */
+export class GPUBufferReadbackAllocator {
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+
+    /**
+     * Free buffers, ascending by size.
+     * @type {GPUBuffer[]}
+     */
+    #ready = [];
+
+    /**
+     * @type {number}
+     */
+    #ready_byte_size = 0;
+
+    /**
+     * Bytes in buffers handed out and not yet given back.
+     * @type {number}
+     */
+    #held_byte_size = 0;
+
+    /**
+     * @type {number}
+     */
+    #budget_bytes;
+
+    /**
+     * @param {GPUDevice} device
+     * @param {Object} [options]
+     * @param {number} [options.budget_bytes] free bytes kept before the largest free buffers are destroyed
+     */
+    constructor(device, { budget_bytes = DEFAULT_BUDGET_BYTES } = {}) {
+        assert.defined(device, 'device');
+        assert.isNonNegativeInteger(budget_bytes, 'budget_bytes');
+
+        this.#device = device;
+        this.#budget_bytes = budget_bytes;
+    }
+
+    /**
+     * Bytes in every buffer this pool has made and not destroyed, held or free.
+     * @returns {number}
+     */
+    get gpu_memory_usage() {
+        return this.#ready_byte_size + this.#held_byte_size;
+    }
+
+    /**
+     * Bytes sitting in the free list.
+     * @returns {number}
+     */
+    get ready_byte_size() {
+        return this.#ready_byte_size;
+    }
+
+    /**
+     * Bytes in buffers currently handed out.
+     * @returns {number}
+     */
+    get held_byte_size() {
+        return this.#held_byte_size;
+    }
+
+    /**
+     * Free buffers.
+     * @returns {number}
+     */
+    get ready_count() {
+        return this.#ready.length;
+    }
+
+    /**
+     * The smallest free buffer of at least `min_size_bytes`, or a new one. **Unmapped**, ready to be
+     * the destination of a copy. Contents are whatever the last use left.
+     *
+     * @param {number} min_size_bytes
+     * @returns {GPUBuffer}
+     */
+    get(min_size_bytes) {
+        assert.isNonNegativeInteger(min_size_bytes, 'min_size_bytes');
+        assert.greaterThan(min_size_bytes, 0, 'min_size_bytes');
+
+        const ready = this.#ready;
+        const index = binarySearchHighIndex(ready, { size: min_size_bytes }, by_size);
+
+        let result;
+
+        if (index < ready.length) {
+            result = ready[index];
+
+            ready.splice(index, 1);
+
+            this.#ready_byte_size -= result.size;
+        } else {
+            result = this.#device.createBuffer({
+                label: `readback ${id_count++}`,
+                size: round_up(min_size_bytes, SIZE_GRANULARITY),
+                // the only usage pair WebGPU permits alongside MAP_READ
+                usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+                mappedAtCreation: false,
+            });
+        }
+
+        assert.greaterThanOrEqual(result.size, min_size_bytes, 'result.size < min_size_bytes');
+        assert.equal(result.mapState, "unmapped", 'result.mapState !== "unmapped"');
+
+        this.#held_byte_size += result.size;
+
+        return result;
+    }
+
+    /**
+     * Give a buffer back. A mapped buffer is unmapped here; a buffer whose mapping is still pending
+     * cannot be given back — let the mapping settle, or {@link discard} it.
+     *
+     * @param {GPUBuffer} buffer
+     */
+    release(buffer) {
+        assert.defined(buffer, 'buffer');
+        assert.equal(buffer.usage, GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST, 'buffer.usage !== GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST');
+
+        const state = buffer.mapState;
+
+        if (state === "mapped") {
+            buffer.unmap();
+        } else if (state !== "unmapped") {
+            throw new Error(`Invalid map state: ${state}`);
+        }
+
+        this.#held_byte_size -= buffer.size;
+
+        const ready = this.#ready;
+        const index = binarySearchHighIndex(ready, buffer, by_size);
+
+        ready.splice(index, 0, buffer);
+
+        this.#ready_byte_size += buffer.size;
+
+        this.#trim();
+    }
+
+    /**
+     * Destroy a buffer that was handed out, instead of giving it back — for a holder being torn down
+     * while a mapping is still pending, which WebGPU lets `destroy()` abort but not `unmap()`.
+     *
+     * @param {GPUBuffer} buffer
+     */
+    discard(buffer) {
+        assert.defined(buffer, 'buffer');
+
+        this.#held_byte_size -= buffer.size;
+
+        buffer.destroy();
+    }
+
+    /**
+     * Keep the free list under budget, dropping the largest buffers first: they cost the most, and a
+     * spike is the least likely size to be asked for again.
+     */
+    #trim() {
+        const ready = this.#ready;
+
+        while (this.#ready_byte_size > this.#budget_bytes && ready.length > 0) {
+            const largest = ready.pop();
+
+            this.#ready_byte_size -= largest.size;
+
+            largest.destroy();
+        }
+    }
+
+    destroy() {
+        const ready = this.#ready;
+
+        for (let i = 0; i < ready.length; i++) {
+            ready[i].destroy();
+        }
+
+        ready.length = 0;
+
+        this.#ready_byte_size = 0;
+    }
+}

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

@@ -6,6 +6,13 @@
  * 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 {
     /**
@@ -13,6 +20,38 @@ export class GPUBufferStagingAllocator {
      * @param {GPUDevice} device
      */
     constructor(device: GPUDevice);
+    /**
+     * 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: number;
+    /**
+     * 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: number;
+    /**
+     * An idle buffer is destroyed after this many frames even with the pool under its budget.
+     *
+     * @type {number}
+     */
+    param_backstop_frames: number;
+    /**
+     * Most buffers destroyed by one {@link update}.
+     *
+     * @type {number}
+     */
+    param_max_reclaim_per_frame: number;
+    /**
+     * Most idle buffers one {@link update} looks at.
+     *
+     * @type {number}
+     */
+    param_scan_budget: number;
     /**
      * Bytes in every buffer this pool has made and not destroyed: free, handed out, or on the way
      * back.
@@ -33,6 +72,18 @@ export class GPUBufferStagingAllocator {
      * this pool did not hand out
      */
     release(buffer: GPUBuffer): boolean;
+    /**
+     * Advance the pool's frame clock; once a frame, with the other pools'.
+     */
+    increment_time(): void;
+    /**
+     * 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(): void;
     destroy(): void;
     #private;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"GPUBufferStagingAllocator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/GPUBufferStagingAllocator.js"],"names":[],"mappings":"AASA;;;;;;;;GAQG;AACH;IA8CI;;;OAGG;IACH,+BAIC;IAED;;;;;OAKG;IACH,+BAEC;IAGD;;;;OAIG;IACH,oBAHW,MAAM,aAsChB;IAkCD;;;;;OAKG;IACH,4BAHa,OAAO,CA0BnB;IAgCD,gBAUC;;CACJ"}
+{"version":3,"file":"GPUBufferStagingAllocator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/GPUBufferStagingAllocator.js"],"names":[],"mappings":"AAwFA;;;;;;;;;;;;;;;GAeG;AACH;IA0GI;;;OAGG;IACH,+BAIC;IA9GD;;;;;OAKG;IACH,wBAFU,MAAM,CAEuB;IAEvC;;;;;OAKG;IACH,+BAFU,MAAM,CAEmB;IAEnC;;;;OAIG;IACH,uBAFU,MAAM,CAEY;IAE5B;;;;OAIG;IACH,6BAFU,MAAM,CAEgB;IAEhC;;;;OAIG;IACH,mBAFU,MAAM,CAEO;IA6EvB;;;;;OAKG;IACH,+BAEC;IAGD;;;;OAIG;IACH,oBAHW,MAAM,aA2ChB;IAsBD;;;;;OAKG;IACH,4BAHa,OAAO,CAwBnB;IAkCD;;OAEG;IACH,uBAEC;IAED;;;;;;OAMG;IACH,eA+BC;IAED,gBAUC;;CACJ"}