@woosh/meep-engine 3.49.0 → 3.50.0

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

@@ -24,7 +24,8 @@ const DESCRIPTOR_CHUNK_BYTES = 256 * 1024;
 const GATHER_SIZE_GRANULARITY = 1024;
 
 /**
- * Requests at or above which a batch is gathered by a dispatch rather than copied range by range.
+ * Copies at or above which a batch is gathered by a dispatch rather than copied range by range —
+ * one per single request, and per row of a run (a run of whole records: per page it touches).
  *
  * **Measured, not chosen**, on a real device: Chrome 141 / Dawn, NVIDIA Lovelace, reading a 64-byte
  * range out of each of N 176-byte rows spread across 4 KiB pages. Best of five blocks of a hundred
@@ -83,17 +84,40 @@ const INITIAL_CAPACITY = 64;
 
 /*
  * One request is RECORD_WORDS words of the flat record array, at handle * RECORD_WORDS. The first
- * six are written by `request`, the last two by `encode`.
+ * seven are written by `request_run`, the last two by `encode`. A request is a run of rows — one
+ * row for `request` — and the word offset and count are per row.
  */
 const R_TABLE = 0;
 const R_ROW = 1;
-const R_WORD_OFFSET = 2;
-const R_WORD_COUNT = 3;
-const R_GENERATION = 4;
-const R_TARGET_OFFSET = 5;
-const R_SOURCE_WORD = 6;
-const R_DESTINATION_WORD = 7;
-const RECORD_WORDS = 8;
+const R_ROW_COUNT = 2;
+const R_WORD_OFFSET = 3;
+const R_WORD_COUNT = 4;
+const R_GENERATION = 5;
+const R_TARGET_OFFSET = 6;
+const R_SOURCE_WORD = 7;
+const R_DESTINATION_WORD = 8;
+const RECORD_WORDS = 9;
+
+/**
+ * The generations of a run's rows, summed mod 2^32 — one word that tells whether any row of the run
+ * was freed between two moments. Every free adds exactly one to its row's generation, and nothing
+ * else changes one, so the sum moves by the number of frees in the run and comes back only after
+ * 2^32 of them: an exact test, where a hash of the generations would be a probable one.
+ *
+ * @param {import("./GPUTypedTable.js").GPUTypedTable} table
+ * @param {number} first_row
+ * @param {number} row_count
+ * @returns {number}
+ */
+function generation_sum(table, first_row, row_count) {
+    let sum = 0;
+
+    for (let i = 0; i < row_count; i++) {
+        sum = (sum + table.generation_of(first_row + i)) >>> 0;
+    }
+
+    return sum;
+}
 
 /**
  * @enum {number}
@@ -128,11 +152,26 @@ class GPUReadbackBatch {
     count = 0;
 
     /**
-     * Requests whose row was resident when the batch was encoded.
+     * Requests whose rows were all resident when the batch was encoded.
      * @type {number}
      */
     live = 0;
 
+    /**
+     * Rows of the live requests: one gather descriptor each.
+     * @type {number}
+     */
+    rows = 0;
+
+    /**
+     * `copyBufferToBuffer` calls the live requests would take on the copy path — what the gather
+     * threshold is measured against. One per row, except that a run of whole records is one per
+     * page it crosses, since its rows sit back to back there.
+     *
+     * @type {number}
+     */
+    copies = 0;
+
     /**
      * Bytes of the packed image.
      * @type {number}
@@ -207,6 +246,14 @@ class GPUReadbackBatch {
  * shader packs a batch contiguously in request order, so a consumer's run of rows lands in its
  * destination as one `set` — which a per-row function could never have done.
  *
+ * **A run is one request.** {@link request_run} asks for the same byte range of consecutive rows —
+ * the rows of an `add_run`, say — under one handle and one status. It is split at page boundaries
+ * here, never by the caller, and its ranges land back to back in the target. It is all or nothing:
+ * Delivered only when every row is, Dropped when any row is (not resident at encode, not occupied,
+ * or freed while in flight), and it counts once in {@link delivered_count}, {@link dropped_count}
+ * and {@link stalled_count}. A run of whole records is one copy per page it touches rather than one
+ * per row.
+ *
  * **Gather, then one copy.** Rows sit at scattered offsets across pages, so a compute shader packs
  * the requested ranges contiguously before a single copy into a readback buffer. Packing a *range*
  * rather than a record is what makes it worth doing: an entity's world matrix is 64 bytes of a
@@ -382,7 +429,7 @@ export class GPUDatabaseReadback {
      * @param {Object} options
      * @param {import("./GPUDatabase.js").GPUDatabase} options.database
      * @param {GPUDevice} options.device
-     * @param {number} [options.gather_threshold] requests at or above which a dispatch is used
+     * @param {number} [options.gather_threshold] copies at or above which a dispatch is used
      * @param {number} [options.max_in_flight] batches in flight before a frame's requests are dropped
      * @param {string} [options.label]
      */
@@ -410,7 +457,8 @@ export class GPUDatabaseReadback {
     }
 
     /**
-     * Requests at or above which a batch is gathered rather than copied range by range.
+     * Copies at or above which a batch is gathered rather than copied range by range — see
+     * {@link DEFAULT_GATHER_THRESHOLD} for what counts as one.
      * @returns {number}
      */
     get gather_threshold() {
@@ -557,8 +605,33 @@ export class GPUDatabaseReadback {
      * @returns {number} a handle into {@link status}, valid until the frame after its result lands
      */
     request(table, row, byte_offset, byte_size, target, target_byte_offset = 0) {
+        return this.request_run(table, row, 1, byte_offset, byte_size, target, target_byte_offset);
+    }
+
+    /**
+     * Ask for the same byte range of `row_count` consecutive rows, landing back to back in `target`
+     * from `target_byte_offset` — row `first_row + i`'s range at `target_byte_offset + i * byte_size`
+     * — under one handle.
+     *
+     * The run may cross pages; it is split at their boundaries here. Its status is
+     * {@link GPUReadbackStatus.Delivered} only when every row was delivered, and
+     * {@link GPUReadbackStatus.Dropped} when any row was dropped — a page not resident or a row not
+     * occupied when the batch was encoded, a row freed while it was in flight, or the pipeline full
+     * — and then nothing of it is written.
+     *
+     * @param {number} table from {@link table}
+     * @param {number} first_row
+     * @param {number} row_count at least 1
+     * @param {number} byte_offset within each record, word-aligned
+     * @param {number} byte_size per row, a positive multiple of the word size
+     * @param {Uint8Array} target memory the caller owns and keeps, as for {@link request}
+     * @param {number} target_byte_offset where the first row's range lands
+     * @returns {number} a handle into {@link status}, valid until the frame after its result lands
+     */
+    request_run(table, first_row, row_count, byte_offset, byte_size, target, target_byte_offset) {
         assert.isNonNegativeInteger(table, 'table');
-        assert.isNonNegativeInteger(row, 'row');
+        assert.isNonNegativeInteger(first_row, 'first_row');
+        assert.isPositiveInteger(row_count, 'row_count');
         assert.isNonNegativeInteger(byte_offset, 'byte_offset');
         assert.isPositiveInteger(byte_size, 'byte_size');
         assert.isNonNegativeInteger(target_byte_offset, 'target_byte_offset');
@@ -573,17 +646,18 @@ export class GPUDatabaseReadback {
         // constant messages: these run per row per frame, and a template literal built to describe a
         // failure that does not happen is the cost on the path being measured
         assert.lessThanOrEqual(byte_offset + byte_size, tables[table].descriptor.packed_element_size_bytes, 'range reaches past the record');
-        assert.lessThanOrEqual(target_byte_offset + byte_size, target.length, 'range reaches past the target');
+        assert.lessThanOrEqual(target_byte_offset + row_count * byte_size, target.length, 'range reaches past the target');
 
         const handle = this.#allocate_handle();
         const base = handle * RECORD_WORDS;
         const records = this.#records;
 
         records[base + R_TABLE] = table;
-        records[base + R_ROW] = row;
+        records[base + R_ROW] = first_row;
+        records[base + R_ROW_COUNT] = row_count;
         records[base + R_WORD_OFFSET] = byte_offset / WORD_SIZE;
         records[base + R_WORD_COUNT] = byte_size / WORD_SIZE;
-        records[base + R_GENERATION] = tables[table].generation_of(row);
+        records[base + R_GENERATION] = generation_sum(tables[table], first_row, row_count);
         records[base + R_TARGET_OFFSET] = target_byte_offset;
 
         this.#targets[handle] = target;
@@ -729,7 +803,7 @@ export class GPUDatabaseReadback {
 
         batch.buffer = this.#allocator.get(batch.byte_size);
 
-        if (live < this.#gather_threshold) {
+        if (batch.copies < this.#gather_threshold) {
             this.#encode_copies(encoder, batch);
         } else {
             this.#encode_gather(encoder, batch);
@@ -758,13 +832,15 @@ export class GPUDatabaseReadback {
      * table and the page are looked up when they change rather than per request. Live requests are
      * counted per table on the way through, which is all the gather path's bucketing needs.
      *
+     * A run is walked page by page, and is dropped whole if any page it touches is not resident or
+     * any of its rows is not occupied. Only its first row's source is kept; the copy path finds the
+     * pages after that one again.
+     *
      * @param {GPUReadbackBatch} batch
      * @returns {number} live requests
      */
     #resolve(batch) {
-        const database = this.#database;
-        const tables = database.tables;
-        const data_start = database.data_start_offset;
+        const tables = this.#database.tables;
 
         const records = this.#records;
         const status = this.#status;
@@ -777,11 +853,12 @@ export class GPUDatabaseReadback {
 
         let destination = 0;
         let live = 0;
+        let rows = 0;
+        let copies = 0;
         let dropped = 0;
 
         let table_index = -1;
         let table = null;
-        let descriptor = null;
         let elements_per_page = 0;
         let record_words = 0;
 
@@ -793,67 +870,104 @@ export class GPUDatabaseReadback {
             const base = handle * RECORD_WORDS;
 
             const t = records[base + R_TABLE];
-            const row = records[base + R_ROW];
+            const first_row = records[base + R_ROW];
+            const row_count = records[base + R_ROW_COUNT];
+            const end_row = first_row + row_count;
 
             if (t !== table_index) {
                 table_index = t;
                 table = tables[t];
-                descriptor = table.descriptor;
-                elements_per_page = descriptor.elements_per_page;
-                record_words = descriptor.packed_element_size_bytes / WORD_SIZE;
+                elements_per_page = table.descriptor.elements_per_page;
+                record_words = table.descriptor.packed_element_size_bytes / WORD_SIZE;
                 page_index = -1;
             }
 
-            const p = Math.floor(row / elements_per_page);
+            let source = -1;
+            let pages = 0;
+
+            for (let row = first_row; row < end_row; row = (page_index + 1) * elements_per_page) {
+                const p = Math.floor(row / elements_per_page);
+
+                if (p !== page_index) {
+                    page_index = p;
+                    page_base = this.#page_base(table, p);
+                }
 
-            if (p !== page_index) {
-                page_index = p;
+                if (page_base === -1) {
+                    break;
+                }
 
-                const page = table.pages.get(p);
+                if (source === -1) {
+                    source = page_base + (row - p * elements_per_page) * record_words;
+                }
 
-                page_base = (page === undefined || page.slot_offset === -1)
-                    ? -1
-                    : page.slot_offset + data_start + descriptor.page_header_words;
+                pages++;
             }
 
-            if (page_base === -1 || !table.occupancy.get(row)) {
-                // the page is not on the GPU, or the row was removed and its bytes are whatever the
-                // last occupant left
+            if (page_base === -1 || table.occupancy.nextClearBit(first_row) < end_row) {
+                // a page is not on the GPU, or a row was removed and its bytes are whatever the last
+                // occupant left
                 status[handle] = GPUReadbackStatus.Dropped;
                 dropped++;
 
                 continue;
             }
 
-            records[base + R_SOURCE_WORD] = page_base
-                + (row - page_index * elements_per_page) * record_words
-                + records[base + R_WORD_OFFSET];
+            const word_count = records[base + R_WORD_COUNT];
+
+            records[base + R_SOURCE_WORD] = source + records[base + R_WORD_OFFSET];
             records[base + R_DESTINATION_WORD] = destination;
 
-            destination += records[base + R_WORD_COUNT];
+            destination += row_count * word_count;
 
             live++;
+            rows += row_count;
+            copies += word_count === record_words ? pages : row_count;
             starts[t + 1]++;
         }
 
         this.#dropped_count += dropped;
 
         batch.live = live;
+        batch.rows = rows;
+        batch.copies = copies;
         batch.byte_size = destination * WORD_SIZE;
 
         return live;
     }
 
+    /**
+     * Where a page's records start in the database buffer, in words.
+     *
+     * @param {import("./GPUTypedTable.js").GPUTypedTable} table
+     * @param {number} page_index
+     * @returns {number} or -1 when the page is not on the GPU
+     */
+    #page_base(table, page_index) {
+        const page = table.pages.get(page_index);
+
+        if (page === undefined || page.slot_offset === -1) {
+            return -1;
+        }
+
+        return page.slot_offset + this.#database.data_start_offset + table.descriptor.page_header_words;
+    }
+
     /**
      * Copy each range straight out of the database into its place in the image. No shader, no
      * descriptor upload, no bind group — which below the threshold is cheaper than all three.
      *
+     * A run is copied page by page: its rows' ranges one at a time, or — when the range is the
+     * whole record — each page's stretch of the run as one copy, since its records are back to back
+     * there just as they are in the image.
+     *
      * @param {import("../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} encoder
      * @param {GPUReadbackBatch} batch
      */
     #encode_copies(encoder, batch) {
         const source = this.#database.buffer;
         const destination = batch.buffer;
+        const tables = this.#database.tables;
 
         const records = this.#records;
         const status = this.#status;
@@ -871,15 +985,58 @@ export class GPUDatabaseReadback {
 
             const base = handle * RECORD_WORDS;
 
-            encoder.copyBufferToBuffer(
-                source,
-                records[base + R_SOURCE_WORD] * WORD_SIZE,
-                destination,
-                records[base + R_DESTINATION_WORD] * WORD_SIZE,
-                records[base + R_WORD_COUNT] * WORD_SIZE,
-            );
+            const word_count = records[base + R_WORD_COUNT];
+            const row_count = records[base + R_ROW_COUNT];
+
+            let source_word = records[base + R_SOURCE_WORD];
+            let destination_word = records[base + R_DESTINATION_WORD];
+
+            if (row_count === 1) {
+                encoder.copyBufferToBuffer(source, source_word * WORD_SIZE, destination, destination_word * WORD_SIZE, word_count * WORD_SIZE);
+
+                copies++;
 
-            copies++;
+                continue;
+            }
+
+            const table = tables[records[base + R_TABLE]];
+            const elements_per_page = table.descriptor.elements_per_page;
+            const record_words = table.descriptor.packed_element_size_bytes / WORD_SIZE;
+            const whole = word_count === record_words;
+
+            const end_row = records[base + R_ROW] + row_count;
+
+            let row = records[base + R_ROW];
+
+            while (row < end_row) {
+                const page_index = Math.floor(row / elements_per_page);
+                const page_end = Math.min(end_row, (page_index + 1) * elements_per_page);
+                const in_page = page_end - row;
+
+                if (whole) {
+                    encoder.copyBufferToBuffer(source, source_word * WORD_SIZE, destination, destination_word * WORD_SIZE, in_page * record_words * WORD_SIZE);
+
+                    copies++;
+                } else {
+                    for (let k = 0; k < in_page; k++) {
+                        encoder.copyBufferToBuffer(
+                            source, (source_word + k * record_words) * WORD_SIZE,
+                            destination, (destination_word + k * word_count) * WORD_SIZE,
+                            word_count * WORD_SIZE,
+                        );
+                    }
+
+                    copies += in_page;
+                }
+
+                destination_word += in_page * word_count;
+                row = page_end;
+
+                if (row < end_row) {
+                    // resolved resident a moment ago, in this same encode
+                    source_word = this.#page_base(table, page_index + 1) + records[base + R_WORD_OFFSET];
+                }
+            }
         }
 
         this.#copies_encoded += copies;
@@ -942,7 +1099,8 @@ export class GPUDatabaseReadback {
         const descriptor_stride = GPU_TABLE_GATHER_DESCRIPTOR_WORDS;
         const max_per_chunk = Math.max(1, Math.floor(DESCRIPTOR_CHUNK_BYTES / (descriptor_stride * WORD_SIZE)));
 
-        const scratch_words = Math.min(live, max_per_chunk) * descriptor_stride;
+        // a descriptor per row: the shader finds each row's page itself, so a run needs no splitting
+        const scratch_words = Math.min(batch.rows, max_per_chunk) * descriptor_stride;
 
         if (this.#descriptor_scratch.length < scratch_words) {
             this.#descriptor_scratch = new Uint32Array(scratch_words);
@@ -972,18 +1130,27 @@ export class GPUDatabaseReadback {
 
             for (let i = run_start; i < run_end; i++) {
                 const base = order[i] * RECORD_WORDS;
-                const d = filled * descriptor_stride;
 
-                scratch[d] = records[base + R_ROW];
-                scratch[d + 1] = records[base + R_WORD_OFFSET];
-                scratch[d + 2] = records[base + R_WORD_COUNT];
-                scratch[d + 3] = records[base + R_DESTINATION_WORD];
+                const first_row = records[base + R_ROW];
+                const row_count = records[base + R_ROW_COUNT];
+                const word_offset = records[base + R_WORD_OFFSET];
+                const word_count = records[base + R_WORD_COUNT];
+                const destination = records[base + R_DESTINATION_WORD];
+
+                for (let k = 0; k < row_count; k++) {
+                    const d = filled * descriptor_stride;
+
+                    scratch[d] = first_row + k;
+                    scratch[d + 1] = word_offset;
+                    scratch[d + 2] = word_count;
+                    scratch[d + 3] = destination + k * word_count;
 
-                filled++;
+                    filled++;
 
-                if (filled === max_per_chunk) {
-                    this.#dispatch_gather(encoder, scratch, filled, settings, gather_buffer);
-                    filled = 0;
+                    if (filled === max_per_chunk) {
+                        this.#dispatch_gather(encoder, scratch, filled, settings, gather_buffer);
+                        filled = 0;
+                    }
                 }
             }
 
@@ -1103,11 +1270,11 @@ export class GPUDatabaseReadback {
             }
 
             const base = handle * RECORD_WORDS;
-            const row = records[base + R_ROW];
+            const row_count = records[base + R_ROW_COUNT];
 
-            if (tables[records[base + R_TABLE]].generation_of(row) !== records[base + R_GENERATION]) {
-                // the row was freed while this was in flight, and an id freed is an id already
-                // handed out again — answering would be answering about a stranger
+            if (generation_sum(tables[records[base + R_TABLE]], records[base + R_ROW], row_count) !== records[base + R_GENERATION]) {
+                // a row was freed while this was in flight, and an id freed is an id already handed
+                // out again — answering would be answering about a stranger
                 status[handle] = GPUReadbackStatus.Dropped;
                 dropped++;
 
@@ -1115,7 +1282,7 @@ export class GPUDatabaseReadback {
             }
 
             const source = records[base + R_DESTINATION_WORD] * WORD_SIZE;
-            const length = records[base + R_WORD_COUNT] * WORD_SIZE;
+            const length = row_count * records[base + R_WORD_COUNT] * WORD_SIZE;
             const target = targets[handle];
             const target_offset = records[base + R_TARGET_OFFSET];
 
@@ -1217,6 +1384,8 @@ export class GPUDatabaseReadback {
 
         batch.count = 0;
         batch.live = 0;
+        batch.rows = 0;
+        batch.copies = 0;
         batch.byte_size = 0;
         batch.state = BatchState.Assembling;
 

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

@@ -145,6 +145,18 @@ export class GPUTypedTable<T> {
      * @returns {number} the run's first row, or {@link GPU_DATABASE_NULL} for no values
      */
     add_run_records(values: T[], writer: GPURecordWriter): number;
+    /**
+     * A run of `count` rows each written from the same `value`, through a generated writer: what
+     * {@link add_run_records} would do with an array of `count` copies, without the array. For the
+     * rows of a run a shader fills — the GPU fluid's lattice samples — whose size changes with every
+     * call, so no caller-held array of values could be the right length.
+     *
+     * @param {number} count at least 1
+     * @param {T} value
+     * @param {GPURecordWriter} writer generated against this table's type
+     * @returns {number} the run's first row
+     */
+    add_run_filled(count: number, value: T, writer: GPURecordWriter): number;
     /**
      * Remove an element from the table, freeing its slot — and every row it owns.
      *

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":"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"}
+{"version":3,"file":"GPUTypedTable.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/GPUTypedTable.js"],"names":[],"mappings":"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"}

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

@@ -391,6 +391,29 @@ export class GPUTypedTable {
         return first;
     }
 
+    /**
+     * A run of `count` rows each written from the same `value`, through a generated writer: what
+     * {@link add_run_records} would do with an array of `count` copies, without the array. For the
+     * rows of a run a shader fills — the GPU fluid's lattice samples — whose size changes with every
+     * call, so no caller-held array of values could be the right length.
+     *
+     * @param {number} count at least 1
+     * @param {T} value
+     * @param {GPURecordWriter} writer generated against this table's type
+     * @returns {number} the run's first row
+     */
+    add_run_filled(count, value, writer) {
+        assert.isPositiveInteger(count, 'count');
+
+        const first = this.#find_run(count);
+
+        for (let i = 0; i < count; i++) {
+            this.set_record(first + i, value, writer);
+        }
+
+        return first;
+    }
+
 
     /**
      * The lowest row where `count` free rows start.
@@ -417,7 +440,9 @@ export class GPUTypedTable {
 
         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`);
+        // a constant message: an interpolated one is built on every call, whether the assertion
+        // holds or not (132 bytes a run, measured on the GPU fluid's read API)
+        assert.lessThanOrEqual(start + count, descriptor.page_limit * descriptor.elements_per_page, 'the run does not fit in the table below its page limit');
 
         return start;
     }
@@ -1162,10 +1187,10 @@ export class GPUTypedTable {
     set_record(element_index, value, writer) {
         assert.isNonNegativeInteger(element_index, 'element_index');
         assert.defined(writer, 'writer');
-        // The message names no type: `WebGPUType.toString` rebuilds the struct's whole WGSL
-        // declaration, and an interpolation is evaluated whether the assertion holds or not — which
-        // put a code generator on the per-row write path, where a writer exists to take one off.
-        assert.equal(writer.type, this.descriptor.type, `writer was generated against a type other than '${this.descriptor.name}''s — its field offsets would land anywhere in a record of this one`);
+        // The message is a constant: an interpolation is evaluated whether the assertion holds or
+        // not, and naming the type rebuilt its whole WGSL declaration per row; naming the table
+        // still built a string a row (64 bytes a call, GPUTypedTable.set_record.allocation.spec.js).
+        assert.equal(writer.type, this.descriptor.type, 'writer was generated against a type other than the table\'s — its field offsets would land anywhere in a record of this one');
 
         const descriptor = this.descriptor;
         const record_size = descriptor.packed_element_size_bytes;
@@ -1215,10 +1240,20 @@ export class GPUTypedTable {
         }
 
         // A partial writer leaves the row's other fields in the shadow. Publish that whole
-        // record, rather than leaving the upload slot's previous occupant in those fields.
-        new Uint8Array(upload_buffer.data, record_start + u32.size, record_size).set(
-            new Uint8Array(page.cpu_data_buffer, page.cpu_data_address + in_page_index * record_size, record_size)
-        );
+        // record, rather than leaving the upload slot's previous occupant in those fields. Word by
+        // word through the retained views: a byte view each side made per row was ~280 bytes a call
+        // on the per-row write path (GPUTypedTable.set_record.allocation.spec.js). Records are whole
+        // words and the stream's strides are too, so both ends are word-aligned.
+        const upload = this.#upload_words.over(upload_buffer.data).u32;
+        const source = shadow.u32;
+
+        const record_words = record_size / WORD_SIZE;
+        const from = (page.cpu_data_address + in_page_index * record_size) / WORD_SIZE;
+        const to = record_start / WORD_SIZE + 1;
+
+        for (let w = 0; w < record_words; w++) {
+            upload[to + w] = source[from + w];
+        }
     }
 
     /**
@@ -1394,8 +1429,10 @@ export class GPUTypedTable {
     set_fields(element_index, value, writer) {
         assert.isNonNegativeInteger(element_index, 'element_index');
         assert.defined(writer, 'writer');
-        // Naming no type in the message is deliberate — see `set_record`.
-        assert.equal(writer.type, this.descriptor.type, `writer was generated against a type other than '${this.descriptor.name}''s — its field offsets would land anywhere in a record of this one`);
+        // Every message here is a constant, as in `set_record`: an interpolation is evaluated whether
+        // the assertion holds or not, and these four built 216 bytes of strings a row
+        // (GPUTypedTable.set_record.allocation.spec.js) on a path written once a row a frame.
+        assert.equal(writer.type, this.descriptor.type, 'writer was generated against a type other than the table\'s — its field offsets would land anywhere in a record of this one');
 
         const descriptor = this.descriptor;
         const record_size = descriptor.packed_element_size_bytes;
@@ -1403,9 +1440,9 @@ export class GPUTypedTable {
 
         const page = this.pages.get(Math.floor(element_index / elements_per_page));
 
-        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`);
-        assert.defined(page, `page of element ${element_index} of '${descriptor.name}'`);
-        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`);
+        assert.ok(this.occupancy.get(element_index), 'the element is not occupied — a partial write patches a record, it does not create one');
+        assert.defined(page, 'the element\'s page');
+        assert.defined(page.cpu_data_buffer, 'the element\'s page has no CPU shadow — a partial write cannot run against an unmapped page');
 
         const record_byte_base = page.cpu_data_address + (element_index % elements_per_page) * record_size;
         const record_word_base = record_byte_base / WORD_SIZE;

package/src/shade/renderer/camera/CAMERA_RESOURCE.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The camera, as the chunks that read it declare it.
+ * @type {ShaderResourceDescriptor}
+ */
+export const CAMERA_RESOURCE: ShaderResourceDescriptor;
+import { ShaderResourceDescriptor } from "../shader/resource/ShaderResourceDescriptor.js";
+//# sourceMappingURL=CAMERA_RESOURCE.d.ts.map

package/src/shade/renderer/camera/CAMERA_RESOURCE.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CAMERA_RESOURCE.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/camera/CAMERA_RESOURCE.js"],"names":[],"mappings":"AAGA;;;GAGG;AACH,8BAFU,wBAAwB,CAE+D;yCAPxD,gDAAgD"}

package/src/shade/renderer/camera/CAMERA_RESOURCE.js

@@ -0,0 +1,8 @@
+import { ShaderResourceDescriptor } from "../shader/resource/ShaderResourceDescriptor.js";
+import { CAMERA_UNIFORM_STRUCT } from "./CAMERA_UNIFORM_STRUCT.js";
+
+/**
+ * The camera, as the chunks that read it declare it.
+ * @type {ShaderResourceDescriptor}
+ */
+export const CAMERA_RESOURCE = ShaderResourceDescriptor.uniform("camera", CAMERA_UNIFORM_STRUCT);