@woosh/meep-engine 3.58.0 → 3.59.0

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

@@ -0,0 +1,404 @@
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { VGEO_CLUSTER_ROW_OFFSET } from "../layout/VGEO_CLUSTER_ROW_OFFSET.js";
+import { VGEO_CUT_STAT } from "../layout/VGEO_CUT_STAT.js";
+import { VGEO_GROUP_ROW_OFFSET } from "../layout/VGEO_GROUP_ROW_OFFSET.js";
+import { VGEO_INSTANCE_OFFSET } from "../layout/VGEO_INSTANCE_OFFSET.js";
+import { VGEO_NODE_ROW_OFFSET } from "../layout/VGEO_NODE_ROW_OFFSET.js";
+import { VGEO_NO_CHILD_PAGE } from "../layout/VGEO_NO_CHILD_PAGE.js";
+import { VGEO_PAGE_ROW_NONE } from "../layout/VGEO_PAGE_ROW_NONE.js";
+import { VGEO_QUEUE_TARGET_GROUP_BIT } from "../layout/VGEO_QUEUE_TARGET_GROUP_BIT.js";
+import { VGEO_QUEUE_TARGET_PARENT_BIT } from "../layout/VGEO_QUEUE_TARGET_PARENT_BIT.js";
+import { chunk_vgeo_cut_access } from "./chunk_vgeo_cut_access.js";
+import { chunk_vgeo_cut_stat } from "./chunk_vgeo_cut_stat.js";
+import { VGEO_CUT_EXPAND } from "./VGEO_CUT_EXPAND.js";
+import { VGEO_CUT_FLAG_COARSEN } from "./VGEO_CUT_FLAG_COARSEN.js";
+import { VGEO_CUT_VERDICT } from "./VGEO_CUT_VERDICT.js";
+
+/**
+ * The cut's rule, once, for every traversal that selects clusters: the camera's wavefront
+ * (`shader_vgeo_cut_traverse`) and a box cut. 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 design §4's per-cluster form together with its first term. That term is load-bearing
+ * and §4 states the rule without it: a group that is resident but not yet selectable has clusters
+ * satisfying the rest of the rule while their coarse stand-in is drawn over the same surface, a few
+ * microns apart, with the depth buffer choosing between them. That reads as corrupt geometry rather
+ * than as a missing page, which is what makes it hard to attribute and worth stating first.
+ *
+ * ```wgsl
+ * fn vg_cut_node(instance_base: u32, page_row: u32, node: u32) -> VGExpand
+ * fn vg_cut_cluster(instance_base: u32, page_row: u32, group: u32, member: u32) -> VGVerdict
+ * fn vg_child(instance_slot: u32, expand: VGExpand, k: u32) -> VGItem
+ * ```
+ *
+ * The rule is evaluated in an instance's own space, against the instance record
+ * (`VGEO_INSTANCE_OFFSET`): its eye, projection constant and distance weight for `vg_project`,
+ * its lookup base for the child pages. What it is culled against is the traversal's, so the
+ * importing shader defines both culls, each a test of a bound of the whole subtree under 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
+ * ```
+ *
+ * What a traversal does with a verdict is its own: the camera draws, wants and claims; a box cut
+ * takes the cluster's triangles.
+ *
+ * Requires the importing shader to declare `params`, `vg_lookup`, `vg_arena`, `instances` and
+ * `feedback`. Claiming a page is the traversal's: the camera's takes `chunk_vgeo_cut_claim`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_rule = CodeChunk.from(
+    //language=WGSL
+    `
+const VG_QUEUE_GROUP_BIT = ${VGEO_QUEUE_TARGET_GROUP_BIT}u;
+const VG_QUEUE_PARENT_BIT = ${VGEO_QUEUE_TARGET_PARENT_BIT}u;
+const VG_PAGE_ROW_NONE = ${VGEO_PAGE_ROW_NONE}u;
+const VG_NO_CHILD_PAGE = ${VGEO_NO_CHILD_PAGE}u;
+
+const VG_EXPAND_NONE = ${VGEO_CUT_EXPAND.NONE}u;
+const VG_EXPAND_NODES = ${VGEO_CUT_EXPAND.NODES}u;
+const VG_EXPAND_CLUSTERS = ${VGEO_CUT_EXPAND.CLUSTERS}u;
+const VG_EXPAND_PAGE = ${VGEO_CUT_EXPAND.PAGE}u;
+const VG_EXPAND_PARENTS = ${VGEO_CUT_EXPAND.PARENTS}u;
+
+const VG_VERDICT_NONE = ${VGEO_CUT_VERDICT.NONE}u;
+const VG_VERDICT_BELOW = ${VGEO_CUT_VERDICT.BELOW}u;
+const VG_VERDICT_TAKE = ${VGEO_CUT_VERDICT.TAKE}u;
+const VG_VERDICT_CLAMP = ${VGEO_CUT_VERDICT.CLAMP}u;
+const VG_VERDICT_HELD = ${VGEO_CUT_VERDICT.HELD}u;
+const VG_VERDICT_REFINE = ${VGEO_CUT_VERDICT.REFINE}u;
+
+/**
+ * One unit of work: a node visit, or a single cluster of one group.
+ *
+ * The same four words the queue holds, and bit 31 of \`visit\` tells the two apart — a node
+ * index below it, a group index above it with \`aux\` naming the cluster inside that group.
+ */
+struct VGItem {
+    instance_slot: u32,
+    page_row: u32,
+    visit: u32,
+    aux: u32,
+}
+
+/**
+ * What an executed item wants done next, as a count and a rule for the k-th child rather than as
+ * children written somewhere.
+ *
+ * This is the whole reason the descent can stay in registers: a producer states its production at
+ * constant cost and any lane of the wave can then build child \`k\` of it from five numbers.
+ */
+struct VGExpand {
+    kind: u32,
+    count: u32,
+    page_row: u32,
+    first: u32,
+    span: u32,
+}
+
+/**
+ * The rule's answer for one cluster (\`VGEO_CUT_VERDICT\`), and what acting on it needs: the
+ * cluster within its page, and for a refinement or a stand-in, the child it was refining into.
+ */
+struct VGVerdict {
+    kind: u32,
+    cluster: u32,
+    // REFINE and HELD: the child page's row
+    child_page_row: u32,
+    // CLAMP and HELD: the child page's index in its geometry, and the child group
+    child_page_index: u32,
+    child_group: u32,
+    // CLAMP: the source page's child-table entry, and this cluster's own projected error
+    child_ref: u32,
+    projected: f32,
+}
+
+fn vg_expand_none() -> VGExpand {
+    return VGExpand(VG_EXPAND_NONE, 0u, 0u, 0u, 0u);
+}
+
+fn vg_verdict(kind: u32, cluster: u32) -> VGVerdict {
+    return VGVerdict(kind, cluster, VG_PAGE_ROW_NONE, VG_NO_CHILD_PAGE, 0u, 0u, 0.0);
+}
+
+/**
+ * A node: cull, then say what it expands into.
+ *
+ * Nothing is enqueued here. An interior node expands into its child nodes and a leaf into every
+ * cluster of its groups, and either is a base and a count — which is what lets the wave take the
+ * first \`subgroup_size\` of them into its own lanes and spill the rest.
+ */
+fn vg_cut_node(instance_base: u32, page_row: u32, node: u32) -> VGExpand {
+    let row = vg_node_base(page_row) + node * VG_NODE_ROW_WORDS;
+
+    let sphere = vg_sphere_at(row + ${VGEO_NODE_ROW_OFFSET.SPHERE}u);
+
+    if (vg_cut_sphere_outside(instance_base, sphere)) {
+        vg_stat(${VGEO_CUT_STAT.CULLED_FRUSTUM}u, 1u);
+        return vg_expand_none();
+    }
+
+    let eye = vg_instance_eye(instance_base);
+    let k = vg_instance_f32(instance_base, ${VGEO_INSTANCE_OFFSET.PROJECTION_K}u);
+    let w = vg_instance_f32(instance_base, ${VGEO_INSTANCE_OFFSET.DISTANCE_WEIGHT}u);
+
+    /*
+     Format §6.2's load-bearing field. A cluster draws only while project(parent) > tau, so if the
+     *largest* parent error under this node still projects to no more than tau, nothing under it can
+     be drawn and the whole subtree goes. The node's sphere is the union of the covered clusters'
+     parent spheres, so the projection is conservative in both terms.
+
+     **It is a descent-only accelerator**, and the coarsen flag turns it off. Its premise is that
+     a subtree nothing can be drawn in is a subtree worth skipping, which is true of a traversal
+     that only ever looks for what to draw. A walk up is looking for something else: the groups
+     under this node are below the cut, and being below the cut is precisely what sends them to
+     their parents. Skipping them here is what made a cut seeded at the leaves draw nothing at all
+     -- the subtree carrying the whole walk was pruned at its first node, silently and by a rule
+     that is correct for the direction it was written for.
+
+     A node has no parent list of its own -- the upward edge is per group (format §6.3) -- so
+     there is nothing to coarsen *from* here, and entering the subtree is the only way to reach
+     the groups that can. That is the cost of walking up through a page: the pages on the way
+     are evaluated whole. It is why CUT_PLAN §1 keeps a frontier at all rather than re-deriving
+     one, and why the frontier is what makes this affordable rather than this pass.
+    */
+    if ((params.flags & ${VGEO_CUT_FLAG_COARSEN}u) == 0u
+        && vg_project(vg_arena_f32(row + ${VGEO_NODE_ROW_OFFSET.MAX_PARENT_ERROR}u), sphere, eye, k, w)
+            <= params.tau) {
+        vg_stat(${VGEO_CUT_STAT.CULLED_LOD}u, 1u);
+        return vg_expand_none();
+    }
+
+    let child_first = vg_arena[row + ${VGEO_NODE_ROW_OFFSET.CHILD_FIRST}u];
+    let child_word = vg_arena[row + ${VGEO_NODE_ROW_OFFSET.CHILD_COUNT_AND_FLAGS}u];
+
+    let child_count = child_word & VG_NODE_CHILD_COUNT_MASK;
+
+    if ((child_word & VG_NODE_LEAF_BIT) == 0u) {
+        return VGExpand(VG_EXPAND_NODES, child_count, page_row, child_first, 0u);
+    }
+
+    // a leaf's children are groups, and its production is every cluster they hold
+    var total = 0u;
+
+    for (var i = 0u; i < child_count; i = i + 1u) {
+        total = total + vg_arena[
+            vg_group_row(page_row, child_first + i) + ${VGEO_GROUP_ROW_OFFSET.CLUSTER_COUNT}u
+        ];
+    }
+
+    return VGExpand(VG_EXPAND_CLUSTERS, total, page_row, child_first, child_count);
+}
+
+/**
+ * The k-th cluster under a leaf, as a group and an index inside it.
+ *
+ * Bounded by the leaf's own group count and branchless, which are both about the same hazard. Every
+ * lane of the wave runs this, including the lanes past the end of the wave's production, and those
+ * hold a \`k\` with no cluster behind it. A walk that stopped when it found the group would run off
+ * the end of the group rows for them, and a run of zero-member rows is an infinite loop rather than
+ * a wrong answer — a hung GPU, on data the builder is free to produce.
+ *
+ * Their result is nonsense and is never executed, because the lane is inactive. It only has to be
+ * in-range and finite.
+ *
+ * It is a loop with a non-uniform trip count and no subgroup operation inside, which WGSL permits
+ * and which taints nothing after it.
+ */
+fn vg_leaf_cluster(page_row: u32, group_first: u32, group_count: u32, k: u32) -> vec2<u32> {
+    var remaining = k;
+    var group = 0u;
+    var found = false;
+
+    for (var i = 0u; i < group_count; i = i + 1u) {
+        let members = vg_arena[
+            vg_group_row(page_row, group_first + i) + ${VGEO_GROUP_ROW_OFFSET.CLUSTER_COUNT}u
+        ];
+
+        /*
+         The latch is the whole of it. Walking on without one is not a slower answer but a wrong
+         one: the walk keeps testing \`remaining\` against later groups, and any later group smaller
+         than the remainder it already settled on takes the item off the group that owns it. Two
+         values of k then name one cluster, and one cluster drawn twice is the exact failure the
+         claim bitmask and the own-group term exist to prevent.
+         */
+        let here = !found && remaining < members;
+
+        group = select(group, i, here);
+        found = found || here;
+
+        // consumed only while still searching, so this never underflows
+        remaining = select(remaining - members, remaining, found);
+    }
+
+    return vec2<u32>(group_first + group, remaining);
+}
+
+/**
+ * One cluster: the rule, once.
+ */
+fn vg_cut_cluster(
+    instance_base: u32,
+    page_row: u32,
+    group: u32,
+    member: u32
+) -> VGVerdict {
+    /*
+     The own-group term. A group that is resident but not selectable draws nothing at all — its
+     coarser selectable ancestors are already covering that surface, and drawing both is the
+     double-draw this whole runtime is arranged to avoid.
+     */
+    if (!vg_group_selectable(page_row, group)) {
+        return vg_verdict(VG_VERDICT_NONE, 0u);
+    }
+
+    let group_row = vg_group_row(page_row, group);
+
+    let cluster = vg_arena[group_row + ${VGEO_GROUP_ROW_OFFSET.CLUSTER_FIRST}u] + member;
+
+    let row = vg_cluster_base(page_row) + cluster * VG_CLUSTER_ROW_WORDS;
+
+    let eye = vg_instance_eye(instance_base);
+    let k = vg_instance_f32(instance_base, ${VGEO_INSTANCE_OFFSET.PROJECTION_K}u);
+    let w = vg_instance_f32(instance_base, ${VGEO_INSTANCE_OFFSET.DISTANCE_WEIGHT}u);
+    let lookup_base = instances[instance_base + ${VGEO_INSTANCE_OFFSET.LOOKUP_WORD_OFFSET}u];
+
+    vg_stat(${VGEO_CUT_STAT.CLUSTERS_TESTED}u, 1u);
+
+    let parent_projected = vg_project(
+        vg_arena_f32(row + ${VGEO_CLUSTER_ROW_OFFSET.PARENT_ERROR}u),
+        vg_sphere_at(row + ${VGEO_CLUSTER_ROW_OFFSET.PARENT_SPHERE}u),
+        eye, k, w
+    );
+
+    if (parent_projected <= params.tau) {
+        /*
+         Below the cut: something coarser covers this surface. A descent from the root never
+         arrives here -- it only descends through a step that projected above tau -- so this
+         is the branch a cut that was *kept* between frames lands in when the camera pulls
+         back, and stopping is what makes such a cut unable to coarsen.
+
+         parent_error and parent_sphere are the consuming step's, and every cluster of a group
+         shares that one step (FORMAT section 11.16), so this decision is group-uniform.
+        */
+        return vg_verdict(VG_VERDICT_BELOW, cluster);
+    }
+
+    /*
+     The culls, on two bounds of this cluster's whole subtree, and **below the election above**.
+
+     Why here and not at the top of the function. The reason to cull is residency rather than the
+     draw: refining claims the child page, and a claim is a touch — the LRU's whole input — so an
+     off-screen cluster that refined anyway would keep pages nobody can see hot and the tier full of
+     them. A cluster that took the branch above is below the cut: it refines into nothing, claims
+     nothing and draws nothing, so culling it buys residency exactly nothing, while skipping its
+     election costs a coarsen its walk up. The parent that election reaches can protrude on screen
+     past everything under it — that is what a coarser surface covering the same region looks like —
+     and with the test above the election it was never reached, so it was neither drawn nor stood in
+     for. A hole, and the tighter the bound the more often.
+
+     Why two bounds. Both contain every vertex reachable below this cluster, which is what makes
+     either safe to cull a subtree on: self_sphere by the builder's construction and FORMAT §11.7,
+     CULL_BOX by §11.17. The box is much the tighter of the two on real geometry — a subtree is a
+     patch of surface and its box is thin where a sphere is round — and the sphere stays because a
+     container written before the box existed has its cube there instead, and a cube culls less than
+     the sphere inside it.
+    */
+    if (vg_cut_sphere_outside(instance_base, vg_sphere_at(row + ${VGEO_CLUSTER_ROW_OFFSET.SELF_SPHERE}u))) {
+        vg_stat(${VGEO_CUT_STAT.CULLED_CLUSTER}u, 1u);
+
+        return vg_verdict(VG_VERDICT_NONE, cluster);
+    }
+
+    let cull_box = vg_box_at(row + ${VGEO_CLUSTER_ROW_OFFSET.CULL_BOX}u);
+
+    if (vg_cut_box_outside(instance_base, cull_box[0], cull_box[1])) {
+        vg_stat(${VGEO_CUT_STAT.CULLED_CLUSTER}u, 1u);
+        vg_stat(${VGEO_CUT_STAT.CULLED_CLUSTER_BOX}u, 1u);
+
+        return vg_verdict(VG_VERDICT_NONE, cluster);
+    }
+
+    let self_projected = vg_project(
+        vg_arena_f32(row + ${VGEO_CLUSTER_ROW_OFFSET.SELF_ERROR}u),
+        vg_sphere_at(row + ${VGEO_CLUSTER_ROW_OFFSET.SELF_SPHERE}u),
+        eye, k, w
+    );
+
+    let child_page_index = vg_arena[row + ${VGEO_CLUSTER_ROW_OFFSET.CHILD_PAGE_INDEX}u];
+
+    if (self_projected <= params.tau || child_page_index == VG_NO_CHILD_PAGE) {
+        return vg_verdict(VG_VERDICT_TAKE, cluster);
+    }
+
+    let child_page_row = vg_lookup[lookup_base + child_page_index];
+    let child_group = vg_arena[row + ${VGEO_CLUSTER_ROW_OFFSET.CHILD_GROUP}u];
+
+    var verdict = vg_verdict(VG_VERDICT_REFINE, cluster);
+
+    verdict.child_page_row = child_page_row;
+    verdict.child_page_index = child_page_index;
+    verdict.child_group = child_group;
+
+    if (child_page_row == VG_PAGE_ROW_NONE) {
+        /*
+         The clamp. Drawing this cluster is not a fallback for a missing one — it is the correct
+         coarser surface over exactly the region the missing page would have refined, which is
+         what makes an arriving cut watertight at every moment rather than only at the end.
+         */
+        verdict.kind = VG_VERDICT_CLAMP;
+        verdict.child_ref = vg_arena[row + ${VGEO_CLUSTER_ROW_OFFSET.CHILD_REF}u];
+        verdict.projected = self_projected;
+
+        return verdict;
+    }
+
+    if (!vg_group_selectable(child_page_row, child_group)) {
+        /*
+         The bytes are here and the group is still waiting on a page holding one of its *other*
+         parents, so there is nothing to fetch from this cluster. Another cluster in this same
+         cut is clamped directly against that page and wants it — monotonicity puts every
+         ancestor of a cluster projecting above tau above tau as well.
+         */
+        verdict.kind = VG_VERDICT_HELD;
+    }
+
+    return verdict;
+}
+
+/**
+ * Child \`k\` of an expansion, as an item.
+ *
+ * Pure, and that is what lets the same rule serve both consumers: the lane that keeps a child calls
+ * it with values shuffled out of the producer's registers, and the lane that spills one calls it
+ * with its own.
+ */
+fn vg_child(instance_slot: u32, expand: VGExpand, k: u32) -> VGItem {
+    if (expand.kind == VG_EXPAND_NODES) {
+        return VGItem(instance_slot, expand.page_row, expand.first + k, 0u);
+    }
+
+    if (expand.kind == VG_EXPAND_CLUSTERS) {
+        let at = vg_leaf_cluster(expand.page_row, expand.first, expand.span, k);
+
+        return VGItem(instance_slot, expand.page_row, at.x | VG_QUEUE_GROUP_BIT, at.y);
+    }
+
+    if (expand.kind == VG_EXPAND_PARENTS) {
+        // entry first + k of the *producing* page's parent rows; the page it names is
+        // resolved and claimed when this item is executed, not here
+        return VGItem(
+            instance_slot, expand.page_row, (expand.first + k) | VG_QUEUE_PARENT_BIT, 0u
+        );
+    }
+
+    // VG_EXPAND_PAGE: the child page's node 0, which is how a descent crosses a page boundary
+    return VGItem(instance_slot, expand.page_row, 0u, 0u);
+}
+`, [chunk_vgeo_cut_access, chunk_vgeo_cut_stat]);

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

@@ -0,0 +1,16 @@
+/**
+ * A cut's counters, `VGEO_CUT_STAT`, in its own slot of the frame's feedback:
+ *
+ * ```wgsl
+ * fn vg_stat(slot: u32, amount: u32)
+ * ```
+ *
+ * Requires the importing shader to declare `params` and `feedback`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_stat: CodeChunk;
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_vgeo_cut_stat.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_vgeo_cut_stat.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_stat.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,kCAFU,SAAS,CAShB;0BAtBuB,0CAA0C"}

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

@@ -0,0 +1,23 @@
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+
+/**
+ * A cut's counters, `VGEO_CUT_STAT`, in its own slot of the frame's feedback:
+ *
+ * ```wgsl
+ * fn vg_stat(slot: u32, amount: u32)
+ * ```
+ *
+ * Requires the importing shader to declare `params` and `feedback`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_stat = 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);
+}
+`);

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

@@ -0,0 +1,17 @@
+/**
+ * A cut asking for the page a clamped cluster could not reach, into its own slot of the frame's feedback, which
+ * `VGeoResidency` ranks with every other slot's:
+ *
+ * ```wgsl
+ * fn vg_want(source_page_row: u32, child_ref: u32, child_page_index: u32, lookup_base: u32, projected: f32)
+ * ```
+ *
+ * Requires the importing shader to declare `params`, `feedback` and `vg_want_stamps`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_want: CodeChunk;
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_vgeo_cut_want.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_vgeo_cut_want.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_want.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;GAaG;AACH,kCAFU,SAAS,CA+CO;0BAhEA,0CAA0C"}

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

@@ -0,0 +1,65 @@
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { VGEO_CUT_STAT } from "../layout/VGEO_CUT_STAT.js";
+import { VGEO_WANT_WORDS } from "../layout/VGEO_WANT_WORDS.js";
+import { chunk_vgeo_cut_stat } from "./chunk_vgeo_cut_stat.js";
+
+/**
+ * A cut asking for the page a clamped cluster could not reach, into its own slot of the frame's feedback, which
+ * `VGeoResidency` ranks with every other slot's:
+ *
+ * ```wgsl
+ * fn vg_want(source_page_row: u32, child_ref: u32, child_page_index: u32, lookup_base: u32, projected: f32)
+ * ```
+ *
+ * Requires the importing shader to declare `params`, `feedback` and `vg_want_stamps`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_want = CodeChunk.from(
+    //language=WGSL
+    `
+const VG_WANT_WORDS = ${VGEO_WANT_WORDS}u;
+
+/**
+ * Ask for the page a clamped cluster could not reach.
+ *
+ * Deduped on the child page, so a hundred clusters clamped against one page produce one request.
+ * The record names the page the want was discovered **through** as well as the page wanted: the
+ * source page's child table holds the exact byte range at child_ref, so the fetch costs one
+ * round trip and no metadata request, and it is also the page format §10 asks to be pinned while
+ * the child is in flight — which nothing but the cut can name, since the format stores parent counts
+ * rather than parent references.
+ *
+ * Priority is the first writer's projected error rather than the maximum over all of them. Taking a
+ * true maximum needs the record's slot, and a later writer cannot read that slot without waiting
+ * for the first writer to publish it. It is pixels of error either way, comparable across assets,
+ * and VGeoResidencyManager maxes across frames.
+ */
+fn vg_want(source_page_row: u32, child_ref: u32, child_page_index: u32, lookup_base: u32, projected: f32) {
+    // persistent and frame-tagged rather than cleared: a stamp already holding this frame's tag
+    // was written by this frame, and anything else is a frame that has gone
+    if (atomicExchange(&vg_want_stamps[lookup_base + child_page_index], params.frame_tag)
+        == params.frame_tag) {
+        return;
+    }
+
+    // this view's slice and this view's counter, so an earlier view's full list takes no room here
+    let slot = atomicAdd(&feedback[params.want_count_offset], 1u);
+
+    if (slot >= params.want_capacity) {
+        vg_stat(${VGEO_CUT_STAT.WANTS_DROPPED}u, 1u);
+        return;
+    }
+
+    let base = params.want_base + slot * VG_WANT_WORDS;
+
+    atomicStore(&feedback[base], source_page_row);
+    atomicStore(&feedback[base + 1u], child_ref);
+    atomicStore(&feedback[base + 2u], child_page_index);
+    // over this view's own threshold, so the residency can rank wants from views that count in
+    // different units at different thresholds on one scale
+    atomicStore(&feedback[base + 3u], bitcast<u32>(projected / params.tau));
+}
+`, [chunk_vgeo_cut_stat]);

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

@@ -1 +1 @@
-{"version":3,"file":"shader_vgeo_cut_collect.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_collect.js"],"names":[],"mappings":"AAqRA,oDAIG;8BAnR2B,qCAAqC"}
+{"version":3,"file":"shader_vgeo_cut_collect.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_collect.js"],"names":[],"mappings":"AA6NA,oDAIG;8BA3N2B,qCAAqC"}