Engine API Reference - v2.25.0-beta.9
    Preparing search index...

    Class ProbeVolume

    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.

    // a volume, lighting a material
    const volume = new ProbeVolume(app.graphicsDevice, {
    aabb: new BoundingBox(new Vec3(0, 1.5, 0), new Vec3(5, 1.5, 4)),
    resolution: [10, 3, 8]
    });
    volume.applyToMaterial(material);
    material.update();

    // bake its probes, and save them
    const baker = new ProbeVolumeBaker(app, volume);
    await baker.bakeLighting();
    baker.destroy();
    const buffer = volume.serialize();

    // later, restore them
    const restored = ProbeVolume.deserialize(app.graphicsDevice, buffer);
    Index
    • Create a new ProbeVolume instance.

      Parameters

      • device: GraphicsDevice

        The graphics device.

      • options: { aabb: BoundingBox; format?: number; resolution: number[] }

        The options.

        • aabb: BoundingBox

          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?: number

          The 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.

        • resolution: number[]

          The number of cells, and so of probes, along the x, y and z axes, each at least 1.

      Returns ProbeVolume

    • set activeLighting(value: number): void

      The index of the lighting the volume shows, see lightingCount. Defaults to 0.

      Parameters

      • value: number

      Returns void

      // show the lighting baked at night
      volume.activeLighting = 1;
    • set blendDistance(value: number): void

      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.

      Parameters

      • value: number

      Returns void

    • set enabled(value: boolean): void

      Whether the probes provide the ambient lighting. When disabled, the materials use the ambient of the environment. Defaults to true.

      Parameters

      • value: boolean

      Returns void

    • set format(value: number): void

      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.

      Parameters

      • value: number

      Returns void

    • set leakReduction(value: boolean): void

      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.

      Parameters

      • value: boolean

      Returns void

    • set normalBias(value: number): void

      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.

      Parameters

      • value: number

      Returns void

    • set reflectionOcclusion(value: boolean): void

      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.

      Parameters

      • value: boolean

      Returns void

    • set shSharpening(value: boolean): void

      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.

      Parameters

      • value: boolean

      Returns void

    • set visibility(value: boolean): void

      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.

      Parameters

      • value: boolean

      Returns void

    • 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.

      Parameters

      • material: Material

        The material.

      • Optionalapply: boolean = true

        True to apply the probe lighting, false to remove it. Defaults to true.

      Returns void

      volume.applyToMaterial(material);
      material.update();
    • 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.

      Parameters

      • Optionalindex: number = 0

        The index of the lighting, see lightingCount. Defaults to 0.

      Returns Float32Array<ArrayBufferLike>

      The spherical harmonics of the probes.