@woosh/meep-engine 3.60.4 → 3.60.5

package/src/shade/renderer/geometry/virtual/VK_LOD_CLUSTERS_COMPARISON_2026_08_20.md

@@ -1,301 +0,0 @@
-# vk_lod_clusters — what NVIDIA's reference implementation does differently
-
-Review of [nvpro-samples/vk_lod_clusters](https://github.com/nvpro-samples/vk_lod_clusters)
-against the current design and builder. It is the closest thing to a reference
-implementation of this design that exists in the open: Nanite-family cluster LOD, GPU cut,
-demand streaming inside a memory budget, both raster (mesh shaders) and ray tracing
-(`VK_NV_cluster_acceleration_structure`). Its stress scene is Zorah at 18.9 G triangles with
-instancing and a 26 GB cache, which is the scale §5 of the design is written for.
-
-The build side is a fork of meshoptimizer's single-header `clusterlod.h`
-(`src/meshopt_clusterlod.h`); the runtime is the sample's own shaders.
-
-> **Status.** Reviewed and decided. What was taken, what was declined and why, and what is
-> scheduled but not yet built, all live in
-> [VIRTUAL_GEOMETRY_PLAN.md](./VIRTUAL_GEOMETRY_PLAN.md) — that file is the one to act on.
-> This one is kept as the analysis behind those decisions.
->
-> It is a **snapshot dated in its filename** and is not maintained against the code. Statements
-> about meep that have since gone stale are corrected inline in block quotes like this one,
-> rather than edited away — the argument that was made at the time is the reason the decision
-> was taken, and rewriting it hides that.
-
-## 1. Where it confirms decisions already made
-
-Corroboration, not findings — but each of these was a judgement call and it is worth knowing
-someone else made it the same way.
-
-| Decision | vk_lod_clusters | meep |
-|---|---|---|
-| Build terminates at one root | `while (context.pending.size() > 1)`, then emits a final group with `bounds.error = FLT_MAX` | round loop to one cluster, `parent_error = +∞` |
-| Group is the LOD and residency atom | groups are "collections of decimated clusters that are seamless with one another"; streaming is per group | group never spans pages, activation is group-atomic |
-| Parents inherit the group's bounds | `boundsMerge` computes the group's sphere; the new cluster inherits it rather than recomputing — explicitly "ensuring monotonicity" | `self_sphere = step.sphere`, shared per step |
-| Error projection | `errorDistance = max(minDistance, sphereDistance - radius·uniformScale)`; test is `error·scale / errorDistance ≥ threshold` | `r_e · h / (2·tan(fov/2)·d)`, `d` = distance to the sphere's closest point |
-| Simplify to a ratio of triangles | `target_size = (merged/3 · simplify_ratio) · 3` | `simplification_ratio = 0.5` |
-| Coarsest LOD always resident | lowest-detail group of every geometry loaded persistently, excluded from the budget | root page always resident |
-| Age/LRU eviction | `stream_agefilter_groups.comp.glsl` | touch-LRU |
-| Blob alignment | group blobs 16-byte aligned, sections relative to the group base | frames 16-byte aligned, page-relative offsets |
-
-## 2. The architectural fork: it traverses, and it traverses on the GPU
-
-Design §4 pins the cut as "evaluated independently per cluster, no traversal". This sample
-does the opposite and does it entirely device-side, and the machinery it uses is the answer
-to the objection that made meep pick the flat rule.
-
-### 2.1 There is a node hierarchy above the DAG
-
-The thing traversed is **not** the cluster DAG. It is a separate tree of `Node`s whose leaves
-are groups:
-
-```
-Node_packed_nodeChildCountMinusOne
-Node_packed_nodeChildOffset      // index into geometry.nodes
-Node_packed_isGroup
-Node_packed_groupIndex           // when isGroup
-traversalMetric                  // bounding sphere + maxQuadricError
-```
-
-Each LOD level gets its own node tree over that level's groups, and "all lod levels' node
-trees are then linked together at the root of the hierarchy". Descending is one test per
-node: `testForTraversal` on the node's own metric; an inner node enqueues its children, a
-group node enqueues the group, whose clusters are then emitted.
-
-**Correction (later revision).** This section originally said "meep has no equivalent
-structure". That is wrong. meep's **pages already form a rooted, acyclic, fully-reachable
-DAG** — all three properties stated in VGEO_FORMAT §11.3–11.4 and enforced by the validator
-— and it is a real DAG, not a chain: on a 98k-triangle sphere at 32 KB pages, 91 pages, 291
-edges, in-degree up to 7, and 82 of the 91 pages have more than one parent. What meep lacks
-is not a hierarchy but a **metric on the one it has**: a child-table entry carries enough to
-*fetch* a page and nothing with which to decide whether to. See
-[VIRTUAL_GEOMETRY_PLAN.md](./VIRTUAL_GEOMETRY_PLAN.md) §2.2, which supersedes this paragraph.
-
-What remains true is the difference in *granularity*. nvpro's nodes cover groups; a page
-covers a band's worth of them. Node granularity is what buys fine culling and width at the
-top; page granularity is what buys the decision that actually costs money, which is whether
-to fetch. Both now exist: a metric on every child-table entry and page header, and a group
-tree inside each page (VGEO_FORMAT §6.1–6.2), at 0.3%–1.6% of asset size.
-
-### 2.2 Culling skips subtrees, not clusters
-
-`processSubTask` frustum-tests each node and, with `USE_TWO_PASS_CULLING`, HiZ-tests it
-against the previous frame's depth pyramid. A node that fails takes its whole subtree with
-it. The flat rule cannot do this; it has already paid for every cluster by the time the
-per-view filters see them.
-
-(Design §4's claim that the cut is view-agnostic and reusable by shadow views has since been
-withdrawn — virtual geometry is view-dependent, and this sample pays for a traversal per view
-because that is what the problem costs.)
-
-### 2.3 Streaming residency is the traversal's stopping condition
-
-```glsl
-uint64_t groupAddress = geometry.streamingGroupAddresses.d[groupIndex];
-if (groupAddress >= STREAMING_INVALID_ADDRESS_START) {
-  traverseNode = false;                       // stop descending here
-  uint64_t last = atomicMax(geometry.streamingGroupAddresses.d[groupIndex],
-                            streaming.request.frameIndex);
-  bool triggerRequest = last != streaming.request.frameIndex;   // dedupe within the frame
-  ...                                          // append to request.loadGeometryGroups
-}
-```
-
-Two things fall out of this that meep pays for separately:
-
-- **The residency clamp is free.** Design §4 needs an explicit "or child group
-  non-selectable" clause in the cut rule, and calls it "what makes *no holes, ever* true".
-  A traversal simply stops, and the coarser ancestor it already passed is the stand-in. No
-  clamp, no selectable bit, no group-atomic flag to keep coherent.
-- **The want-list needs no structure of its own.** An invalid address *is* the request slot:
-  the top bit marks it invalid, the low 63 bits hold the frame index, and `atomicMax` both
-  records the request and deduplicates it within the frame. meep's design has pages emitting
-  "wants" resolved from the emitting page; this is finer-grained (per group) and costs one
-  64-bit slot per group that had to exist anyway.
-
-### 2.4 Persistent threads make DAG traversal data-parallel
-
-`traversal_run.comp.glsl` runs a fixed thread pool over a producer/consumer queue —
-`traversalNodeInfos` with separate atomic read and write counters and an in-flight
-`traversalTaskCounter`. Variable child counts are packed densely across a subgroup with a
-prefix sum (`subgroupInclusiveAdd`), and enqueues avoid per-thread atomics via ballot:
-
-```glsl
-uvec4 voteNodes = subgroupBallot(traverseNode);
-if (subgroupElect()) { offsetNodes = atomicAdd(buildRW.traversalNodeWriteCounter, countNodes); ... }
-offsetNodes = subgroupBroadcastFirst(offsetNodes) + subgroupBallotExclusiveBitCount(voteNodes);
-```
-
-This is the piece worth taking whichever cut rule wins. "Traversal is serial" is not true of
-this shape, and Shade already has the subgroup primitives (the one-sweep radix sort uses
-them).
-
-## 3. Build-side ideas worth borrowing
-
-### 3.1 Error composition is a tunable blend, not pure addition
-
-```cpp
-bounds.error = std::max(bounds.error * config.simplify_error_merge_previous, error)
-             + error * config.simplify_error_merge_additive;
-```
-
-meep composes purely additively: `sqrt(residual) + max(child error)`. Design §4 justifies
-that with the triangle inequality and notes that a plain max does not bound cumulative
-drift. meshopt splits the difference and exposes both coefficients. Since pure addition
-demonstrably over-scales (§4 says so itself), and pure max under-bounds, a blend with the
-two coefficients as build options is strictly more expressive than what meep has, and costs
-one line.
-
-### 3.2 A stuck detector with an escalation ladder
-
-Simplification is "considered stuck if the result exceeds `merged.size() *
-simplify_threshold`", and the builder then falls back from
-`meshopt_simplifyWithAttributes` to **permissive**, then to **sloppy** mode, with
-`simplify_error_factor_sloppy` inflating the recorded error to pay for the reduced fidelity.
-
-meep's ladder is: simplify at ratio → if the re-split produced nothing, pass the group
-through unchanged → if no band or group size makes progress, throw. There is no middle rung.
-A permissive mode (allow non-manifold collapses, allow boundary movement where the boundary
-is not a group seam) with an honest error penalty would let the builder reduce in exactly the
-cases where it currently gives up — and those cases are real: the boundary-quadric gap in
-design §2 means open geometry reduces at recorded-zero error today, which is worse than
-reducing at an inflated one.
-
-> **Since this was written**: boundary constraint quadrics landed (plan §4.1), so that closing
-> argument is spent — open geometry no longer reduces at recorded-zero error, and the choice is
-> no longer between an honest inflated error and a dishonest zero. The case for a middle rung
-> survives it, but it is now the plain one: a group that cannot be reduced is carried forward
-> untouched, and enough of those is what makes a build fail to converge and throw. Plan §2.1
-> records that the sloppy-mode escalation is *safe* to build now for the same reason.
-
-### 3.3 A minimum cluster size
-
-`meshopt_buildMeshletsFlex` takes `min_triangles` as well as `max_triangles`, so a cluster
-can float within a band instead of being whatever the partition left behind.
-
-meep's splitter caps and never floors. Measured fill on the current builder runs 120
-tris/cluster at the leaves down to 67 at the coarse levels. A floor, enforced by merging
-under-filled pieces the way `pack_pieces` already does inside a group, would close that.
-
-> **Since this was written**: the leaf half landed (plan §1). A group of leaves with room to
-> spare between them is *re-cut* into fewer and fuller leaves rather than simplified —
-> `try_repack` in `vgeo_build_levels.js` — and the re-cut **replaces** them rather than
-> becoming their parent, because a step of zero error is a step the cut rule can never take.
-> Only leaves: above them the same re-cut would orphan a subtree. So the 120-at-the-leaves half
-> of that measurement is addressed and the 67-at-the-coarse-levels half still stands.
-
-### 3.4 Spatial variants at every partitioning step
-
-`clusterize()` picks `meshopt_buildMeshletsSpatial()` or `meshopt_buildMeshletsFlex()` on
-`config.cluster_spatial`; `partition()` passes `partition_spatial` to
-`meshopt_partitionClusters()`; groups are then reordered with `meshopt_spatialSortRemap()`.
-Spatial partitioning is a first-class option at every level, not a fallback.
-
-meep uses connectivity everywhere and falls back to Morton proximity only when a cluster is
-alone in its component. That ordering is defensible — it keeps clusters connected, which the
-design pins — but "spatial or connectivity" being a build *option* rather than a hardcoded
-policy is worth copying, because the right answer is plainly content-dependent: a scanned
-surface wants connectivity, a CAD assembly of loose parts wants space.
-
-Also note groups are sized "around `partition_size`" but "may be up to 1/3 larger" — soft
-group sizes, like meep's.
-
-### 3.5 Mantissa-bit dropping instead of quantization
-
-The README recommends "mantissa-bit dropping for positions and UVs" ahead of the lossless
-group compression.
-
-Design §2 lists cluster-local position quantization as new work "spanning encode, metadata
-struct, and every decode shader" — a large, invasive change. Dropping low mantissa bits of
-float32 keeps the layout, the struct and every decode shader **exactly as they are** and
-simply makes the bytes compress. It is not a substitute for quantization's memory win, but
-it is a fraction of the work for a real share of the benefit, and it composes with a page
-codec meep has not chosen yet (§12 lists it as open).
-
-## 4. Runtime ideas that need a small format change
-
-### 4.1 Per-level summary table → conservative instance LOD brackets
-
-`instance_classify_lod.comp.glsl` computes, per instance, a conservative **minimum and
-maximum LOD level**:
-
-- min: evaluate the metric at the closest point of the instance sphere, using *each level's
-  maximum error*; take the first level that passes.
-- max: place a sphere at the far end of the instance's bounding sphere and use the smallest
-  cluster group's error and radius as a worst case.
-
-This is sound because "successive LoD levels have monotonically increasing error/radius", so
-the transition cannot happen later than the bracket says.
-
-What it enables in this sample is BLAS sharing — one instance's acceleration structure
-reused by every other instance of that geometry whose bracket allows it. Measured on their
-LEGO scene: **3.9 ms → 1.6 ms frame time, 62 MB → 9 MB**. The stated limitation is that
-distant objects then render more detail than they need, and that one shared BLAS per
-geometry is a simplification they have not lifted.
-
-The bracket itself is worth more to meep than the BLAS trick. It needs one thing the format
-does not have: a **per-level summary table in the header** — `(max_error, max_radius,
-cluster_count)` per level, `level_count` entries. The builder already computes exactly this
-(`VGeoLevelSummary.max_error`) and throws it away at write time. With it, a runtime can:
-
-- bracket every instance without touching a single cluster record;
-- collapse instances whose bracket is one level onto a single shared cut, which is the whole
-  ballgame for a CAD scene of ten thousand identical fasteners;
-- prefetch precisely the bands a bracket spans, rather than discovering them by traversal.
-
-This is the cheapest high-leverage format change on this list, and it is additive — a table
-after the header, or a reserved-field pointer to it.
-
-### 4.2 Clamp the distance rather than special-casing the camera inside the sphere
-
-`errorDistance = max(minDistance, sphereDistance - radius·uniformScale)`.
-
-Design §4 handles the same degeneracy with a convention: "the camera-inside-sphere ⇒ +∞
-convention applies only when `r_e > 0` (otherwise leaves become undrawable exactly at close
-range)". A `minDistance` clamp gets the same behaviour with no qualifier and no branch —
-inside the sphere, the error is simply large but finite, and a zero-error leaf still projects
-to zero.
-
-### 4.3 GPU-driven allocation beats host estimates
-
-`docs/clas_allocation.md` reports host-side size estimates being "way too conservative (e.g.
-often 3-5x bigger than actual)" and moves allocation on-device with a readback for the real
-sizes. Two allocator designs are given: naive dense compaction (discouraged — "high memory
-movement bursts") and a **persistent device-resident allocator that moves an allocation only
-once, after construction**, with a free-gap list maintained on the GPU
-(`stream_allocator_build_freegaps.comp.glsl`,
-`stream_allocator_freegaps_insert.comp.glsl`).
-
-Design §2 records the mirror-image problem on meep's side: `GPUMeshletManager`'s
-compaction/growth is a CPU-side rebuild costing ~2× VRAM transiently, and meshlet-address
-migration is an unhandled TODO. A device-resident free-gap allocator that relocates once is
-the shape of the answer, and there is a working one to read.
-
-## 5. Not applicable, or deliberately different
-
-- **Ray tracing (CLAS/BLAS)** — `VK_NV_cluster_acceleration_structure` has no WebGPU
-  equivalent and will not for years. BLAS caching, merging and sharing are all downstream of
-  it. The *LOD-bracket* idea behind sharing (§4.1) is the transferable part.
-- **DLSS** — vendor-specific.
-- **Mesh shaders** — Shade's bucket pipeline issues `drawIndirect` per material with
-  instanceCount = meshlet count, which is the WebGPU-shaped equivalent; nothing to change.
-- **Their scene format** — `.nvsngeo` is a cache, not a streaming container: it has no page
-  structure, no directory, no integrity model, and no content addressing. `.vgeo` is ahead
-  here, and deliberately so.
-
-## 6. Recommendation
-
-In order of leverage per unit of work:
-
-1. **Write the per-level summary table into the header** (§4.1). Cheap, additive, and it is
-   the prerequisite for instance bracketing, shared cuts and precise prefetch.
-2. **Blend the error composition** (§3.1) and **clamp the distance** (§4.2). Two lines each,
-   both strictly better than what is pinned.
-3. **Build a node hierarchy over groups** (§2.1), even if the cut stays flat — it is what
-   makes subtree culling and prefetch possible at all, and it does not touch cluster records.
-4. **Measure the flat rule against a traversal at scale before treating §4's "no traversal"
-   as settled** (§2.2, §2.4). The persistent-thread + subgroup-ballot scheme removes the
-   parallelism objection; the residency clamp and the want-list both get simpler if traversal
-   wins (§2.3).
-5. **A stuck detector with a permissive fallback** (§3.2) and **a minimum cluster size**
-   (§3.3) — both address measured weaknesses in the current builder.
-6. **Mantissa-bit dropping** (§3.5) as the cheap first move on payload size, ahead of full
-   quantization.