@woosh/meep-engine 3.23.0 → 3.25.0

package/src/shade/renderer/buffer/table/serde/generate_record_writer.js

@@ -0,0 +1,395 @@
+import { assert } from "../../../../../core/assert.js";
+import LineBuilder from "../../../../../core/codegen/LineBuilder.js";
+import {
+    atomic_i32,
+    atomic_u32,
+    bool,
+    f32,
+    i32,
+    mat3x2f,
+    mat4x4f,
+    u32,
+    vec2f,
+    vec2i,
+    vec2u,
+    vec3f,
+    vec3i,
+    vec3u,
+    vec4f,
+    vec4i,
+    vec4u
+} from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { GPU_DATABASE_BUFFER_ELEMENT_TYPE } from "../GPU_DATABASE_BUFFER_ELEMENT_TYPE.js";
+
+/**
+ * @typedef {import("../../../shader/type/WebGPUType.js").WebGPUType} WebGPUType
+ * @typedef {import("../../../shader/type/WebGPUStruct.js").WebGPUStruct} WebGPUStruct
+ */
+
+const WORD_SIZE = GPU_DATABASE_BUFFER_ELEMENT_TYPE.size;
+
+/**
+ * How many words a primitive occupies, and which of the two views takes them — or `undefined` for
+ * a type this generator will not emit.
+ *
+ * The refusals are deliberate and they are all the same refusal: a matrix whose columns are
+ * `vec3` (`mat3x3f`, `mat2x3f`, `mat4x3f`) pads each column out to 16 bytes in WGSL, and
+ * {@link write_wgsl_type_value} writes its floats end to end instead. One of the two is wrong
+ * about where the second column starts, and generating code that agrees with the CPU writer would
+ * only pin the disagreement in a second place. `f16` is out for the same reason — half the views
+ * here are the wrong width for it.
+ *
+ * @type {Map<WebGPUType, {words: number, view: string}>}
+ */
+const PRIMITIVE_LAYOUT = new Map([
+    [bool, { words: 1, view: 'u32' }],
+    [u32, { words: 1, view: 'u32' }],
+    [atomic_u32, { words: 1, view: 'u32' }],
+    // An i32 goes through the u32 view: assignment into a `Uint32Array` is a `ToUint32`, which is
+    // the same thirty-two bits a two's-complement `Int32Array` store would leave.
+    [i32, { words: 1, view: 'u32' }],
+    [atomic_i32, { words: 1, view: 'u32' }],
+    [f32, { words: 1, view: 'f32' }],
+
+    [vec2i, { words: 2, view: 'u32' }],
+    [vec3i, { words: 3, view: 'u32' }],
+    [vec4i, { words: 4, view: 'u32' }],
+
+    [vec2u, { words: 2, view: 'u32' }],
+    [vec3u, { words: 3, view: 'u32' }],
+    [vec4u, { words: 4, view: 'u32' }],
+
+    [vec2f, { words: 2, view: 'f32' }],
+    [vec3f, { words: 3, view: 'f32' }],
+    [vec4f, { words: 4, view: 'f32' }],
+
+    // 16 floats end to end, which is both what WGSL lays out for a vec4-column matrix and what
+    // the CPU writer produces
+    [mat4x4f, { words: 16, view: 'f32' }],
+    // likewise: vec2 columns, 8 bytes each, no padding between them
+    [mat3x2f, { words: 6, view: 'f32' }],
+]);
+
+/**
+ * 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.
+ *
+ * @typedef {object} WriterTarget
+ * @property {string} f32 name of the `Float32Array` parameter
+ * @property {string} u32 name of the `Uint32Array` parameter
+ * @property {string} base name of the base-word parameter
+ * @property {function(number):number} word_of maps a byte offset within the record to a word index
+ *           relative to `base`
+ */
+
+/**
+ * Emit the stores that put `value_expr` — already bound to a local — at `byte_offset` within the
+ * record, into every target.
+ *
+ * @param {LineBuilder} builder
+ * @param {WriterTarget[]} targets
+ * @param {number} byte_offset within the record
+ * @param {WebGPUType} type
+ * @param {string} value_expr
+ */
+function emit_value(builder, targets, byte_offset, type, value_expr) {
+    if (type.isStruct === true) {
+        const fields = type.fields;
+
+        for (let i = 0; i < fields.length; i++) {
+            const field = fields[i];
+
+            emit_value(builder, targets, byte_offset + field.offset, field.type, `${value_expr}.${field.name}`);
+        }
+
+        return;
+    }
+
+    if (type.isArray === true) {
+        assert.notOk(type.runtime_sized, `'${type}' is runtime sized — a record is fixed width`);
+
+        const element_type = type.type;
+        const element_stride = element_type.aligned_size;
+
+        for (let i = 0; i < type.count; i++) {
+            emit_value(builder, targets, byte_offset + i * element_stride, element_type, `${value_expr}[${i}]`);
+        }
+
+        return;
+    }
+
+    const layout = PRIMITIVE_LAYOUT.get(type);
+
+    if (layout === undefined) {
+        throw new Error(`Unsupported type '${type}' — see PRIMITIVE_LAYOUT for which types a record writer will emit and why`);
+    }
+
+    assert.equal(byte_offset % WORD_SIZE, 0, `'${value_expr}' sits at byte ${byte_offset}, which is not a whole number of ${WORD_SIZE}-byte words into the record`);
+
+    const word = byte_offset / WORD_SIZE;
+
+    if (layout.words === 1) {
+        for (const target of targets) {
+            builder.add(`${target[layout.view]}[${target.base} + ${target.word_of(word)}] = ${value_expr};`);
+        }
+
+        return;
+    }
+
+    for (let i = 0; i < layout.words; i++) {
+        for (const target of targets) {
+            builder.add(`${target[layout.view]}[${target.base} + ${target.word_of(word + i)}] = ${value_expr}[${i}];`);
+        }
+    }
+}
+
+/**
+ * Byte ranges covering `fields`, ascending, with touching or overlapping ones merged.
+ *
+ * Merging is what makes the result worth generating from rather than iterating: `NODE3D_STRUCT`'s
+ * four CPU-owned fields are three separate spans in the source declaration and two ranges once
+ * `pack()` and this have had their say, so a row's update costs two descriptors rather than four.
+ *
+ * @param {WGSLStructField[]} fields
+ * @returns {number[]} `[byte_offset, byte_length]` pairs
+ */
+function cover_fields(fields) {
+    const spans = fields
+        .map(field => [field.offset, field.offset + field.size])
+        .sort((a, b) => a[0] - b[0]);
+
+    const ranges = [];
+
+    let lo = spans[0][0];
+    let hi = spans[0][1];
+
+    for (let i = 1; i < spans.length; i++) {
+        const span = spans[i];
+
+        if (span[0] > hi) {
+            ranges.push(lo, hi - lo);
+
+            lo = span[0];
+        }
+
+        hi = Math.max(hi, span[1]);
+    }
+
+    ranges.push(lo, hi - lo);
+
+    return ranges;
+}
+
+/**
+ * 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;
+
+    /**
+     * 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;
+
+    /**
+     * `[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;
+
+    /**
+     * Total words across {@link ranges} — what one row's update adds to a partial stream's data
+     * blob.
+     *
+     * @type {number}
+     */
+    range_word_count;
+
+    /**
+     * 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;
+
+    /**
+     * 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;
+
+    /**
+     * 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;
+}
+
+/**
+ * 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, field_names) {
+    assert.defined(type, 'type');
+    assert.equal(type.isWebGPUType, true, 'type.isWebGPUType !== true');
+    assert.equal(type.isStruct, true, `'${type}' is not a struct — a record writer is named fields, and there are none to name`);
+    assert.equal(type.size % WORD_SIZE, 0, `'${type}' is ${type.size} bytes, not a whole number of ${WORD_SIZE}-byte words`);
+
+    const names = field_names === undefined
+        ? type.fields.map(field => field.name)
+        : field_names;
+
+    assert.isArray(names, 'field_names');
+    assert.greaterThan(names.length, 0, 'field_names.length');
+
+    const fields = names.map(name => type.get(name));
+
+    // Ascending offset, so the generated stores run forward through the record and the ranges they
+    // fill are laid out in the order the descriptors will name them.
+    fields.sort((a, b) => a.offset - b.offset);
+
+    const ranges = cover_fields(fields);
+
+    // Word index within the blob of each range's first word — the running total of the ranges
+    // before it.
+    const range_word_starts = [];
+    let range_word_count = 0;
+
+    for (let i = 0; i < ranges.length; i += 2) {
+        assert.equal(ranges[i] % WORD_SIZE, 0, `range starting at byte ${ranges[i]} of '${type}' is not word-aligned`);
+        assert.equal(ranges[i + 1] % WORD_SIZE, 0, `range of ${ranges[i + 1]} bytes in '${type}' is not a whole number of words`);
+
+        range_word_starts.push(range_word_count);
+
+        range_word_count += ranges[i + 1] / WORD_SIZE;
+    }
+
+    /**
+     * Word index within the blob for a word index within the record.
+     *
+     * @param {number} word
+     * @returns {number}
+     */
+    function blob_word_of(word) {
+        for (let i = 0; i < ranges.length; i += 2) {
+            const start = ranges[i] / WORD_SIZE;
+            const end = start + ranges[i + 1] / WORD_SIZE;
+
+            if (word >= start && word < end) {
+                return range_word_starts[i / 2] + (word - start);
+            }
+        }
+
+        throw new Error(`word ${word} of '${type}' is not covered by any range — the cover is built from the same fields the stores are`);
+    }
+
+    /**
+     * @type {WriterTarget}
+     */
+    const record_target = { f32: 'f32', u32: 'u32', base: 'word_base', word_of: word => word };
+
+    /**
+     * @type {WriterTarget}
+     */
+    const blob_target = { f32: 'data_f32', u32: 'data_u32', base: 'data_word_base', word_of: blob_word_of };
+
+    /**
+     * @param {WriterTarget[]} targets
+     * @returns {string}
+     */
+    function body(targets) {
+        const builder = new LineBuilder();
+
+        for (const field of fields) {
+            const local = `_${field.name}`;
+
+            builder.add(`const ${local} = value.${field.name};`);
+
+            emit_value(builder, targets, field.offset, field.type, local);
+        }
+
+        return builder.build();
+    }
+
+    const record_body = body([record_target]);
+    const both_body = body([record_target, blob_target]);
+
+    const writer = new GPURecordWriter();
+
+    writer.type = type;
+    writer.fields = fields.map(field => field.name);
+    writer.ranges = ranges;
+    writer.range_word_count = range_word_count;
+
+    writer.write_record = new Function('f32', 'u32', 'word_base', 'value', record_body);
+    writer.write_record_and_ranges = new Function(
+        'f32', 'u32', 'word_base',
+        'data_f32', 'data_u32', 'data_word_base',
+        'value',
+        both_body
+    );
+
+    writer.source = [
+        `function write_record(f32, u32, word_base, value){`,
+        record_body,
+        `}`,
+        `function write_record_and_ranges(f32, u32, word_base, data_f32, data_u32, data_word_base, value){`,
+        both_body,
+        `}`,
+    ].join('\n');
+
+    return writer;
+}

package/src/shade/renderer/buffer/table/single/GPUSingleTypeTable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUSingleTypeTable.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/buffer/table/single/GPUSingleTypeTable.js"],"names":[],"mappings":"AA2EA;;;GAGG;AACH;IAsCI;;;;;;OAMG;IACH;QAJ8B,MAAM;QACL,IAAI,EAAxB,UAAU;QACO,YAAY,GAA7B,MAAM;OAoBhB;IA9DD;;;OAGG;IACH,eAHU,UAAU,CAGf;IAEL;;;OAGG;IACH,2BAAM;IAEN;;;OAGG;IACH,sBAA2E;IAE3E;;;OAGG;IACH,kBAAyB;IAOzB;;;OAGG;IACH,+BAEC;IA6BD;;;OAGG;IACH,WAFW,MAAM,QAQhB;IAED;;;OAGG;IACH,QAFY,MAAM,CAIjB;IAED;;;;OAIG;IACH,WAHW,MAAM,kBA6ChB;IAED;;;;OAIG;IACH,aAHW,MAAM,OAiBhB;IAuCD;;;OAGG;IACH,oBAFW,sBAAsB,QAkDhC;IAED,0BAQC;IAED,gBAEC;;CACJ;qCAjUY,OAAO,8CAA8C,EAAE,sBAAsB;yBAC7E,OAAO,oCAAoC,EAAE,UAAU"}
+{"version":3,"file":"GPUSingleTypeTable.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/buffer/table/single/GPUSingleTypeTable.js"],"names":[],"mappings":"AA6EA;;;GAGG;AACH;IA4DI;;;;;;OAMG;IACH;QAJ8B,MAAM;QACL,IAAI,EAAxB,UAAU;QACO,YAAY,GAA7B,MAAM;OAoBhB;IApFD;;;OAGG;IACH,eAHU,UAAU,CAGf;IAEL;;;OAGG;IACH,2BAAM;IAEN;;;OAGG;IACH,sBAA2E;IAE3E;;;OAGG;IACH,kBAAyB;IA6BzB;;;OAGG;IACH,+BAEC;IA6BD;;;OAGG;IACH,WAFW,MAAM,QAQhB;IAED;;;OAGG;IACH,QAFY,MAAM,CAIjB;IAED;;;;OAIG;IACH,WAHW,MAAM,kBAyChB;IAgCD;;;;OAIG;IACH,aAHW,MAAM,OAiBhB;IAuCD;;;OAGG;IACH,oBAFW,sBAAsB,QAkDhC;IAED,0BAQC;IAED,gBAEC;;CACJ;qCA7WY,OAAO,8CAA8C,EAAE,sBAAsB;yBAC7E,OAAO,oCAAoC,EAAE,UAAU"}

package/src/shade/renderer/buffer/table/single/GPUSingleTypeTable.js

@@ -2,6 +2,12 @@ import { assert } from "../../../../../core/assert.js";
 import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
 import { BitSet } from "../../../../../core/binary/BitSet.js";
 import { platform_compute_endianness } from "../../../../../core/binary/platform_compute_endianness.js";
+import {
+    u32_index_clear,
+    u32_index_count,
+    u32_index_get,
+    u32_index_set,
+} from "../../../../../core/collection/map/u32_index.js";
 import { round_up } from "../../../../../core/math/round_up.js";
 import { KILOBYTE } from "../../../../../core/science/units/memory/KILOBYTE.js";
 import { write_wgsl_type_value } from "../../../shader/type/serde/write_gpu_typed_buffer.js";
@@ -22,10 +28,6 @@ import { GPU_DATABASE_UPLOAD_DISPATCH_GROUP_SIZE } from "../GPU_DATABASE_UPLOAD_
 const UPLOAD_BUFFER_LIMIT = 64 * KILOBYTE;
 const INITIAL_BUFFER_SIZE = 4 * KILOBYTE;
 
-// how many recent upload records set() scans for an existing record with the same id
-// (see GPUTypedTable's constant of the same name)
-const UPLOAD_BUFFER_DEDUP_LOOKBACK = 256;
-
 const UPDATE_SETTINGS_STRUCT = WebGPUStruct.from({
     count: u32,
     record_size: u32,
@@ -102,6 +104,28 @@ export class GPUSingleTypeTable {
      */
     occupancy = new BitSet();
 
+    /**
+     * Byte offset in {@link upload_buffer} of the record pending for an id, for every id that has
+     * one.
+     *
+     * Every record is consumed by its own thread of a single {@link update} dispatch, so two
+     * records aimed at one id are last-writer-wins across workgroups that have no ordering between
+     * them — the buffer must therefore hold at most one record per id. This was a backwards scan
+     * over the last 256 records, and a window is not a guarantee: a record further back than the
+     * scan reached stayed queued alongside the one that replaced it. The sibling
+     * {@link GPUTypedTable} was found doing exactly that, through a downstream report of corrupted
+     * animation bindings.
+     *
+     * No consumer of this table has reached it — each writes an id once per frame — which is the
+     * only reason it was latent rather than live here.
+     *
+     * `null` until the table takes its first write.
+     *
+     * @private
+     * @type {Uint32Array|null}
+     */
+    #pending_records = null;
+
     /**
      * @type {GPUDevice}
      */
@@ -178,25 +202,20 @@ export class GPUSingleTypeTable {
         const stride = this.type.aligned_size + u32.size;
         const tail = upload_buffer.position;
 
-        // Dedupe against recent records: each record is consumed by its own thread in a
-        // single update dispatch, so two records for the same id would race
+        // Dedupe against everything queued, not a window of it: each record is consumed by its own
+        // thread in a single update dispatch, so two records for the same id would race
         // (last-writer-wins, non-deterministic). Overwrite the previous value in place.
-        const max_lookback = Math.min(
-            UPLOAD_BUFFER_DEDUP_LOOKBACK,
-            Math.floor(tail / stride),
-        );
+        const pending_record = this.#pending_record_offset(id);
 
-        for (let i = 1; i <= max_lookback; i++) {
-            const candidate_start = tail - i * stride;
-            upload_buffer.position = candidate_start;
-            if (upload_buffer.readUint32() === id) {
-                write_wgsl_type_value(value, upload_buffer, this.type);
-                upload_buffer.position = tail;
-                return;
-            }
-        }
+        if (pending_record >= 0) {
+            upload_buffer.position = pending_record + u32.size;
 
-        upload_buffer.position = tail;
+            write_wgsl_type_value(value, upload_buffer, this.type);
+
+            upload_buffer.position = tail;
+
+            return;
+        }
 
         // Reserve the whole stride up front. The writes below only reach the last field,
         // so on a type that pads out to `aligned_size` they would leave the buffer short
@@ -209,6 +228,37 @@ export class GPUSingleTypeTable {
 
         upload_buffer.position = round_up(upload_buffer.position, stride);
 
+        this.#pending_records = u32_index_set(this.#pending_records, id, tail);
+    }
+
+    /**
+     * Byte offset of the record already pending for an id, or -1. One record per id is the
+     * invariant that keeps the update dispatch race-free — see {@link #pending_records}.
+     *
+     * Also where a stream dispatched since the last write gets noticed: {@link update} rewinds
+     * {@link upload_buffer} by moving its position back to zero and tells nobody, so the index can
+     * outlive the records it points at. {@link set} consults this before appending, which is what
+     * the staleness check rests on.
+     *
+     * @private
+     * @param {number} id
+     * @returns {number} byte offset of the pending record, or -1
+     */
+    #pending_record_offset(id) {
+        const pending = this.#pending_records;
+
+        if (pending === null || u32_index_count(pending) === 0) {
+            return -1;
+        }
+
+        if (this.upload_buffer.position === 0) {
+            // the stream was dispatched and rewound since these were recorded
+            u32_index_clear(pending);
+
+            return -1;
+        }
+
+        return u32_index_get(pending, id);
     }
 
     /**

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

@@ -1,3 +1,17 @@
+/**
+ * ref: Gribb-Hartmann
+ * Updates frustum planes from a View-Projection matrix.
+ * Geared for Reverse-Z (WebGPU/DirectX range [0,1]).
+ *
+ * Exported because it is the engine's **one** answer to this question and somebody else asks it:
+ * the virtual-geometry cut extracts the same six rows from an object-space view-projection, in a
+ * shader, and shipped with the near plane's sign wrong. A spec that holds the two against each
+ * other is worth more than a second derivation with a comment saying it matches.
+ *
+ * @param {Float32Array} planes
+ * @param {Float32Array} vp ViewProjection matrix
+ */
+export function construct_frustum_planes(planes: Float32Array, vp: Float32Array): void;
 export class Camera {
     transform: Transform64;
     view_matrix: Float32Array;

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

@@ -1 +1 @@
-{"version":3,"file":"Camera.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/camera/Camera.js"],"names":[],"mappings":"AAiFA;IAMI,uBAA8B;IAE9B,0BAA4B;IAC5B,gCAAkC;IAClC,qCAAuC;IAEvC;;;OAGG;IACH,SAFU,YAAY,CAES;IAoB/B,oBAEC;IAED,mBAEC;IAED,mBAEC;IAED,kBAEC;IAED,sBAKC;IAED,qBAEC;IAED,0BAEC;IAED,6BAEC;IAED;;;OAGG;IACH,YAFW,MAAM,QAchB;IAED,aAQC;IAED,iBAEC;IAED,eAMC;IAED;;;OAGG;IACH,cAFW,MAAM,WAQhB;IAED,wBAKC;IAED,0BAEC;IAED,2BAuDC;IAED,uBAIC;IAED,eAQC;;CACJ;4BAvR2B,8CAA8C"}
+{"version":3,"file":"Camera.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/camera/Camera.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;GAYG;AACH,iDAHW,YAAY,MACZ,YAAY,QA8DtB;AAED;IAMI,uBAA8B;IAE9B,0BAA4B;IAC5B,gCAAkC;IAClC,qCAAuC;IAEvC;;;OAGG;IACH,SAFU,YAAY,CAES;IAoB/B,oBAEC;IAED,mBAEC;IAED,mBAEC;IAED,kBAEC;IAED,sBAKC;IAED,qBAEC;IAED,0BAEC;IAED,6BAEC;IAED;;;OAGG;IACH,YAFW,MAAM,QAchB;IAED,aAQC;IAED,iBAEC;IAED,eAMC;IAED;;;OAGG;IACH,cAFW,MAAM,WAQhB;IAED,wBAKC;IAED,0BAEC;IAED,2BAuDC;IAED,uBAIC;IAED,eAQC;;CACJ;4BA7R2B,8CAA8C"}

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

@@ -14,10 +14,16 @@ let id_counter = 0;
  * ref: Gribb-Hartmann
  * Updates frustum planes from a View-Projection matrix.
  * Geared for Reverse-Z (WebGPU/DirectX range [0,1]).
+ *
+ * Exported because it is the engine's **one** answer to this question and somebody else asks it:
+ * the virtual-geometry cut extracts the same six rows from an object-space view-projection, in a
+ * shader, and shipped with the near plane's sign wrong. A spec that holds the two against each
+ * other is worth more than a second derivation with a comment saying it matches.
+ *
  * @param {Float32Array} planes
  * @param {Float32Array} vp ViewProjection matrix
  */
-function construct_frustum_planes(planes, vp) {
+export function construct_frustum_planes(planes, vp) {
     // Left Plane (w + x)
     // Row 3 + Row 0
     plane3_normalize(

package/src/shade/renderer/dynamic/GPUDynamicMeshResidency.js

@@ -125,7 +125,7 @@ export class GPUDynamicMeshResidency {
      */
     create_bindings(encoder, mesh, camera) {
         const draw_buffer = encoder.allocateTransientValueBuffer(DYNAMIC_MESH_DRAW_STRUCT, {
-            model: mesh.transform_global,
+            model: mesh.transform.matrix,
             color: mesh.color,
         });
 

package/src/shade/renderer/geometry/GEOMETRY_METADATA_STRUCT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GEOMETRY_METADATA_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/GEOMETRY_METADATA_STRUCT.js"],"names":[],"mappings":"AAKA,oDAgB8B;6BAnBD,gCAAgC"}
+{"version":3,"file":"GEOMETRY_METADATA_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/GEOMETRY_METADATA_STRUCT.js"],"names":[],"mappings":"AAKA,oDA+B8B;6BAlCD,gCAAgC"}

package/src/shade/renderer/geometry/GEOMETRY_METADATA_STRUCT.js

@@ -18,5 +18,20 @@ export const GEOMETRY_METADATA_STRUCT = WebGPUStruct.from({
     meshlets_count: u32,
 
     bounding_sphere: vec4f,
-    bounding_box: WebGPUArray.from(f32, 6)
+    bounding_box: WebGPUArray.from(f32, 6),
+
+    /**
+     * Row in the virtual-geometry table, or {@link VGEO_GEOMETRY_ROW_NONE}.
+     *
+     * A VG geometry has no static meshlets — `meshlets_count` is zero, so the mesh-to-meshlet
+     * expansion contributes nothing for it by construction — and everything it draws comes from a
+     * cut selected that frame. This field is how a pass handed a list of visible instances tells
+     * the two apart, and it is the only change virtual geometry asks of the engine's record
+     * formats: the draw records, the meshlet metadata, the material buckets and the indirect draws
+     * are all unchanged.
+     *
+     * Appended rather than inserted. Every other consumer reads this struct by field name or
+     * computes an offset from it, so a field at the end costs them nothing.
+     */
+    vg_row: u32,
 }, "GeometryMetadata").pack();

package/src/shade/renderer/geometry/GPUGeometryManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUGeometryManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/GPUGeometryManager.js"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH;IAqJI;;;OAGG;IACH,+BAUC;IA7JD;;;OAGG;IACH,iBAFU,YAAU,IAAI,CAED;IA0CvB;;;OAGG;IACH,4GAEC;IAED;;;;OAIG;IACH,8BAA0B;IAE1B;;;;OAIG;IACH,uBAAsB;IAOtB;;;OAGG;IACH,kCAEC;IAwBD;;;OAGG;IACH,kCAEC;IAGD;;;OAGG;IACH,0EAEC;IAED;;;OAGG;IACH,+BAiBC;IAkBD;;;;OAIG;IACH,qBAHW,mBAAmB,GAClB,MAAM,CAMjB;IAED;;;;OAIG;IACH,cAHW,eAAe,GACd,OAAO,CAIlB;IAGD;;;;OAIG;IACH,cAHW,eAAe,GACb,OAAO,CAiEnB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,2BAPW,eAAe,GACb,mBAAmB,CAiC/B;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,uBAHW,mBAAmB,GACjB,OAAO,CAqBnB;IAED;;;;;;;OAOG;IACH,uBAHW,eAAe,GACb,mBAAmB,GAAC,SAAS,CAIzC;IAED;;;;OAIG;IACH,iBAHW,eAAe,GACb,OAAO,CAsCnB;IAyBD,gBAWC;IAED;;;;;;OAMG;IACH,qBANW,sBAAsB,QAuChC;IAmDD,cAmCC;IAED,0CAWC;;CA+BJ;qCArnBY,OAAO,wCAAwC,EAAE,sBAAsB;8BACvE,OAAO,sBAAsB,EAAE,eAAe;oCAC9C,OAAO,gCAAgC,EAAE,qBAAqB;oCANvC,0BAA0B;kCAC5B,gCAAgC;sCAH5B,gCAAgC"}
+{"version":3,"file":"GPUGeometryManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/GPUGeometryManager.js"],"names":[],"mappings":"AAmBA;;;;GAIG;AACH;IAqJI;;;OAGG;IACH,+BAUC;IA7JD;;;OAGG;IACH,iBAFU,YAAU,IAAI,CAED;IA0CvB;;;OAGG;IACH,4GAEC;IAED;;;;OAIG;IACH,8BAA0B;IAE1B;;;;OAIG;IACH,uBAAsB;IAOtB;;;OAGG;IACH,kCAEC;IAwBD;;;OAGG;IACH,kCAEC;IAGD;;;OAGG;IACH,0EAEC;IAED;;;OAGG;IACH,+BAiBC;IAkBD;;;;OAIG;IACH,qBAHW,mBAAmB,GAClB,MAAM,CAMjB;IAED;;;;OAIG;IACH,cAHW,eAAe,GACd,OAAO,CAIlB;IAGD;;;;OAIG;IACH,cAHW,eAAe,GACb,OAAO,CA+EnB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,2BAPW,eAAe,GACb,mBAAmB,CAiC/B;IAED;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,uBAHW,mBAAmB,GACjB,OAAO,CAqBnB;IAED;;;;;;;OAOG;IACH,uBAHW,eAAe,GACb,mBAAmB,GAAC,SAAS,CAIzC;IAED;;;;OAIG;IACH,iBAHW,eAAe,GACb,OAAO,CAsCnB;IAyBD,gBAWC;IAED;;;;;;OAMG;IACH,qBANW,sBAAsB,QAuChC;IAmDD,cAmCC;IAED,0CAWC;;CAqCJ;qCAzoBY,OAAO,wCAAwC,EAAE,sBAAsB;8BACvE,OAAO,sBAAsB,EAAE,eAAe;oCAC9C,OAAO,gCAAgC,EAAE,qBAAqB;oCANvC,0BAA0B;kCAC5B,gCAAgC;sCAH5B,gCAAgC"}

package/src/shade/renderer/geometry/GPUGeometryManager.js

@@ -250,18 +250,32 @@ export class GPUGeometryManager {
         metadata.allocated = false;
         metadata.index = this.__last_geometry_index++;
 
-        const meshlets = geometry.meshlets;
+        if (geometry.isVirtualGeometry === true) {
+            /*
+             A virtual geometry has no meshlets to allocate and no tree to trace. Everything it
+             draws comes from a cut selected per view per frame, out of pages
+             `GPUVirtualGeometryPool` installed into the *shared* meshlet pool — so its clusters are
+             in the same buffers as everything else, and only the route to them differs.
 
-        metadata.meshlets = this.#meshlets.add_batch(meshlets);
+             The row still carries the source's bounds and triangle count, which is what
+             instance-level culling reads and what makes a VG instance an ordinary instance
+             everywhere above this line.
+             */
+            metadata.vg_row = geometry.vg_row;
+        } else {
+            const meshlets = geometry.meshlets;
 
-        // watch for data migration
-        metadata.meshlets.changed.add(() => {
+            metadata.meshlets = this.#meshlets.add_batch(meshlets);
 
-            // TODO need to handle this properly
+            // watch for data migration
+            metadata.meshlets.changed.add(() => {
 
-            console.warn('Meshlet GPU address changed.')
+                // TODO need to handle this properly
 
-        });
+                console.warn('Meshlet GPU address changed.')
+
+            });
+        }
 
         this.#geometries.set(geometry, metadata);
 
@@ -634,8 +648,14 @@ export class GPUGeometryManager {
             index_count: indexCount,
             bounding_sphere: geometry.bounding_sphere,
             bounding_box: geometry.bounding_box,
-            meshlets_address: g_meta.meshlets.metadata.offset,
-            meshlets_count: g_meta.meshlets.meshlet_count,
+            /*
+             Zero and zero for a virtual geometry, and the zero count is load-bearing rather than
+             defensive: `shader_meshes_to_meshlet_counts` reads it and therefore contributes nothing
+             for a VG instance without knowing what one is.
+             */
+            meshlets_address: g_meta.meshlets?.metadata.offset ?? 0,
+            meshlets_count: g_meta.meshlets?.meshlet_count ?? 0,
+            vg_row: g_meta.vg_row,
         }, GEOMETRY_METADATA_STRUCT, metadata.buffer, offset);
 
     }