Alternative stencil resolvers for VoxelBlockManager

[swahtz]

Summary

This PR focuses on two independent costs that are part of resolving a 3×3×3 stencil through the VoxelBlockManager: 27 root-down tree traversals (one per tap), and a 27-element per-thread index array to hold the result. This PR adds new resolver functions (alongside the existing computeBoxStencil) that address each cost, and one that addresses both.

Each stencil shape comes in a plain and a Cached form, with a single convention stated on the class:

• <name> — resolves each tap by a root-down tree traversal. Thread-local like decodeInverseMap itself: no shared memory, no barrier, safe from divergent threads — the entire decode+resolve pipeline is.
• <name>Cached — the block cooperatively stages a per-leaf neighbour table in shared memory, so each tap is a direct in-leaf lookup. Substantially faster, but must be called by all threads (uses __syncthreads) and costs shared memory (the staged table only).

Independently, compute<Name> materializes taps into a 27-slot array while forEach<Name> streams (tap, index) to a device-inlined callback, avoiding the per-thread array entirely.

method	shape	resolution	output
computeBoxStencil (existing)	27-tap	tree walk	materialized
forEachBoxStencil	27-tap	tree walk	streamed
computeBoxStencilCached	27-tap	cached table	materialized
forEachBoxStencilCached	27-tap	cached table	streamed
computeCrossStencil	7-tap	tree walk	materialized
computeCrossStencilCached	7-tap	cached table	materialized

The cached resolvers exploit a structural property of the VBM: a block's voxels span few distinct, consecutive leaves, so the block cooperatively stages a per-leaf neighbour table in shared memory (built by all threads, not a leader) and each tap becomes a direct in-leaf lookup. A 3×3×3 stencil touches at most 7 neighbouring leaves, not 27 independent lookups. Blocks spanning more than MaxCachedLeaves fall back to per-tap traversal.

Built on the register-decode API (#2258)

This PR now stacks on #2258's consolidated thread-local decode (decodeInverseMap into registers; the shared-memory decodeInverseMaps is removed there). Every resolver takes the calling thread's decoded (leafIndex, voxelOffset) by value; the cached forms additionally take the block's firstLeafID and jumpMap and derive everything the staging needs from that metadata — the block's first leaf is firstLeafID, and the spanned-leaf count is 1 + popcount(jumpMap). Consequences:

• No materialized per-block maps exist anywhere: the leader election over smem_leafIndex[tID-1], its atomicMax span counter, and two of the three prologue barriers in the cached forms are gone (cachedLeafSpan is now a thread-local popcount).
• Shared memory is the resolver's table alone (ptxas -v, width 128): 3456 B for the cached box (down from 4228 B — the 512 B + 256 B map arrays and 4 B counter are gone), 896 B for the cached cross (down from 1668 B).
• The plain forms are divergent-safe end-to-end, decode included — previously the resolver was divergent-safe but the decode feeding it was cooperative.
• The one-thread-per-slot blockDim contract is dropped: resolvers operate on whatever slot the caller passes.

#2258 should merge first; this branch includes its commits via merge.

Measurements

All six resolvers measured in one run, on one grid, against one baseline, with the same consumer: resolve the taps, then accumulate C interleaved sidecar channels per tap (box variants accumulate their 27, cross variants their 7). Sparse sphere shell: 1.29M active voxels across 9140 leaves, mean leaf occupancy 141/512. RTX PRO 6000 (sm_120), median of 50 iterations. Output is byte-exact within each stencil shape.

One sidecar channel

method	shape	resolution	divergent-safe?	smem	output	w128 ms	w128 ×	w512 ms	w512 ×
computeBoxStencil (existing)	27-tap box	tree walk	yes	none	materialized	0.1856	1.00×	0.2616	1.00×
forEachBoxStencil	27-tap box	tree walk	yes	none	streamed	0.1388	1.34×	0.1428	1.83×
computeBoxStencilCached	27-tap box	cached table	no	3456 B	materialized	0.1527	1.22×	0.1427	1.83×
forEachBoxStencilCached	27-tap box	cached table	no	3456 B	streamed	0.0844	2.20×	0.0875	2.99×
computeCrossStencil	7-pt cross	tree walk	yes	none	materialized	0.0434	4.27×	0.0474	5.52×
computeCrossStencilCached	7-pt cross	cached table	no	896 B	materialized	0.0318	5.84×	0.0394	6.64×

Speedups share the computeBoxStencil baseline — noting that the cross resolvers deliberately resolve 7 taps rather than 27, which is the point of matching the resolver to the stencil shape. Throughout, a pair like 2.20× / 2.99× means BlockWidth 128 / BlockWidth 512.

What each technique contributes

• Streaming alone removes the 27-element index array; caching alone removes the tree walks. The costs are independent, so fusing them beats either — 2.20× / 2.99× versus 1.34× / 1.83× (streaming) and 1.22× / 1.83× (caching).
• Matching the resolver to the stencil shape is the largest single lever: the cross resolvers are 4.3–6.6×.

Feature width erodes every margin

At 8 sidecar channels the taps × C payload gather (identical for all resolvers) starts to dominate: forEachBoxStencilCached 1.47× / 2.12×, computeBoxStencilCached 1.22× / 1.48×, computeCrossStencilCached 4.37× / 4.59×. The ordering is unchanged.

Register cost of materialization

For the cached 27-tap consumer (ptxas -v, sm_120, one channel) the uint64_t st[27] array costs 22 registers and a 216-byte stack frame (62 → 40 registers, 216 B → 0 between computeBoxStencilCached and forEachBoxStencilCached; the 216 B is exactly 27 × sizeof(uint64_t)) — the relief the streaming variants capture.

Validation

• Byte-exact within each stencil shape, at two levels: raw taps (all 27 slots of every thread materialized to global and compared bytewise — box resolvers vs computeBoxStencil, cross vs cross) and consumer output (the accumulated float channels compared bitwise), at block widths 128/512, on 16%–60% leaf-occupancy topology and at both feature widths measured. The resolvers change how a tap index is found, never which index.
• The TestNanoVDBCUDA.VoxelBlockManager_* unit tests pass on the merged branch.

Notes

• The resolvers are additive; computeBoxStencil's move to by-value decoded slots is VBM select-based inverse-map decode #2258's API change, which this PR inherits. Callers choose between plain and cached forms on two axes that are genuinely theirs to weigh: whether the call site is uniform, and whether the block can spare the shared memory for the table (16 × 27 leaf pointers for the box, 16 × 7 for the cross — now the only shared memory in the pipeline).
• MaxCachedLeaves is 16.
• There is deliberately no forEachCrossStencil: a 7-element stencil is cheap enough to materialize that removing the array measured as a wash.
• This PR subsumes NanoVDB VBM: Streaming box-stencil #2262, left open for comparison until the design discussion concludes.