Development

Lights, influence, and shadows

The scene owns retained light handles. Common supplied types use physical units. Directional intensity is illuminance in lux, point and spot intensity is candela, and finite area luminance is nits (candela per square metre). Area dimensions and local influence distances are metres. A rectangular emitter uses two orthogonal world axes and two half extents. For a sphere, the area descriptor’s half width is its radius.

Place a rectangle emitter

This excerpt places a rectangular emitter with a conservative automatic realtime cutoff. Its axes default to the world XY plane. Orient and translate it through the descriptor to match the actual emitting surface.

#include <Renderer/Runtime/RendererRuntime.h>

namespace SnAPI::Renderer::Docs
{
    TResult<LightHandle> AddSoftbox(RenderScene& scene)
    {
        AreaLightDesc source{};
        source.HalfWidth = 0.6f;
        source.HalfHeight = 0.4f;
        source.LuminanceNits = 4200.0f;
        source.Influence = {.Mode = LocalLightInfluence::EMode::Auto,
                            .MinimumIlluminanceLux = 0.01f};
        source.CastsShadows = true;
        // The scene retains this light until DestroyLight or scene retirement.
        return scene.CreateAreaLight(source);
    }
}

Update the light through scene setters according to mobility. A change that cannot be represented as an edit of the existing area record uses the replacement API, and the returned handle becomes the current identity.

Distinguish emitter shape and receiver influence

Emitter size affects geometric response and visibility samples. Realtime influence bounds select candidate receivers and supply the fade. Manual influence uses the authored range, Auto derives a cutoff from a conservative illumination threshold, and Unbounded keeps geometric falloff. The physical influence domain bypasses the realtime receiver cutoff for reference transport. A finite support range is a performance policy, not a change to the photometric units.

Clustered direct lighting culls local records against screen XY and a depth slice. The receiver only considers the relevant cluster’s candidates. A local emitter can overlap several clusters, and the packed record and cluster limits remain finite. Test support mode, authored range, and occupancy/overflow before attributing a scene’s cost to light count alone.

Choose visibility producers

Shadow participation on a descriptor makes the light eligible. A profile must compose or bind a matching shadow producer. Directional cascades, pooled punctual depth, and finite emitter visibility have separate graph paths. Point and spot depth visibility can reuse static layers with appropriate mobility and cache configuration. Finite emitter visibility depends on the selected raster or trace provider and sampling policy. A local shadow receiver and screen-space contact shadows solve different coverage problems. Verify the actual producer on the terminal graph.