Snapshot · Nov 21, 2026

Environment probes, reflections, and GI

Lighting providers are independently selectable. A sky specular probe represents the sky, a local reflection probe represents a region, and a diffuse irradiance source supplies spatially blended diffuse light. Keep sky background, diffuse irradiance, and filtered specular reflection separate. An indoor configuration can omit sky lighting while retaining its local sources.

Build a reflection stack

In screen-first mode, reflection tracing uses visible screen data first. When the screen result is unavailable or unsuitable, a prepared world source can resolve a world-space hit. Covered local specular probes and a filtered Sky Light supply further fallbacks. Selection also depends on confidence, roughness, and the profile’s policy. The stock options include a mode that prefers world verification near mirrors. Even with identical geometry, provider radiance and available bounces depend on the data each provider receives.

Use local probe bounds and capture positions that represent their actual coverage. Box projection changes the cubemap lookup direction to approximate parallax inside that volume. It cannot reproduce arbitrary geometric occlusion away from the capture location. Prefiltered levels supply material-roughness response.

The stock profile exposes live provider toggles for already admitted screen, world, local, and sky paths. Preparing a previously absent producer or changing graph topology requires a new preparation. To isolate behavior, inspect the Reflection Source, Reflection Source Mix, and SSR Hit Confidence outputs when the profile exposes them. A black Reflection Source pixel means no admitted provider supplied its displayed result.

Treat diffuse GI as its own channel

A surface-cache source can provide reusable surface/radiance data for indirect diffuse gather or world specular queries. In the stock profile, their enablement is independent. Probe-only scenes can omit the cache. Surface-cache consumers should read the prepared source contract and select available tracing tiers explicitly. Software and hardware traversal, SDF and mesh representations, and atmosphere on ray miss are design dimensions. Availability and qualification vary by producer and backend.

A cheap raster environment contribution can sample a supplied filtered probe. Atmospheric miss radiance is also available to a prepared ray producer. The existence of one source does not require inventing a raster sky-visibility pass or performing world gather in every profile.

Register an assigned local reflection probe

This function excerpt registers an existing linear HDR cube as the probe’s radiance source. The supplied lifetime token must keep the cube alive. Bump the source revision on replacement or when updating data behind the same handle. Capture or filtering and lighting initialization follow the canonical probe preparation path before a receiver can use the probe.

#include <memory>
#include <utility>

#include <Renderer/Runtime/RendererRuntime.h>

namespace SnAPI::Renderer::Docs
{
    TResult<EnvironmentProbeHandle> AddRoomProbe(
        RendererRuntime& runtime, RenderScene& scene, TextureHandle cube,
        std::shared_ptr<const void> cubeOwner, std::uint64_t revision)
    {
        // Use the room's extents for parallax while keeping coverage localized.
        EnvironmentProbeDesc desc{};
        desc.PositionWorldSpace = {0.0, 1.5, 0.0};
        desc.HalfExtentWorldSpace = {2.0f, 1.5f, 2.0f};
        desc.ParallaxHalfExtentWorldSpace = {{4.0f, 1.5f, 3.0f}};
        desc.ContributesDiffuse = false;
        desc.Scene = &scene;
        desc.RadianceSource = {
            .Mode = EProbeRadianceSource::AssignedCube,
            .Texture = cube,
            .Revision = revision,
            .Lifetime = std::move(cubeOwner),
        };
        return runtime.CreateEnvironmentProbe(desc);
    }
}

The influence box determines where the local provider participates. The larger parallax proxy approximates the room walls for lookup correction. This example leaves diffuse contribution to other sources. Destroy the probe through the runtime after the receiver’s last use.