@woosh/meep-engine 3.23.0 → 3.25.0

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

@@ -0,0 +1,19 @@
+/**
+ * Words per descriptor in the readback gather stream:
+ * `[element_index, word_offset, word_count, destination_offset]`.
+ *
+ * `word_offset` is relative to the start of the record — a caller reading an entity's world matrix
+ * asks for 16 words at the matrix's offset, not the 44 the whole row occupies. `destination_offset`
+ * is an absolute word index into the batch's gather buffer, which every dispatch of a batch binds
+ * whole, so a batch spanning several tables packs into one contiguous image and needs one copy.
+ *
+ * Deliberately the same shape and stride as {@link GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS}: a
+ * partial write and a gathered read are the same address arithmetic run in opposite directions, and
+ * one descriptor layout for both is one thing to get right.
+ *
+ * @see gpu_table_gather_shader
+ * @see GPUDatabaseReadback
+ * @type {number}
+ */
+export const GPU_TABLE_GATHER_DESCRIPTOR_WORDS: number;
+//# sourceMappingURL=GPU_TABLE_GATHER_DESCRIPTOR_WORDS.d.ts.map

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

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

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

@@ -0,0 +1,18 @@
+/**
+ * Words per descriptor in the readback gather stream:
+ * `[element_index, word_offset, word_count, destination_offset]`.
+ *
+ * `word_offset` is relative to the start of the record — a caller reading an entity's world matrix
+ * asks for 16 words at the matrix's offset, not the 44 the whole row occupies. `destination_offset`
+ * is an absolute word index into the batch's gather buffer, which every dispatch of a batch binds
+ * whole, so a batch spanning several tables packs into one contiguous image and needs one copy.
+ *
+ * Deliberately the same shape and stride as {@link GPU_TABLE_PARTIAL_UPLOAD_DESCRIPTOR_WORDS}: a
+ * partial write and a gathered read are the same address arithmetic run in opposite directions, and
+ * one descriptor layout for both is one thing to get right.
+ *
+ * @see gpu_table_gather_shader
+ * @see GPUDatabaseReadback
+ * @type {number}
+ */
+export const GPU_TABLE_GATHER_DESCRIPTOR_WORDS = 4;

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

@@ -0,0 +1,39 @@
+/**
+ * Native-endian `f32` and `u32` views over an `ArrayBuffer`, rebuilt only when the buffer under
+ * them changes.
+ *
+ * A generated record writer addresses its destination by word index rather than walking a
+ * {@link BinaryBuffer} cursor, so it needs both views; building them per call would put an
+ * allocation back onto the path the writer exists to clear. They cannot simply be built once
+ * either — a page's shadow is reallocated when it is materialized, an upload buffer whenever it
+ * grows — so this holds the identity of what it last looked at. That is what lets every call site
+ * say "give me the views over this buffer" without any of the places that *replace* a buffer
+ * having to know that views exist.
+ *
+ * Native endianness is the correct one and not a shortcut: every consumer of these words reads
+ * them as `platform_compute_endianness()` — the two GPU upload streams, and the page shadow the
+ * upload is read back out of.
+ */
+export class WordViews {
+    /**
+     * @type {Float32Array}
+     */
+    f32: Float32Array;
+    /**
+     * @type {Uint32Array}
+     */
+    u32: Uint32Array;
+    /**
+     * Point the views at `buffer`, rebuilding them only if they are not already over it.
+     *
+     * A trailing byte or three is dropped rather than refused — {@link BinaryBuffer.setCapacity}
+     * takes whatever capacity it is handed, and a view is only ever addressed at word offsets the
+     * caller already knows are inside its data.
+     *
+     * @param {ArrayBuffer} buffer
+     * @returns {this}
+     */
+    over(buffer: ArrayBuffer): this;
+    #private;
+}
+//# sourceMappingURL=WordViews.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WordViews.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/buffer/table/WordViews.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH;IAMI;;OAEG;IACH,KAFU,YAAY,CAEQ;IAE9B;;OAEG;IACH,KAFU,WAAW,CAEQ;IAE7B;;;;;;;;;OASG;IACH,aAHW,WAAW,GACT,IAAI,CAgBhB;;CACJ"}

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

@@ -0,0 +1,62 @@
+import { assert } from "../../../../core/assert.js";
+
+const EMPTY = new ArrayBuffer(0);
+
+/**
+ * Native-endian `f32` and `u32` views over an `ArrayBuffer`, rebuilt only when the buffer under
+ * them changes.
+ *
+ * A generated record writer addresses its destination by word index rather than walking a
+ * {@link BinaryBuffer} cursor, so it needs both views; building them per call would put an
+ * allocation back onto the path the writer exists to clear. They cannot simply be built once
+ * either — a page's shadow is reallocated when it is materialized, an upload buffer whenever it
+ * grows — so this holds the identity of what it last looked at. That is what lets every call site
+ * say "give me the views over this buffer" without any of the places that *replace* a buffer
+ * having to know that views exist.
+ *
+ * Native endianness is the correct one and not a shortcut: every consumer of these words reads
+ * them as `platform_compute_endianness()` — the two GPU upload streams, and the page shadow the
+ * upload is read back out of.
+ */
+export class WordViews {
+    /**
+     * @type {ArrayBuffer}
+     */
+    #source = EMPTY;
+
+    /**
+     * @type {Float32Array}
+     */
+    f32 = new Float32Array(EMPTY);
+
+    /**
+     * @type {Uint32Array}
+     */
+    u32 = new Uint32Array(EMPTY);
+
+    /**
+     * Point the views at `buffer`, rebuilding them only if they are not already over it.
+     *
+     * A trailing byte or three is dropped rather than refused — {@link BinaryBuffer.setCapacity}
+     * takes whatever capacity it is handed, and a view is only ever addressed at word offsets the
+     * caller already knows are inside its data.
+     *
+     * @param {ArrayBuffer} buffer
+     * @returns {this}
+     */
+    over(buffer) {
+        if (this.#source === buffer) {
+            return this;
+        }
+
+        assert.defined(buffer, 'buffer');
+
+        const word_count = buffer.byteLength >> 2;
+
+        this.#source = buffer;
+        this.f32 = new Float32Array(buffer, 0, word_count);
+        this.u32 = new Uint32Array(buffer, 0, word_count);
+
+        return this;
+    }
+}

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

@@ -0,0 +1,27 @@
+export const GPU_TABLE_GATHER_SETTINGS_STRUCT: WebGPUStruct;
+/**
+ * Pack requested sub-ranges of scattered database rows into one contiguous image, so that a batch of
+ * readbacks costs one copy and one map instead of one of each per row.
+ *
+ * **Why a shader at all.** Rows a caller asks about sit wherever their pages were allocated, which
+ * is nowhere near each other, and `copyBufferToBuffer` copies one range per call. A hundred rows is
+ * a hundred encoded copies against one dispatch; the dispatch wins as soon as there are enough of
+ * them, and {@link GPUDatabaseReadback} measures where that is and takes the copies below it.
+ *
+ * **Why a range and not a record.** An entity's world matrix is 64 bytes of a 176-byte row. The
+ * descriptor carries `word_offset` and `word_count` so the gather moves what was asked for.
+ *
+ * A thread that cannot resolve its row — page index past the table, page freed since the request was
+ * made — writes nothing at all rather than writing zeros. Its destination words keep whatever the
+ * previous use of the batch buffer left there, which is deliberately indistinguishable from any
+ * other stale value: the guard against acting on one is the request's generation, checked on the CPU
+ * when the result is applied, and a shader-written "missing" marker would be a second, weaker answer
+ * to a question already settled.
+ *
+ * @see GPUDatabaseReadback
+ * @see gpu_table_partial_upload_shader the same addressing run the other way
+ */
+export const gpu_table_gather_shader: ComputeShader;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=gpu_table_gather_shader.d.ts.map

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

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

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

@@ -0,0 +1,117 @@
+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_GATHER_DESCRIPTOR_WORDS } from "./GPU_TABLE_GATHER_DESCRIPTOR_WORDS.js";
+
+export const GPU_TABLE_GATHER_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,
+});
+
+const resources = new ShaderResourceSetDescriptor();
+
+// per-dispatch, 24 bytes, read-only — the same bargain the two upload shaders make: a uniform would
+// cost a transient buffer, a staging buffer and a copy per chunk to carry six integers already known
+// on the CPU at encode time.
+resources.setImmediate('settings', GPU_TABLE_GATHER_SETTINGS_STRUCT);
+
+resources.createGroup()
+    .addStorageBuffer('descriptors', WebGPUArray.from(GPU_DATABASE_BUFFER_ELEMENT_TYPE), false)
+    .addStorageBuffer('database', WebGPUArray.from(GPU_DATABASE_BUFFER_ELEMENT_TYPE), false)
+    .addStorageBuffer('gathered', WebGPUArray.from(GPU_DATABASE_BUFFER_ELEMENT_TYPE), true);
+
+/**
+ * Pack requested sub-ranges of scattered database rows into one contiguous image, so that a batch of
+ * readbacks costs one copy and one map instead of one of each per row.
+ *
+ * **Why a shader at all.** Rows a caller asks about sit wherever their pages were allocated, which
+ * is nowhere near each other, and `copyBufferToBuffer` copies one range per call. A hundred rows is
+ * a hundred encoded copies against one dispatch; the dispatch wins as soon as there are enough of
+ * them, and {@link GPUDatabaseReadback} measures where that is and takes the copies below it.
+ *
+ * **Why a range and not a record.** An entity's world matrix is 64 bytes of a 176-byte row. The
+ * descriptor carries `word_offset` and `word_count` so the gather moves what was asked for.
+ *
+ * A thread that cannot resolve its row — page index past the table, page freed since the request was
+ * made — writes nothing at all rather than writing zeros. Its destination words keep whatever the
+ * previous use of the batch buffer left there, which is deliberately indistinguishable from any
+ * other stale value: the guard against acting on one is the request's generation, checked on the CPU
+ * when the result is applied, and a shader-written "missing" marker would be a second, weaker answer
+ * to a question already settled.
+ *
+ * @see GPUDatabaseReadback
+ * @see gpu_table_partial_upload_shader the same addressing run the other way
+ */
+export const gpu_table_gather_shader = ComputeShader.from({
+    label: `GPUDatabase/Gather readback ranges`,
+    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_GATHER_DESCRIPTOR_WORDS}u;
+
+    let element_id = descriptors[descriptor_offset];
+    let word_offset = descriptors[descriptor_offset + 1u];
+    let word_count = descriptors[descriptor_offset + 2u];
+    let destination_offset = descriptors[descriptor_offset + 3u];
+
+    // A range that reaches past the record would read the next slot and report it as this row. The
+    // CPU asserts this when the request is queued; the guard is here because the cost of getting it
+    // wrong is a plausible-looking answer about the wrong entity.
+    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 request was queued — its last element removed in the same
+    // update cycle. Without this guard the u32 add below wraps and read_offset lands inside the
+    // allocation-table region, which reads back as a page address dressed up as a row.
+    if(page_address == 0xFFFFFFFFu){
+        return;
+    }
+
+    let read_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++){
+        gathered[destination_offset + i] = database[read_offset + i];
+    }
+
+}
+        `
+    ),
+    resources
+});

package/src/shade/renderer/buffer/table/serde/generate_record_writer.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Compile a writer for `field_names` of `type`.
+ *
+ * {@link write_wgsl_type_value} walks the type on every record: a property lookup, a type
+ * dispatch and a `BinaryBuffer` cursor advance per field, per write. The offsets it arrives at are
+ * the same ones every time, so this arrives at them once and emits the stores.
+ *
+ * The fields a caller does *not* name matter as much as the ones it does. A consumer that owns
+ * part of a record — `GPUSceneContext` owns a node's local TRS and its parent row, the GPU owns
+ * the composed matrices — names its own, and gets both a writer that leaves the rest alone and
+ * the byte ranges to tell the GPU about. Naming every field instead gives a whole-record writer,
+ * which is what {@link GPUTypedTable.set} would have produced reflectively.
+ *
+ * @param {WebGPUStruct} type packed struct; offsets are read off its fields as they stand
+ * @param {string[]} [field_names] defaults to every field, in declaration order
+ * @returns {GPURecordWriter}
+ */
+export function generate_record_writer(type: WebGPUStruct, field_names?: string[]): GPURecordWriter;
+/**
+ * A compiled writer for some subset of a record's fields — what {@link GPUTypedTable.set_record}
+ * and {@link GPUTypedTable.set_fields} take in place of walking the type.
+ *
+ * Built by {@link generate_record_writer}; there is no reason to construct one directly.
+ */
+export class GPURecordWriter {
+    /**
+     * The record type this writer was generated against. A table only accepts a writer whose type
+     * is its own — a writer carries hard-coded offsets, so handing one to the wrong table would
+     * scatter fields across a record that has nothing to do with them.
+     *
+     * @type {WebGPUStruct}
+     */
+    type: WebGPUStruct;
+    /**
+     * Names of the fields this writer sets, in ascending offset order. Anything else in the record
+     * is left exactly as it was found, on every destination.
+     *
+     * @type {string[]}
+     */
+    fields: string[];
+    /**
+     * `[byte_offset, byte_length]` pairs covering {@link fields}, ascending and non-touching — the
+     * ranges {@link write_record_and_ranges} lays out, and the descriptors a partial upload
+     * queues for them.
+     *
+     * @type {number[]}
+     */
+    ranges: number[];
+    /**
+     * Total words across {@link ranges} — what one row's update adds to a partial stream's data
+     * blob.
+     *
+     * @type {number}
+     */
+    range_word_count: number;
+    /**
+     * Write the owned fields of `value` into the record starting at word `word_base`.
+     *
+     * The destination is named as a pair of views rather than a buffer because it is not always a
+     * page: the same call patches a whole record already pending in an upload buffer, where the
+     * record starts one word past the element id.
+     *
+     * @type {function(Float32Array, Uint32Array, number, *):void}
+     * @param {Float32Array} f32
+     * @param {Uint32Array} u32
+     * @param {number} word_base word the record starts at
+     * @param {*} value
+     */
+    write_record: (arg0: Float32Array, arg1: Uint32Array, arg2: number, arg3: any) => void;
+    /**
+     * As {@link write_record}, and in the same pass lay {@link ranges} out end to end starting at
+     * `data_word_base` of a partial stream's data blob.
+     *
+     * One pass rather than a write followed by a copy: the ranges of a given struct are fixed when
+     * the writer is generated, so the two destinations of every field are both constants and the
+     * value is only read once.
+     *
+     * @type {function(Float32Array, Uint32Array, number, Float32Array, Uint32Array, number, *):void}
+     * @param {Float32Array} f32
+     * @param {Uint32Array} u32
+     * @param {number} word_base word the record starts at
+     * @param {Float32Array} data_f32
+     * @param {Uint32Array} data_u32
+     * @param {number} data_word_base word the first range is laid out at
+     * @param {*} value
+     */
+    write_record_and_ranges: (arg0: Float32Array, arg1: Uint32Array, arg2: number, arg3: Float32Array, arg4: Uint32Array, arg5: number, arg6: any) => void;
+    /**
+     * Source of the two generated functions, for a spec to read and a developer to print. Not used
+     * at runtime — the functions are already compiled.
+     *
+     * @type {string}
+     */
+    source: string;
+}
+/**
+ * One destination the generated code stores into: a pair of views and the expression giving the
+ * word the record (or the range blob) starts at.
+ */
+export type WriterTarget = {
+    /**
+     * name of the `Float32Array` parameter
+     */
+    f32: string;
+    /**
+     * name of the `Uint32Array` parameter
+     */
+    u32: string;
+    /**
+     * name of the base-word parameter
+     */
+    base: string;
+    /**
+     * maps a byte offset within the record to a word index
+     * relative to `base`
+     */
+    word_of: (arg0: number) => number;
+};
+export type WebGPUType = import("../../../shader/type/WebGPUType.js").WebGPUType;
+export type WebGPUStruct = import("../../../shader/type/WebGPUStruct.js").WebGPUStruct;
+//# sourceMappingURL=generate_record_writer.d.ts.map

package/src/shade/renderer/buffer/table/serde/generate_record_writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate_record_writer.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/buffer/table/serde/generate_record_writer.js"],"names":[],"mappings":"AA2QA;;;;;;;;;;;;;;;;GAgBG;AACH,6CAJW,YAAY,gBACZ,MAAM,EAAE,GACN,eAAe,CAgH3B;AApND;;;;;GAKG;AACH;IAEI;;;;;;OAMG;IACH,MAFU,YAAY,CAEjB;IAEL;;;;;OAKG;IACH,QAFU,MAAM,EAAE,CAEX;IAEP;;;;;;OAMG;IACH,QAFU,MAAM,EAAE,CAEX;IAEP;;;;;OAKG;IACH,kBAFU,MAAM,CAEC;IAEjB;;;;;;;;;;;;OAYG;IACH,qBANmB,YAAY,QAAE,WAAW,QAAE,MAAM,gBAAK,IAAI,CAMhD;IAEb;;;;;;;;;;;;;;;;OAgBG;IACH,gCATmB,YAAY,QAAE,WAAW,QAAE,MAAM,QAAE,YAAY,QAAE,WAAW,QAAE,MAAM,gBAAK,IAAI,CASxE;IAExB;;;;;OAKG;IACH,QAFU,MAAM,CAET;CACV;;;;;;;;;SA5La,MAAM;;;;SACN,MAAM;;;;UACN,MAAM;;;;;oBACG,MAAM,KAAE,MAAM;;yBAxDxB,OAAO,oCAAoC,EAAE,UAAU;2BACvD,OAAO,sCAAsC,EAAE,YAAY"}