@woosh/meep-engine 3.22.0 → 3.23.0

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

@@ -11,6 +11,8 @@ 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 { 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";
 import { GPUPageMetadata } from "./GPUPageMetadata.js";
 import { GPUTypedTable } from "./GPUTypedTable.js";
 import { PageBufferPool } from "./PageBufferPool.js";
@@ -521,70 +523,17 @@ export class GPUDatabase {
         // transfer elements (chunked)
         for (let i = 0; i < table_count; i++) {
             const table = tables[i];
-            const upload_data = table.element_upload_buffer;
-            const cursor = upload_data.position;
 
-            if (cursor === 0) {
-                // no data
-                continue;
-            }
-
-            const table_descriptor = table.descriptor;
-            const record_stride = table_descriptor.packed_element_size_bytes + u32.size;
-            const total_element_count = cursor / record_stride;
-
-            assert.isNonNegativeInteger(total_element_count, 'total_element_count');
-
-            // Chunk the upload to avoid oversized transient buffers
-            const max_elements_per_chunk = Math.max(1, Math.floor(UPLOAD_CHUNK_SIZE / record_stride));
-
-            let elements_uploaded = 0;
-
-            while (elements_uploaded < total_element_count) {
-                const chunk_count = Math.min(max_elements_per_chunk, total_element_count - elements_uploaded);
-                const chunk_byte_offset = elements_uploaded * record_stride;
-                const chunk_byte_size = chunk_count * record_stride;
-
-                assert.isNonNegativeInteger(chunk_count, 'chunk_count');
-
-                // immediate data — a plain value written straight into the pass, not a buffer
-                const settings = {
-                    count: chunk_count,
-                    // record_size is read by the upload shader as a count of
-                    // GPU_DATABASE_BUFFER_ELEMENT_TYPE (u32) units. Records
-                    // are stored at type.size stride (no record-level padding),
-                    // with WGSL alignment applied within fields and array elements.
-                    record_size: table_descriptor.packed_element_size_bytes / GPU_DATABASE_BUFFER_ELEMENT_TYPE.size,
-                    elements_per_page: table_descriptor.elements_per_page,
-                    page_lookup_address: table_descriptor.page_lookup_address,
-                    page_header_words: table_descriptor.page_header_words,
-                    page_limit: table_descriptor.page_limit,
-                };
-
-                const upload_buffer = encoder.allocateTransientBufferAndLoad(
-                    upload_data.data,
-                    GPUBufferUsage.STORAGE,
-                    chunk_byte_offset,
-                    chunk_byte_size
-                );
-
-                gpu_table_element_upload_shader.dispatchThreads({
-                    encoder,
-                    bindings: {
-                        settings,
-                        upload_buffer,
-                        database: this.buffer,
-                    },
-                    thread_count_x: chunk_count,
-                });
-
-                elements_uploaded += chunk_count;
-            }
+            // 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.
+            this.#upload_element_records(table, encoder);
+            this.#upload_partial_ranges(table, encoder);
 
-            // reset upload buffer
-            table.element_upload_buffer.position = 0;
-
-            // Trim upload buffer if it grew too large
+            // Trim upload buffers if they grew too large
             table.trim_upload_buffer();
         }
 
@@ -605,6 +554,186 @@ export class GPUDatabase {
         }
     }
 
+    /**
+     * Dispatch a table's pending whole-record writes, chunked so no single transient buffer grows
+     * past {@link UPLOAD_CHUNK_SIZE}. Rewinds the buffer.
+     *
+     * @param {GPUTypedTable} table
+     * @param {ShadeGPUCommandContext} encoder
+     */
+    #upload_element_records(table, encoder) {
+        const upload_data = table.element_upload_buffer;
+        const cursor = upload_data.position;
+
+        if (cursor === 0) {
+            // no data
+            return;
+        }
+
+        const table_descriptor = table.descriptor;
+        const record_stride = table_descriptor.packed_element_size_bytes + u32.size;
+        const total_element_count = cursor / record_stride;
+
+        assert.isNonNegativeInteger(total_element_count, 'total_element_count');
+
+        // Chunk the upload to avoid oversized transient buffers
+        const max_elements_per_chunk = Math.max(1, Math.floor(UPLOAD_CHUNK_SIZE / record_stride));
+
+        let elements_uploaded = 0;
+
+        while (elements_uploaded < total_element_count) {
+            const chunk_count = Math.min(max_elements_per_chunk, total_element_count - elements_uploaded);
+            const chunk_byte_offset = elements_uploaded * record_stride;
+            const chunk_byte_size = chunk_count * record_stride;
+
+            assert.isNonNegativeInteger(chunk_count, 'chunk_count');
+
+            // immediate data — a plain value written straight into the pass, not a buffer
+            const settings = {
+                count: chunk_count,
+                // record_size is read by the upload shader as a count of
+                // GPU_DATABASE_BUFFER_ELEMENT_TYPE (u32) units. Records
+                // are stored at type.size stride (no record-level padding),
+                // with WGSL alignment applied within fields and array elements.
+                record_size: table_descriptor.packed_element_size_bytes / GPU_DATABASE_BUFFER_ELEMENT_TYPE.size,
+                elements_per_page: table_descriptor.elements_per_page,
+                page_lookup_address: table_descriptor.page_lookup_address,
+                page_header_words: table_descriptor.page_header_words,
+                page_limit: table_descriptor.page_limit,
+            };
+
+            const upload_buffer = encoder.allocateTransientBufferAndLoad(
+                upload_data.data,
+                GPUBufferUsage.STORAGE,
+                chunk_byte_offset,
+                chunk_byte_size
+            );
+
+            gpu_table_element_upload_shader.dispatchThreads({
+                encoder,
+                bindings: {
+                    settings,
+                    upload_buffer,
+                    database: this.buffer,
+                },
+                thread_count_x: chunk_count,
+            });
+
+            elements_uploaded += chunk_count;
+        }
+
+        // reset upload buffer
+        upload_data.position = 0;
+    }
+
+    /**
+     * Dispatch a table's pending sub-record ("partial") writes and rewind both of that stream's
+     * buffers.
+     *
+     * The stream is a fixed-stride descriptor array plus a data blob the descriptors index. One
+     * thread per descriptor, so chunking is a descriptor count — but the data words a chunk's
+     * descriptors reach have to travel with it. That works because both buffers are append-only
+     * and grow together: descriptor `data_offset` is non-decreasing, so a run of descriptors owns
+     * one contiguous slice of the blob. The dispatch carries the slice's base and the shader
+     * subtracts it.
+     *
+     * @param {GPUTypedTable} table
+     * @param {ShadeGPUCommandContext} encoder
+     */
+    #upload_partial_ranges(table, encoder) {
+        const descriptors = table.partial_upload_descriptors;
+        const descriptor_cursor = descriptors.position;
+
+        if (descriptor_cursor === 0) {
+            // nothing pending — the cost of the whole feature to a table that never uses it
+            return;
+        }
+
+        const data = table.partial_upload_data;
+        const word_size = GPU_DATABASE_BUFFER_ELEMENT_TYPE.size;
+        const descriptor_stride = GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS * word_size;
+        const total_descriptor_count = descriptor_cursor / descriptor_stride;
+
+        assert.isNonNegativeInteger(total_descriptor_count, 'total_descriptor_count');
+
+        const descriptor_words = new Uint32Array(descriptors.data, 0, descriptor_cursor / word_size);
+
+        const table_descriptor = table.descriptor;
+
+        const max_descriptors_per_chunk = Math.max(1, Math.floor(UPLOAD_CHUNK_SIZE / descriptor_stride));
+
+        let descriptors_uploaded = 0;
+
+        while (descriptors_uploaded < total_descriptor_count) {
+            const chunk_data_start = descriptor_words[descriptors_uploaded * GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS + 3];
+
+            let chunk_count = 0;
+            let chunk_data_end = chunk_data_start;
+
+            while (
+                chunk_count < max_descriptors_per_chunk
+                && descriptors_uploaded + chunk_count < total_descriptor_count
+                ) {
+                const base = (descriptors_uploaded + chunk_count) * GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS;
+                const range_end = descriptor_words[base + 3] + descriptor_words[base + 2];
+                const next_data_end = Math.max(chunk_data_end, range_end);
+
+                // Always take one descriptor, however big its range — a range can't exceed a
+                // record, and a record can't exceed a page.
+                if (chunk_count > 0 && (next_data_end - chunk_data_start) * word_size > UPLOAD_CHUNK_SIZE) {
+                    break;
+                }
+
+                chunk_data_end = next_data_end;
+                chunk_count++;
+            }
+
+            // A chunk whose descriptors were all retired reads no data at all, and a zero-sized
+            // transient buffer is not allocatable. Every descriptor appended at least one word, so
+            // one word is always there to bind.
+            const chunk_data_bytes = Math.max(word_size, (chunk_data_end - chunk_data_start) * word_size);
+
+            const settings = {
+                count: chunk_count,
+                record_size: table_descriptor.packed_element_size_bytes / word_size,
+                elements_per_page: table_descriptor.elements_per_page,
+                page_lookup_address: table_descriptor.page_lookup_address,
+                page_header_words: table_descriptor.page_header_words,
+                page_limit: table_descriptor.page_limit,
+                data_word_base: chunk_data_start,
+            };
+
+            const descriptor_buffer = encoder.allocateTransientBufferAndLoad(
+                descriptors.data,
+                GPUBufferUsage.STORAGE,
+                descriptors_uploaded * descriptor_stride,
+                chunk_count * descriptor_stride
+            );
+
+            const data_buffer = encoder.allocateTransientBufferAndLoad(
+                data.data,
+                GPUBufferUsage.STORAGE,
+                chunk_data_start * word_size,
+                chunk_data_bytes
+            );
+
+            gpu_table_partial_upload_shader.dispatchThreads({
+                encoder,
+                bindings: {
+                    settings,
+                    descriptors: descriptor_buffer,
+                    data: data_buffer,
+                    database: this.buffer,
+                },
+                thread_count_x: chunk_count,
+            });
+
+            descriptors_uploaded += chunk_count;
+        }
+
+        table.rewind_partial_upload();
+    }
+
     /**
      * Build and upload the per-page GPU header for every page flagged in
      * {@link GPUTypedTable.header_dirty_pages}. Header layout:

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

@@ -24,6 +24,26 @@ export class GPUTypedTable<T> {
      * @type {BinaryBuffer}
      */
     element_upload_buffer: BinaryBuffer;
+    /**
+     * 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: BinaryBuffer;
+    /**
+     * 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: BinaryBuffer;
     /**
      * When a page is updated - it is marked as dirty.
      *
@@ -96,8 +116,79 @@ export class GPUTypedTable<T> {
      */
     set(element_index: number, value: T): void;
     /**
-     * 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: number, byte_offset: number, value: any, type: WebGPUType): void;
+    /**
+     * 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: number, byte_offset: number, source: ArrayBuffer | ArrayBufferView, source_offset?: number, byte_length?: number): void;
+    /**
+     * Drop the partial upload stream, its per-row index included. Called by
+     * {@link GPUDatabase.update} once the stream has been dispatched.
+     */
+    rewind_partial_upload(): void;
+    /**
+     * 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(): void;
     /**
@@ -163,6 +254,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;
 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":"AA4CA;;;GAGG;AACH;IAmDI;;;OAGG;IACH,wBAFW,uBAAuB,EASjC;IA5DD;;OAEG;IACH,YAFU,uBAAuB,CAEtB;IAEX;;;;OAIG;IACH,OAFU,IAAI,MAAM,EAAC,eAAe,CAAC,CAEnB;IAElB;;;;OAIG;IACH,uBAFU,YAAY,CAE6D;IAEnF;;;;;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;IAoED;;;;;;OAMG;IACH,mBAJW,MAAM,GACJ,CAAC,GAAC,SAAS,CA4BvB;IAgDD;;;OAGG;IACH,cAsBC;IA+BD;;;;OAIG;IACH,mBAHW,MAAM,SACN,CAAC,QAkFX;IAED;;;OAGG;IACH,2BAIC;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;sCAnkBY,OAAO,8BAA8B,EAAE,uBAAuB;6BAC9D,OAAO,qBAAqB,EAAE,cAAc;gCAJzB,sBAAsB;6BAPzB,yCAAyC;uBAC/C,mCAAmC"}
+{"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"}