@woosh/meep-engine 3.31.0 → 3.33.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";
 
 /**
  *
@@ -8,11 +9,140 @@ import { binarySearchHighIndex } from "../../../core/collection/array/binarySear
 let id_count = 0;
 
 /**
- * Provides staging buffers for pushing data from CPU to GPU.
+ * 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.
+ *
+ * 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`).
+ *
+ * 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}
      */
@@ -24,6 +154,60 @@ 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;
+
+    /**
+     * 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
@@ -35,17 +219,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;
     }
 
 
@@ -57,48 +237,45 @@ 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,
             });
-
         }
 
+        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"');
 
         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
@@ -109,42 +286,133 @@ 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);
 
+        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) {
-        const state = buffer.mapState;
+        if (!this.#held.delete(buffer)) {
+            return false;
+        }
 
-        // TODO have a cleanup mechanism to prevent memory leak
+        const state = buffer.mapState;
 
         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);
+
+        this.#returned_at.set(buffer, this.#frame);
+    }
+
+    /**
+     * 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();
+    }
+
+    /**
+     * 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;
+
         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;
+    }
+}