Sharing a native VXGI cache

VXGIVolumeAdapter targets the public sampling contract of Three.js r186's experimental VXGIVolume. Pass an already constructed volume to the adapter. This avoids a bundled voxelizer fork and lets an application share a single radiance cache with diffuse GI and specular tracing.

The adapter expects boundsMinNode, volumeSizeNode, voxelSizeNode, maxLevelNode, radianceNode, opacityNode, directionalNode, directionalWidthNode, dirty flags, worldBounds, and update/dispose. These names are deliberately explicit so upstream contract changes fail visibly.

Native opacity contains directional weights while native radiance has its own weight. The adapter normalizes the latter, then premultiplies it by the directional opacity expected by this library. Coarse radiance can be read from the six-direction atlas, with half-texel block clamping to prevent adjacent blocks bleeding into one another.

Keep directionalRadiance fixed after constructing the adapter. Changing it requires new receiver graphs. Choose native voxelization bounds/layers through the upstream volume's own API. A native volume with longer X, Y or Z extents can be traversed because the tracer derives per-axis cell counts from size/cell width.

Call the adapter update exactly once in the application's chosen cache-update phase. Do not independently schedule both an upstream owner and this adapter to rebuild the same cache twice in a frame. The adapter's revision counts successful update calls, not an introspection of the upstream cache's internal dispatch count.

Ownership is explicit: new VXGIVolumeAdapter(source, true) lets adapter disposal destroy the source. Set the orchestrator's ownsVolume: true as well if it should dispose the adapter. Otherwise both adapter/source lifetimes remain the caller's responsibility.

Native validation

The npm Three.js r186 GPU voxelizer and this adapter were executed on native WebGPU on an Apple M4 with Chrome 152. Automated readback tests cover isotropic and directional caches, green textured emission, forward/backward Z rays, rough-cone mip sampling, a black occluder, source movement clearing previous occupancy, and restoration. A directional sharp-ray shader bug found by these tests was fixed by materializing shared sampling coordinates before conditional atlas branches.

These fixtures are in tests/browser/integration.js, run by npm run test:browser; their measurements are in validation/webgpu/results.json. The portable cache is separately tested for light motion and multiple receiver ownership. The native adapter's broader diffuse-light transport, all axis combinations, and other GPU vendors are not certified by those fixtures. Repeat the native suite on target hardware before a stable release. WebGL validation deliberately skips the native-only adapter.

The upstream radiance is outgoing diffuse transport plus emission. Sharing that cache does not make it a full directional specular-transport solution. Multiple diffuse bounce injection, when enabled upstream, is separate from reflected glossy-of-glossy paths.