@woosh/meep-engine 3.26.0 → 3.28.0

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

@@ -0,0 +1,19 @@
+/**
+ * Where a row is, in the arena — and nothing else.
+ *
+ * Split out of {@link chunk_vgeo_cut_access} because three passes want an address and only one of
+ * them wants a projection. Before the split, a pass that needed one field of a page header wrote
+ * its own accessor rather than take a chunk that also declares the frustum test, the instance eye
+ * and the error projection; `shader_vgeo_cut_reseed` said so where its copy was
+ * (`vg_reseed_page_field`). The answer to "the chunk declares more than this pass binds" is a
+ * smaller chunk, not a second accessor.
+ *
+ * Requires the importing shader to declare `params` and `vg_arena`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_arena: CodeChunk;
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_vgeo_cut_arena.d.ts.map

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

@@ -0,0 +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,CAwEZ;0BAjGmB,0CAA0C"}

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

@@ -0,0 +1,98 @@
+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_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";
+import { VGEO_NODE_ROW_WORDS } from "../layout/VGEO_NODE_ROW_WORDS.js";
+import { VGEO_PAGE_ROW_OFFSET } from "../layout/VGEO_PAGE_ROW_OFFSET.js";
+import { VGEO_PAGE_ROW_WORDS } from "../layout/VGEO_PAGE_ROW_WORDS.js";
+import { VGEO_PARENT_ROW_WORDS } from "../layout/VGEO_PARENT_ROW_WORDS.js";
+
+/**
+ * Where a row is, in the arena — and nothing else.
+ *
+ * Split out of {@link chunk_vgeo_cut_access} because three passes want an address and only one of
+ * them wants a projection. Before the split, a pass that needed one field of a page header wrote
+ * its own accessor rather than take a chunk that also declares the frustum test, the instance eye
+ * and the error projection; `shader_vgeo_cut_reseed` said so where its copy was
+ * (`vg_reseed_page_field`). The answer to "the chunk declares more than this pass binds" is a
+ * smaller chunk, not a second accessor.
+ *
+ * Requires the importing shader to declare `params` and `vg_arena`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_arena = CodeChunk.from(
+    //language=WGSL
+    `
+const VG_PAGE_ROW_WORDS = ${VGEO_PAGE_ROW_WORDS}u;
+const VG_NODE_ROW_WORDS = ${VGEO_NODE_ROW_WORDS}u;
+const VG_GROUP_ROW_WORDS = ${VGEO_GROUP_ROW_WORDS}u;
+const VG_CLUSTER_ROW_WORDS = ${VGEO_CLUSTER_ROW_WORDS}u;
+const VG_PARENT_ROW_WORDS = ${VGEO_PARENT_ROW_WORDS}u;
+const VG_INSTANCE_WORDS = ${VGEO_INSTANCE_WORDS}u;
+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;
+
+/**
+ * A page's slot: its header, then its node, group and cluster rows.
+ *
+ * The stride is a uniform rather than a constant because the tier derives it from the page size its
+ * containers are bounded at, and it is a **multiply** rather than a table read because format
+ * §11.14 made that legal — design §6 asked for fixed-size page slots from the start and the bound
+ * is what it was waiting for. There is no page table, no allocator, and no second storage binding
+ * to keep coherent with this one.
+ */
+fn vg_slot_base(page_row: u32) -> u32 {
+    return page_row * params.page_slot_words;
+}
+
+fn vg_page_field(page_row: u32, field: u32) -> u32 {
+    return vg_arena[vg_slot_base(page_row) + field];
+}
+
+fn vg_node_base(page_row: u32) -> u32 {
+    return vg_slot_base(page_row) + VG_PAGE_ROW_WORDS;
+}
+
+fn vg_group_base(page_row: u32) -> u32 {
+    return vg_node_base(page_row)
+        + vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.NODE_COUNT}u) * VG_NODE_ROW_WORDS;
+}
+
+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;
+}
+
+/**
+ * The fourth section: this page's parent rows, which is where a walk *up* reads.
+ *
+ * It may be empty, and a reader has to check rather than assume: the page row's parent
+ * entry count is zero for
+ * every page of a container written before format 4, which has no upward edge at all. Zero is not a
+ * malformed page; it is an asset that can only be re-descended.
+ */
+fn vg_parent_base(page_row: u32) -> u32 {
+    return vg_cluster_base(page_row)
+        + vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.CLUSTER_COUNT}u) * VG_CLUSTER_ROW_WORDS;
+}
+
+fn vg_arena_f32(word: u32) -> f32 {
+    return bitcast<f32>(vg_arena[word]);
+}
+
+fn vg_sphere_at(word: u32) -> vec4<f32> {
+    return vec4<f32>(
+        bitcast<f32>(vg_arena[word]),
+        bitcast<f32>(vg_arena[word + 1u]),
+        bitcast<f32>(vg_arena[word + 2u]),
+        bitcast<f32>(vg_arena[word + 3u])
+    );
+}
+`, []);

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

@@ -0,0 +1,31 @@
+/**
+ * One page, claimed once per instance, and touched when the claim is won.
+ *
+ * This is the invariant the whole cut rests on — "at most one draw record per (instance, cluster)" —
+ * and it was written out three times: here's-the-original in `shader_vgeo_cut_traverse`, a
+ * line-for-line copy in `shader_vgeo_cut_reseed`, and inline in `shader_vgeo_cut_seed`. The
+ * copies had already begun to differ: the seed pass omitted the `claim_word_count` bound the other
+ * two take. It was correct — the seed pass establishes that bound a few lines earlier — but a
+ * correctness invariant whose three spellings disagree about which checks it needs is one nobody
+ * can read off the source any more.
+ *
+ * The touch is the other half and travels with it, because a claim that does not stamp the page is
+ * a page that ages out of the LRU while it is on screen. LRU on last-**touched**, never on
+ * last-wanted: stamping at fetch time freezes the stamp of exactly the pages that are being drawn
+ * and evicts them, which is the fallback-chain bug the virtual texture cache already keys on touch
+ * to avoid.
+ *
+ * One bit per page row, because the feedback buffer is per frame rather than per invocation: the
+ * bit dedups across every view and bucket of the frame and is the record the host reads, so there
+ * is no list to fill and no touch a full list could lose.
+ *
+ * Requires the importing shader to declare `params`, `vg_arena`, `instances`, `claim` and
+ * `feedback`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_claim: CodeChunk;
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_vgeo_cut_claim.d.ts.map

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

@@ -0,0 +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":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,mCAFU,SAAS,CAiEQ;0BAlGD,0CAA0C"}

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

@@ -0,0 +1,99 @@
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.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_PAGE_ROW_OFFSET } from "../layout/VGEO_PAGE_ROW_OFFSET.js";
+import { chunk_vgeo_cut_arena } from "./chunk_vgeo_cut_arena.js";
+
+/**
+ * One page, claimed once per instance, and touched when the claim is won.
+ *
+ * This is the invariant the whole cut rests on — "at most one draw record per (instance, cluster)" —
+ * and it was written out three times: here's-the-original in `shader_vgeo_cut_traverse`, a
+ * line-for-line copy in `shader_vgeo_cut_reseed`, and inline in `shader_vgeo_cut_seed`. The
+ * copies had already begun to differ: the seed pass omitted the `claim_word_count` bound the other
+ * two take. It was correct — the seed pass establishes that bound a few lines earlier — but a
+ * correctness invariant whose three spellings disagree about which checks it needs is one nobody
+ * can read off the source any more.
+ *
+ * The touch is the other half and travels with it, because a claim that does not stamp the page is
+ * a page that ages out of the LRU while it is on screen. LRU on last-**touched**, never on
+ * last-wanted: stamping at fetch time freezes the stamp of exactly the pages that are being drawn
+ * and evicts them, which is the fallback-chain bug the virtual texture cache already keys on touch
+ * to avoid.
+ *
+ * One bit per page row, because the feedback buffer is per frame rather than per invocation: the
+ * bit dedups across every view and bucket of the frame and is the record the host reads, so there
+ * is no list to fill and no touch a full list could lose.
+ *
+ * Requires the importing shader to declare `params`, `vg_arena`, `instances`, `claim` and
+ * `feedback`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_claim = CodeChunk.from(
+    //language=WGSL
+    `
+fn vg_stat(slot: u32, amount: u32) {
+    atomicAdd(&feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + slot], amount);
+}
+
+/**
+ * Record that this page was selected from this frame — design §6's eviction key.
+ */
+fn vg_touch_page(page_row: u32) {
+    atomicOr(&feedback[params.touch_bits_base + (page_row >> 5u)], 1u << (page_row & 31u));
+}
+
+/**
+ * The claim itself, against a slice of the bitmask the caller already has in hand.
+ *
+ * Taken this way rather than always through the instance record because the seed pass computes the
+ * slice base in the same invocation that claims with it — it has just written it to the instance
+ * record, and reading it straight back would be a storage round trip for a value already in a
+ * register.
+ *
+ * @returns whether this invocation is the one that claimed the page
+ */
+fn vg_claim_page_at(claim_base: u32, ordinal_capacity: u32, page_row: u32) -> bool {
+    let ordinal = vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.ORDINAL}u);
+
+    if (ordinal >= ordinal_capacity) {
+        return false;
+    }
+
+    let bit = claim_base + 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;
+    }
+
+    vg_stat(${VGEO_CUT_STAT.PAGES}u, 1u);
+
+    vg_touch_page(page_row);
+
+    return true;
+}
+
+/**
+ * The same claim, for a caller holding an instance rather than its slice. An instance whose slice
+ * of the bitmask does not fit is refused upstream, in the seed pass, rather than run unclaimed.
+ */
+fn vg_claim_page(instance_base: u32, page_row: u32) -> bool {
+    return vg_claim_page_at(
+        instances[instance_base + ${VGEO_INSTANCE_OFFSET.CLAIM_BASE}u],
+        instances[instance_base + ${VGEO_INSTANCE_OFFSET.ORDINAL_CAPACITY}u],
+        page_row
+    );
+}
+`, [chunk_vgeo_cut_arena]);

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

@@ -0,0 +1,17 @@
+/**
+ * Put one page on the wavefront queue at its root node.
+ *
+ * Both passes that start a descent — the seed, from an instance's root page, and the reseed, from
+ * last frame's frontier — push the same four words and drop on the same bound, and both wrote it
+ * out. `shader_vgeo_cut_traverse` does not use this: it reserves a run for a whole workgroup's
+ * spill in one `atomicAdd` and writes into it, which is a different thing wearing the same words.
+ *
+ * Requires the importing shader to declare `params`, `queue_out` and `feedback`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_queue: CodeChunk;
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_vgeo_cut_queue.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_vgeo_cut_queue.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/chunk_vgeo_cut_queue.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,mCAFU,SAAS,CAsBQ;0BAtCD,0CAA0C"}

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

@@ -0,0 +1,39 @@
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { VGEO_CUT_STAT } from "../layout/VGEO_CUT_STAT.js";
+import { chunk_vgeo_cut_claim } from "./chunk_vgeo_cut_claim.js";
+
+/**
+ * Put one page on the wavefront queue at its root node.
+ *
+ * Both passes that start a descent — the seed, from an instance's root page, and the reseed, from
+ * last frame's frontier — push the same four words and drop on the same bound, and both wrote it
+ * out. `shader_vgeo_cut_traverse` does not use this: it reserves a run for a whole workgroup's
+ * spill in one `atomicAdd` and writes into it, which is a different thing wearing the same words.
+ *
+ * Requires the importing shader to declare `params`, `queue_out` and `feedback`.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_cut_queue = CodeChunk.from(
+    //language=WGSL
+    `
+fn vg_queue_push_root(instance_slot: u32, page_row: u32) {
+    let slot = atomicAdd(&queue_out.count, 1u);
+
+    if (slot >= params.queue_capacity) {
+        vg_stat(${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;
+}
+`, [chunk_vgeo_cut_claim]);

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":"AA0PA,oDAIG;8BAxP2B,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":"AA2QA,oDAIG;8BAzQ2B,qCAAqC"}

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

@@ -102,7 +102,24 @@ fn vg_store_plane(base: u32, plane: u32, row_w: vec4<f32>, row: vec4<f32>, sign:
 fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
     let input_index = global_id.x;
 
-    if (input_index >= input_meshes.count) {
+    /*
+     The count, against what the collection can actually hold, the way every sibling filter over
+     this shape reads it. The producer feeding this seam — \`shader_hzb_mesh_filter_2way\` — reserves
+     a slot with an unconditional \`atomicAdd\` and bounds-checks only the element *write*, so a
+     bucket whose positive set overflows hands over a count past the end of its own elements. The
+     indirect dispatch is built from that same count, so the overshoot arrives here as extra lanes
+     rather than as a loop bound this pass could have ignored.
+
+     Reading past the end is not the failure — robustness bounds that. The failure is what the
+     bounded read comes back with: a mesh row this bucket never selected, which the lines below
+     treat as a real instance, and if that row's geometry happens to be virtual it is collected and
+     cut. Every other bound in this pass degrades toward *fewer* instances; this one degraded into a
+     cut of geometry nobody asked for, which is the one direction a silently-wrong picture comes
+     from.
+     */
+    let input_size = min(input_meshes.count, arrayLength(&input_meshes.elements));
+
+    if (input_index >= input_size) {
         return;
     }
 

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

@@ -1 +1 @@
-{"version":3,"file":"shader_vgeo_cut_queue_prepare.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_queue_prepare.js"],"names":[],"mappings":"AA2EA,0DAIG;8BA3E2B,qCAAqC"}
+{"version":3,"file":"shader_vgeo_cut_queue_prepare.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_queue_prepare.js"],"names":[],"mappings":"AAiEA,0DAIG;8BAnE2B,qCAAqC"}

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

@@ -1,5 +1,3 @@
-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_WRITE } from "../../../../gpu_primitive/COLLECTION_U32_STRUCT_WRITE.js";
 import { ComputeShader } from "../../../../shader/ComputeShader.js";
@@ -8,8 +6,6 @@ import {
 } from "../../../../gpu_primitive/indirect/STRUCT_DISPATCH_COMPUTE_COMMAND.js";
 import { ShaderResourceSetDescriptor } from "../../../../shader/resource/ShaderResourceSetDescriptor.js";
 import { chunk_divide_round_up_u32 } from "../../../../shader/chunk/math/chunk_divide_round_up_u32.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";
 import { VGEO_CUT_WORKGROUP_SIZE } from "./VGEO_CUT_WORKGROUP_SIZE.js";
 
@@ -27,6 +23,11 @@ import { VGEO_CUT_WORKGROUP_SIZE } from "./VGEO_CUT_WORKGROUP_SIZE.js";
  * the buffer this iteration reads is the one the next iteration writes, and there is exactly one
  * moment when neither pass is touching it.
  *
+ * **It records no statistic.** There is another wavefront after it, so the count it sees is a
+ * frontier rather than a remainder, and it runs once per iteration per expansion site, so anything
+ * it stored would be overwritten by the next iteration and then by the next site. What the descent
+ * was left holding is {@link shader_vgeo_cut_queue_remainder}, recorded once, after the loop.
+ *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
@@ -40,8 +41,6 @@ resources.createGroup()
     // what the next wavefront will produce into
     .addStorageBuffer("queue_spare", COLLECTION_U32_STRUCT_WRITE, true)
     .addStorageBuffer("command", STRUCT_DISPATCH_COMPUTE_COMMAND, true)
-    // the frame's counters: this is the only pass that can see how deep the descent went
-    .addStorageBuffer("feedback", WebGPUArray.from(atomic_u32), true)
 ;
 
 const body = CodeChunk.from(
@@ -56,15 +55,6 @@ fn main() {
     atomicStore(&queue_ready.count, count);
     atomicStore(&queue_spare.count, 0u);
 
-    /*
-     What was outstanding when this pass ran. A plain store rather than an add, so the last prepare
-     of the frame is the one that is read — and the seam records one extra prepare after the
-     wavefront loop, whose whole purpose is to leave this number behind. A descent that stops with
-     work still queued is the one degradation that costs a hole rather than coarseness, and until
-     now nothing anywhere counted it (REVIEW_LEDGER M8).
-     */
-    atomicStore(&feedback[${VGEO_FEEDBACK_OFFSET.STATS}u + ${VGEO_CUT_STAT.QUEUE_REMAINING}u], count);
-
     command.workgroupCountX = divide_round_up_u32(count, ${VGEO_CUT_WORKGROUP_SIZE}u);
     command.workgroupCountY = 1u;
     command.workgroupCountZ = 1u;

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_vgeo_cut_queue_remainder.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/runtime/cut/shader_vgeo_cut_queue_remainder.js"],"names":[],"mappings":"AAwEA,4DAIG;8BAxE2B,qCAAqC"}

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":"AA6HA,mDAIG;8BA9H2B,qCAAqC"}

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

@@ -0,0 +1,130 @@
+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 { chunk_vgeo_cut_claim } from "./chunk_vgeo_cut_claim.js";
+import { chunk_vgeo_cut_queue } from "./chunk_vgeo_cut_queue.js";
+import { COLLECTION_U32_STRUCT_WRITE } from "../../../../gpu_primitive/COLLECTION_U32_STRUCT_WRITE.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
+    `
+@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_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.GEOMETRY_ROW}u)
+        != vg_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_claim_page(instance_base, page_row)) {
+        return;
+    }
+
+    vg_queue_push_root(instance_slot, page_row);
+}
+`, [chunk_vgeo_cut_claim, chunk_vgeo_cut_queue]);
+
+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":"AAsIA,iDAIG;8BArI2B,qCAAqC"}