@woosh/meep-engine 3.26.0 → 3.27.0

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

@@ -0,0 +1,77 @@
+import { atomic_u32 } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../../shader/type/WebGPUArray.js";
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { VGEO_CUT_STAT } from "../layout/VGEO_CUT_STAT.js";
+import { VGEO_FEEDBACK_OFFSET } from "../layout/VGEO_FEEDBACK_OFFSET.js";
+import { VGEO_CUT_PARAMS_STRUCT } from "./VGEO_CUT_PARAMS_STRUCT.js";
+
+/**
+ * After the wavefront loop: what the descent stopped with still queued.
+ *
+ * A queue item never popped is a subtree never descended, and the parent that would have stood in
+ * over it was not drawn either — it failed `project(self) <= tau`, which is what sent the descent
+ * down there. So this is the one bound of the cut that costs a **hole** rather than coarseness
+ * (RUNTIME_PLAN §4.5), and the only one whose reading cannot be inferred from the others.
+ *
+ * ## Why it is its own pass
+ *
+ * Only the pass *after the last wavefront* is looking at a remainder. The prepare pass runs
+ * between wavefronts, so its count is a frontier, and it runs once per iteration per expansion
+ * site, so whatever it stored the next iteration and then the next site would overwrite.
+ *
+ * An **add** rather than a store, because a frame holds more than one cut — two per view, since the
+ * two-way HZB filter splits positive from maybe — and they all record into the frame's one feedback
+ * buffer. A store would let the last site to run set the number for the whole frame, an empty cut
+ * zeroing a truncation another had just reported. Summing is the same combiner as every other stat
+ * in `VGEO_CUT_STAT` and is zero exactly when nothing was left behind, which is the property
+ * `VGeoResidencyManager` and anyone lowering `max_iterations` needs of it.
+ *
+ * The count lives in a transient the graph is about to recycle, so reading it on the CPU would be a
+ * readback of a buffer the frame is still writing. Two storage buffers, one uniform and one
+ * workgroup is cheaper than the alternative of not knowing.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("params", VGEO_CUT_PARAMS_STRUCT)
+    // the queue the last wavefront produced into and nothing consumed
+    .addStorageBuffer("queue_ready", COLLECTION_U32_STRUCT_READ, false)
+    .addStorageBuffer("feedback", WebGPUArray.from(atomic_u32), true)
+;
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(1)
+fn main() {
+    /*
+     Clamped the way the prepare pass clamps it, and for the same reason: a wavefront reserves its
+     output with atomicAdd and lets the count run past capacity, so the raw number counts items that
+     were never written. What was dropped at the append is QUEUE_DROPPED and is already counted
+     there; counting it here as well would report one lost subtree twice.
+     */
+    let outstanding = min(queue_ready.count, params.queue_capacity);
+
+    if (outstanding == 0u) {
+        return;
+    }
+
+    atomicAdd(
+        &feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + ${VGEO_CUT_STAT.QUEUE_REMAINING}u],
+        outstanding
+    );
+}
+`);
+
+export const shader_vgeo_cut_queue_remainder = ComputeShader.from({
+    label: "VGeo cut queue remainder",
+    body,
+    resources,
+});

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

@@ -0,0 +1,3 @@
+export const shader_vgeo_cut_reseed: ComputeShader;
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_vgeo_cut_reseed.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_vgeo_cut_reseed.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_reseed.js"],"names":[],"mappings":"AAqLA,mDAIG;8BAtL2B,qCAAqC"}

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

@@ -0,0 +1,186 @@
+import { atomic_u32, u32 } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../../shader/type/WebGPUArray.js";
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { COLLECTION_U32_STRUCT_WRITE } from "../../../../gpu_primitive/COLLECTION_U32_STRUCT_WRITE.js";
+import { VGEO_CUT_STAT } from "../layout/VGEO_CUT_STAT.js";
+import { VGEO_FEEDBACK_OFFSET } from "../layout/VGEO_FEEDBACK_OFFSET.js";
+import { VGEO_INSTANCE_OFFSET } from "../layout/VGEO_INSTANCE_OFFSET.js";
+import { VGEO_INSTANCE_WORDS } from "../layout/VGEO_INSTANCE_WORDS.js";
+import { VGEO_PAGE_ROW_NONE } from "../layout/VGEO_PAGE_ROW_NONE.js";
+import { VGEO_PAGE_ROW_OFFSET } from "../layout/VGEO_PAGE_ROW_OFFSET.js";
+import { VGEO_CUT_PARAMS_STRUCT } from "./VGEO_CUT_PARAMS_STRUCT.js";
+import { VGEO_CUT_WORKGROUP_SIZE } from "./VGEO_CUT_WORKGROUP_SIZE.js";
+
+/**
+ * Seed a cut from where the last one stood, instead of from the root.
+ *
+ * `shader_vgeo_cut_seed` puts one item per instance on the queue naming node 0 of that instance's
+ * root page, and the descent re-derives the whole cut — 39 levels on a converted container, at
+ * about half a microsecond a level a dispatch, every frame, for a camera that may not have moved.
+ * This pass puts the pages that cut *ended* on back on the queue instead, and the descent starts
+ * there: what has to change between two frames is a level or two in either direction, which the
+ * existing refinement and `VGEO_CUT_FLAG_COARSEN`'s walk up both reach.
+ *
+ * ## Pages, not groups
+ *
+ * `CUT_PLAN_2026_09_14` §1 describes the frontier as a set of groups. This one is a set of **page
+ * rows**, which is coarser and very much simpler: a page is the unit the claim is built on and the
+ * unit a visit evaluates whole, so a reseeded page needs no new item kind, no entry format and no
+ * dedup beyond the claim the descent already takes. Every group of the page is re-tested by the
+ * pure rule, and testing a group the cut did not need costs the test and nothing else.
+ *
+ * ## What makes a stale frontier safe
+ *
+ * Two things, and neither is a repair. A page row is reused, so a frontier written against one
+ * occupant could name another after an eviction — the host compares the pool's eviction count
+ * against the one the frontier was captured at and drops the whole view's frontier when they
+ * differ, rather than mending it. And a frontier that is merely *old* is not wrong at all: it names
+ * pages that are still a consistent place to stand, and the descent leaves them for finer ones
+ * while the coarsen path walks up from them.
+ *
+ * So the failure mode is a cut that costs what today's costs, which is the fallback the seam
+ * already has.
+ *
+ * ## One lane per (instance, page row)
+ *
+ * The frontier is per view rather than per (view, instance), so every instance is offered every
+ * page in it and the claim decides. That is a superset of what each instance needs — correct, and
+ * cheap while a view holds a handful of virtual-geometry instances. It is why this is a first form
+ * rather than the last one: §1.1 keys a frontier by mesh row precisely so a thousand instances do
+ * not each pay for the union, and that is the change this shape is waiting for.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("params", VGEO_CUT_PARAMS_STRUCT)
+    .addStorageBuffer("vg_arena", WebGPUArray.from(u32), false)
+    .addStorageBuffer("instances", WebGPUArray.from(u32), false)
+    .addStorageBuffer("frontier", WebGPUArray.from(u32), false)
+    .addStorageBuffer("queue_out", COLLECTION_U32_STRUCT_WRITE, true)
+    .addStorageBuffer("claim", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("feedback", WebGPUArray.from(atomic_u32), true)
+;
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+/**
+ * A field of a page's slot header. Indexed rather than read through the traversal's accessors,
+ * because those come with a chunk that declares rather more than this pass binds.
+ */
+fn vg_reseed_page_field(page_row: u32, field: u32) -> u32 {
+    return vg_arena[page_row * params.page_slot_words + field];
+}
+
+/**
+ * The claim, and the touch that goes with it — the seed pass's, taken against a page row that came
+ * off a bitmask rather than off a reference already resolved.
+ */
+fn vg_reseed_claim(instance_base: u32, page_row: u32) -> bool {
+    let ordinal = vg_reseed_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.ORDINAL}u);
+
+    if (ordinal >= instances[instance_base + ${VGEO_INSTANCE_OFFSET.ORDINAL_CAPACITY}u]) {
+        return false;
+    }
+
+    let bit = instances[instance_base + ${VGEO_INSTANCE_OFFSET.CLAIM_BASE}u] + ordinal;
+
+    let word = bit >> 5u;
+
+    if (word >= params.claim_word_count) {
+        return false;
+    }
+
+    let mask = 1u << (bit & 31u);
+
+    if ((atomicOr(&claim[word], mask) & mask) != 0u) {
+        return false;
+    }
+
+    atomicAdd(&feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + ${VGEO_CUT_STAT.PAGES}u], 1u);
+
+    atomicOr(&feedback[params.touch_bits_base + (page_row >> 5u)], 1u << (page_row & 31u));
+
+    return true;
+}
+
+@compute @workgroup_size(${VGEO_CUT_WORKGROUP_SIZE})
+fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
+    let rows = params.frontier_word_count * 32u;
+
+    if (rows == 0u) {
+        return;
+    }
+
+    let lane = global_id.x;
+
+    let instance_slot = lane / rows;
+    let page_row = lane - instance_slot * rows;
+
+    if (instance_slot >= params.instance_capacity) {
+        return;
+    }
+
+    if ((frontier[page_row >> 5u] & (1u << (page_row & 31u))) == 0u) {
+        return;
+    }
+
+    let instance_base = instance_slot * ${VGEO_INSTANCE_WORDS}u;
+
+    let root_row = instances[instance_base + ${VGEO_INSTANCE_OFFSET.ROOT_PAGE_ROW}u];
+
+    if (root_row == ${VGEO_PAGE_ROW_NONE}u) {
+        return;
+    }
+
+    /*
+     The page must belong to the geometry this instance draws. A frontier is a set of rows of a
+     shared tier and an instance of another geometry has no business standing on them — its claim
+     would reject the ordinal eventually, but the geometry row is the honest test and it is two
+     reads of a header that is already in cache.
+    */
+    if (vg_reseed_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.GEOMETRY_ROW}u)
+        != vg_reseed_page_field(root_row, ${VGEO_PAGE_ROW_OFFSET.GEOMETRY_ROW}u)) {
+        return;
+    }
+
+    /*
+     The claim, for the two reasons the seed takes one on the root: it stamps the page as touched,
+     which is the LRU's whole input, and it is what stops a page reached both from the frontier and
+     from a descent later in this same cut from being drawn twice.
+    */
+    if (!vg_reseed_claim(instance_base, page_row)) {
+        return;
+    }
+
+    let slot = atomicAdd(&queue_out.count, 1u);
+
+    if (slot >= params.queue_capacity) {
+        atomicAdd(
+            &feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + ${VGEO_CUT_STAT.QUEUE_DROPPED}u], 1u
+        );
+
+        return;
+    }
+
+    let base = slot * 4u;
+
+    queue_out.elements[base] = instance_slot;
+    queue_out.elements[base + 1u] = page_row;
+    // node 0, which is how every page visit in this runtime begins
+    queue_out.elements[base + 2u] = 0u;
+    queue_out.elements[base + 3u] = 0u;
+}
+`, []);
+
+export const shader_vgeo_cut_reseed = ComputeShader.from({
+    label: "VGeo cut reseed",
+    body,
+    resources,
+});

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

@@ -1 +1 @@
-{"version":3,"file":"shader_vgeo_cut_seed.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_seed.js"],"names":[],"mappings":"AA2IA,iDAIG;8BA1I2B,qCAAqC"}
+{"version":3,"file":"shader_vgeo_cut_seed.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_seed.js"],"names":[],"mappings":"AAuJA,iDAIG;8BAtJ2B,qCAAqC"}

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

@@ -53,7 +53,25 @@ const body = CodeChunk.from(
 fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
     let instance_slot = global_id.x;
 
-    if (instance_slot >= prefix_sums.count) {
+    /*
+     The same clamp the collect pass puts on its own input, one pass further along, because the
+     count that arrives here is produced the same way: \`shader_vgeo_cut_collect\` reserves a claim
+     width with an unconditional \`atomicAdd\` and bounds-checks only the element write, and the
+     prefix scan rewrites the elements and leaves the count untouched. So a frame that offered more
+     virtual instances than the collection holds hands this pass a count past the end of it, and —
+     as everywhere in the cut — the indirect dispatch is built from that count, so the overshoot
+     arrives as lanes.
+
+     One clamp covers both of this pass's reads: the scanned elements and the instance records are
+     sized from the same \`instance_capacity\`, so a slot past the end of one is past the end of the
+     other. A lane that ran anyway would take its root page row from whatever the bound range gives
+     it back rather than from an instance, and put *that* into the queue — a wavefront descending a
+     page on behalf of an instance the collect pass never wrote, claiming and touching it. The LRU
+     would then hold pages up for geometry nobody is looking at.
+     */
+    let instance_count = min(prefix_sums.count, arrayLength(&prefix_sums.elements));
+
+    if (instance_slot >= instance_count) {
         return;
     }
 
@@ -110,13 +128,7 @@ fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
 
     atomicAdd(&feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + ${VGEO_CUT_STAT.PAGES}u], 1u);
 
-    if (atomicExchange(&feedback[params.touch_stamp_base + page_row], 1u) == 0u) {
-        let touch_slot = atomicAdd(&feedback[${VGEO_FEEDBACK_OFFSET.TOUCH_COUNT}u], 1u);
-
-        if (touch_slot < params.touch_capacity) {
-            atomicStore(&feedback[params.touch_base + touch_slot], page_row);
-        }
-    }
+    atomicOr(&feedback[params.touch_bits_base + (page_row >> 5u)], 1u << (page_row & 31u));
 
     let slot = atomicAdd(&queue_out.count, 1u);
 

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

@@ -1 +1 @@
-{"version":3,"file":"shader_vgeo_cut_traverse.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_traverse.js"],"names":[],"mappings":"AA6gBA,qDAIG;8BA9gB2B,qCAAqC"}
+{"version":3,"file":"shader_vgeo_cut_traverse.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_traverse.js"],"names":[],"mappings":"AAq5BA,qDAIG;8BAt5B2B,qCAAqC"}