Lighting and shadows

One directional sun, punctual lights imported through KHR_lights_punctual, and environment lighting from the sky itself. Lighting state is assembled once per frame in Rendering/SceneLighting.cs and consumed by every pass from one buffer, so shadows, GI and the sky cannot disagree about where the sun is.

Lights are a list, baked once a frame

SceneLighting holds a plain List<LightSource> plus a constant ambient term. Once per frame Bake turns that list into the GPU structure every pass reads. Nothing else in the engine keeps its own copy of the lighting state.

Lighting.Ambient = new Vector4(0.12f, 0.13f, 0.16f, 1f);

Lighting.Add(new LightSource
{
    Kind = LightKind.Spot,
    Name = "porch",
    Position = new Vector3(24f, 6f, 7.5f),
    Direction = Vector3.Normalize(new Vector3(0f, -1f, -0.4f)),
    Color = new Vector4(1f, 0.86f, 0.66f, 1f),
    Intensity = 40f,
    Range = 24f,
    InnerConeAngle = 0.25f,
    OuterConeAngle = 0.55f,
    CastShadows = true,
    Priority = 10
});

Eight lights, and what happens to the ninth

SceneLightParams.MaxLights is 8. That is a hard GPU limit, not a soft target: the uniform buffer has eight slots. When a scene has more, Bake sorts by Priority and takes the first eight, using the camera position to break ties by distance.

Lights imported from a glTF file arrive through Model.ImportedPunctualLights and are appended by the model itself, which means an asset carrying twelve lights will consume the whole budget on its own. Model.LightIntensityScale and RenderQuality.KhrLightIntensityScale exist to bring their photometric magnitudes back into engine range.

Cascaded shadow maps

Three sun cascades and one punctual slot share a single square depth atlas, each quadrant a tile of half the side length. Four slots, one texture, one binding — which is why the shadow pass is also the one pass that sets its own viewport.

The two depth biases are marked initialization rather than runtime for a reason: D3D12 and Vulkan read them when the pipeline state is created, so assigning them after startup changes the property and nothing else. Set them through RenderQuality.DefaultShadowDepthBias in the application constructor. Normal-offset bias, by contrast, travels in the uniform buffer and can move every frame — which is why it is the knob to reach for first.

Cascade stability

A slowly moving sun is the classic way to make shadow edges crawl: every frame the cascade matrix changes slightly, every frame the depth texels land somewhere new, and the eye reads the resulting shimmer as noise. Two mechanisms suppress it.

• Angular quantisation. The light direction is snapped to a grid controlled by ShadowLightAngleStep (0.25 by default), so small sun movement produces no matrix change at all.
• Texel snapping. The light-space translation is rounded to whole shadow texels, sized so the cascade matrices stay bitwise identical for ShadowTargetStableFrames frames — eight by default.

CascadedShadow exposes the result for inspection: MatricesStable tells you whether the guarantee currently holds, EffectiveLightAngleStep the step actually in use, and Epoch increments whenever the atlas contents become invalid. The reference application puts all three on screen, because "why is my shadow crawling" is answered by reading them.

Known gaps

• Partial Punctual shadows. One slot, one light. A scene with two shadow-casting spots gets one shadow.
• Absent Point-light shadow cubes. The punctual slot is a single projection, so omnidirectional shadow casting is not available.
• Absent Baked lightmaps. All lighting is dynamic. That is a feature for changing scenes and a cost for static ones.

For indirect light rather than direct, continue to global illumination and ambient occlusion.