@woosh/meep-engine 3.23.0 → 3.24.0

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

@@ -0,0 +1,74 @@
+/**
+ * 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 {
+    /**
+     * @param {GPUDevice} device
+     * @param {Object} [options]
+     * @param {number} [options.budget_bytes] free bytes kept before the largest free buffers are destroyed
+     */
+    constructor(device: GPUDevice, { budget_bytes }?: {
+        budget_bytes?: number;
+    });
+    /**
+     * Bytes in every buffer this pool has made and not destroyed, held or free.
+     * @returns {number}
+     */
+    get gpu_memory_usage(): number;
+    /**
+     * Bytes sitting in the free list.
+     * @returns {number}
+     */
+    get ready_byte_size(): number;
+    /**
+     * Bytes in buffers currently handed out.
+     * @returns {number}
+     */
+    get held_byte_size(): number;
+    /**
+     * Free buffers.
+     * @returns {number}
+     */
+    get ready_count(): number;
+    /**
+     * 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: number): GPUBuffer;
+    /**
+     * 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: GPUBuffer): void;
+    /**
+     * 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: GPUBuffer): void;
+    destroy(): void;
+    #private;
+}
+//# sourceMappingURL=GPUBufferReadbackAllocator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUBufferReadbackAllocator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/buffer/GPUBufferReadbackAllocator.js"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IA4BI;;;;OAIG;IACH;QAF4B,YAAY,GAA7B,MAAM;OAQhB;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;OAGG;IACH,0BAEC;IAED;;;;;;OAMG;IACH,oBAHW,MAAM,aAkChB;IAED;;;;;OAKG;IACH,iCAsBC;IAED;;;;;OAKG;IACH,iCAMC;IAkBD,gBAUC;;CACJ"}

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

@@ -0,0 +1,240 @@
+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;
+    }
+}

package/src/shade/renderer/buffer/table/GPUDatabase.d.ts

@@ -49,6 +49,19 @@ export class GPUDatabase {
      * @returns {GPUTypedTable|undefined}
      */
     get(name: string): GPUTypedTable<any> | undefined;
+    /**
+     * Batched readback of rows, or ranges of rows, into CPU memory.
+     *
+     * Built on first mention. {@link update} drives it: results are applied at the head of an
+     * update and this frame's requests are encoded at its tail, so a caller gets its answers at one
+     * stated moment rather than whenever a mapping settles.
+     *
+     * The single-element {@link debug_table_read_element} is unaffected and stays what it is — a
+     * debug affordance that creates and destroys a buffer per call.
+     *
+     * @returns {GPUDatabaseReadback}
+     */
+    get readback(): GPUDatabaseReadback;
     /**
      * Byte offset where the data region starts (after the allocation table).
      * In {@link GPU_DATABASE_BUFFER_ELEMENT_TYPE} units.
@@ -115,4 +128,5 @@ export class GPUDatabase {
 export type ShadeGPUCommandContext = import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext;
 export type GPUDatabaseDefinition = import("./GPUDatabaseDefinition.js").GPUDatabaseDefinition;
 import { GPUTypedTable } from "./GPUTypedTable.js";
+import { GPUDatabaseReadback } from "./GPUDatabaseReadback.js";
 //# sourceMappingURL=GPUDatabase.d.ts.map

package/src/shade/renderer/buffer/table/GPUDatabase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUDatabase.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUDatabase.js"],"names":[],"mappings":"AA0CA;;;;;;;;;GASG;AACH;IA0EI;;;;;;OAMG;IACH;QAL0C,UAAU,EAAzC,qBAAqB;QACF,MAAM;QACR,KAAK,GAAtB,MAAM;QACW,uBAAuB,GAAxC,MAAM;OAuEhB;IApJD;;;OAGG;IACH,YAFU,qBAAqB,CAEpB;IAEX;;;;OAIG;IACH,QAFU,oBAAe,CAElB;IASP;;;OAGG;IACH,kBAAO;IAyCP;;OAEG;IACH,8BAEC;IAgFD;;;;;OAKG;IACH,UAHW,MAAM,GACJ,qBAAc,SAAS,CAUnC;IAGD;;;;;OAKG;IACH,gCAEC;IAoPD;;;OAGG;IACH,gBAFW,sBAAsB,QA+EhC;IA+OD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,2BAJW,MAAM,GACJ,QAAQ,KAAG,CAAC,CA6HxB;IAED;;;;;;;OAOG;IACH,+BAJW,MAAM,iBACN,MAAM,GACJ,YAAU,CAkCtB;IAED;;;OAGG;IACH,+BAQC;IAED;;OAEG;IACH,gBAIC;;CACJ;qCA99BY,OAAO,2CAA2C,EAAE,sBAAsB;oCAC1E,OAAO,4BAA4B,EAAE,qBAAqB;8BANzC,oBAAoB"}
+{"version":3,"file":"GPUDatabase.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUDatabase.js"],"names":[],"mappings":"AA2CA;;;;;;;;;GASG;AACH;IAoFI;;;;;;OAMG;IACH;QAL0C,UAAU,EAAzC,qBAAqB;QACF,MAAM;QACR,KAAK,GAAtB,MAAM;QACW,uBAAuB,GAAxC,MAAM;OAuEhB;IA9JD;;;OAGG;IACH,YAFU,qBAAqB,CAEpB;IAEX;;;;OAIG;IACH,QAFU,oBAAe,CAElB;IASP;;;OAGG;IACH,kBAAO;IAmDP;;OAEG;IACH,8BAEC;IAgFD;;;;;OAKG;IACH,UAHW,MAAM,GACJ,qBAAc,SAAS,CAUnC;IAGD;;;;;;;;;;;OAWG;IACH,oCAcC;IAED;;;;;OAKG;IACH,gCAEC;IAoPD;;;OAGG;IACH,gBAFW,sBAAsB,QA6FhC;IA+OD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,2BAJW,MAAM,GACJ,QAAQ,KAAG,CAAC,CA6HxB;IAED;;;;;;;OAOG;IACH,+BAJW,MAAM,iBACN,MAAM,GACJ,YAAU,CAkCtB;IAED;;;OAGG;IACH,+BAQC;IAED;;OAEG;IACH,gBASC;;CACJ;qCAvhCY,OAAO,2CAA2C,EAAE,sBAAsB;oCAC1E,OAAO,4BAA4B,EAAE,qBAAqB;8BANzC,oBAAoB;oCALd,0BAA0B"}

package/src/shade/renderer/buffer/table/GPUDatabase.js

@@ -10,6 +10,7 @@ import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { inspect_gpu_buffer } from "../inspect_gpu_buffer.js";
 import { inspect_gpu_buffer_typed } from "../inspect_gpu_buffer_typed.js";
 import { GPU_DATABASE_BUFFER_ELEMENT_TYPE } from "./GPU_DATABASE_BUFFER_ELEMENT_TYPE.js";
+import { GPUDatabaseReadback } from "./GPUDatabaseReadback.js";
 import { gpu_table_element_upload_shader } from "./gpu_table_element_upload_shader.js";
 import { gpu_table_partial_upload_shader } from "./gpu_table_partial_upload_shader.js";
 import { GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS } from "./GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS.js";
@@ -117,6 +118,16 @@ export class GPUDatabase {
      */
     #page_buffer_pool;
 
+    /**
+     * Batched row readback, built on first use.
+     *
+     * Lazy because it owns persistent mappable buffers, and most databases are written and never
+     * read: a database nobody asks about must not pay for the ring that would answer.
+     *
+     * @type {GPUDatabaseReadback|null}
+     */
+    #readback = null;
+
     /**
      * @return {number}
      */
@@ -219,6 +230,34 @@ export class GPUDatabase {
     }
 
 
+    /**
+     * Batched readback of rows, or ranges of rows, into CPU memory.
+     *
+     * Built on first mention. {@link update} drives it: results are applied at the head of an
+     * update and this frame's requests are encoded at its tail, so a caller gets its answers at one
+     * stated moment rather than whenever a mapping settles.
+     *
+     * The single-element {@link debug_table_read_element} is unaffected and stays what it is — a
+     * debug affordance that creates and destroys a buffer per call.
+     *
+     * @returns {GPUDatabaseReadback}
+     */
+    get readback() {
+        let readback = this.#readback;
+
+        if (readback === null) {
+            readback = new GPUDatabaseReadback({
+                database: this,
+                device: this.#device,
+                label: `${this.#label}/readback`,
+            });
+
+            this.#readback = readback;
+        }
+
+        return readback;
+    }
+
     /**
      * Byte offset where the data region starts (after the allocation table).
      * In {@link GPU_DATABASE_BUFFER_ELEMENT_TYPE} units.
@@ -479,6 +518,14 @@ export class GPUDatabase {
         const tables = this.tables;
         const table_count = tables.length;
 
+        // The readback's apply point, and the reason it is here: this is the one moment in a frame
+        // where the database is being brought up to date and nothing is midway through reading it.
+        // A result that landed on its own promise's timing would change a value underneath whatever
+        // was running when the mapping happened to settle.
+        if (this.#readback !== null) {
+            this.#readback.apply();
+        }
+
         // Allocate new pages and deallocate empty ones
         for (let i = 0; i < table_count; i++) {
             const table = tables[i];
@@ -524,12 +571,12 @@ export class GPUDatabase {
         for (let i = 0; i < table_count; i++) {
             const table = tables[i];
 
-            // Whole records first, sub-record ranges second. In one update cycle a row normally
-            // has a pending write in one stream or the other, never both — `GPUTypedTable` patches
-            // or retires across the two as writes come in. The one case it reconciles through a
-            // bounded scan rather than an index is a range landing on a whole record queued long
-            // before it, and that case leaves both entries live. This order is what settles it,
-            // and it settles it the way append order already did: the range lands on top.
+            // Whole records first, sub-record ranges second. In one update cycle a row has a
+            // pending write in one stream or the other, never both — `GPUTypedTable` patches or
+            // retires across the two as writes come in, and both streams index a row's pending
+            // entries rather than scanning back for them, so neither reconciliation can miss one.
+            // The order is what append order already said anyway: a range queued after a record
+            // lands on top of it.
             this.#upload_element_records(table, encoder);
             this.#upload_partial_ranges(table, encoder);
 
@@ -552,6 +599,12 @@ export class GPUDatabase {
                 page.gpu_version = page.cpu_version;
             }
         }
+
+        // Last, so a row written this frame reads back as what it now holds rather than as what it
+        // held before. A frame with no requests records nothing here at all.
+        if (this.#readback !== null) {
+            this.#readback.encode(encoder);
+        }
     }
 
     /**
@@ -1005,6 +1058,11 @@ export class GPUDatabase {
      * Release GPU resources
      */
     destroy() {
+        if (this.#readback !== null) {
+            this.#readback.destroy();
+            this.#readback = null;
+        }
+
         this.buffer.destroy();
         this.#page_buffer_pool.clear();
         this.#device = null;

package/src/shade/renderer/buffer/table/GPUDatabaseReadback.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Reading rows back from a {@link GPUDatabase} in batches: one gather, one copy, one map, and one
+ * point in the frame where the answers land — in memory the caller already owns.
+ *
+ * **Why this is not `debug_table_read_element`.** That resolves one row's byte offset and calls
+ * {@link inspect_gpu_buffer_typed}, which creates a `MAP_READ` buffer, copies, submits, maps and
+ * destroys it — per call. It is a debug affordance and stays one. Here the buffers persist, the
+ * requests of a frame travel together, and the result arrives at a stated moment rather than
+ * whenever a promise happens to settle.
+ *
+ * **The caller names memory, and nothing is called.** A request is a table handle, a row, a byte
+ * range of the record, and a `Uint8Array` plus offset to put it in. At the apply point the service
+ * copies the bytes there and marks the request's handle in {@link status}; the consumer reads the
+ * status when its own system next runs, which is when it wanted the value anyway. There is no
+ * callback and no promise, for the same reason: a function called per row is a closure allocated
+ * per row and a permanently megamorphic call site, and code running inside the apply point could
+ * re-enter this service, or destroy the database, from the middle of `GPUDatabase.update`. The
+ * shader packs a batch contiguously in request order, so a consumer's run of rows lands in its
+ * destination as one `set` — which a per-row function could never have done.
+ *
+ * **Gather, then one copy.** Rows sit at scattered offsets across pages, so a compute shader packs
+ * the requested ranges contiguously before a single copy into a readback buffer. Packing a *range*
+ * rather than a record is what makes it worth doing: an entity's world matrix is 64 bytes of a
+ * 176-byte row.
+ *
+ * **But the request list is itself an upload.** A gather needs its descriptors on the GPU, so every
+ * frame with any request writes a buffer, allocates, binds and dispatches. For one row that costs
+ * far more than the value retrieved. Below {@link DEFAULT_GATHER_THRESHOLD} — a measured number, see
+ * its docblock — the batch degrades to direct `copyBufferToBuffer` calls into the same readback
+ * buffer, with no shader at all. A frame with no requests skips the whole path: no buffer, no
+ * command.
+ *
+ * **One apply point, in encode order.** Results are delivered from {@link apply}, at the head of a
+ * frame, and never on the timing of the map's own promise. A component that changed value in the
+ * middle of an update because a readback happened to settle would be a different world for the
+ * systems that ran before it and the ones that ran after. And a batch is delivered only after every
+ * older batch has been: `mapAsync` promises are not promised to settle in the order the maps were
+ * started, and a consumer asking for the same row every frame must never see a fresh value
+ * overwritten by a stale one.
+ *
+ * **Nothing here may reach simulation state.** A readback is a frame or more late and settles on the
+ * GPU's own schedule, so an outcome that depended on one would depend on frame pacing, and the
+ * determinism gate with it. This answers tools, sounds and cosmetics. Where the simulation wants a
+ * GPU-owned pose it evaluates the chain exactly, on the CPU.
+ *
+ * @see GPUStateAuthority which says whose value is worth reading back in the first place
+ * @see GPUReadbackStatus
+ */
+export class GPUDatabaseReadback {
+    /**
+     * @param {Object} options
+     * @param {import("./GPUDatabase.js").GPUDatabase} options.database
+     * @param {GPUDevice} options.device
+     * @param {number} [options.gather_threshold] requests at or above which a dispatch is used
+     * @param {number} [options.max_in_flight] batches in flight before a frame's requests are dropped
+     * @param {string} [options.label]
+     */
+    constructor({ database, device, gather_threshold, max_in_flight, label, }: {
+        database: import("./GPUDatabase.js").GPUDatabase;
+        device: GPUDevice;
+        gather_threshold?: number;
+        max_in_flight?: number;
+        label?: string;
+    });
+    /**
+     * Requests at or above which a batch is gathered rather than copied range by range.
+     * @returns {number}
+     */
+    get gather_threshold(): number;
+    /**
+     * Batches in flight before a frame's requests are refused.
+     * @returns {number}
+     */
+    get max_in_flight(): number;
+    /**
+     * Per handle, what became of the request — a {@link GPUReadbackStatus}.
+     *
+     * Read it fresh each time rather than keeping a reference: the array is replaced when the
+     * handle space grows. A status is readable for one frame, from the apply point that set it to
+     * the next.
+     *
+     * @returns {Uint8Array}
+     */
+    get status(): Uint8Array;
+    /**
+     * How many handles exist. Grows to the working set of a steady stream of requests and stops:
+     * handles are recycled a frame after their result lands.
+     *
+     * @returns {number}
+     */
+    get handle_capacity(): number;
+    /**
+     * Requests made and not yet encoded.
+     * @returns {number}
+     */
+    get pending_count(): number;
+    /**
+     * Batches encoded and not yet delivered or discarded.
+     * @returns {number}
+     */
+    get in_flight_count(): number;
+    /**
+     * How many `copyBufferToBuffer` calls this service has encoded, over its life. Read by profiles,
+     * and by the specs that assert an empty frame encodes nothing.
+     *
+     * @returns {number}
+     */
+    get copies_encoded(): number;
+    /**
+     * How many gather dispatches this service has encoded, over its life.
+     * @returns {number}
+     */
+    get dispatches_encoded(): number;
+    /**
+     * Requests whose bytes reached their target.
+     * @returns {number}
+     */
+    get delivered_count(): number;
+    /**
+     * Requests thrown away because of the row — its page was not resident when the batch was
+     * encoded, it was not occupied, or it was freed before the answer landed.
+     *
+     * Reported rather than swallowed: a consumer whose readbacks are all being dropped is asking
+     * about rows that keep dying, and silence reads downstream as "the value did not change".
+     *
+     * @returns {number}
+     */
+    get dropped_count(): number;
+    /**
+     * Requests thrown away because of the pipeline — {@link max_in_flight} batches were still
+     * waiting on the device when the frame's batch was due, or a mapping was refused. Separate
+     * from {@link dropped_count} because the cure is different: those rows died, these the device
+     * stopped answering about.
+     *
+     * @returns {number}
+     */
+    get stalled_count(): number;
+    /**
+     * Resolve a table name to the handle {@link request} takes. Once, at setup: a string lookup
+     * per row per frame is what this exists to avoid.
+     *
+     * From here on the table counts how many times each of its rows is freed, which is what lets
+     * an answer about a row that died and was reused be told from an answer about the row asked
+     * for.
+     *
+     * @param {string} name
+     * @returns {number}
+     */
+    table(name: string): number;
+    /**
+     * Ask for a byte range of a row to be copied into `target`, at a later apply point.
+     *
+     * Positional, and a few integer stores: this is called once per row per frame by anything that
+     * tracks rows, so it takes no options object and allocates nothing.
+     *
+     * @param {number} table from {@link table}
+     * @param {number} row
+     * @param {number} byte_offset within the record, word-aligned
+     * @param {number} byte_size a positive multiple of the word size
+     * @param {Uint8Array} target memory the caller owns and keeps; the bytes are written here at
+     *        the apply point. A byte view on purpose — a consumer that reads floats holds a
+     *        `Float32Array` over the same buffer, made once
+     * @param {number} [target_byte_offset]
+     * @returns {number} a handle into {@link status}, valid until the frame after its result lands
+     */
+    request(table: number, row: number, byte_offset: number, byte_size: number, target: Uint8Array, target_byte_offset?: number): number;
+    /**
+     * Deliver every batch whose bytes have arrived, oldest first and stopping at the first that has
+     * not, then start the map for every batch whose frame has been submitted.
+     *
+     * **This is the apply point.** Call it at the head of a frame, before any system runs. A batch
+     * therefore reaches its targets at the first frame head at which its mapping — and every older
+     * batch's — has resolved, which is the frame after the one that encoded it at the earliest:
+     * never inside an update, and never at two different moments for two requests of the same
+     * batch. No caller-supplied code runs here.
+     *
+     * @returns {number} requests delivered
+     */
+    apply(): number;
+    /**
+     * Record this frame's batch: a gather and one copy, or a handful of copies, or nothing at all.
+     *
+     * @param {import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} encoder
+     * @returns {boolean} whether anything was encoded
+     */
+    encode(encoder: import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext): boolean;
+    destroy(): void;
+    #private;
+}
+//# sourceMappingURL=GPUDatabaseReadback.d.ts.map

package/src/shade/renderer/buffer/table/GPUDatabaseReadback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUDatabaseReadback.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUDatabaseReadback.js"],"names":[],"mappings":"AA6LA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH;IA+II;;;;;;;OAOG;IACH;QAN2D,QAAQ,EAAxD,OAAO,kBAAkB,EAAE,WAAW;QACnB,MAAM;QACR,gBAAgB,GAAjC,MAAM;QACW,aAAa,GAA9B,MAAM;QACW,KAAK,GAAtB,MAAM;OAuBhB;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;;;;;OAQG;IACH,yBAEC;IAED;;;;;OAKG;IACH,8BAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;;;;OAKG;IACH,6BAEC;IAED;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,8BAEC;IAED;;;;;;;;OAQG;IACH,4BAEC;IAED;;;;;;;OAOG;IACH,4BAEC;IAED;;;;;;;;;;OAUG;IACH,YAHW,MAAM,GACJ,MAAM,CAclB;IAED;;;;;;;;;;;;;;;OAeG;IACH,eAVW,MAAM,OACN,MAAM,eACN,MAAM,aACN,MAAM,UACN,UAAU,uBAGV,MAAM,GACJ,MAAM,CAgDlB;IAED;;;;;;;;;;;OAWG;IACH,SAFa,MAAM,CAwDlB;IAED;;;;;OAKG;IACH,gBAHW,OAAO,2CAA2C,EAAE,sBAAsB,GACxE,OAAO,CAyDnB;IAijBD,gBAyBC;;CACJ"}