@woosh/meep-engine 3.23.0 → 3.24.0

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

@@ -45,5 +45,15 @@ export class GPUPageMetadata {
      * @type {number}
      */
     cpu_data_address: number;
+    /**
+     * Word views over {@link cpu_data_buffer}, for the generated record writers — see
+     * {@link GPUTypedTable.set_record}. Call `over(page.cpu_data_buffer)` before use; the views
+     * rebuild themselves if the shadow underneath has been replaced since, which is why nothing
+     * that assigns {@link cpu_data_buffer} has to know about them.
+     *
+     * @type {WordViews}
+     */
+    words: WordViews;
 }
+import { WordViews } from "./WordViews.js";
 //# sourceMappingURL=GPUPageMetadata.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"GPUPageMetadata.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUPageMetadata.js"],"names":[],"mappings":"AAAA;IACI;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;OAKG;IACH,aAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,iBAFU,WAAW,GAAC,SAAS,CAEf;IAEhB;;;;;OAKG;IACH,kBAFU,MAAM,CAEK;CACxB"}
+{"version":3,"file":"GPUPageMetadata.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUPageMetadata.js"],"names":[],"mappings":"AAEA;IACI;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;OAKG;IACH,aAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,aAFU,MAAM,CAEA;IAEhB;;;;OAIG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,iBAFU,WAAW,GAAC,SAAS,CAEf;IAEhB;;;;;OAKG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;;;;OAOG;IACH,OAFU,SAAS,CAEK;CAC3B;0BApEyB,gBAAgB"}

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

@@ -1,3 +1,5 @@
+import { WordViews } from "./WordViews.js";
+
 export class GPUPageMetadata {
     /**
      * Ordered index of the page in the table
@@ -54,4 +56,14 @@ export class GPUPageMetadata {
      * @type {number}
      */
     cpu_data_address = 0;
+
+    /**
+     * Word views over {@link cpu_data_buffer}, for the generated record writers — see
+     * {@link GPUTypedTable.set_record}. Call `over(page.cpu_data_buffer)` before use; the views
+     * rebuild themselves if the shadow underneath has been replaced since, which is why nothing
+     * that assigns {@link cpu_data_buffer} has to know about them.
+     *
+     * @type {WordViews}
+     */
+    words = new WordViews();
 }

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

@@ -0,0 +1,96 @@
+/**
+ * Persistent, mappable buffers for reading GPU data back — a ring, so that a batch may be in flight
+ * while the next one is recorded.
+ *
+ * The pattern is {@link GPUTimerArray}'s: buffers created once and kept, rather than a fresh
+ * `MAP_READ` buffer created, copied into, mapped and destroyed per read, which is what
+ * {@link inspect_via_copy} does and is the reason it is a debug affordance. Buffer creation is not
+ * free, and a per-call one also means the allocator sees a new lifetime on every read.
+ *
+ * Slots never shrink. A ring sized by the busiest frame of a session stays that size, which is a
+ * bounded cost measured in the largest batch, and the alternative is recreating buffers as the
+ * request count breathes.
+ *
+ * @see GPUDatabaseReadback
+ */
+export class GPUReadbackStagingRing {
+    /**
+     * @param {GPUDevice} device
+     * @param {Object} [options]
+     * @param {number} [options.frames_in_flight] slot count
+     * @param {string} [options.label]
+     */
+    constructor(device: GPUDevice, { frames_in_flight, label, }?: {
+        frames_in_flight?: number;
+        label?: string;
+    });
+    /**
+     * Number of slots, which is how many batches may be in flight at once.
+     *
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * Bytes currently held across every slot. Zero until the first batch, because a database that is
+     * never read back must not pay for the machinery that would read it.
+     *
+     * @returns {number}
+     */
+    get byte_size(): number;
+    /**
+     * Take a slot able to hold `byte_size`, growing its buffer if it is too small.
+     *
+     * @param {number} byte_size
+     * @returns {GPUReadbackStagingSlot|null} `null` when every slot is still in flight. That is not
+     * an error — it means readbacks are being requested faster than they are being read, and the
+     * caller's correct response is to leave the requests queued for the next frame rather than to
+     * overwrite bytes something is still reading
+     */
+    acquire(byte_size: number): GPUReadbackStagingSlot | null;
+    /**
+     * Give a slot back. Its buffer stays.
+     *
+     * @param {GPUReadbackStagingSlot} slot
+     */
+    release(slot: GPUReadbackStagingSlot): void;
+    destroy(): void;
+    #private;
+}
+/**
+ * One slot of a {@link GPUReadbackStagingRing}.
+ */
+declare class GPUReadbackStagingSlot {
+    /**
+     * `MAP_READ | COPY_DST`, which is the only pair WebGPU allows a mappable read buffer — so this
+     * is a copy destination and nothing else. A shader that wants to write gathered data writes a
+     * storage buffer, which is then copied here.
+     *
+     * @type {GPUBuffer|null}
+     */
+    buffer: GPUBuffer | null;
+    /**
+     * @type {number}
+     */
+    index: number;
+    /**
+     * Where a mapping of this slot is copied to, so that the GPU buffer can be unmapped at once and
+     * the bytes still be there at the apply point.
+     *
+     * Lives on the slot rather than on the batch: a slot holds one batch at a time, so this is one
+     * allocation per slot per high-water mark instead of one per frame. The owner sizes it.
+     *
+     * @type {Uint8Array|null}
+     */
+    cpu_bytes: Uint8Array | null;
+    /**
+     * Whether the slot has been handed out and not yet given back. The ring will not hand out a
+     * busy slot, which is the whole reason it has more than one: a batch is copied into one slot in
+     * the frame that encodes it and mapped a frame or more later, and reusing it in between would
+     * overwrite the bytes being read.
+     *
+     * @type {boolean}
+     */
+    busy: boolean;
+}
+export {};
+//# sourceMappingURL=GPUReadbackStagingRing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUReadbackStagingRing.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUReadbackStagingRing.js"],"names":[],"mappings":"AA2DA;;;;;;;;;;;;;;GAcG;AACH;IAyBI;;;;;OAKG;IACH;QAH4B,gBAAgB,GAAjC,MAAM;QACW,KAAK,GAAtB,MAAM;OAqBhB;IAED;;;;OAIG;IACH,mBAEC;IAED;;;;;OAKG;IACH,wBAYC;IAED;;;;;;;;OAQG;IACH,mBANW,MAAM,GACJ,sBAAsB,GAAC,IAAI,CA6BvC;IAED;;;;OAIG;IACH,cAFW,sBAAsB,QAOhC;IA0BD,gBAWC;;CACJ;AA3ND;;GAEG;AACH;IACI;;;;;;OAMG;IACH,QAFU,YAAU,IAAI,CAEV;IAEd;;OAEG;IACH,OAFU,MAAM,CAEL;IAEX;;;;;;;;OAQG;IACH,WAFU,UAAU,GAAC,IAAI,CAER;IAEjB;;;;;;;OAOG;IACH,MAFU,OAAO,CAEJ;CAChB"}

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

@@ -0,0 +1,15 @@
+/**
+ * What a readback handle says about its request, read off {@link GPUDatabaseReadbackstatus }.
+ *
+ * A status is readable for one frame: from the apply point that set it to the next, after which
+ * the handle is recycled and reads as {@link None }. That is the frame in which the consumer's own
+ * system runs, which is when it wanted the value anyway.
+ */
+export type GPUReadbackStatus = number;
+export namespace GPUReadbackStatus {
+    let None: number;
+    let Pending: number;
+    let Delivered: number;
+    let Dropped: number;
+}
+//# sourceMappingURL=GPUReadbackStatus.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUReadbackStatus.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUReadbackStatus.js"],"names":[],"mappings":";;;;;;;gCAOU,MAAM"}

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

@@ -0,0 +1,34 @@
+/**
+ * What a readback handle says about its request, read off {@link GPUDatabaseReadback#status}.
+ *
+ * A status is readable for one frame: from the apply point that set it to the next, after which
+ * the handle is recycled and reads as {@link None}. That is the frame in which the consumer's own
+ * system runs, which is when it wanted the value anyway.
+ *
+ * @enum {number}
+ */
+export const GPUReadbackStatus = {
+    /**
+     * Not in use — never requested, or recycled because the frame in which its result could be read
+     * has passed.
+     */
+    None: 0,
+
+    /**
+     * Asked and not yet answered.
+     */
+    Pending: 1,
+
+    /**
+     * The bytes are in the target.
+     */
+    Delivered: 2,
+
+    /**
+     * Answered with nothing: the row's page was not resident when the batch was encoded, the row was
+     * freed while the batch was in flight, the mapping was refused, or the pipeline was full — see
+     * {@link GPUDatabaseReadback#dropped_count} and {@link GPUDatabaseReadback#stalled_count} for
+     * which.
+     */
+    Dropped: 3,
+};

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

@@ -77,6 +77,15 @@ export class GPUTypedTable<T> {
      * @returns {number} element index
      */
     add(value: T): number;
+    /**
+     * {@link add} through a generated writer — {@link set_record} is to {@link set} what this is to
+     * {@link add}.
+     *
+     * @param {T} value
+     * @param {GPURecordWriter} writer generated against this table's type
+     * @returns {number} element index
+     */
+    add_record(value: T, writer: GPURecordWriter): number;
     /**
      * Remove an element from the table, freeing its slot.
      * The slot will be zero-filled in the CPU shadow and an upload will be queued.
@@ -84,6 +93,20 @@ export class GPUTypedTable<T> {
      * @param {number} element_index
      */
     remove(element_index: number): void;
+    /**
+     * Start counting how many times each row is freed. Idempotent. Called by whoever reads rows
+     * back and needs to know whether the row it asked about is still the row that answered — see
+     * {@link generation_of}.
+     */
+    track_generations(): void;
+    /**
+     * How many times a row has been freed since {@link track_generations}. Zero for a table that
+     * is not tracking, and for a row never freed since.
+     *
+     * @param {number} row
+     * @returns {number}
+     */
+    generation_of(row: number): number;
     /**
      * Reset every slot to free in one shot. Cheaper than calling
      * {@link remove} per element when the caller knows it's about to
@@ -115,6 +138,27 @@ export class GPUTypedTable<T> {
      * @param {T} value
      */
     set(element_index: number, value: T): void;
+    /**
+     * Write a whole record through a writer generated for its type, instead of walking the type
+     * on every call.
+     *
+     * Same contract as {@link set} in every other respect — the row is created if the table has
+     * never held it, the CPU shadow is patched, and the record joins the whole-record upload
+     * stream — and the bytes it leaves behind are the same ones. What changes is the cost: the
+     * field offsets are constants inside {@link GPURecordWriter.write_record} rather than
+     * something rediscovered per field per row, and the shadow and the queued record are written
+     * through views rather than a `BinaryBuffer` cursor.
+     *
+     * A writer naming only some of the type's fields is legal here and means what it says: the
+     * rest of the record keeps whatever the shadow held, and so does the queued record. That is
+     * rarely what a caller wants from *this* method, though — a partial writer belongs in
+     * {@link set_fields}, which uploads only the bytes it wrote.
+     *
+     * @param {number} element_index
+     * @param {T} value
+     * @param {GPURecordWriter} writer generated against this table's type
+     */
+    set_record(element_index: number, value: T, writer: GPURecordWriter): void;
     /**
      * Overwrite one field (or sub-struct) of an existing record, leaving the rest of it untouched
      * — on the CPU shadow and on the GPU alike.
@@ -156,11 +200,8 @@ export class GPUTypedTable<T> {
      * the GPU is free to retire threads in any order. In append order:
      *
      * - **partial after whole-record** — the pending whole record is patched in place and nothing
-     *   is appended, so the row is not in both streams at once. This is the one case bounded by
-     *   {@link UPLOAD_BUFFER_DEDUP_LOOKBACK}, since it borrows {@link set}'s backwards scan. A
-     *   whole record further back than the window is missed and the range is queued beside it —
-     *   still correct, because {@link GPUDatabase.update} dispatches a table's whole records
-     *   before its ranges, so the range lands on top of the record exactly as append order said.
+     *   is appended, so the row is not in both streams at once. The record is found through
+     *   {@link #pending_records}, so it is found however long ago it was queued.
      * - **whole-record after partial** — {@link set} retires the row's pending descriptors (blanks
      *   their word count, making those threads no-ops); the whole record supersedes them.
      * - **partial after partial, the same range or a sub-range of a pending one** — the pending
@@ -171,8 +212,8 @@ export class GPUTypedTable<T> {
      *   are retired and one covering their union is appended, its words read back out of the CPU
      *   shadow, which is already correct by then.
      *
-     * Every case but the first is exact rather than windowed: a row's pending descriptors are
-     * indexed by id, so they are found however long the stream has grown.
+     * Every one of those is exact rather than windowed: both streams index a row's pending
+     * entries by id, so they are found however long either stream has grown.
      *
      * @param {number} element_index row to patch; must already be occupied
      * @param {number} byte_offset offset of the range within the record, 4-byte aligned
@@ -181,6 +222,32 @@ export class GPUTypedTable<T> {
      * @param {number} [byte_length] length of the range, a whole number of u32 words
      */
     set_bytes(element_index: number, byte_offset: number, source: ArrayBuffer | ArrayBufferView, source_offset?: number, byte_length?: number): void;
+    /**
+     * Patch the fields a generated writer owns, on the CPU shadow and on the GPU, and leave the
+     * rest of the record alone — {@link set_bytes} for a struct whose owned fields are known at
+     * generation time rather than named per call.
+     *
+     * The point is the bookkeeping, not the stores. `set_bytes` has to treat every range as an
+     * event of its own: a page lookup, a record view, a pending-record check, a chain walk, a
+     * descriptor append. A caller patching a struct's two CPU-owned blocks through it pays all of
+     * that twice, which measured at roughly double one range's cost rather than the few extra
+     * words the second range actually is. A writer knows both ranges belong to one row's update
+     * before the call starts, so this pays for the row once: the fields reach the shadow and the
+     * stream's data blob in a single pass over the value, and the descriptors go out together.
+     *
+     * The ordering rules across the two streams are {@link set_bytes}'s and are followed exactly
+     * — a row's update lands on a pending whole record if there is one, and joins ranges already
+     * queued for the row through the same merge, one range at a time, because what to do with an
+     * overlap is a property of what is pending and not of the writer.
+     *
+     * The row must already be occupied, for the reason a partial write always must: it patches a
+     * record, it does not create one.
+     *
+     * @param {number} element_index
+     * @param {T} value
+     * @param {GPURecordWriter} writer generated against this table's type
+     */
+    set_fields(element_index: number, value: T, writer: GPURecordWriter): void;
     /**
      * Drop the partial upload stream, its per-row index included. Called by
      * {@link GPUDatabase.update} once the stream has been dispatched.
@@ -255,6 +322,7 @@ export class GPUTypedTable<T> {
 export type GPUTypedTableDescriptor = import("./GPUTypedTableDescriptor.js").GPUTypedTableDescriptor;
 export type PageBufferPool = import("./PageBufferPool.js").PageBufferPool;
 export type WebGPUType = import("../../shader/type/WebGPUType.js").WebGPUType;
+export type GPURecordWriter = import("./serde/generate_record_writer.js").GPURecordWriter;
 import { GPUPageMetadata } from "./GPUPageMetadata.js";
 import { BinaryBuffer } from "../../../../core/binary/BinaryBuffer.js";
 import { BitSet } from "../../../../core/binary/BitSet.js";

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

@@ -1 +1 @@
-{"version":3,"file":"GPUTypedTable.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUTypedTable.js"],"names":[],"mappings":"AAoFA;;;GAGG;AACH;IAkGI;;;OAGG;IACH,wBAFW,uBAAuB,EASjC;IA3GD;;OAEG;IACH,YAFU,uBAAuB,CAEtB;IAEX;;;;OAIG;IACH,OAFU,IAAI,MAAM,EAAC,eAAe,CAAC,CAEnB;IAElB;;;;OAIG;IACH,uBAFU,YAAY,CAE6D;IAEnF;;;;;;;;;;;OAWG;IACH,4BAFU,YAAY,CAE6B;IAEnD;;;;;OAKG;IACH,qBAFU,YAAY,CAEsB;IA2B5C;;;;;OAKG;IACH,iBAFU,MAAM,CAEe;IAE/B;;;;OAIG;IACH,WAFU,MAAM,CAES;IAEzB;;;;;;OAMG;IACH,oBAFU,MAAM,CAEkB;IAElC;;;OAGG;IACH,kBAFU,cAAc,GAAC,SAAS,CAEjB;IAejB;;;;;OAKG;IACH,WAHW,CAAC,GACC,MAAM,CAQlB;IAED;;;;;OAKG;IACH,sBAFW,MAAM,QAkChB;IAED;;;;;;;;;;OAUG;IACH,cAcC;IAwED;;;;;;OAMG;IACH,mBAJW,MAAM,GACJ,CAAC,GAAC,SAAS,CA4BvB;IAgDD;;;OAGG;IACH,cAsBC;IA+BD;;;;OAIG;IACH,mBAHW,MAAM,SACN,CAAC,QAuFX;IAED;;;;;;;;;;;;;OAaG;IACH,yBALW,MAAM,eACN,MAAM,oBAEN,UAAU,QAqBpB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACH,yBANW,MAAM,eACN,MAAM,UACN,WAAW,GAAC,eAAe,kBAC3B,MAAM,gBACN,MAAM,QAoEhB;IAiJD;;;OAGG;IACH,8BAMC;IAED;;;OAGG;IACH,2BAYC;IAED;;OAEG;IACH,oBAEC;IAED;;;;;;;;;;OAUG;IACH,+BAEC;IAED;;;;;;;;;;OAUG;IACH,mCAJW,WAAW,UACX,MAAM,GACL,MAAM,CAoBjB;IAED;;;;;;;;;;;;OAYG;IACH,kCAMC;IAED;;;;;;;;;;;;;;OAcG;IACH,mCAHW,MAAM,GACL,MAAM,CAKjB;IAED,mBAEC;;CACJ;sCA79BY,OAAO,8BAA8B,EAAE,uBAAuB;6BAC9D,OAAO,qBAAqB,EAAE,cAAc;yBAC5C,OAAO,iCAAiC,EAAE,UAAU;gCALjC,sBAAsB;6BATzB,yCAAyC;uBAC/C,mCAAmC"}
+{"version":3,"file":"GPUTypedTable.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUTypedTable.js"],"names":[],"mappings":"AAwEA;;;GAGG;AACH;IAyKI;;;OAGG;IACH,wBAFW,uBAAuB,EASjC;IAlLD;;OAEG;IACH,YAFU,uBAAuB,CAEtB;IAEX;;;;OAIG;IACH,OAFU,IAAI,MAAM,EAAC,eAAe,CAAC,CAEnB;IAElB;;;;OAIG;IACH,uBAFU,YAAY,CAE6D;IAEnF;;;;;;;;;;;OAWG;IACH,4BAFU,YAAY,CAE6B;IAEnD;;;;;OAKG;IACH,qBAFU,YAAY,CAEsB;IAiF5C;;;;;OAKG;IACH,iBAFU,MAAM,CAEe;IAE/B;;;;OAIG;IACH,WAFU,MAAM,CAES;IAmBzB;;;;;;OAMG;IACH,oBAFU,MAAM,CAEkB;IAElC;;;OAGG;IACH,kBAFU,cAAc,GAAC,SAAS,CAEjB;IAejB;;;;;OAKG;IACH,WAHW,CAAC,GACC,MAAM,CAQlB;IAED;;;;;;;OAOG;IACH,kBAJW,CAAC,UACD,eAAe,GACb,MAAM,CAQlB;IAED;;;;;OAKG;IACH,sBAFW,MAAM,QAsChB;IAED;;;;OAIG;IACH,0BAIC;IAED;;;;;;OAMG;IACH,mBAHW,MAAM,GACJ,MAAM,CAUlB;IAsBD;;;;;;;;;;OAUG;IACH,cAuBC;IAmGD;;;;;;OAMG;IACH,mBAJW,MAAM,GACJ,CAAC,GAAC,SAAS,CA4BvB;IAgDD;;;OAGG;IACH,cAsBC;IA+BD;;;;OAIG;IACH,mBAHW,MAAM,SACN,CAAC,QAyEX;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,0BAJW,MAAM,SACN,CAAC,UACD,eAAe,QA4DzB;IAED;;;;;;;;;;;;;OAaG;IACH,yBALW,MAAM,eACN,MAAM,oBAEN,UAAU,QAqBpB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8CG;IACH,yBANW,MAAM,eACN,MAAM,UACN,WAAW,GAAC,eAAe,kBAC3B,MAAM,gBACN,MAAM,QA+DhB;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,0BAJW,MAAM,SACN,CAAC,UACD,eAAe,QA6GzB;IA0KD;;;OAGG;IACH,8BASC;IAED;;;OAGG;IACH,2BAYC;IAED;;OAEG;IACH,oBAEC;IAED;;;;;;;;;;OAUG;IACH,+BAEC;IAED;;;;;;;;;;OAUG;IACH,mCAJW,WAAW,UACX,MAAM,GACL,MAAM,CAoBjB;IAED;;;;;;;;;;;;OAYG;IACH,kCAMC;IAED;;;;;;;;;;;;;;OAcG;IACH,mCAHW,MAAM,GACL,MAAM,CAKjB;IAED,mBAEC;;CACJ;sCAp1CY,OAAO,8BAA8B,EAAE,uBAAuB;6BAC9D,OAAO,qBAAqB,EAAE,cAAc;yBAC5C,OAAO,iCAAiC,EAAE,UAAU;8BACpD,OAAO,mCAAmC,EAAE,eAAe;gCAPxC,sBAAsB;6BAhBzB,yCAAyC;uBAC/C,mCAAmC"}