@woosh/meep-engine 3.29.0 → 3.31.0

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

@@ -13,9 +13,11 @@ import { read_wgsl_type_value } from "../../shader/type/serde/read_gpu_typed_buf
 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_NULL } from "./GPU_DATABASE_NULL.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";
+import { gpu_table_range_well_formed } from "./gpu_table_range_well_formed.js";
 import { WordViews } from "./WordViews.js";
 
 /**
@@ -43,6 +45,24 @@ const WRITE_STAGE_BUFFER = BinaryBuffer.fromEndianness(platform_compute_endianne
  */
 const WORD_SIZE = GPU_DATABASE_BUFFER_ELEMENT_TYPE.size;
 
+/**
+ * {@link GPUTypedTable.null_words} of a table whose definition declared no links or ranges.
+ * @type {Uint32Array}
+ */
+const NO_NULL_WORDS = new Uint32Array(0);
+
+/**
+ * {@link GPUTypedTable.owning_links} of a table that owns nothing.
+ * @type {ReadonlyArray<{word: number, target: GPUTypedTable}>}
+ */
+const NO_OWNING_LINKS = Object.freeze([]);
+
+/**
+ * {@link GPUTypedTable.owning_ranges} of a table that owns no runs.
+ * @type {ReadonlyArray<{first_word: number, count_word: number, target: GPUTypedTable}>}
+ */
+const NO_OWNING_RANGES = Object.freeze([]);
+
 /**
  * Byte stride of one entry in {@link GPUTypedTable.partial_upload_descriptors}.
  * @type {number}
@@ -243,6 +263,36 @@ export class GPUTypedTable {
      */
     page_buffer_pool;
 
+    /**
+     * Word offsets, within one record, of every word that names a row: each link word the table's
+     * definition declared (see {@link GPUDatabaseDefinition#add_link}), and the first word of each
+     * range ({@link GPUDatabaseDefinition#add_range}), whose count needs nothing — zero is the empty
+     * range's. Each holds {@link GPU_DATABASE_NULL} wherever nothing has been written: on a freed
+     * row, in its CPU shadow and in the record the GPU is sent, and on every row of a new page. A 0
+     * there would name row 0.
+     *
+     * Set by the database after construction, like {@link page_buffer_pool}. Empty for a table
+     * built on its own.
+     * @type {Uint32Array}
+     */
+    null_words = NO_NULL_WORDS;
+
+    /**
+     * The owning links of the table's records, each with the table it points into: the rows
+     * {@link remove} takes with a row. Set by the database once every table exists, since a link
+     * can point into a table built after this one. Empty for a table built on its own.
+     * @type {ReadonlyArray<{word: number, target: GPUTypedTable}>}
+     */
+    owning_links = NO_OWNING_LINKS;
+
+    /**
+     * The owning ranges of the table's records, each with the table its runs are in: the runs
+     * {@link remove} takes with a row. Set by the database alongside {@link owning_links}. Empty for a
+     * table built on its own.
+     * @type {ReadonlyArray<{first_word: number, count_word: number, target: GPUTypedTable}>}
+     */
+    owning_ranges = NO_OWNING_RANGES;
+
     /**
      *
      * @param {GPUTypedTableDescriptor} descriptor
@@ -287,14 +337,209 @@ export class GPUTypedTable {
     }
 
     /**
-     * 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.
+     * Add `values` as a run — consecutive rows, in order — at the lowest place they fit, and return
+     * the first row. What a range names (see {@link GPUDatabaseDefinition#add_range}).
+     *
+     * First fit over occupancy: holes shorter than the run are skipped, a word of the bitset at a
+     * time. {@link add} is the same search for a run of one, so the two share one idea of which rows
+     * are free. A run may cross a page boundary — every reader looks a row's page up for itself —
+     * and it never moves once handed out.
+     *
+     * No values is no run: {@link GPU_DATABASE_NULL} comes back and no row is taken, so
+     * `(add_run(values), values.length)` is always a range — the empty one, `(NULL, 0)`, when there
+     * is nothing to hold.
+     *
+     * @param {T[]} values
+     * @returns {number} the run's first row, or {@link GPU_DATABASE_NULL} for no values
+     */
+    add_run(values) {
+        assert.isArray(values, 'values');
+
+        if (values.length === 0) {
+            return GPU_DATABASE_NULL;
+        }
+
+        const first = this.#find_run(values.length);
+
+        for (let i = 0; i < values.length; i++) {
+            this.set(first + i, values[i]);
+        }
+
+        return first;
+    }
+
+    /**
+     * {@link add_run} through a generated writer, as {@link add_record} is {@link add} through one.
+     *
+     * @param {T[]} values
+     * @param {GPURecordWriter} writer generated against this table's type
+     * @returns {number} the run's first row, or {@link GPU_DATABASE_NULL} for no values
+     */
+    add_run_records(values, writer) {
+        assert.isArray(values, 'values');
+
+        if (values.length === 0) {
+            return GPU_DATABASE_NULL;
+        }
+
+        const first = this.#find_run(values.length);
+
+        for (let i = 0; i < values.length; i++) {
+            this.set_record(first + i, values[i], writer);
+        }
+
+        return first;
+    }
+
+
+    /**
+     * The lowest row where `count` free rows start.
+     *
+     * @param {number} count
+     * @returns {number}
+     */
+    #find_run(count) {
+        assert.isPositiveInteger(count, 'count');
+
+        const occupancy = this.occupancy;
+
+        let start = occupancy.nextClearBit(0);
+
+        for (; ;) {
+            const next_taken = occupancy.nextSetBit(start);
+
+            if (next_taken === -1 || next_taken - start >= count) {
+                break;
+            }
+
+            start = occupancy.nextClearBit(next_taken);
+        }
+
+        const descriptor = this.descriptor;
+
+        assert.lessThanOrEqual(start + count, descriptor.page_limit * descriptor.elements_per_page, `a run of ${count} does not fit in '${descriptor.name}' below its page limit`);
+
+        return start;
+    }
+
+    /**
+     * Remove an element from the table, freeing its slot — and every row it owns.
+     *
+     * The slot is emptied in the CPU shadow — zeros, with {@link GPU_DATABASE_NULL} in its link
+     * words and in the first word of its ranges — and the same record is queued for the GPU.
+     *
+     * A row whose owning links and ranges (see {@link GPUDatabaseDefinition#add_link} and
+     * {@link GPUDatabaseDefinition#add_range}) name rows takes them with it, and those take theirs: a
+     * clip its run of bindings, a skin its joints, a chain's node the one after it. The rows are
+     * found through a worklist rather than by recursion, so a chain of any length cannot run the stack
+     * out, and a row that is already free is skipped — so a second removal of the same row does
+     * nothing, and a chain that loops back ends where it started. Each row goes through the same path
+     * a removal on its own takes.
+     *
+     * Only rows cascade. Whatever a row stood for outside the database — a clip's pose targets, a
+     * skin's skinning bindings — is the caller's to give back. And only removal cascades: see
+     * {@link GPUDatabaseDefinition#add_link} for what ownership does not do.
      *
      * @param {number} element_index
      */
     remove(element_index) {
         assert.isNonNegativeInteger(element_index, 'element_index');
 
+        if (this.owning_links.length === 0 && this.owning_ranges.length === 0) {
+            this.#remove_row(element_index);
+            return;
+        }
+
+        // [table, row] pairs, flattened
+        const work = [this, element_index];
+
+        while (work.length > 0) {
+            const row = /** @type {number} */ (work.pop());
+            const table = /** @type {GPUTypedTable} */ (work.pop());
+
+            if (!table.occupancy.get(row)) {
+                // already free: removed twice, or reached again round a loop
+                continue;
+            }
+
+            // read what the row owns before it is emptied
+            table.#collect_owned(row, work);
+            table.#remove_row(row);
+        }
+    }
+
+    /**
+     * Push `[table, row]` onto `work` for every row the owning links and ranges of an occupied `row`
+     * name, read from the CPU shadow.
+     *
+     * A run's rows are visited only where they are live, and when their table owns nothing they are
+     * removed here and then rather than queued. A range that names no run the table could hold is
+     * skipped, and left for the link check to report.
+     *
+     * @param {number} row
+     * @param {Array<GPUTypedTable|number>} work
+     */
+    #collect_owned(row, work) {
+        const links = this.owning_links;
+        const ranges = this.owning_ranges;
+
+        if (links.length === 0 && ranges.length === 0) {
+            return;
+        }
+
+        const descriptor = this.descriptor;
+        const elements_per_page = descriptor.elements_per_page;
+        const page = this.pages.get(Math.floor(row / elements_per_page));
+
+        assert.defined(page.cpu_data_buffer, `page ${page.index} of '${descriptor.name}' has no CPU shadow to read row ${row}'s owned rows from`);
+
+        const shadow = page.words.over(page.cpu_data_buffer).u32;
+        const base = page.cpu_data_address / WORD_SIZE + (row % elements_per_page) * (descriptor.packed_element_size_bytes / WORD_SIZE);
+
+        for (let i = 0; i < links.length; i++) {
+            const link = links[i];
+            const value = shadow[base + link.word];
+
+            if (value !== GPU_DATABASE_NULL) {
+                work.push(link.target, value);
+            }
+        }
+
+        for (let i = 0; i < ranges.length; i++) {
+            const range = ranges[i];
+            const first = shadow[base + range.first_word];
+            const count = shadow[base + range.count_word];
+            const target = range.target;
+
+            const well_formed = gpu_table_range_well_formed(first, count, target.descriptor);
+
+            assert.ok(well_formed, `row ${row} of '${descriptor.name}' holds a malformed range (${first}, ${count}) into '${target.descriptor.name}'`);
+
+            if (!well_formed || first === GPU_DATABASE_NULL) {
+                continue;
+            }
+
+            const end = first + count;
+            const occupancy = target.occupancy;
+
+            if (target.owning_links.length === 0 && target.owning_ranges.length === 0) {
+                for (let r = occupancy.nextSetBit(first); r !== -1 && r < end; r = occupancy.nextSetBit(r + 1)) {
+                    target.#remove_row(r);
+                }
+            } else {
+                for (let r = occupancy.nextSetBit(first); r !== -1 && r < end; r = occupancy.nextSetBit(r + 1)) {
+                    work.push(target, r);
+                }
+            }
+        }
+    }
+
+    /**
+     * {@link remove} for one row, taking nothing with it.
+     *
+     * @param {number} element_index
+     */
+    #remove_row(element_index) {
         if (!this.occupancy.get(element_index)) {
             // already free
             return;
@@ -314,13 +559,25 @@ export class GPUTypedTable {
             this.header_dirty_pages.set(page_index, true);
 
             if (page.cpu_data_buffer !== undefined) {
-                // zero-fill the slot in the CPU shadow
-                const record_size = this.descriptor.packed_element_size_bytes;
+                // zero-fill the slot in the CPU shadow, through the page's word view rather than a
+                // byte view made for the purpose — a cascade frees a run a row at a time
+                const record_words = this.descriptor.packed_element_size_bytes / WORD_SIZE;
                 const in_page_index = element_index % this.descriptor.elements_per_page;
-                const byte_offset = page.cpu_data_address + in_page_index * record_size;
+                const record_word = page.cpu_data_address / WORD_SIZE + in_page_index * record_words;
+
+                const shadow = page.words.over(page.cpu_data_buffer).u32;
+
+                for (let w = record_word, end = record_word + record_words; w < end; w++) {
+                    shadow[w] = 0;
+                }
+
+                // …except its links, which name no row — 0 would name row 0. A value written into
+                // this row later that leaves a link out keeps the NULL rather than inheriting row 0.
+                const null_words = this.null_words;
 
-                const view = new Uint8Array(page.cpu_data_buffer, byte_offset, record_size);
-                view.fill(0);
+                for (let i = 0; i < null_words.length; i++) {
+                    shadow[record_word + null_words[i]] = GPU_DATABASE_NULL;
+                }
 
                 page.cpu_version++;
             }
@@ -385,11 +642,19 @@ export class GPUTypedTable {
      *
      * The CPU data shadow is left as-is — subsequent {@link add} /
      * {@link set} calls overwrite slots before anything reads them, and
-     * marshalling reads don't honour occupancy. Only occupancy state
-     * is reset and page headers are marked dirty so the GPU's bitmap
-     * matches.
+     * marshalling reads don't honour occupancy — except the
+     * {@link null_words} of the rows it frees, which get
+     * {@link GPU_DATABASE_NULL} as a removal would leave them, so a later
+     * value that leaves a link or range out names no row. Nothing is
+     * shipped: only occupancy state is reset and page headers are marked
+     * dirty so the GPU's bitmap matches.
+     *
+     * Refused for a table that owns rows: clearing takes no owned rows with it, and doing so would
+     * mean visiting every row it is meant to skip. Remove the owners instead.
      */
     clear() {
+        assert.equal(this.owning_links.length + this.owning_ranges.length, 0, `'${this.descriptor.name}' owns rows through its links or ranges; clear() would leave them all behind`);
+
         if (this.occupancy.cardinality() === 0) {
             // already empty — nothing to publish
             return;
@@ -404,6 +669,30 @@ export class GPUTypedTable {
             }
         }
 
+        const null_words = this.null_words;
+
+        if (null_words.length > 0) {
+            const occupancy = this.occupancy;
+            const descriptor = this.descriptor;
+            const elements_per_page = descriptor.elements_per_page;
+            const record_words = descriptor.packed_element_size_bytes / WORD_SIZE;
+
+            for (let row = occupancy.nextSetBit(0); row !== -1; row = occupancy.nextSetBit(row + 1)) {
+                const page = this.pages.get(Math.floor(row / elements_per_page));
+
+                if (page === undefined || page.cpu_data_buffer === undefined) {
+                    continue;
+                }
+
+                const shadow = page.words.over(page.cpu_data_buffer).u32;
+                const record_word = page.cpu_data_address / WORD_SIZE + (row % elements_per_page) * record_words;
+
+                for (let i = 0; i < null_words.length; i++) {
+                    shadow[record_word + null_words[i]] = GPU_DATABASE_NULL;
+                }
+            }
+        }
+
         this.occupancy.reset();
 
         for (const [page_index, page] of this.pages) {
@@ -467,17 +756,48 @@ export class GPUTypedTable {
             page.cpu_data_buffer = pool !== undefined
                 ? pool.acquire().buffer
                 : new ArrayBuffer(this.descriptor.page_byte_size);
+
+            this.#null_fill_page(page);
         }
 
         return page;
     }
 
+    /**
+     * Put {@link GPU_DATABASE_NULL} into the {@link null_words} of every row of a new page shadow. A
+     * shadow starts out as zeros, and 0 in a link names row 0: this is what makes a link no write has
+     * touched name no row on a page just made, as {@link remove} makes it on a row just freed.
+     * Nothing for a table with no links or ranges.
+     *
+     * @param {GPUPageMetadata} page with its CPU shadow
+     */
+    #null_fill_page(page) {
+        const null_words = this.null_words;
+
+        if (null_words.length === 0) {
+            return;
+        }
+
+        const descriptor = this.descriptor;
+        const record_words = descriptor.packed_element_size_bytes / WORD_SIZE;
+        const elements_per_page = descriptor.elements_per_page;
+        const shadow = page.words.over(page.cpu_data_buffer).u32;
+
+        let record_word = page.cpu_data_address / WORD_SIZE;
+
+        for (let slot = 0; slot < elements_per_page; slot++, record_word += record_words) {
+            for (let i = 0; i < null_words.length; i++) {
+                shadow[record_word + null_words[i]] = GPU_DATABASE_NULL;
+            }
+        }
+    }
+
     /**
      * Queue a zero-filled upload for a single element.
      * @param {number} element_index
      */
     #queue_zero_upload(element_index) {
-        const word_count = this.descriptor.packed_element_size_bytes / 4;
+        const word_count = this.descriptor.packed_element_size_bytes / WORD_SIZE;
 
         const upload_buffer = this.element_upload_buffer;
 
@@ -492,25 +812,82 @@ export class GPUTypedTable {
         const existing_record = this.#pending_record_offset(element_index);
 
         if (existing_record >= 0) {
-            // zero the matched record's value bytes, leaving its id alone
-            upload_buffer.position = existing_record + u32.size;
+            // zero the matched record's value, leaving its id alone
+            const words = this.#upload_words.over(upload_buffer.data).u32;
 
-            for (let i = 0; i < word_count; i++) {
-                upload_buffer.writeUint32(0);
-            }
+            this.#fill_freed_record(words, existing_record / WORD_SIZE + 1, word_count);
 
-            upload_buffer.position = tail;
             return;
         }
 
-        upload_buffer.writeUint32(element_index);
-        for (let i = 0; i < word_count; i++) {
-            upload_buffer.writeUint32(0);
-        }
+        // Reserve the whole record before taking views over the buffer — this is the call that
+        // can move the storage they would be over. Records are whole words, so the tail is a
+        // word boundary.
+        const record_end = tail + (1 + word_count) * WORD_SIZE;
+
+        upload_buffer.ensureCapacity(record_end);
+
+        const words = this.#upload_words.over(upload_buffer.data).u32;
+        const id_word = tail / WORD_SIZE;
+
+        words[id_word] = element_index;
+
+        this.#fill_freed_record(words, id_word + 1, word_count);
+
+        upload_buffer.position = record_end;
 
         this.#pending_records = u32_index_set(this.#pending_records, element_index, tail);
     }
 
+    /**
+     * Write a freed record into a queued slot of {@link element_upload_buffer}: zeros, with
+     * {@link GPU_DATABASE_NULL} in every one of the {@link null_words}.
+     *
+     * @param {Uint32Array} words word view over the stream
+     * @param {number} value_word where the record's value starts, in words
+     * @param {number} word_count the record's length, in words
+     */
+    #fill_freed_record(words, value_word, word_count) {
+        for (let w = value_word, end = value_word + word_count; w < end; w++) {
+            words[w] = 0;
+        }
+
+        const null_words = this.null_words;
+
+        for (let i = 0; i < null_words.length; i++) {
+            words[value_word + null_words[i]] = GPU_DATABASE_NULL;
+        }
+    }
+
+    /**
+     * One `u32` word of an occupied row's record, from the CPU shadow: a field read without
+     * deserializing the record, at the word a link or range declaration names — or a field's
+     * `offset / 4`. The shadow holds the bytes the row's next upload copies from, so this is what the
+     * GPU holds once the database has been updated. `undefined` for a free row, as {@link get} is.
+     *
+     * @param {number} element_index
+     * @param {number} word offset from the start of the record, in `u32` words
+     * @returns {number|undefined}
+     */
+    get_word(element_index, word) {
+        if (!this.occupancy.get(element_index)) {
+            return undefined;
+        }
+
+        const descriptor = this.descriptor;
+        const elements_per_page = descriptor.elements_per_page;
+        const record_words = descriptor.packed_element_size_bytes / WORD_SIZE;
+
+        assert.isNonNegativeInteger(word, 'word');
+        assert.lessThan(word, record_words, 'word');
+
+        const page = this.pages.get(Math.floor(element_index / elements_per_page));
+
+        assert.defined(page.cpu_data_buffer, `page ${page.index} of '${descriptor.name}' has no CPU shadow — was the table unmapped?`);
+
+        return page.words.over(page.cpu_data_buffer).u32[page.cpu_data_address / WORD_SIZE + (element_index % elements_per_page) * record_words + word];
+    }
+
     /**
      * Reads CPU-resident data, or whatever is in the upload buffer if the element is not CPU-resident.
      *
@@ -519,6 +896,20 @@ export class GPUTypedTable {
      * @throws {Error} if the element is not CPU-resident and not in the upload buffer
      */
     get(element_index) {
+        if (!this.occupancy.get(element_index)) {
+            /**
+             * A freed row is not a record. {@link remove} zero-fills the shadow bytes and clears the
+             * bit but leaves the page allocated, so reading the bytes back gave a fully-formed
+             * record of zeros — against the `@returns {T|undefined}` one line above, which callers
+             * have been written to. Zero is a valid row index, so a caller walking a linked chain
+             * out of such a record walks to row 0 and back to row 0, forever.
+             *
+             * The occupancy bit is already the authority `#resolve` and `debug_table_read_all` read;
+             * the marshalling paths that deliberately ignore it do not come through here.
+             */
+            return undefined;
+        }
+
         const page_index = Math.floor(element_index / this.descriptor.elements_per_page);
         const page = this.pages.get(page_index);
 
@@ -641,6 +1032,8 @@ export class GPUTypedTable {
             page.cpu_data_buffer = new ArrayBuffer(this.descriptor.page_byte_size);
         }
 
+        this.#null_fill_page(page);
+
         this.pages.set(page_index, page);
 
         this.cpu_dirty_pages.set(page_index, true);
@@ -667,9 +1060,16 @@ export class GPUTypedTable {
         const record_size = this.descriptor.packed_element_size_bytes;
         SCRATCH_BUFFER.fromArrayBuffer(page.cpu_data_buffer);
         const in_page_index = element_index % this.descriptor.elements_per_page;
-        SCRATCH_BUFFER.position = page.cpu_data_address + in_page_index * record_size;
+        const shadow_record_start = page.cpu_data_address + in_page_index * record_size;
+        SCRATCH_BUFFER.position = shadow_record_start;
         write_wgsl_type_value(value, SCRATCH_BUFFER, type);
 
+        // The shadow is now the row's whole truth, including any field `value` did not carry:
+        // write_wgsl_type_value skips an undefined field, which on the shadow is exactly right —
+        // the row keeps what it had. The upload record is what that same skip used to corrupt, so
+        // it is copied from here rather than written a second time; see below.
+        const shadow_bytes = new Uint8Array(page.cpu_data_buffer, shadow_record_start, record_size);
+
         page.cpu_version++;
 
         if (!was_occupied) {
@@ -703,23 +1103,36 @@ export class GPUTypedTable {
 
         const dedup_record_start = this.#pending_record_offset(element_index);
 
+        /*
+         The record is copied from the shadow rather than written from `value` a second time.
+
+         A value is allowed to omit fields — write_wgsl_type_value skips an undefined one, and
+         several callers rely on that — and on the shadow the skip means "keep what the row had".
+         On the upload stream it meant "keep whatever bytes were at this offset", because the
+         record is appended into capacity BinaryBuffer never zeroes and GPUDatabase rewinds the
+         stream by setting position = 0 each frame. So a partial set shipped a previous frame's
+         record fragment: for {a: u32, b: u32}, set(0, {a:1, b:2}) one frame and set(5, {a:7}) the
+         next put b = 2 into row 5 on the GPU while row 5's shadow correctly kept its own b. Every
+         later CPU read said one thing and every shader said another, silently and frame-dependently.
+
+         The shadow is already correct at this point, which is the rule set_bytes follows.
+        */
         if (dedup_record_start >= 0) {
             // Overwrite the existing record's value section, then restore the tail so subsequent
             // writes still append at the end.
             upload_buffer.position = dedup_record_start + value_offset;
 
-            write_wgsl_type_value(value, upload_buffer, type);
+            upload_buffer.writeBytes(shadow_bytes, 0, record_size);
 
             upload_buffer.position = tail;
         } else {
-            // Reserve the whole stride up front. The writes below only reach the last
-            // field, so on a type with tail padding they would leave the buffer short of
-            // the tail we are about to move `position` to — and `position` is what
-            // GPUDatabase.update copies out to, past the end of `data`.
+            // Reserve the whole stride up front, so a type with tail padding does not leave the
+            // buffer short of the tail we are about to move `position` to — and `position` is
+            // what GPUDatabase.update copies out to, past the end of `data`.
             upload_buffer.ensureCapacity(tail + step_size);
 
             upload_buffer.writeUint32(element_index);
-            write_wgsl_type_value(value, upload_buffer, type);
+            upload_buffer.writeBytes(shadow_bytes, 0, record_size);
             upload_buffer.position = tail + step_size;
 
             this.#pending_records = u32_index_set(this.#pending_records, element_index, tail);
@@ -1286,6 +1699,23 @@ export class GPUTypedTable {
         }
     }
 
+    /**
+     * Whether anything written to this table has yet to reach the GPU: a record or a range in
+     * either upload stream, a page whose header the GPU holds stale, or a page it has not been
+     * given a slot for. Exactly what {@link GPUDatabase.update} consumes and clears.
+     *
+     * A freed row counts. {@link remove} writes no record of its own, but it queues a zeroed one
+     * and marks the page's header, and until those go up the GPU holds the row as it was.
+     *
+     * @returns {boolean}
+     */
+    get has_pending_upload() {
+        return this.element_upload_buffer.position !== 0
+            || this.partial_upload_descriptors.position !== 0
+            || this.header_dirty_pages.size() !== 0
+            || this.cpu_dirty_pages.size() !== 0;
+    }
+
     /**
      * @return {number} number of occupied element slots
      */

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

@@ -1 +1 @@
-{"version":3,"file":"GPUTypedTableDescriptor.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUTypedTableDescriptor.js"],"names":[],"mappings":"AAQA;;GAEG;AAGH;IA+FI;;;;;;;OAOG;IACH,kBANW,UAAU,oBACV,MAAM,eACN,MAAM,EA4ChB;IA9ID;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;OAEG;IACH,MAFU,UAAU,CAEf;IAEL;;;OAGG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;;;;OAMG;IACH,2BAFU,MAAM,CAEc;IAE9B;;;;;OAKG;IACH,wBAFU,MAAM,CAEW;IAE3B;;;;;;OAMG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;OASG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,gCAEC;IAED;;;;;OAKG;IACH,qCAEC;IAED;;;OAGG;IACH,6BAEC;IAkFD;;;OAGG;IACH,4BAKC;IAED;;;;;;;;OAQG;IACH,+BAKC;IAED;;;OAGG;IACH,6BAKC;IAED;;;;;;;;;;;;;;OAcG;IACH,4BARW,MAAM,OACN,OAAO,GAKL,SAAS,CAUrB;IAED;;;;;;OAMG;IACH,6BAHW,MAAM,GACJ,SAAS,CASrB;IAED;;;OAGG;IACH,8BAYC;IAED;;;OAGG;IACH,sCAEC;IAED;;;;;OAKG;IACH,yCAEC;IAED;;;OAGG;IACH,uCAEC;IAED;;;;;OAKG;IACH,2CAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,0CAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,0CARW,MAAM,OACN,OAAO,GAKL,MAAM,CAOlB;IAED;;;;;;OAMG;IACH,wBANW,OAAO,GAIL,SAAS,CAyBrB;IAED;;;OAGG;IACH,uBAFa,SAAS,CAqBrB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+DG;IACH,oCARW,MAAM,OACN,OAAO,GAKL,SAAS,CAwOrB;IAED;;;;;;;;;;;;;OAaG;IACH,qCAHW,MAAM,GACJ,SAAS,CAqCrB;IAED;;;;;;;;;;;;;;;OAeG;IACH,sCAHW,MAAM,GACJ,SAAS,CAmCrB;IA2BD;;;;OAIG;IACH,cAHW,uBAAuB,GACtB,OAAO,CAMlB;IAED,eAEC;IAED,mBAEC;IAGL;;;OAGG;IACH,oCAFU,OAAO,CAE0C;;CAN1D;yBA70BY,OAAO,iCAAiC,EAAE,UAAU;0BAPvC,oCAAoC"}
+{"version":3,"file":"GPUTypedTableDescriptor.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUTypedTableDescriptor.js"],"names":[],"mappings":"AAQA;;GAEG;AAGH;IA+FI;;;;;;;OAOG;IACH,kBANW,UAAU,oBACV,MAAM,eACN,MAAM,EA4ChB;IA9ID;;;OAGG;IACH,MAFU,MAAM,CAEN;IAEV;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;OAEG;IACH,MAFU,UAAU,CAEf;IAEL;;;OAGG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;;;;OAMG;IACH,2BAFU,MAAM,CAEc;IAE9B;;;;;OAKG;IACH,wBAFU,MAAM,CAEW;IAE3B;;;;;;OAMG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;OASG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,gCAEC;IAED;;;;;OAKG;IACH,qCAEC;IAED;;;OAGG;IACH,6BAEC;IAkFD;;;OAGG;IACH,4BAKC;IAED;;;;;;;;OAQG;IACH,+BAKC;IAED;;;OAGG;IACH,6BAKC;IAED;;;;;;;;;;;;;;OAcG;IACH,4BARW,MAAM,OACN,OAAO,GAKL,SAAS,CAUrB;IAED;;;;;;OAMG;IACH,6BAHW,MAAM,GACJ,SAAS,CASrB;IAED;;;OAGG;IACH,8BAYC;IAED;;;OAGG;IACH,sCAEC;IAED;;;;;OAKG;IACH,yCAEC;IAED;;;OAGG;IACH,uCAEC;IAED;;;;;OAKG;IACH,2CAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;OAKG;IACH,0CAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,0CARW,MAAM,OACN,OAAO,GAKL,MAAM,CAOlB;IAED;;;;;;OAMG;IACH,wBANW,OAAO,GAIL,SAAS,CAyBrB;IAED;;;OAGG;IACH,uBAFa,SAAS,CAqBrB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+DG;IACH,oCARW,MAAM,OACN,OAAO,GAKL,SAAS,CAwOrB;IAED;;;;;;;;;;;;;OAaG;IACH,qCAHW,MAAM,GACJ,SAAS,CAqCrB;IAED;;;;;;;;;;;;;;;OAeG;IACH,sCAHW,MAAM,GACJ,SAAS,CAmCrB;IAkDD;;;;OAIG;IACH,cAHW,uBAAuB,GACtB,OAAO,CAMlB;IAED,eAEC;IAED,mBAEC;IAGL;;;OAGG;IACH,oCAFU,OAAO,CAE0C;;CAN1D;yBAp2BY,OAAO,iCAAiC,EAAE,UAAU;0BAPvC,oCAAoC"}