Create a new ProbeVolume instance.
The graphics device.
The options.
The box covered by the probes. It is divided into cells, with a probe at the center of each cell, and typically matches the interior of a building or a room, so that the probes light it up to its walls.
Optionalformat?: numberThe pixel format of the probe texture, either PIXELFORMAT_RGBA16F or PIXELFORMAT_RGBA8. 8-bit texels use half the memory, but store the coefficients relative to L0, which the hardware filtering interpolates only approximately. Defaults to PIXELFORMAT_RGBA16F.
The number of cells, and so of probes, along the x, y and z axes, each at least 1.
The box covered by the probes. Do not modify it.
The index of the lighting the volume shows, see lightingCount. Defaults to 0.
The distance, in world units, over which the ambient lighting blends from the probes to the ambient of the environment outside of the box. Defaults to 1.
Whether the probes provide the ambient lighting. When disabled, the materials use the ambient of the environment. Defaults to true.
The pixel format of the probe texture, see the constructor. It can be changed at any time, which encodes the probes again from their data, without baking them again.
Whether the probes were set, by setData, a bake or ProbeVolume.deserialize. Until then, the volume shows the ambient lighting of the environment.
The multiplier of the ambient lighting of the probes. Defaults to 1.
Whether the surfaces ignore the invalid probes, and favor the probes in front of them over the probes behind them, which reduces light leaking through walls. Defaults to true.
The distance, in world units, a surface is offset along its normal when sampling the probes. This reduces the darkening of the surfaces by the probes behind them. Defaults to 0.5.
The total number of probes.
Whether the probes occlude the reflections of the environment where they are darker than it, such as inside a closed room, which would otherwise reflect the sky. The reflections are scaled by the ratio of the luminance of the ambient lighting of the probes to that of the environment, up to 1. Defaults to true.
The number of probes along the x, y and z axes. Do not modify it.
Whether to sharpen the lighting reconstructed from the L1 spherical harmonics of the probes, which on their own give a soft, washed out result. A quadratic zonal harmonic along the dominant direction of the light is estimated from how directional the L1 coefficients are (ZH3, Roughton et al., I3D 2024), which brings the result close to L2 without storing more data: the surfaces facing directional light get brighter, and the surfaces facing away from it darker. Defaults to true.
Whether the surfaces ignore the probes they are hidden from, using the visibility of the probes, captured by the baker. For each of the eight probes around a surface, it bounds the probability that the probe sees the surface, from the mean and the variance of the distances the probe sees in its direction (Chebyshev's inequality, as in DDGI). This removes most of the leaking through walls, at the cost of a filtered fetch for each of the probes. Has no effect when the volume has no visibility. Defaults to true.
Applies the probe lighting to a material, which then takes its ambient lighting from the probes, or removes it, so that the material takes its ambient lighting from the environment. The material is lit by the probe volume active at the time, as a volume provides its data through global uniforms. Call Material#update afterwards.
The material.
Optionalapply: boolean = true
True to apply the probe lighting, false to remove it. Defaults to true.
Frees the textures of the volume.
Returns a lighting of the volume: the spherical harmonics of the probes, the L0 and the three L1 coefficients (x, y and z) of the incoming radiance, for each of the red, green and blue channels of each probe. Probes are ordered along x, then y, then z. Do not modify it, use setData instead.
Optionalindex: number = 0
The index of the lighting, see lightingCount. Defaults to 0.
The spherical harmonics of the probes.
Serializes the placement, the validity, the offsets and the visibility of the probes, and their lightings, see ProbeVolume.deserialize. The visibility is stored as half floats. The data shared by the lightings comes first, followed by each lighting.
The serialized data.
Sets a lighting of the volume, the spherical harmonics of the probes, see getData for the layout. Setting the lighting at the index lightingCount adds a lighting. The lighting shown, see activeLighting, is uploaded to the probe texture.
The spherical harmonics of the probes.
Optionalindex: number = 0
The index of the lighting, up to lightingCount. Defaults to 0.
StaticdeserializeCreates a probe volume from data produced by ProbeVolume#serialize, with all its lightings, showing the first one.
The graphics device.
The serialized data.
Optionaloptions: { format?: number } = {}
The options.
Optionalformat?: numberThe pixel format of the probe texture, see the constructor.
The probe volume.
A regular grid of light probes covering a box, providing the ambient lighting of the surfaces of the materials it is applied to. The box is divided into cells, with a probe at the center of each cell. Each probe stores the incoming radiance at its position as L1 spherical harmonics, and the surfaces interpolate the eight probes around them. Outside the box, the ambient lighting blends back to the ambient of the environment.
The probe data is produced by ProbeVolumeBaker, at runtime or ahead of time, and can be saved with ProbeVolume#serialize and restored with ProbeVolume.deserialize. Restored probes work on any device, including the devices which cannot bake them, see ProbeVolumeBaker.isSupported.
The baker can also find the invalid probes, which are inside geometry and would darken the surfaces around them. With ProbeVolume#leakReduction, the surfaces ignore those, and favor the probes in front of them over the probes behind them, which reduces light leaking through walls.
The baker can also capture the visibility of the probes, the distances to the surfaces around them, which the surfaces use to ignore the probes they are hidden from, see ProbeVolume#visibility. This removes most of the remaining leaking, such as on the floor along a wall with probes on both sides, at the cost of a filtered fetch for each of the eight probes around a surface.
The spherical harmonics of the probes form a lighting, see ProbeVolume#getData. A volume can hold several lightings, baked under different lighting, such as at different times of the day, and shows one of them, see ProbeVolume#activeLighting. The validity, the offsets and the visibility of the probes depend only on the geometry, and are shared by the lightings.
The volume provides its data to shaders through the global uniforms of the graphics device, so one volume is active at a time.
Example