API reference
VoxelReflections
new VoxelReflections(options) accepts a RadianceVolume, an optional ownership flag, portable volume options and tracer options. Omitting volume creates an owned StaticVoxelVolume.
| Method | Behavior |
|---|---|
update(renderer, scene) |
Update a dirty cache before rendering. A null renderer is allowed only by the portable backend. |
invalidateGeometry() |
Rebuild geometry and lighting on the next update. Required for material changes as well. |
invalidateLighting() |
Retain baked geometry; update light transport. |
configure(options) |
Change uniform settings without rebuilding material graphs. |
bind(material, options) |
Attach a reflected-specular term to a standard/physical node material. |
unbind(material) |
Restore the material's prior emissive/environment nodes. |
createTraceNode(nodes) |
Return premultiplied RGB and accumulated opacity. |
createRadianceNode(nodes) |
Return radiance plus optional fallback; no BRDF weighting. |
createSpecularNode(nodes) |
Return a BRDF-weighted reflected term. |
dispose() |
Restore bindings and dispose owned resources; idempotent. |
Tracer options
| Option | Default | Meaning |
|---|---|---|
maxSteps |
384 | Compile-time loop bound; integer 16–1024. Create a new tracer to change it. |
maxDistance |
100 | World-space distance from the biased ray origin. |
normalBias |
1.25 | Surface offset in cell widths, range 0–8. |
stepScale |
0.5 | Rough-cone step fraction and opacity correction, range 0.1–1. |
coneSpread |
1 | Multiplier on the roughness² aperture, range 0.01–4. |
sharpThreshold |
0.08 | DDA/cone cutoff; changing across the cutoff can change the visual response discontinuously. |
intensity |
1 | Multiplier on the final radiance/specular term, range 0–100. |
A SurfaceNodes object can override world position, world normal, surface-to-camera view direction and scalar perceptual roughness. A SpecularNodes object additionally accepts RGB F0 and RGB environment/fallback radiance. Nodes, not JavaScript numeric values, are expected in these objects; use float and vec3 from three/tsl.
StaticVoxelVolume
| Option | Default | Meaning |
|---|---|---|
resolution |
64 | Power of two, 16–128. Fixed for the volume's lifetime. |
bounds |
Inferred | Finite positive Box3. Expanded to a cube; inferred bounds receive padding. |
maxVoxelTests |
20,000,000 | Upper bound on conservative triangle/voxel candidates per bake. |
layerMask |
All layers | Bitmask, not a layer index. Primary-camera layers do not limit collection. |
filter |
None | Additional per-object predicate. |
unsupported |
error |
skip records warnings for unsupported deformed meshes. |
shadows |
true | Voxel DDA shadowing during direct-light injection. |
shadowBias |
1.8 | Shadow-ray offset in cells. |
ambient |
0 | Constant irradiance added before the Lambertian 1 / π factor. |
maxLights |
16 | Maximum supported lights collected for a CPU injection. |
setBounds(box) copies the box and marks geometry dirty. Read worldBounds after a successful bake to obtain the actual enclosing cube. statistics includes triangle/mesh counts, occupancy, work count, phase timings, nominal storage and skip warnings. getLevels exposes the current numeric mip levels for tooling; treat returned data as read-only.
Changing textures/materials requires geometry invalidation. CPU image sampling requires a loaded, origin-clean image or an uncompressed DataTexture. UV transforms, wrap modes and texture color space are honored. Texture filtering is nearest for static material capture; source anisotropic filtering, source normal maps and arbitrary material graphs are not reproduced.
Binding options
fallback is zero by default. replaceEnvironment defaults to true. f0 and roughness allow explicit node overrides. Binding adds the reflected term to emission so the application's regular direct-light shading remains present; this is a compositing integration, not a replacement physical lighting model.
The main entry point exports orchestrator, tracer, portable backend, collector, voxelizer, lighting injector and material binding. ./core exports the numeric algorithms and reference tracer. ./vxgi exports the structural native-volume adapter without importing the upstream add-on itself.