@woosh/meep-engine 3.58.0 → 3.59.0

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"}