@woosh/meep-engine 3.58.0 → 3.60.0

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

@@ -2,11 +2,7 @@ import { assert } from "../../../../../core/assert.js";
 import { VGEO_CUT_FLAG_COARSEN } from "./cut/VGEO_CUT_FLAG_COARSEN.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_feedback_slot_stats,
-    vgeo_feedback_slot_want_count,
-    vgeo_feedback_slot_wants
-} from "./cut/vgeo_cut_feedback_layout.js";
+import { VGEO_CUT_STAT } from "./layout/VGEO_CUT_STAT.js";
 import { VGEO_CUT_STAT_COUNT } from "./layout/VGEO_CUT_STAT_COUNT.js";
 import { vgeo_frontier_words } from "./vgeo_frontier_words.js";
 import { write_gpu_typed_buffer } from "../../../shader/type/serde/write_gpu_typed_buffer.js";
@@ -124,6 +120,13 @@ export class VGeoViewCut {
      */
     stats = new Uint32Array(VGEO_CUT_STAT_COUNT);
 
+    /**
+     * The params' fields as {@link write_params} last wrote them, kept so writing them allocates nothing.
+     *
+     * @type {Object}
+     */
+    #params_fields = {};
+
     /**
      * @param {Object} options
      * @param {GPUDevice} options.device
@@ -348,48 +351,67 @@ export class VGeoViewCut {
         return true;
     }
 
+    /**
+     * Take this view's slot of a reading: its counters, and what they say about its descent.
+     *
+     * One counter is not a statistic, it is an instruction. `QUEUE_REMAINING` is non-zero exactly
+     * when the descent ran out of wavefronts and abandoned subtrees it had not expanded — a hole in
+     * the picture rather than a coarser surface — and this is the only moment anything on the host
+     * learns it.
+     *
+     * A slot two views shared — they were past the frame's layout — holds the sum of their counters,
+     * so a remainder in it says one of them ran out and not which. Escalating both would raise a
+     * bound that was never binding, for good; each has a slot of its own next frame, and escalates
+     * from that.
+     *
+     * @param {Uint32Array} words the reading
+     * @param {number} base where this slot's counters start in it
+     * @param {boolean} shared whether another consumer shared the slot
+     * @param {GPUVirtualGeometryRuntime} runtime
+     */
+    read_feedback(words, base, shared, runtime) {
+        for (let i = 0; i < VGEO_CUT_STAT_COUNT; i++) {
+            this.stats[i] = words[base + i];
+        }
+
+        this.note_incomplete_descent(shared ? 0 : words[base + VGEO_CUT_STAT.QUEUE_REMAINING], runtime);
+    }
+
     /**
      * Publish the frame's shared settings and this view's own, as one uniform.
      *
      * Everything but the projection, the threshold's scale, the slot and `flags` is a property of the
      * runtime or the frame, so it is read from the runtime at write time rather than mirrored here —
-     * a second copy of `tau` is a second thing to forget to update.
+     * a second copy of `tau` is a second thing to forget to update. The slot's own fields are the
+     * runtime's to fill ({@link GPUVirtualGeometryRuntime#fill_slot_params}).
      *
      * @param {Object} options
      * @param {GPUVirtualGeometryRuntime} options.runtime inside an open frame
      * @param {number} options.slot this view's slot in the frame's feedback
      * @param {boolean} [options.coarsen] whether this view's cut may walk up
+     * @param {number} [options.tau] the threshold, for a cut whose records carry an error scale of their own rather
+     *   than a view's pixels; `runtime.tau × tau_scale` otherwise
      * @returns {void}
      */
-    write_params({ runtime, slot, coarsen = false }) {
+    write_params({ runtime, slot, coarsen = false, tau = undefined }) {
         assert.defined(runtime, 'runtime');
         assert.isNonNegativeInteger(slot, 'slot');
 
-        const layout = runtime.feedback_layout;
-
-        assert.defined(layout, 'runtime.feedback_layout — begin_frame must have run');
-        assert.lessThan(slot, layout.slot_count, 'slot');
-
-        write_gpu_typed_buffer({
-            tau: runtime.tau * this.tau_scale,
-            projection_k: this.#projection_k,
-            distance_weight: this.#distance_weight,
-            queue_capacity: runtime.queue_capacity,
-            claim_word_count: runtime.claim_word_capacity,
-            descent_steps: runtime.descent_steps,
-            page_slot_words: runtime.pool.page_slot_words,
-            touch_bits_base: layout.touch_bits_base,
-            stats_base: vgeo_feedback_slot_stats(slot),
-            want_count_offset: vgeo_feedback_slot_want_count(slot),
-            want_base: vgeo_feedback_slot_wants(layout, slot),
-            want_capacity: layout.slot_want_capacity,
-            frontier_word_count: this.#frontier_word_count,
-            frame_tag: runtime.frame_tag_of(slot),
-            instance_capacity: runtime.instance_capacity,
-            meshlet_capacity: runtime.meshlet_capacity,
-            flags: (runtime.cull_enabled ? VGEO_CUT_FLAG_CULL : 0)
-                | (coarsen ? VGEO_CUT_FLAG_COARSEN : 0),
-        }, VGEO_CUT_PARAMS_STRUCT, this.#scratch, 0);
+        const params = runtime.fill_slot_params(this.#params_fields, slot);
+
+        params.tau = tau ?? runtime.tau * this.tau_scale;
+        params.projection_k = this.#projection_k;
+        params.distance_weight = this.#distance_weight;
+        params.queue_capacity = runtime.queue_capacity;
+        params.claim_word_count = runtime.claim_word_capacity;
+        params.descent_steps = runtime.descent_steps;
+        params.frontier_word_count = this.#frontier_word_count;
+        params.instance_capacity = runtime.instance_capacity;
+        params.meshlet_capacity = runtime.meshlet_capacity;
+        params.flags = (runtime.cull_enabled ? VGEO_CUT_FLAG_CULL : 0)
+            | (coarsen ? VGEO_CUT_FLAG_COARSEN : 0);
+
+        write_gpu_typed_buffer(params, VGEO_CUT_PARAMS_STRUCT, this.#scratch, 0);
 
         this.#device.queue.writeBuffer(
             this.#params, 0, this.#scratch, 0, VGEO_CUT_PARAMS_STRUCT.aligned_size

package/src/shade/renderer/geometry/virtual/runtime/cut/VGEO_CUT_VERDICT.d.ts

@@ -0,0 +1,14 @@
+/**
+ * What the cut's rule says about one cluster ({@link chunk_vgeo_cut_rule }'s `vg_cut_cluster`). A traversal acts on
+ * it: the camera's draws, wants and claims, a box cut takes the cluster's triangles.
+ */
+export type VGEO_CUT_VERDICT = number;
+export namespace VGEO_CUT_VERDICT {
+    let NONE: number;
+    let BELOW: number;
+    let TAKE: number;
+    let CLAMP: number;
+    let HELD: number;
+    let REFINE: number;
+}
+//# sourceMappingURL=VGEO_CUT_VERDICT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGEO_CUT_VERDICT.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/VGEO_CUT_VERDICT.js"],"names":[],"mappings":";;;;+BAMU,MAAM"}

package/src/shade/renderer/geometry/virtual/runtime/cut/VGEO_CUT_VERDICT.js

@@ -0,0 +1,37 @@
+/**
+ * What the cut's rule says about one cluster ({@link chunk_vgeo_cut_rule}'s `vg_cut_cluster`). A traversal acts on
+ * it: the camera's draws, wants and claims, a box cut takes the cluster's triangles.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @enum {number}
+ */
+export const VGEO_CUT_VERDICT = {
+    /**
+     * Nothing: its own group is not selectable, or the cluster's subtree is culled.
+     */
+    NONE: 0,
+    /**
+     * Below the cut: its parent is already fine enough, so something coarser covers this surface. A descent
+     * never arrives here; a cut walking up does.
+     */
+    BELOW: 1,
+    /**
+     * In the cut: fine enough, or a leaf.
+     */
+    TAKE: 2,
+    /**
+     * In the cut as a stand-in: it would refine, but its child page is not resident, so it covers the region the
+     * missing page would have refined and the page is wanted.
+     */
+    CLAMP: 3,
+    /**
+     * In the cut as a stand-in: it would refine, its child page is here, but the child group still waits on a page
+     * holding one of its other parents. Nothing to fetch from this cluster.
+     */
+    HELD: 4,
+    /**
+     * Refine: descend into the child page, which is resident with its group selectable.
+     */
+    REFINE: 5,
+};

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_vgeo_cut_arena.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_arena.js"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;GAeG;AACH,mCAFU,SAAS,CA0FZ;0BAnHmB,0CAA0C"}
+{"version":3,"file":"chunk_vgeo_cut_arena.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_arena.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;GAeG;AACH,mCAFU,SAAS,CAwGZ;0BAnImB,0CAA0C"}

package/src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_arena.js

@@ -1,6 +1,8 @@
 import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
 import { VGEO_CLUSTER_ROW_WORDS } from "../layout/VGEO_CLUSTER_ROW_WORDS.js";
 import { VGEO_GEOMETRY_ROW_WORDS } from "../layout/VGEO_GEOMETRY_ROW_WORDS.js";
+import { VGEO_GROUP_FLAG_SELECTABLE } from "../layout/VGEO_GROUP_FLAG_SELECTABLE.js";
+import { VGEO_GROUP_ROW_OFFSET } from "../layout/VGEO_GROUP_ROW_OFFSET.js";
 import { VGEO_GROUP_ROW_WORDS } from "../layout/VGEO_GROUP_ROW_WORDS.js";
 import { VGEO_INSTANCE_WORDS } from "../layout/VGEO_INSTANCE_WORDS.js";
 import { VGEO_NODE_ROW_LEAF_BIT } from "../layout/VGEO_NODE_ROW_LEAF_BIT.js";
@@ -38,6 +40,7 @@ const VG_GEOMETRY_ROW_WORDS = ${VGEO_GEOMETRY_ROW_WORDS}u;
 
 const VG_NODE_LEAF_BIT = ${VGEO_NODE_ROW_LEAF_BIT}u;
 const VG_NODE_CHILD_COUNT_MASK = 0xffu;
+const VG_GROUP_SELECTABLE = ${VGEO_GROUP_FLAG_SELECTABLE}u;
 
 /**
  * A page's slot: its header, then its node, group and cluster rows.
@@ -65,6 +68,19 @@ fn vg_group_base(page_row: u32) -> u32 {
         + vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.NODE_COUNT}u) * VG_NODE_ROW_WORDS;
 }
 
+fn vg_group_row(page_row: u32, group: u32) -> u32 {
+    return vg_group_base(page_row) + group * VG_GROUP_ROW_WORDS;
+}
+
+/**
+ * Whether a group may be drawn from: every page holding one of its parents is resident (format §10). A group that
+ * is resident and not selectable is held, its coarser selectable ancestors covering its surface.
+ */
+fn vg_group_selectable(page_row: u32, group: u32) -> bool {
+    return (vg_arena[vg_group_row(page_row, group) + ${VGEO_GROUP_ROW_OFFSET.FLAGS}u]
+        & VG_GROUP_SELECTABLE) != 0u;
+}
+
 fn vg_cluster_base(page_row: u32) -> u32 {
     return vg_group_base(page_row)
         + vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.GROUP_COUNT}u) * VG_GROUP_ROW_WORDS;

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_vgeo_cut_claim.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_claim.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,mCAFU,SAAS,CAkEQ;0BAlGD,0CAA0C"}
+{"version":3,"file":"chunk_vgeo_cut_claim.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_claim.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,mCAFU,SAAS,CA6D6B;0BA9FtB,0CAA0C"}

package/src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_claim.js

@@ -3,6 +3,7 @@ import { VGEO_CUT_STAT } from "../layout/VGEO_CUT_STAT.js";
 import { VGEO_INSTANCE_OFFSET } from "../layout/VGEO_INSTANCE_OFFSET.js";
 import { VGEO_PAGE_ROW_OFFSET } from "../layout/VGEO_PAGE_ROW_OFFSET.js";
 import { chunk_vgeo_cut_arena } from "./chunk_vgeo_cut_arena.js";
+import { chunk_vgeo_cut_stat } from "./chunk_vgeo_cut_stat.js";
 
 /**
  * One page, claimed once per instance, and touched when the claim is won.
@@ -35,11 +36,6 @@ import { chunk_vgeo_cut_arena } from "./chunk_vgeo_cut_arena.js";
 export const chunk_vgeo_cut_claim = CodeChunk.from(
     //language=WGSL
     `
-fn vg_stat(slot: u32, amount: u32) {
-    // this view's counters: every view of a frame has its own, so a reading says what its cut did
-    atomicAdd(&feedback[params.stats_base + slot], amount);
-}
-
 /**
  * Record that this page was selected from this frame — design §6's eviction key.
  */
@@ -96,4 +92,4 @@ fn vg_claim_page(instance_base: u32, page_row: u32) -> bool {
         page_row
     );
 }
-`, [chunk_vgeo_cut_arena]);
+`, [chunk_vgeo_cut_arena, chunk_vgeo_cut_stat]);

package/src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_descent.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The virtual-geometry cut's descent — design §7's pass, as a descent that lives inside one dispatch — for every
+ * cut: the camera's (`shader_vgeo_cut_traverse`) and a box cut's. A kernel is this chunk with the rule's two culls
+ * and what taking a cluster means to it:
+ *
+ * ```wgsl
+ * fn vg_cut_sphere_outside(instance_base: u32, sphere: vec4<f32>) -> bool
+ * fn vg_cut_box_outside(instance_base: u32, lower: vec3<f32>, upper: vec3<f32>) -> bool
+ * fn vg_cut_take(instance_base: u32, page_row: u32, verdict: VGVerdict)
+ * ```
+ *
+ * `vg_cut_take` is called for a cluster in the cut, a stand-in's too (`VGEO_CUT_VERDICT` TAKE, CLAMP, HELD); the
+ * descent itself counts the stand-ins and wants what a clamp could not reach.
+ *
+ * ## The rule
+ *
+ * A cluster is in the cut iff
+ *
+ * > `own group selectable AND project(parent) > tau AND (project(self) <= tau OR child group not
+ * > selectable)`
+ *
+ * which is {@link chunk_vgeo_cut_rule}'s.
+ *
+ * ## The shape
+ *
+ * The loop over depth is *inside* this kernel: a dispatch is a spill generation rather than a level
+ * of the descent. Depth is what a cut costs. Measured on a 28M-face container at tau = 1 on a 4090:
+ * the descent converges at **39 levels**, carrying 15,027 items — an average frontier of 385 items,
+ * or **six workgroups of 64 on a 128-SM part** — and an empty prepare/traverse pair costs 3.9 us
+ * whatever it contains. Page depth grows like log2(triangles), so a dispatch per level gets *worse*
+ * with better assets and no better with a faster GPU.
+ *
+ * What a lane cannot do is wait for another workgroup: WebGPU guarantees no forward progress across
+ * workgroups, so persistent threads over an MPMC queue — Nanite's answer — is unbounded waiting.
+ * What a lane *can* do is cooperate with the other lanes of its own subgroup, and that is enough:
+ *
+ * - Every lane executes its item and says how many children it produced. No lane walks its own
+ *   subtree while its neighbours idle; production is a **count**, at constant cost.
+ * - `subgroupExclusiveAdd` over those counts numbers the wave's whole production densely. The first
+ *   `subgroup_size` of them are taken back into the wave's own lanes — perfectly packed, one child
+ *   per lane, whoever produced them — and the descent takes another step without touching memory.
+ * - Everything past a full wave **spills** to the global queue under one `atomicAdd`. Breadth the
+ *   wave cannot hold becomes work for other waves rather than a serial loop inside this one.
+ *
+ * So the number of dispatches is the number of spill generations, and the narrow top of the DAG —
+ * twenty levels that move between 1 and 120 items and draw nothing — is one wave taking twenty
+ * steps in registers.
+ *
+ * This is Karis' "Variable sized work" (graphicrants, 2026-03) with its groupshared scatter
+ * removed. That scatter needs HLSL's `GroupMemoryBarrier()` — memory ordering with no execution
+ * sync, sound because a wave is in lockstep — and WGSL has no memory-only workgroup barrier.
+ * `workgroupBarrier` synchronizes execution as well, which pins every subgroup of the workgroup to
+ * the same number of steps and is a deadlock the moment they disagree; `workgroupUniformLoad` is
+ * that same control barrier plus a load, and what it returns is one value uniform across the
+ * workgroup, which is the opposite of the per-lane read a scatter is made of.
+ * `vg_child_owner` finds each item's producer by binary search over the same prefix sums
+ * instead: `log2(subgroup_size)` shuffles, no workgroup memory and no barrier anywhere in this
+ * file, so nothing here needs the workgroup to agree on anything.
+ *
+ * ## What WGSL will not let this do
+ *
+ * Every loop around a subgroup operation needs a **uniform trip count**, and nothing launders one —
+ * not `subgroupAdd`, not `subgroupMax`, not even `subgroupBroadcastFirst`, which launders a value
+ * for a use but not for control flow. Nor may such a loop carry a non-uniform `break`, `continue`
+ * or `return`. So the descent runs `params.descent_steps` times and masks; a wave that drains its
+ * subtree early pays the remaining steps at about ten instructions each rather than leaving. That
+ * makes `descent_steps` a tuning knob rather than a safety bound, and
+ * `VGEO_CUT_STAT.QUEUE_REMAINING` is what says when it is set too low.
+ *
+ * Divergence *inside* the loop is free: Tint models reconvergence, so a non-uniform `if` that opens
+ * and closes taints nothing after it, and the spill's per-lane loop is fine because it contains no
+ * subgroup operation of its own.
+ *
+ * ## One lane per cluster
+ *
+ * A leaf produces one item per cluster of its groups and the wave packs them, so what bounds a
+ * lane's work is the packing rather than a chunk size, and consecutive lanes read consecutive
+ * cluster rows instead of striding over runs of them.
+ *
+ * ## Why page-granular dedup is enough, and why it is necessary
+ *
+ * The page DAG is many-parented — 82 of 91 pages of a measured 98k sphere have more than one parent
+ * — so an undeduped descent would visit a page once per parent and draw its whole cut that many
+ * times. The claim is one bit per (instance, resident page), which is affordable. Cluster-granular
+ * dedup is what this avoids: the resident cluster count is exactly the number design §4 is trying
+ * not to pay per frame.
+ *
+ * Visiting a cluster the descent "should not" have reached costs only the test, because the
+ * predicate is a pure function of the row and gives the same answer from every direction. Missing
+ * one costs a hole. That asymmetry is the whole design:
+ *
+ * - **No cluster is drawn twice.** It is evaluated once per page visit, and the claim makes that at
+ *   most once per instance.
+ * - **No cluster the flat rule would draw is missed.** If `project(C.parent) > tau`, then any
+ *   parent cluster `P` of `C`'s group has `project(P.self) = project(C.parent) > tau` — every
+ *   cluster of a group shares the consuming step's sphere and error — and monotonicity gives
+ *   `project(P.parent) >= project(P.self)`, so `P` satisfies the predicate's first half and by
+ *   induction its page is visited. `P` fails `project(self) <= tau`, so it either enqueues `C`'s
+ *   page or clamps, and it clamps only when `C`'s group is not selectable, in which case `C` must
+ *   not be drawn. Neither cull intervenes: a node's sphere contains `P.parent_sphere` and its
+ *   `max_parent_error` is at least `P.parent_error`, so the LOD cull cannot fire, and both culls
+ *   are on bounds of `P`'s whole subtree, which contains `C` — so they fire only where `C` is
+ *   outside the cut's volume anyway.
+ *
+ * Note that the per-cluster culls do **not** have to agree across a group's several parents, and
+ * nothing here asks them to. A group is claimed and descended once, by whichever parent reaches it
+ * first; a parent that culls itself out simply is not that one. What each test promises is about
+ * its own subtree and nothing else.
+ *
+ * Descent crosses a page boundary by producing the child page's **node 0**: uniform items, one
+ * kernel, no special case for "entering a page". `SAME_PAGE` needs no special case either, because
+ * the CPU resolved it to this page's own index at install, so it looks up a page that is trivially
+ * resident and falls through to the only question it was really asking — is that group selectable.
+ *
+ * ## Bounds
+ *
+ * Every append is checked and every overflow is counted, and they all degrade in one direction —
+ * coarser or missing, never doubled. The exception worth knowing is `QUEUE_DROPPED`: a dropped item
+ * is a subtree never descended, and the parent that would have stood in over it was not drawn
+ * either, so that one is a hole.
+ *
+ * Requires the importing shader to declare `params`, `vg_lookup`, `vg_arena`, `vg_want_stamps`,
+ * `instances`, `queue_in`, `queue_out`, `claim` and `feedback`, and the three hooks.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_descent: CodeChunk;
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_vgeo_cut_descent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_vgeo_cut_descent.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_descent.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+HG;AACH,qCAFU,SAAS,CAwUhB;0BAlduB,0CAA0C"}