@woosh/meep-engine 3.22.0 → 3.23.0

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

@@ -5,12 +5,15 @@ import { platform_compute_endianness } from "../../../../core/binary/platform_co
 import { read_wgsl_type_value } from "../../shader/type/serde/read_gpu_typed_buffer.js";
 import { write_wgsl_type_value } from "../../shader/type/serde/write_gpu_typed_buffer.js";
 import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { GPU_DATABASE_BUFFER_ELEMENT_TYPE } from "./GPU_DATABASE_BUFFER_ELEMENT_TYPE.js";
 import { GPU_DATABASE_UPLOAD_BUFFER_LIMIT } from "./GPU_DATABASE_UPLOAD_BUFFER_LIMIT.js";
+import { GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS } from "./GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS.js";
 import { GPUPageMetadata } from "./GPUPageMetadata.js";
 
 /**
  * @typedef {import("./GPUTypedTableDescriptor.js").GPUTypedTableDescriptor} GPUTypedTableDescriptor
  * @typedef {import("./PageBufferPool.js").PageBufferPool} PageBufferPool
+ * @typedef {import("../../shader/type/WebGPUType.js").WebGPUType} WebGPUType
  */
 
 const SCRATCH_BUFFER = new BinaryBuffer();
@@ -20,6 +23,37 @@ const SCRATCH_BUFFER = new BinaryBuffer();
 // (e.g. the upload buffer, where the value section follows the u32 element id).
 const READ_STAGE_BUFFER = BinaryBuffer.fromEndianness(platform_compute_endianness());
 
+// Stages one field / sub-struct for `set_range`, at position 0 so `write_wgsl_type_value`'s
+// top-level alignment round-up is a no-op.
+const WRITE_STAGE_BUFFER = BinaryBuffer.fromEndianness(platform_compute_endianness());
+
+/**
+ * Byte stride of one entry in {@link GPUTypedTable.partial_upload_descriptors}.
+ * @type {number}
+ */
+const PARTIAL_DESCRIPTOR_BYTES = GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS * GPU_DATABASE_BUFFER_ELEMENT_TYPE.size;
+
+/**
+ * Index of the `word_count` word within one partial-upload descriptor — the one word retiring a
+ * descriptor has to reach.
+ * @type {number}
+ */
+const PARTIAL_DESCRIPTOR_WORD_COUNT = 2;
+
+/**
+ * A staging buffer that holds nothing until something is written to it. `BinaryBuffer` allocates a
+ * kilobyte up front, and a table that never takes a partial write must not pay for two of those.
+ *
+ * @returns {BinaryBuffer}
+ */
+function empty_upload_buffer() {
+    const buffer = BinaryBuffer.fromEndianness(platform_compute_endianness());
+
+    buffer.setCapacity(0);
+
+    return buffer;
+}
+
 /**
  * How far {@link GPUTypedTable.set} walks back through
  * {@link GPUTypedTable.element_upload_buffer} looking for an existing
@@ -38,6 +72,12 @@ const READ_STAGE_BUFFER = BinaryBuffer.fromEndianness(platform_compute_endiannes
  * happen in practice; if it ever does, swap this linear scan for a tiny
  * bloom filter or a sparse `id → record_offset` map.
  *
+ * The partial-write stream took the map route from the start — see
+ * {@link GPUTypedTable#set_bytes} — not because its hazard is worse but
+ * because a row can own several ranges at once and every write has to
+ * find all of them, so a scan deep enough to be safe would have cost
+ * more than the feature saves.
+ *
  * @type {number}
  */
 const UPLOAD_BUFFER_DEDUP_LOOKBACK = 256;
@@ -67,6 +107,53 @@ export class GPUTypedTable {
      */
     element_upload_buffer = BinaryBuffer.fromEndianness(platform_compute_endianness());
 
+    /**
+     * Sub-record ranges waiting to be uploaded, as fixed-stride descriptors:
+     * `[u32 element_index, u32 word_offset, u32 word_count, u32 data_offset]`, where `word_offset`
+     * is relative to the start of the record and `data_offset` indexes {@link partial_upload_data}.
+     *
+     * Separate from {@link element_upload_buffer} because ranges are variable length, and the
+     * whole-record shader can only index its buffer by thread id while every record is the same
+     * size. See {@link set_bytes} for how the two streams stay out of each other's way.
+     *
+     * Consumed and rewound by {@link GPUDatabase.update}.
+     * @type {BinaryBuffer}
+     */
+    partial_upload_descriptors = empty_upload_buffer();
+
+    /**
+     * The words {@link partial_upload_descriptors} point at, appended in descriptor order — so a
+     * run of descriptors always owns a contiguous slice of this blob, which is what lets the
+     * upload be chunked.
+     * @type {BinaryBuffer}
+     */
+    partial_upload_data = empty_upload_buffer();
+
+    /**
+     * Index of the most recent pending descriptor for a row — the head of that row's chain
+     * through {@link #partial_descriptor_previous}.
+     *
+     * {@link set}'s dedupe can afford a backwards scan because it only ever looks for one record;
+     * a row here can own several descriptors at once, and every write has to find all of them. A
+     * scan deep enough to be safe would cost more than the whole feature saves, so the stream
+     * carries an index instead — which also makes reconciliation exact rather than windowed.
+     *
+     * Empty for a table that never takes a partial write, which is the only thing {@link set} and
+     * {@link remove} have to check.
+     *
+     * @type {Map<number,number>}
+     */
+    #partial_descriptor_head = new Map();
+
+    /**
+     * For descriptor `i`, the index of the previous pending descriptor targeting the same row, or
+     * -1 at the end of the chain. Parallel to {@link partial_upload_descriptors}, and kept on this
+     * side rather than in a fifth descriptor word so the GPU-side stride stays at four.
+     *
+     * @type {number[]}
+     */
+    #partial_descriptor_previous = [];
+
     /**
      * When a page is updated - it is marked as dirty.
      *
@@ -236,6 +323,10 @@ export class GPUTypedTable {
 
         const upload_buffer = this.element_upload_buffer;
 
+        // A whole-record write supersedes any sub-record range queued for the row earlier in the
+        // frame — and a zero record most of all, since the row is being freed.
+        this.#retire_partial_records(element_index);
+
         // Dedupe like set() does: same-frame slot recycling (set -> remove -> add -> set)
         // must not leave both the old value record and this zero record alive in one
         // dispatch, or the GPU row becomes schedule-dependent.
@@ -454,6 +545,11 @@ export class GPUTypedTable {
         // a workgroup (last-writer-wins is non-deterministic). The CPU
         // shadow above is already idempotent w.r.t. repeated set() calls,
         // so the GPU side is the only thing that needed the dedupe.
+        //
+        // A whole record also supersedes any sub-record range queued for this row earlier in the
+        // frame — see set_bytes for the ordering rules across the two streams.
+        this.#retire_partial_records(element_index);
+
         const upload_buffer = this.element_upload_buffer;
         const value_offset = u32.size;
         const step_size = value_offset + record_size;
@@ -482,13 +578,329 @@ export class GPUTypedTable {
     }
 
     /**
-     * Trim the upload buffer if it exceeds the configured limit.
-     * Called after the upload buffer has been consumed during {@link GPUDatabase.update}.
+     * 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.
+     *
+     * `byte_offset` says where the value lives inside the record; a caller takes it from the
+     * `offset` that its {@link WebGPUStruct} field already carries. Naming an offset rather than a
+     * field is deliberate: the table knows nothing about what its type means, and a caller
+     * updating several adjacent fields can hand over one covering range instead of three writes.
+     *
+     * @param {number} element_index row to patch; must already be occupied
+     * @param {number} byte_offset offset of the range within the record
+     * @param {*} value
+     * @param {WebGPUType} type type of `value` as it is laid out at `byte_offset`
+     */
+    set_range(element_index, byte_offset, value, type) {
+        assert.defined(type, 'type');
+        assert.equal(type.isWebGPUType, true, 'type.isWebGPUType !== true');
+        assert.isNonNegativeInteger(byte_offset, 'byte_offset');
+        assert.equal(byte_offset % type.align, 0, `byte_offset (${byte_offset}) is not aligned to '${type}' (align ${type.align}) — a value of that type never sits there`);
+
+        const size = type.size;
+
+        WRITE_STAGE_BUFFER.ensureCapacity(size);
+
+        // `write_wgsl_type_value` stops at the last field, so a type carrying internal or trailing
+        // padding would leave those bytes holding whatever the previous caller staged. The GPU
+        // never reads them, but the shadow and the upload would stop being a function of `value`.
+        new Uint8Array(WRITE_STAGE_BUFFER.data, 0, size).fill(0);
+
+        WRITE_STAGE_BUFFER.position = 0;
+        write_wgsl_type_value(value, WRITE_STAGE_BUFFER, type);
+
+        this.set_bytes(element_index, byte_offset, WRITE_STAGE_BUFFER.data, 0, size);
+    }
+
+    /**
+     * Overwrite a byte range of an existing record from raw bytes — the primitive
+     * {@link set_range} is built on.
+     *
+     * The range is written to the CPU shadow and queued for the GPU as a sub-record ("partial")
+     * upload: a descriptor in {@link partial_upload_descriptors} plus its words in
+     * {@link partial_upload_data}, applied by `gpu_table_partial_upload_shader`. Nothing outside
+     * `[byte_offset, byte_offset + byte_length)` is serialized, uploaded, or touched, which is the
+     * entire point — a caller that owns twelve words of a forty-four word record should pay for
+     * twelve.
+     *
+     * The range must be a whole number of u32 words at a 4-byte-aligned offset. The database
+     * buffer is an `array<u32>`, so anything finer would need a masked read-modify-write on the
+     * GPU; every WGSL field is at least 4-byte aligned, so the restriction costs a real caller
+     * nothing.
+     *
+     * The row must already be occupied. A partial write patches a record, it never creates one:
+     * allocating a page here would publish a row whose other fields nobody ever wrote.
+     *
+     * ## Ordering
+     *
+     * Within one update cycle a word of a row must end up with exactly one pending writer, or the
+     * writes race — each upload entry is consumed by its own thread within a single dispatch, and
+     * 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.
+     * - **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
+     *   descriptor's words are patched in place.
+     * - **partial after partial, disjoint ranges** — both stay. Different words, different
+     *   threads, no race. This is what keeps a caller updating three scattered fields cheap.
+     * - **partial after partial, overlapping without containment** — the overlapping descriptors
+     *   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.
+     *
+     * @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
+     * @param {ArrayBuffer|ArrayBufferView} source
+     * @param {number} [source_offset] byte offset into `source`
+     * @param {number} [byte_length] length of the range, a whole number of u32 words
+     */
+    set_bytes(element_index, byte_offset, source, source_offset = 0, byte_length = source.byteLength - source_offset) {
+        assert.isNonNegativeInteger(element_index, 'element_index');
+        assert.isNonNegativeInteger(byte_offset, 'byte_offset');
+        assert.isNonNegativeInteger(source_offset, 'source_offset');
+        assert.isPositiveInteger(byte_length, 'byte_length');
+
+        const descriptor = this.descriptor;
+        const record_size = descriptor.packed_element_size_bytes;
+        const word_size = GPU_DATABASE_BUFFER_ELEMENT_TYPE.size;
+
+        assert.equal(byte_offset % word_size, 0, `byte_offset (${byte_offset}) must be a multiple of ${word_size} — the database buffer is an array<u32> and a partial write is not masked`);
+        assert.equal(byte_length % word_size, 0, `byte_length (${byte_length}) must be a multiple of ${word_size} — the database buffer is an array<u32> and a partial write is not masked`);
+        assert.lessThanOrEqual(byte_offset + byte_length, record_size, `range [${byte_offset}, ${byte_offset + byte_length}) reaches past the end of a ${record_size} byte record of '${descriptor.name}'`);
+
+        assert.ok(this.occupancy.get(element_index), `element ${element_index} of '${descriptor.name}' is not occupied — a partial write patches a record, it does not create one`);
+
+        const source_bytes = source instanceof ArrayBuffer
+            ? new Uint8Array(source)
+            : new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
+
+        assert.lessThanOrEqual(source_offset + byte_length, source_bytes.byteLength, `source holds ${source_bytes.byteLength} bytes, short of the ${source_offset + byte_length} the range asks for`);
+
+        const elements_per_page = descriptor.elements_per_page;
+        const page_index = Math.floor(element_index / elements_per_page);
+        const page = this.pages.get(page_index);
+
+        assert.defined(page, `page ${page_index} of '${descriptor.name}'`);
+
+        // A partial write is a read-modify-write of a record that already exists, so it has
+        // nowhere to run against a page whose shadow was released — materializing a zeroed one
+        // the way `set` does would silently blank every field this call doesn't write.
+        assert.defined(page.cpu_data_buffer, `page ${page_index} of '${descriptor.name}' has no CPU shadow — a partial write cannot run against an unmapped page`);
+
+        // Patch the CPU shadow first. Everything the GPU is told below is then read back out of
+        // it rather than out of `source`, so the two cannot disagree by construction — and the
+        // merge path, which has to upload words this call never supplied, has somewhere to get
+        // them from.
+        const record_bytes = new Uint8Array(
+            page.cpu_data_buffer,
+            page.cpu_data_address + (element_index % elements_per_page) * record_size,
+            record_size
+        );
+
+        record_bytes.set(
+            source_bytes.subarray(source_offset, source_offset + byte_length),
+            byte_offset
+        );
+
+        page.cpu_version++;
+
+        // A pending whole record for this row wins the frame outright: patch its bytes and append
+        // nothing, so the row stays in exactly one stream.
+        const upload_buffer = this.element_upload_buffer;
+        const upload_tail = upload_buffer.position;
+        const pending_record = this.#find_upload_record(element_index);
+
+        upload_buffer.position = upload_tail;
+
+        if (pending_record >= 0) {
+            new Uint8Array(upload_buffer.data, pending_record + u32.size + byte_offset, byte_length)
+                .set(record_bytes.subarray(byte_offset, byte_offset + byte_length));
+
+            return;
+        }
+
+        this.#stage_partial_range(element_index, byte_offset / word_size, byte_length / word_size, record_bytes);
+    }
+
+    /**
+     * Queue `[word_offset, word_offset + word_count)` of a row for the partial upload stream,
+     * merging with whatever is already pending for that row. See {@link set_bytes} for the rules.
+     *
+     * @param {number} element_index
+     * @param {number} word_offset within the record
+     * @param {number} word_count
+     * @param {Uint8Array} record_bytes the row's CPU shadow, already patched
+     */
+    #stage_partial_range(element_index, word_offset, word_count, record_bytes) {
+        const descriptors = this.partial_upload_descriptors;
+        const data = this.partial_upload_data;
+        const previous = this.#partial_descriptor_previous;
+        const word_size = GPU_DATABASE_BUFFER_ELEMENT_TYPE.size;
+
+        const tail = descriptors.position;
+        const head = this.#partial_descriptor_head.get(element_index);
+
+        let lo = word_offset;
+        let hi = word_offset + word_count;
+        let overlaps = false;
+
+        for (let i = head === undefined ? -1 : head; i >= 0; i = previous[i]) {
+            descriptors.position = i * PARTIAL_DESCRIPTOR_BYTES + u32.size;
+
+            const candidate_lo = descriptors.readUint32();
+            const candidate_count = descriptors.readUint32();
+
+            if (candidate_count === 0) {
+                // retired by a whole-record write, or absorbed into a union below
+                continue;
+            }
+
+            const candidate_hi = candidate_lo + candidate_count;
+
+            if (candidate_lo <= lo && candidate_hi >= hi) {
+                // Contains the new range — patch its words in place. Nothing else pending for the
+                // row can overlap the new range, because it would have to overlap this descriptor
+                // too, and the invariant says it doesn't.
+                const candidate_data = descriptors.readUint32();
+
+                descriptors.position = tail;
+
+                new Uint8Array(data.data, (candidate_data + (lo - candidate_lo)) * word_size, word_count * word_size)
+                    .set(record_bytes.subarray(lo * word_size, hi * word_size));
+
+                return;
+            }
+
+            if (candidate_hi > lo && candidate_lo < hi) {
+                overlaps = true;
+            }
+        }
+
+        // Overlapping without containment: retire what overlaps and let the new descriptor cover
+        // the union. Absorbing one range can bring the union into contact with another, so the
+        // chain is walked until a pass finds nothing left to absorb — over a chain of a handful of
+        // entries, which is what a row that is patched field by field has.
+        for (let absorbing = overlaps; absorbing;) {
+            absorbing = false;
+
+            for (let i = head === undefined ? -1 : head; i >= 0; i = previous[i]) {
+                descriptors.position = i * PARTIAL_DESCRIPTOR_BYTES + u32.size;
+
+                const candidate_lo = descriptors.readUint32();
+                const candidate_count = descriptors.readUint32();
+
+                if (candidate_count === 0) {
+                    continue;
+                }
+
+                const candidate_hi = candidate_lo + candidate_count;
+
+                if (candidate_hi <= lo || candidate_lo >= hi) {
+                    // disjoint — different words, different thread, no race to resolve
+                    continue;
+                }
+
+                lo = Math.min(lo, candidate_lo);
+                hi = Math.max(hi, candidate_hi);
+
+                descriptors.position = i * PARTIAL_DESCRIPTOR_BYTES + PARTIAL_DESCRIPTOR_WORD_COUNT * u32.size;
+                descriptors.writeUint32(0);
+
+                absorbing = true;
+            }
+        }
+
+        descriptors.position = tail;
+
+        const data_offset = data.position / word_size;
+
+        // The words come out of the shadow rather than out of the caller's `source`, so a union
+        // wider than what this call supplied still carries the right values.
+        data.writeBytes(record_bytes, lo * word_size, (hi - lo) * word_size);
+
+        descriptors.writeUint32(element_index);
+        descriptors.writeUint32(lo);
+        descriptors.writeUint32(hi - lo);
+        descriptors.writeUint32(data_offset);
+
+        const index = tail / PARTIAL_DESCRIPTOR_BYTES;
+
+        previous[index] = head === undefined ? -1 : head;
+        this.#partial_descriptor_head.set(element_index, index);
+    }
+
+    /**
+     * Blank the word count of every pending partial descriptor targeting a row, making its thread
+     * a no-op, and drop the row's chain. Called when a whole-record write supersedes them.
+     *
+     * Exact, not windowed — the chain reaches every descriptor for the row however long the stream
+     * has grown — and it costs a table that never takes a partial write one comparison.
+     *
+     * @param {number} element_index
+     */
+    #retire_partial_records(element_index) {
+        const heads = this.#partial_descriptor_head;
+
+        if (heads.size === 0) {
+            return;
+        }
+
+        const head = heads.get(element_index);
+
+        if (head === undefined) {
+            return;
+        }
+
+        const descriptors = this.partial_upload_descriptors;
+        const previous = this.#partial_descriptor_previous;
+        const tail = descriptors.position;
+
+        for (let i = head; i >= 0; i = previous[i]) {
+            descriptors.position = i * PARTIAL_DESCRIPTOR_BYTES + PARTIAL_DESCRIPTOR_WORD_COUNT * u32.size;
+            descriptors.writeUint32(0);
+        }
+
+        descriptors.position = tail;
+
+        heads.delete(element_index);
+    }
+
+    /**
+     * Drop the partial upload stream, its per-row index included. Called by
+     * {@link GPUDatabase.update} once the stream has been dispatched.
+     */
+    rewind_partial_upload() {
+        this.partial_upload_descriptors.position = 0;
+        this.partial_upload_data.position = 0;
+
+        this.#partial_descriptor_head.clear();
+        this.#partial_descriptor_previous.length = 0;
+    }
+
+    /**
+     * Trim the upload buffers if they exceed the configured limit.
+     * Called after the upload buffers have been consumed during {@link GPUDatabase.update}.
      */
     trim_upload_buffer() {
         if (this.element_upload_buffer.capacity > GPU_DATABASE_UPLOAD_BUFFER_LIMIT) {
             this.element_upload_buffer.setCapacity(GPU_DATABASE_UPLOAD_BUFFER_LIMIT);
         }
+
+        if (this.partial_upload_descriptors.capacity > GPU_DATABASE_UPLOAD_BUFFER_LIMIT) {
+            this.partial_upload_descriptors.setCapacity(GPU_DATABASE_UPLOAD_BUFFER_LIMIT);
+        }
+
+        if (this.partial_upload_data.capacity > GPU_DATABASE_UPLOAD_BUFFER_LIMIT) {
+            this.partial_upload_data.setCapacity(GPU_DATABASE_UPLOAD_BUFFER_LIMIT);
+        }
     }
 
     /**

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

@@ -0,0 +1,14 @@
+/**
+ * Words per descriptor in the partial (sub-record) upload stream:
+ * `[element_index, word_offset, word_count, data_offset]`.
+ *
+ * `word_offset` is relative to the start of the record, `data_offset` is an absolute word index
+ * into the table's partial data blob — a dispatch rebases it by `settings.data_word_base` so a
+ * chunk can carry a slice of that blob rather than all of it.
+ *
+ * @see GPUTypedTable#set_bytes
+ * @see gpu_table_partial_upload_shader
+ * @type {number}
+ */
+export const GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS: number;
+//# sourceMappingURL=GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wDAFU,MAAM,CAE2C"}

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

@@ -0,0 +1,13 @@
+/**
+ * Words per descriptor in the partial (sub-record) upload stream:
+ * `[element_index, word_offset, word_count, data_offset]`.
+ *
+ * `word_offset` is relative to the start of the record, `data_offset` is an absolute word index
+ * into the table's partial data blob — a dispatch rebases it by `settings.data_word_base` so a
+ * chunk can carry a slice of that blob rather than all of it.
+ *
+ * @see GPUTypedTable#set_bytes
+ * @see gpu_table_partial_upload_shader
+ * @type {number}
+ */
+export const GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS = 4;

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

@@ -0,0 +1,17 @@
+export const GPU_TABLE_PARTIAL_UPLOAD_SETTINGS_STRUCT: WebGPUStruct;
+/**
+ * Applies sub-record ("partial") writes to the database.
+ *
+ * The whole-record upload shader can index its buffer by thread id because every record there is
+ * the same size. Partial writes are variable length, so the stream is split in two: a fixed-stride
+ * descriptor array this shader indexes by thread id, and a data blob the descriptors point into.
+ * One thread per descriptor, copying `word_count` words.
+ *
+ * A descriptor with `word_count == 0` is a retired entry — {@link GPUTypedTable} blanks descriptors
+ * that a later whole-record write superseded rather than compacting the buffer — and its thread
+ * falls through the copy loop without writing anything.
+ */
+export const gpu_table_partial_upload_shader: ComputeShader;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=gpu_table_partial_upload_shader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_table_partial_upload_shader.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/gpu_table_partial_upload_shader.js"],"names":[],"mappings":"AAUA,oEAoBG;AAcH;;;;;;;;;;;GAWG;AACH,4DA2DG;6BAjH0B,mCAAmC;8BAElC,+BAA+B"}

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

@@ -0,0 +1,116 @@
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { GPU_DATABASE_BUFFER_ELEMENT_TYPE } from "./GPU_DATABASE_BUFFER_ELEMENT_TYPE.js";
+import { GPU_DATABASE_UPLOAD_DISPATCH_GROUP_SIZE } from "./GPU_DATABASE_UPLOAD_DISPATCH_GROUP_SIZE.js";
+import { GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS } from "./GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS.js";
+
+export const GPU_TABLE_PARTIAL_UPLOAD_SETTINGS_STRUCT = WebGPUStruct.from({
+    // number of descriptors in this dispatch, one thread each
+    count: u32,
+    // size of one record in GPU_DATABASE_BUFFER_ELEMENT_TYPE units (u32 words).
+    // Used as the in-page slot stride and as the bound a descriptor's range must
+    // stay inside.
+    record_size: u32,
+    elements_per_page: u32,
+    // u32 offset into the database buffer where this table's page address table
+    // begins.
+    page_lookup_address: u32,
+    // size of the per-page GPU header in u32 words; records start there.
+    page_header_words: u32,
+    // per-table maximum page count, used to drop element ids whose page index
+    // would walk past the end of this table's address region.
+    page_limit: u32,
+    // word index, within the table's partial data blob, of the first word this
+    // chunk's `data` binding holds. Descriptors carry absolute blob offsets, so
+    // the shader subtracts this to index the chunk.
+    data_word_base: u32,
+});
+
+const resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, 28 bytes, read-only — same reasoning as the whole-record upload: a uniform would
+// cost a transient buffer, a staging buffer and a copy per chunk to carry seven integers already
+// known on the CPU at encode time.
+resources.setImmediate('settings', GPU_TABLE_PARTIAL_UPLOAD_SETTINGS_STRUCT);
+
+resources.createGroup()
+    .addStorageBuffer('descriptors', WebGPUArray.from(GPU_DATABASE_BUFFER_ELEMENT_TYPE), false)
+    .addStorageBuffer('data', WebGPUArray.from(GPU_DATABASE_BUFFER_ELEMENT_TYPE), false)
+    .addStorageBuffer('database', WebGPUArray.from(GPU_DATABASE_BUFFER_ELEMENT_TYPE), true);
+
+/**
+ * Applies sub-record ("partial") writes to the database.
+ *
+ * The whole-record upload shader can index its buffer by thread id because every record there is
+ * the same size. Partial writes are variable length, so the stream is split in two: a fixed-stride
+ * descriptor array this shader indexes by thread id, and a data blob the descriptors point into.
+ * One thread per descriptor, copying `word_count` words.
+ *
+ * A descriptor with `word_count == 0` is a retired entry — {@link GPUTypedTable} blanks descriptors
+ * that a later whole-record write superseded rather than compacting the buffer — and its thread
+ * falls through the copy loop without writing anything.
+ */
+export const gpu_table_partial_upload_shader = ComputeShader.from({
+    label: `GPUTypedTable/Upload partial records`,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${GPU_DATABASE_UPLOAD_DISPATCH_GROUP_SIZE})
+fn main(@builtin(global_invocation_id) global_id : vec3<u32>){
+    let descriptor_index = global_id.x;
+
+    if(descriptor_index >= settings.count){
+        return;
+    }
+
+    let descriptor_offset = descriptor_index * ${GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS}u;
+
+    let element_id = descriptors[descriptor_offset];
+    let word_offset = descriptors[descriptor_offset + 1u];
+    let word_count = descriptors[descriptor_offset + 2u];
+    let data_offset = descriptors[descriptor_offset + 3u] - settings.data_word_base;
+
+    // A word_count of 0 — a descriptor retired by a later whole-record write — needs no test of
+    // its own: the copy loop below runs zero times.
+
+    // A range that reaches past the record would write into the next slot. The CPU asserts this
+    // when the range is queued; the guard is here because the cost of getting it wrong is silent
+    // corruption of an unrelated row.
+    if(word_offset + word_count > settings.record_size){
+        return;
+    }
+
+    let page_index = element_id / settings.elements_per_page;
+    let page_offset = element_id % settings.elements_per_page;
+
+    if(page_index >= settings.page_limit){
+        // page index overflow
+        return;
+    }
+
+    let page_lookup_index = page_index + settings.page_lookup_address;
+    let page_address = database[page_lookup_index];
+
+    // Page may have been freed since this write was queued (its last element removed in the same
+    // update cycle). Without this guard the u32 add below wraps and write_offset lands inside the
+    // allocation-table region.
+    if(page_address == 0xFFFFFFFFu){
+        return;
+    }
+
+    let write_offset = page_address + settings.page_header_words + page_offset * settings.record_size + word_offset;
+
+    // copy the range
+    for(var i = 0u; i < word_count; i++){
+        database[write_offset + i] = data[data_offset + i];
+    }
+
+}
+        `
+    ),
+    resources
+});