@woosh/meep-engine 3.23.0 → 3.25.0

package/src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryRuntime.d.ts

@@ -0,0 +1,176 @@
+/**
+ * What one frame of virtual geometry needs that is not a page: the threshold, the feedback buffer
+ * every view writes into, and the parameters every pass reads.
+ *
+ * It sits above {@link GPUVirtualGeometryPool} for the same reason the pool sits above
+ * `VGeoRuntimeTables`: residency is a fact about a scene, and τ, a render target's height and a
+ * frame's worth of wants are facts about a *frame*. A cut is selected per view — design §4, and
+ * virtual geometry is view-dependent by construction — but everything here is shared between them,
+ * which is exactly what §4 means by "the setup is shared rather than the result".
+ *
+ * **The feedback buffer is per frame and not per invocation**, and that is what dedups a touch
+ * across the buckets and passes a frame is split into. Each expansion site gets its own claim
+ * bitmask (different instance sets) and writes into this one buffer.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUVirtualGeometryRuntime {
+    /**
+     * @param {Object} options
+     * @param {GPUVirtualGeometryPool} options.pool
+     * @param {GPUDevice} options.device
+     * @param {number} [options.want_capacity] pages one frame may ask for, across every view
+     * @param {number} [options.touch_capacity] page rows one frame may report drawing from
+     * @param {number} [options.visible_instance_hint] VG instances one expansion site is expected
+     *     to see; what {@link claim_word_capacity} is sized from, and nothing else
+     * @param {number} [options.claim_word_capacity] words of the per-invocation claim bitmask,
+     *     overriding the derivation below
+     * @param {number} [options.queue_capacity] traversal items one wavefront may hold
+     * @param {number} [options.max_iterations] wavefronts before the descent is abandoned
+     * @param {number} [options.cluster_chunk] clusters one group-chunk item covers
+     */
+    constructor({ pool, device, want_capacity, touch_capacity, visible_instance_hint, claim_word_capacity, queue_capacity, max_iterations, cluster_chunk, }: {
+        pool: GPUVirtualGeometryPool;
+        device: GPUDevice;
+        want_capacity?: number;
+        touch_capacity?: number;
+        visible_instance_hint?: number;
+        claim_word_capacity?: number;
+        queue_capacity?: number;
+        max_iterations?: number;
+        cluster_chunk?: number;
+    });
+    /**
+     * Pixels of permitted error — the single quality/perf lever, and a runtime dial by design §4.
+     * @type {number}
+     */
+    tau: number;
+    /**
+     * @type {boolean}
+     */
+    cull_enabled: boolean;
+    /**
+     * @returns {GPUVirtualGeometryPool}
+     */
+    get pool(): GPUVirtualGeometryPool;
+    /**
+     * @returns {GPUBuffer}
+     */
+    get params_buffer(): GPUBuffer;
+    /**
+     * @returns {number}
+     */
+    get queue_capacity(): number;
+    /**
+     * @returns {number}
+     */
+    get claim_word_capacity(): number;
+    /**
+     * @returns {number}
+     */
+    get max_iterations(): number;
+    /**
+     * This frame's feedback resource. Every expansion site writes into it and one readback reads it.
+     * @returns {number}
+     */
+    get feedback(): number;
+    /**
+     * Hand back the version of the feedback resource that an expansion left behind.
+     *
+     * A frame is cut once per bucket per HZB pass per view, and every one of those writes into the
+     * *same* feedback buffer — which is exactly what dedups a touch across them. But a FrameGraph
+     * resource is versioned: the handle `begin_frame` created is version 0, and a second expansion
+     * that wrote version 0 again after the first had produced version 65 would be reading stale
+     * contents while claiming not to. The graph says so, loudly, and it is right to.
+     *
+     * So the runtime carries the *current* version and each expansion publishes what it produced.
+     * The readback then reads the last one, which is the only version that has seen every view.
+     *
+     * @param {number} handle
+     * @returns {void}
+     */
+    publish_feedback(handle: number): void;
+    /**
+     * @returns {ReturnType<vgeo_cut_feedback_layout>}
+     */
+    get feedback_layout(): {
+        touch_stamp_base: number;
+        want_stamp_base: number;
+        want_base: number;
+        touch_base: number;
+        word_count: number;
+    };
+    /**
+     * Open a frame: publish the page tables, size the feedback buffer against what is resident, and
+     * write the parameters every pass of every view will read.
+     *
+     * The sizing happens here rather than at construction because two of its terms move with
+     * residency — one touch stamp per page-table row, one want stamp per lookup word — and a frame
+     * is the coarsest granularity at which they hold still.
+     *
+     * @param {FrameGraph} graph
+     * @param {Object} view
+     * @param {number} view.screen_height pixels of the render target
+     * @param {number} view.fov_y radians
+     * @param {number} [view.meshlet_capacity] records the shared meshlet collection holds
+     * @returns {number} the feedback resource
+     */
+    begin_frame(graph: FrameGraph, { screen_height, fov_y }: {
+        screen_height: number;
+        fov_y: number;
+        meshlet_capacity?: number;
+    }): number;
+    /**
+     * What one expansion site was handed, folded into the parameters every pass of the frame reads.
+     *
+     * The two capacities the cut bounds its appends against are properties of **collections the
+     * seam is given**, not of the frame — and they used to be a constant: `meshlet_capacity`
+     * defaulted to 1 << 20 against a meshlet collection whose engine default is 2e5, so `vg_draw`
+     * bounds-checked against a number five times the buffer it was writing into (REVIEW_LEDGER M6).
+     *
+     * One params buffer serves the whole frame, so a frame with sites of different sizes takes the
+     * **minimum** — conservative, and the direction every other bound in the cut fails in. Written
+     * at record time, like everything else here, so the last value published before submit is what
+     * every pass of the frame executes against.
+     *
+     * @param {Object} options
+     * @param {number} options.instance_capacity records the VG instance buffer holds
+     * @param {number} options.meshlet_capacity records the shared meshlet collection holds
+     * @returns {void}
+     */
+    declare_collections({ instance_capacity, meshlet_capacity }: {
+        instance_capacity: number;
+        meshlet_capacity: number;
+    }): void;
+    /**
+     * @returns {number}
+     */
+    get instance_capacity(): number;
+    /**
+     * @returns {number}
+     */
+    get meshlet_capacity(): number;
+    /**
+     * The graph this frame was opened on.
+     *
+     * A cut writes into the feedback resource `begin_frame` created, and a resource handle belongs
+     * to one graph — so a rasterization path running on a *different* graph inside the same frame
+     * (a shadow view builds its own) would be naming a resource that graph has never heard of. The
+     * seam checks this and skips, which is also design §9's position: one cut per view, and shadow
+     * cuts are out of scope for v1.
+     *
+     * @returns {FrameGraph|undefined}
+     */
+    get frame_graph(): any;
+    /**
+     * Close a frame. The feedback resource stops being valid; reading it is
+     * {@link VGeoFeedbackLoop}'s, which schedules the readback while the graph is still being built.
+     *
+     * @returns {void}
+     */
+    end_frame(): void;
+    destroy(): void;
+    #private;
+}
+//# sourceMappingURL=GPUVirtualGeometryRuntime.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUVirtualGeometryRuntime.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryRuntime.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;GAgBG;AACH;IAwFI;;;;;;;;;;;;;OAaG;IACH;QAZ2C,IAAI;QACjB,MAAM;QACR,aAAa,GAA9B,MAAM;QACW,cAAc,GAA/B,MAAM;QACW,qBAAqB,GAAtC,MAAM;QAEW,mBAAmB,GAApC,MAAM;QAEW,cAAc,GAA/B,MAAM;QACW,cAAc,GAA/B,MAAM;QACW,aAAa,GAA9B,MAAM;OAqDhB;IA3GD;;;OAGG;IACH,KAFU,MAAM,CAER;IAER;;OAEG;IACH,cAFU,OAAO,CAEG;IAoGpB;;OAEG;IACH,mCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;OAEG;IACH,6BAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;;;;;;;;;;;OAcG;IACH,yBAHW,MAAM,GACJ,IAAI,CAMhB;IAED;;OAEG;IACH;;;;;;MAEC;IAED;;;;;;;;;;;;;;OAcG;IACH;QALwB,aAAa,EAA1B,MAAM;QACO,KAAK,EAAlB,MAAM;QACQ,gBAAgB,GAA9B,MAAM;QACJ,MAAM,CAqClB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAJ2B,iBAAiB,EAAjC,MAAM;QACU,gBAAgB,EAAhC,MAAM;QACJ,IAAI,CAehB;IAED;;OAEG;IACH,gCAEC;IAED;;OAEG;IACH,+BAEC;IAED;;;;;;;;;;OAUG;IACH,uBAEC;IAyBD;;;;;OAKG;IACH,aAFa,IAAI,CAOhB;IAED,gBAEC;;CACJ"}

package/src/shade/renderer/geometry/virtual/runtime/GPUVirtualGeometryRuntime.js

@@ -0,0 +1,425 @@
+import { assert } from "../../../../../core/assert.js";
+import { BufferResourceDescriptor } from "../../../../device/graph/BufferResourceDescriptor.js";
+import { noop } from "../../../../../core/function/noop.js";
+import { write_gpu_typed_buffer } from "../../../shader/type/serde/write_gpu_typed_buffer.js";
+import { VGEO_CUT_FLAG_CULL } from "./cut/VGEO_CUT_FLAG_CULL.js";
+import { VGEO_CUT_PARAMS_STRUCT } from "./cut/VGEO_CUT_PARAMS_STRUCT.js";
+import { vgeo_cut_feedback_layout } from "./cut/vgeo_cut_feedback_layout.js";
+
+/**
+ * What one frame of virtual geometry needs that is not a page: the threshold, the feedback buffer
+ * every view writes into, and the parameters every pass reads.
+ *
+ * It sits above {@link GPUVirtualGeometryPool} for the same reason the pool sits above
+ * `VGeoRuntimeTables`: residency is a fact about a scene, and τ, a render target's height and a
+ * frame's worth of wants are facts about a *frame*. A cut is selected per view — design §4, and
+ * virtual geometry is view-dependent by construction — but everything here is shared between them,
+ * which is exactly what §4 means by "the setup is shared rather than the result".
+ *
+ * **The feedback buffer is per frame and not per invocation**, and that is what dedups a touch
+ * across the buckets and passes a frame is split into. Each expansion site gets its own claim
+ * bitmask (different instance sets) and writes into this one buffer.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class GPUVirtualGeometryRuntime {
+    /**
+     * @type {GPUVirtualGeometryPool}
+     */
+    #pool;
+
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+
+    /**
+     * @type {GPUBuffer}
+     */
+    #params;
+
+    /**
+     * @type {number}
+     */
+    #want_capacity;
+
+    /**
+     * @type {number}
+     */
+    #touch_capacity;
+
+    /**
+     * @type {number}
+     */
+    #claim_word_capacity;
+
+    /**
+     * @type {number}
+     */
+    #queue_capacity;
+
+    /**
+     * @type {number}
+     */
+    #max_iterations;
+
+    /**
+     * @type {number}
+     */
+    #cluster_chunk;
+
+    /**
+     * Pixels of permitted error — the single quality/perf lever, and a runtime dial by design §4.
+     * @type {number}
+     */
+    tau = 1;
+
+    /**
+     * @type {boolean}
+     */
+    cull_enabled = true;
+
+    /**
+     * This frame's feedback resource, or -1 outside a frame.
+     * @type {number}
+     */
+    #feedback = -1;
+
+    /**
+     * @type {ReturnType<vgeo_cut_feedback_layout>|undefined}
+     */
+    #layout;
+
+    /**
+     * @type {FrameGraph|undefined}
+     */
+    #graph;
+
+    /**
+     * @type {number}
+     */
+    #projection_k = 1;
+
+    /**
+     * @type {number}
+     */
+    #instance_capacity = 0;
+
+    /**
+     * @type {number}
+     */
+    #meshlet_capacity = 0;
+
+    /**
+     * @param {Object} options
+     * @param {GPUVirtualGeometryPool} options.pool
+     * @param {GPUDevice} options.device
+     * @param {number} [options.want_capacity] pages one frame may ask for, across every view
+     * @param {number} [options.touch_capacity] page rows one frame may report drawing from
+     * @param {number} [options.visible_instance_hint] VG instances one expansion site is expected
+     *     to see; what {@link claim_word_capacity} is sized from, and nothing else
+     * @param {number} [options.claim_word_capacity] words of the per-invocation claim bitmask,
+     *     overriding the derivation below
+     * @param {number} [options.queue_capacity] traversal items one wavefront may hold
+     * @param {number} [options.max_iterations] wavefronts before the descent is abandoned
+     * @param {number} [options.cluster_chunk] clusters one group-chunk item covers
+     */
+    constructor({
+                    pool,
+                    device,
+                    want_capacity = 2048,
+                    touch_capacity = 8192,
+                    visible_instance_hint = 1024,
+                    /*
+                     One bit per (instance, page ordinal), and the two terms are the *pool's* page
+                     capacity and the instances one site expects — so the default follows the tier
+                     it is indexing into rather than standing beside it as a constant. It was
+                     1 << 14 words, which is 512 instances of a 1,024-slot tier and a twentieth of
+                     what design §1 means by thousands of instances of thousands of pages
+                     (REVIEW_LEDGER M18). At the defaults this is 128 KB per expansion site, cleared
+                     once per site, which is not a number worth being frugal about against an
+                     instance silently drawing its whole cut several times over.
+                     */
+                    claim_word_capacity = Math.ceil(
+                        visible_instance_hint * pool.tables.page_capacity / 32
+                    ),
+                    /*
+                     Items, shared by every instance of one site. A thousand instances at the
+                     measured page depth of twelve is a few tens of thousands of visits in flight at
+                     the widest point, which this covers; what it does not cover is a scene that
+                     grows past the hint above, and the reason it is left where it is rather than
+                     raised to fit the worst case is that a queue is two buffers of
+                     `capacity × 16` bytes per site — 2 MiB here — and the worst case is unbounded.
+                     What changed is that running out is no longer silent:
+                     `VGEO_CUT_STAT.QUEUE_REMAINING` is non-zero exactly when the descent stopped
+                     with work outstanding, which is the one degradation that costs a hole.
+                     */
+                    queue_capacity = 1 << 16,
+                    max_iterations = 64,
+                    cluster_chunk = 8,
+                }) {
+        assert.defined(pool, 'pool');
+        assert.defined(device, 'device');
+
+        this.#pool = pool;
+        this.#device = device;
+        this.#want_capacity = want_capacity;
+        this.#touch_capacity = touch_capacity;
+        this.#claim_word_capacity = claim_word_capacity;
+        this.#queue_capacity = queue_capacity;
+        this.#max_iterations = max_iterations;
+        this.#cluster_chunk = cluster_chunk;
+
+        this.#params = device.createBuffer({
+            label: 'GPUVirtualGeometryRuntime/params',
+            size: VGEO_CUT_PARAMS_STRUCT.aligned_size,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+    }
+
+    /**
+     * @returns {GPUVirtualGeometryPool}
+     */
+    get pool() {
+        return this.#pool;
+    }
+
+    /**
+     * @returns {GPUBuffer}
+     */
+    get params_buffer() {
+        return this.#params;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get queue_capacity() {
+        return this.#queue_capacity;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get claim_word_capacity() {
+        return this.#claim_word_capacity;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get max_iterations() {
+        return this.#max_iterations;
+    }
+
+    /**
+     * This frame's feedback resource. Every expansion site writes into it and one readback reads it.
+     * @returns {number}
+     */
+    get feedback() {
+        return this.#feedback;
+    }
+
+    /**
+     * Hand back the version of the feedback resource that an expansion left behind.
+     *
+     * A frame is cut once per bucket per HZB pass per view, and every one of those writes into the
+     * *same* feedback buffer — which is exactly what dedups a touch across them. But a FrameGraph
+     * resource is versioned: the handle `begin_frame` created is version 0, and a second expansion
+     * that wrote version 0 again after the first had produced version 65 would be reading stale
+     * contents while claiming not to. The graph says so, loudly, and it is right to.
+     *
+     * So the runtime carries the *current* version and each expansion publishes what it produced.
+     * The readback then reads the last one, which is the only version that has seen every view.
+     *
+     * @param {number} handle
+     * @returns {void}
+     */
+    publish_feedback(handle) {
+        assert.isNonNegativeInteger(handle, 'handle');
+
+        this.#feedback = handle;
+    }
+
+    /**
+     * @returns {ReturnType<vgeo_cut_feedback_layout>}
+     */
+    get feedback_layout() {
+        return this.#layout;
+    }
+
+    /**
+     * Open a frame: publish the page tables, size the feedback buffer against what is resident, and
+     * write the parameters every pass of every view will read.
+     *
+     * The sizing happens here rather than at construction because two of its terms move with
+     * residency — one touch stamp per page-table row, one want stamp per lookup word — and a frame
+     * is the coarsest granularity at which they hold still.
+     *
+     * @param {FrameGraph} graph
+     * @param {Object} view
+     * @param {number} view.screen_height pixels of the render target
+     * @param {number} view.fov_y radians
+     * @param {number} [view.meshlet_capacity] records the shared meshlet collection holds
+     * @returns {number} the feedback resource
+     */
+    begin_frame(graph, { screen_height, fov_y }) {
+        assert.defined(graph, 'graph');
+        assert.greaterThan(screen_height, 0, 'screen_height');
+
+        this.#pool.flush();
+
+        this.#layout = vgeo_cut_feedback_layout({
+            page_row_capacity: this.#pool.page_row_capacity,
+            lookup_word_count: this.#pool.lookup_word_count,
+            want_capacity: this.#want_capacity,
+            touch_capacity: this.#touch_capacity,
+        });
+
+        const spawn = graph.add('vgeo/frame', {}, noop);
+
+        this.#feedback = spawn.create('vgeo feedback', BufferResourceDescriptor.empty(
+            this.#layout.word_count * 4,
+            GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
+        ));
+
+        this.#graph = graph;
+
+        /*
+         Nothing until an expansion site says what it was handed. Zero is the safe start: a kernel
+         that runs against it appends nothing rather than appending past the end of a collection
+         whose real size it was never told.
+         */
+        this.#instance_capacity = 0;
+        this.#meshlet_capacity = 0;
+
+        this.#projection_k = screen_height / (2 * Math.tan(fov_y * 0.5));
+
+        this.#write_params();
+
+        return this.#feedback;
+    }
+
+    /**
+     * What one expansion site was handed, folded into the parameters every pass of the frame reads.
+     *
+     * The two capacities the cut bounds its appends against are properties of **collections the
+     * seam is given**, not of the frame — and they used to be a constant: `meshlet_capacity`
+     * defaulted to 1 << 20 against a meshlet collection whose engine default is 2e5, so `vg_draw`
+     * bounds-checked against a number five times the buffer it was writing into (REVIEW_LEDGER M6).
+     *
+     * One params buffer serves the whole frame, so a frame with sites of different sizes takes the
+     * **minimum** — conservative, and the direction every other bound in the cut fails in. Written
+     * at record time, like everything else here, so the last value published before submit is what
+     * every pass of the frame executes against.
+     *
+     * @param {Object} options
+     * @param {number} options.instance_capacity records the VG instance buffer holds
+     * @param {number} options.meshlet_capacity records the shared meshlet collection holds
+     * @returns {void}
+     */
+    declare_collections({ instance_capacity, meshlet_capacity }) {
+        assert.isNonNegativeInteger(instance_capacity, 'instance_capacity');
+        assert.isNonNegativeInteger(meshlet_capacity, 'meshlet_capacity');
+
+        this.#instance_capacity = this.#instance_capacity === 0
+            ? instance_capacity
+            : Math.min(this.#instance_capacity, instance_capacity);
+
+        this.#meshlet_capacity = this.#meshlet_capacity === 0
+            ? meshlet_capacity
+            : Math.min(this.#meshlet_capacity, meshlet_capacity);
+
+        this.#write_params();
+    }
+
+    /**
+     * @returns {number}
+     */
+    get instance_capacity() {
+        return this.#instance_capacity;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get meshlet_capacity() {
+        return this.#meshlet_capacity;
+    }
+
+    /**
+     * The graph this frame was opened on.
+     *
+     * A cut writes into the feedback resource `begin_frame` created, and a resource handle belongs
+     * to one graph — so a rasterization path running on a *different* graph inside the same frame
+     * (a shadow view builds its own) would be naming a resource that graph has never heard of. The
+     * seam checks this and skips, which is also design §9's position: one cut per view, and shadow
+     * cuts are out of scope for v1.
+     *
+     * @returns {FrameGraph|undefined}
+     */
+    get frame_graph() {
+        return this.#graph;
+    }
+
+    /**
+     * @returns {void}
+     */
+    #write_params() {
+        write_gpu_typed_buffer_to_device(this.#device, this.#params, {
+            tau: this.tau,
+            projection_k: this.#projection_k,
+            queue_capacity: this.#queue_capacity,
+            claim_word_count: this.#claim_word_capacity,
+            cluster_chunk: this.#cluster_chunk,
+            page_slot_words: this.#pool.page_slot_words,
+            touch_stamp_base: this.#layout.touch_stamp_base,
+            want_stamp_base: this.#layout.want_stamp_base,
+            want_base: this.#layout.want_base,
+            want_capacity: this.#want_capacity,
+            touch_base: this.#layout.touch_base,
+            touch_capacity: this.#touch_capacity,
+            instance_capacity: this.#instance_capacity,
+            meshlet_capacity: this.#meshlet_capacity,
+            flags: this.cull_enabled ? VGEO_CUT_FLAG_CULL : 0,
+        });
+    }
+
+    /**
+     * Close a frame. The feedback resource stops being valid; reading it is
+     * {@link VGeoFeedbackLoop}'s, which schedules the readback while the graph is still being built.
+     *
+     * @returns {void}
+     */
+    end_frame() {
+        this.#feedback = -1;
+        this.#graph = undefined;
+
+        this.#pool.advance_frame();
+    }
+
+    destroy() {
+        this.#params.destroy();
+    }
+}
+
+/**
+ * `write_gpu_typed_buffer` writes into an `ArrayBuffer`; a uniform wants bytes on a device. One
+ * scratch buffer rather than one per frame, because the params block is forty-odd bytes written
+ * once a frame and allocating for it would be the expensive half.
+ *
+ * @type {ArrayBuffer}
+ */
+const PARAMS_SCRATCH = new ArrayBuffer(VGEO_CUT_PARAMS_STRUCT.aligned_size);
+
+/**
+ * @param {GPUDevice} device
+ * @param {GPUBuffer} buffer
+ * @param {Object} value
+ */
+function write_gpu_typed_buffer_to_device(device, buffer, value) {
+    write_gpu_typed_buffer(value, VGEO_CUT_PARAMS_STRUCT, PARAMS_SCRATCH, 0);
+
+    device.queue.writeBuffer(buffer, 0, PARAMS_SCRATCH, 0, VGEO_CUT_PARAMS_STRUCT.aligned_size);
+}