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

    Class ProbeVolumeBaker

    Bakes the light probes of a ProbeVolume in two steps.

    ProbeVolumeBaker#captureGeometry captures, for each probe, the geometry it sees: the scene is rendered from the probe into the six square faces of its tile of an atlas, with the lit materials writing their albedo, normal, distance and emission instead of a color. The geometry gives the validity of the probes, their virtual offsets and their visibility, and is kept for the lighting.

    ProbeVolumeBaker#bakeLighting computes the lighting of the probes, from one of two sources:

    • PROBESOURCE_GBUFFER: the captured geometry, lit by the lighting of the engine without rendering the scene. A quad covering the atlas is drawn with a lit material, which lights each texel as the surface the probe saw through it. This takes a frame for each bounce, so the lighting can be baked again quickly after it changed, such as after the sun moved.
    • PROBESOURCE_SCENE: the scene rendered lit from each probe, a few probes each frame.

    Each bounce lights the scene with the probes of the previous one. The radiance of the faces is then projected onto the spherical harmonics of the probes.

    The geometry stays in memory until the baker is destroyed, for the lighting to be baked again.

    Baking needs a device which renders to half float or float textures, see ProbeVolumeBaker.isSupported: all WebGPU devices, and the WebGL2 devices with the float color buffer extensions. Probes baked ahead of time load on any device.

    const baker = new ProbeVolumeBaker(app, volume, { layers: [worldLayer.id, LAYERID_SKYBOX] });
    await baker.captureGeometry();
    await baker.bakeLighting({ bounces: 2 });

    // after the sun moved, bake the lighting again from the captured geometry
    await baker.bakeLighting({ bounces: 2 });
    baker.destroy();
    Index
    • Create a new ProbeVolumeBaker instance.

      Parameters

      • app: AppBase

        The application, whose scene is baked.

      • Optionalvolume: ProbeVolume

        The probe volume.

      • Optionaloptions: {
            emissive?: boolean;
            faceSize?: number;
            farClip?: number;
            layers?: number[];
            nearClip?: number;
            probesPerFrame?: number;
        } = {}

        The options.

        • Optionalemissive?: boolean

          Whether the geometry includes the emission of the surfaces. Defaults to false.

        • OptionalfaceSize?: number

          The number of texels along a side of a face of a probe. Defaults to 8.

        • OptionalfarClip?: number

          The far clip distance of the capture cameras. Defaults to 1000.

        • Optionallayers?: number[]

          The ids of the layers the probes capture. Defaults to the world and skybox layers.

        • OptionalnearClip?: number

          The near clip distance of the capture cameras. Defaults to 0.05.

        • OptionalprobesPerFrame?: number

          The number of probes captured each frame. Defaults to 32.

      Returns ProbeVolumeBaker

    probesPerFrame: number

    The number of probes captured each frame. A change applies from the next capture or bake.

    • Bakes the lighting of the probes, and sets the data of the volume. Captures the geometry first, if it was not captured yet.

      Parameters

      • Optionaloptions: {
            bounces?: number;
            dilation?: boolean;
            index?: number;
            onProgress?: Function;
            shadowBounds?: BoundingBox | null;
            source?: string;
        } = {}

        The options.

        • Optionalbounces?: number

          The number of indirect bounces after the direct lighting. Defaults to 1.

        • Optionaldilation?: boolean

          Whether to fill the invalid probes from their valid neighbors. Defaults to true.

        • Optionalindex?: number

          The index of the lighting of the volume to set, up to ProbeVolume#lightingCount, which adds a lighting, see ProbeVolume#setData. Defaults to 0.

        • OptionalonProgress?: Function

          Called with the progress, from 0 to 1.

        • OptionalshadowBounds?: BoundingBox | null

          The shadow bounds of the directional lights while baking, see LightComponent#shadowBounds. Defaults to the box of the volume, expanded by its blend distance.

        • Optionalsource?: string

          The source of the lighting: PROBESOURCE_GBUFFER to light the captured geometry, or PROBESOURCE_SCENE to render the scene lit from each probe. Defaults to PROBESOURCE_GBUFFER.

      Returns Promise<{ dilatedProbes: number }>

      The result of the bake.

    • Captures the geometry each probe sees, and sets the validity, the virtual offsets and the visibility of the volume. The capture takes a number of frames.

      Parameters

      • Optionaloptions: {
            onProgress?: Function;
            validity?: boolean;
            validityThreshold?: number;
            virtualOffset?: boolean;
            visibility?: boolean;
            visibilitySize?: number;
        } = {}

        The options.

        • OptionalonProgress?: Function

          Called with the progress, from 0 to 1.

        • Optionalvalidity?: boolean

          Whether to find the invalid probes, which see more back faces than the validity threshold. Defaults to true.

        • OptionalvalidityThreshold?: number

          The fraction of the sphere around a probe covered by back faces above which the probe is invalid. Defaults to 0.25.

        • OptionalvirtualOffset?: boolean

          Whether to capture the invalid probes at a position moved out of the geometry, through the closest back face, by up to 0.45 of a cell. The probes are still interpolated at their positions in the grid, but the leak reduction and the visibility use the positions they were captured at. Defaults to true.

        • Optionalvisibility?: boolean

          Whether to compute the visibility of the probes. Defaults to true.

        • OptionalvisibilitySize?: number

          The number of texels along a side of the octahedral map of the visibility of each probe. Defaults to 16.

      Returns Promise<ProbeVolumeGeometryResult>

      The result of the capture.

    • Returns whether a graphics device can bake probes. Baking renders the scene to half float or float textures. WebGPU devices always support them. WebGL2 devices need the float color buffer extensions (EXT_color_buffer_float or EXT_color_buffer_half_float), which some older or low-end mobile devices do not support. On those devices, the probes can still be baked ahead of time and loaded with ProbeVolume.deserialize; only baking is not supported. The null graphics device, which renders nothing, cannot bake either.

      Parameters

      Returns boolean

      True if the device can bake probes.