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 now 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. No shared memory, no barrier, safe from divergent threads.
• <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.

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, unchanged)	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.

Measurements

All six resolvers measured in one run, on one grid, against one baseline, with the same consumer: resolve the taps, then accumulate C 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 (~72% sparse). 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.1868	1.00×	0.2713	1.00×
forEachBoxStencil	27-tap box	tree walk	yes	none	streamed	0.1408	1.33×	0.1425	1.90×
computeBoxStencilCached	27-tap box	cached table	no	3456 B	materialized	0.1469	1.27×	0.1771	1.53×
forEachBoxStencilCached	27-tap box	cached table	no	3456 B	streamed	0.1014	1.84×	0.1044	2.60×
computeCrossStencil	7-pt cross	tree walk	yes	none	materialized	0.0534	3.50×	0.0545	4.98×
computeCrossStencilCached	7-pt cross	cached table	no	896 B	materialized	0.0414	4.51×	0.0422	6.43×

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 the rest of this description, a pair like 1.26× / 1.56× means BlockWidth 128 / BlockWidth 512.

Shared memory is the resolver's table only: MaxCachedLeaves(16) x entries x 8 B. Confirmed against ptxas -v — a width-128 kernel reports 4228 B total for the cached box (512 B leaf-index array + 256 B voxel-offset array + 3456 B table + 4 B span counter) and 1668 B for the cross.

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 — 1.84x / 2.60x versus 1.33x / 1.53x.
• Matching the resolver to the stencil shape is the largest single lever: the cross resolvers are 3.5-6.4x.

Feature width erodes every margin

At 8 sidecar channels the taps x C payload gather (identical for all resolvers) starts to dominate: forEachBoxStencilCached 1.41x / 2.14x, computeBoxStencilCached 1.22x / 1.26x, computeCrossStencilCached 3.92x / 4.56x. The ordering is unchanged.

Register cost of materialization

For a 27-tap consumer (ptxas -v, sm_120) the uint64_t st[27] array costs 26 registers and a 216-byte stack frame (70 -> 44 registers, 216 B -> 0; the 216 B is exactly 27 x sizeof(uint64)). On sm_120 that is 28 -> 42 resident warps, 58.3% -> 87.5% occupancy — the relief the streaming variants capture.

Validation

• Byte-exact within each stencil shape: the box resolvers all agree with computeBoxStencil, and the cross resolvers all agree with each other, at block widths 64/128/256/512, on sparse and dense topology and at every feature width measured. The resolvers change how a tap index is found, never which index. (A cross resolver writes only the 7 cross slots, so it is compared against a cross-shaped consumer rather than the full box.)
• The VoxelBlockManager_ValueOnIndex unit-test path passes: 250,047 (voxel, tap) comparisons against getAccessor().getValue(), zero mismatches.

Notes

• No existing behaviour changes. computeBoxStencil keeps its documented contract (no shared memory, no barrier, callable from divergent threads); the cached forms are additive. Callers choose between them 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 x 27 leaf pointers for the box, 16 x 7 for the cross).
• MaxCachedLeaves is 16; the box table costs 16 × 27 leaf pointers of shared memory per block (the cross table 16 × 7), which is the main resource trade-off against the naive path.
• Implementing forEachCrossStencil was not measured to win any performance gains over computeCrossStencil, no additional register pressure was created instantiating the 7-integer table vs. the full 27-integer table for the cross stencil. I made the decision to drop this implementation.
• This PR subsumes NanoVDB VBM: Streaming box-stencil #2262, I leave that open as the first step along this path for comparison and until we finish discussing the design.