Direct Lighting Modes
Direct lighting is the light that travels straight from a light component to a surface. Its expensive part is visibility: whether the light is blocked on its way, which is what shadows are. Plasma has four ways to compute it, selected with Rendering.DirectLighting.Mode:
| Value | Mode | Shadows from | Cost grows with | Presets |
|---|---|---|---|---|
| 0 | Classic | Shadow maps (virtual or cascaded) for lights with CastShadows, plus contact shadows. | The number of overlapping and shadow-casting lights. | Low, Medium, High |
| 1 | Probe cached | Shadow rays traced on a sparse grid of screen probes and reused by the pixels around them. | Mostly fixed: a fixed ray budget per probe. | – |
| 2 | ReSTIR DI | One resampled light sample per pixel, traced, reused across frames and neighbours, then denoised. | Fixed per pixel, independent of the light count. | Max |
| 3 | Guided | About one shadow ray per pixel, spent on the lights that were visible last frame, then denoised. | Fixed per pixel. | – |
The CVar's own default is 1, but every quality preset sets it, so in practice Low, Medium and High use classic lighting, Max uses ReSTIR DI (at half resolution), and probe cached and guided lighting are opt-in for projects. The value is accepted in project presets, in player overrides and on a post process volume (see Post process volume).
Requirements. Modes 1, 2 and 3 need hardware ray tracing with ray queries and Rendering.RT.Enable (on DX12 also DXR tier 1.1 and Rendering.DX12.ExposeRayTracing). They are also off while global illumination traces with the software backend. When a mode is unavailable, it logs why once and the lights use the classic path with shadow maps, so a scene always stays lit. The XR render pipeline has no ray-traced direct lighting passes and always uses the classic path.
Classic
The clustered light loop shades every light that reaches a pixel, and lights with CastShadows read their shadow maps (see Dynamic Shadows). Lights without shadow maps can still get contact shadows. Cost rises with the number of lights that overlap on screen and with the number of shadow maps. Use it on GPUs without ray tracing, and wherever the light count is moderate.
Probe cached
Probe-cached direct lighting keeps the light loop for everything that is cheap (the BRDF, normal maps, highlights, area light shapes, cookies), and replaces only the visibility with ray tracing. A probe every Rendering.ProbeDirectLighting.ProbeSpacing pixels (8) selects the lights that matter at its surface, traces shadow rays to them from a fixed budget (RayBudget, 32 per probe), and the pixels around it reuse that visibility. Pixels at shadow edges are refined with their own rays. Each pixel shades only the lights its probe selected, plus one combined term for the rest, so shading cost stops depending on how many lights overlap.
- Only the
DominantLights(4) brightest lights per probe cast shadows; the other selected lights are shaded exactly but unshadowed. - The sun stays on its cascaded or virtual shadow maps unless
Rendering.ProbeDirectLighting.Directionalis on. - Lights it handles stop requesting shadow maps (
Rendering.ProbeDirectLighting.SuppressShadowMaps). Transparent objects and particles then see those lights unshadowed, unless the light hasTransparentShadowson. - Point and spot lights are hard point sources unless
Rendering.ProbeDirectLighting.PointSourceRadiusgives them a radius.
Good for scenes with many shadow-casting local lights, where classic shadow maps would cost too much.
| CVar | Default | Description |
|---|---|---|
Rendering.ProbeDirectLighting.Enable | true | Switch for the pass while the mode is 1. |
Rendering.ProbeDirectLighting.ProbeSpacing | 8 | Probe spacing in pixels. About 8 is the optimum for typical content. |
Rendering.ProbeDirectLighting.RayBudget | 32 | Rays per probe per frame. Same in every preset. |
Rendering.ProbeDirectLighting.MaxLightsPerProbe | 16 | Most lights a probe caches. A probe that runs out shades its pixels with the full loop. |
Rendering.ProbeDirectLighting.DominantLights | 4 | Shadowed lights per probe. |
Rendering.ProbeDirectLighting.Refine | true | Re-traces shadow edges per pixel. |
Rendering.ProbeDirectLighting.Directional | false | Traces the sun too, instead of its shadow maps. |
Rendering.ProbeDirectLighting.SunAngularRadius | 0.5 | Angular radius of the sun in degrees, for soft sun shadows when it is traced. |
Rendering.ProbeDirectLighting.AreaSamples | 8 | Most emitter samples per area light per probe. |
Rendering.ProbeDirectLighting.SuppressShadowMaps | true | Lights the probes handle render no shadow maps. |
ReSTIR DI
ReSTIR direct lighting picks one light sample per pixel from all lights, including emissive triangles, by resampled importance sampling: each pixel draws a handful of candidates, keeps the most important one, and then reuses the winners of its own previous frames and of its neighbours. The surviving sample is traced with one shadow ray and the result is denoised. The cost per pixel does not depend on the number of lights, so scenes with hundreds of lights cost about the same as scenes with ten. Shadows are soft according to each light's PenumbraSize, and emissive surfaces brighter than Rendering.ReSTIRDI.EmissiveThreshold become real light sources with shadows.
- The sun stays on shadow maps unless
Rendering.ReSTIRDI.Directionalis on. - Lights it handles stop requesting shadow maps (
Rendering.ReSTIRDI.SuppressShadowMaps); transparent objects keep a shadow map only for lights withTransparentShadows. - The Max preset runs it at half resolution (
Rendering.ReSTIRDI.HalfRes): sampling and reuse at half resolution, final visibility and shading at full resolution. - Large camera jumps (
CameraCutDistance2 m,CameraCutAngle45°) restart its history.
Pick it for scenes with very many lights or large emissive surfaces. It can show some noise or lag right after lights change.
| CVar | Default | Description |
|---|---|---|
Rendering.ReSTIRDI.Enable | true | Switch for the pass while the mode is 2. Low, Medium and High set it off, so a project preset that picks mode 2 on top of one of them must also set this on. |
Rendering.ReSTIRDI.HalfRes | false | Half-resolution reuse. On in Max. |
Rendering.ReSTIRDI.GridCandidates, FroxelCandidates, EmissiveCandidates | 8, 4, 2 | Candidates per pixel from the world-space grid, the froxel light list and the emissive tiles. Set by the presets. |
Rendering.ReSTIRDI.SpatialTaps | 5 | Neighbours of the first spatial reuse pass. 0 disables it. |
Rendering.ReSTIRDI.MaxHistory | 20 | Temporal history cap. Higher converges further and lags more. |
Rendering.ReSTIRDI.AreaSamples | 2 | Extra emitter rays where a penumbra is wider than a pixel. |
Rendering.ReSTIRDI.Directional | false | Traces the sun (one ray per pixel, SunAngularRadius 0.5°) instead of its shadow maps. |
Rendering.ReSTIRDI.PointSourceRadius | 0 | Minimum radius of point and spot emitters. Each light uses its PenumbraSize when that is larger. |
Rendering.ReSTIRDI.EmissiveThreshold | 0.05 | Emissive luminance above which an object's triangles become lights. |
Rendering.ReSTIRDI.EmissiveTwoSided | false | Emissive triangles radiate from both faces. Turn on for single-quad panels. |
Rendering.ReSTIRDI.Denoiser | 1 | 0 = raw, 1 = NRD ReLAX, 2 = built-in. |
Rendering.ReSTIRDI.FireflyClamp | 8 | Clamps bright outliers while a pixel's history is short. 0 disables. |
Rendering.ReSTIRDI.ReferenceMode | false | No reuse, many candidates, no denoiser: the ground truth to compare against. |
Guided
Guided direct lighting spends a fixed budget of about one shadow ray per pixel. Each 2×2 pixel cell (Rendering.GuidedLighting.HalfRes) draws Rendering.GuidedLighting.SamplesPerCell lights, mostly from the lights its screen tile saw last frame and partly from lights it has not seen yet, traces them (a short screen-space march, then a world ray) and shades the result with the normal light code. A built-in denoiser smooths it over time and space. Lights without shadows stay in the classic loop (Rendering.GuidedLighting.UnshadowedInClassicLoop), which shades them exactly without rays.
No preset selects it; set the mode to 3 in a project preset or on a post process volume. The presets only set its budgets (Low 2 samples per cell; Max one cell per pixel instead of 2×2).
| CVar | Default | Description |
|---|---|---|
Rendering.GuidedLighting.Enable | true | Switch for the pass while the mode is 3. |
Rendering.GuidedLighting.SamplesPerCell | 4 | Light samples per cell, 1–16. With half resolution, 4 is about one ray per pixel. |
Rendering.GuidedLighting.HalfRes | true | 2×2 pixel cells. Off = one cell per pixel, four times the rays. |
Rendering.GuidedLighting.HiddenCandidates | 8 | Lights per cell evaluated from outside last frame's visible list. More finds newly visible lights sooner. |
Rendering.GuidedLighting.Denoiser | 0 | 0 = built-in, 1 = NRD ReLAX, 2 = off. |
Rendering.GuidedLighting.Denoise.SpatialPasses | 3 | Spatial filter passes, 0–5. More flickers less and blurs more. |
Rendering.GuidedLighting.PointSourceRadius | 0 | Minimum radius of point and spot lights. Each light uses its PenumbraSize when that is larger. |
Rendering.GuidedLighting.Reference | false | Runs the slow reference instead: every light in range shadowed every frame, accumulated while the view holds still. |
Post process volume
The Lighting RTDI group of a Post Process Volume sets the mode for a scene or an area. Turn on OverrideRTDI to apply it.
| Property | Default | Description |
|---|---|---|
OverrideRTDI | Off | Applies this group. |
DirectLightingMode | Probe Cached | Classic, Probe Cached, ReSTIR, Guided. Note that the default is not the presets' choice: set it before you turn the override on. |
RTDIEnabled | On | Rendering.ProbeDirectLighting.Enable. |
RTDIDirectional | Off | Probe cached: trace the sun. |
RTDIProbeSpacing | 8 | Probe spacing in pixels, 4–32. |
RTDIRayBudget | 32 | Rays per probe, 1–256. |
RTDIMaxLightsPerProbe | 16 | 1–48. |
RTDIDominantLights | 4 | Shadowed lights per probe, 1–48. |
RTDIRefine, RTDIRefineSoftLights, RTDIRefineDominant | On, On, Off | Per-pixel refinement of shadow edges, of soft lights, and of each pixel's strongest light. |
RTDISpatialFilter, RTDISpatialMaxRadius | On, 16 | Spatial filter of soft shadow edges and its largest radius in pixels. |
RTDITemporalJitter | Off | Pixel-level temporal accumulation of soft shadows. |
RTDIAreaSamples | 8 | Most emitter samples per area light per probe. |
RTDISunAngularRadius | 0.5 | Angular radius of the traced sun in degrees. |
RTDIPointSourceRadius | 0 | Radius of point and spot lights for soft shadows. |
RTDIShadeSelectedOnly, RTDITailSpecular | On, On | Shade only the selected lights plus one combined term; give that term a highlight. |
RTDIProbeHistory | 8 | Frames of reuse for area-light estimates. |
RTDIRefineBudget, RTDIRefineThreshold | 8, 0.005 | Refinement rays per pixel, and the contribution below which a light is not refined. |
Apart from DirectLightingMode, the properties of this group set the Rendering.ProbeDirectLighting.* CVars and only affect probe-cached lighting.
Debugging
Render Mode › Lighting › Direct Lighting Only shows only direct light, without the sky, reflections or ambient occlusion, in whatever mode is active. It is the view for comparing modes and judging shadows.
Each mode has a submenu of diagnostic views under Render Mode › Lighting (the entries repeat the submenu name in front, for example "Probe Direct Lighting Visibility"):
| Submenu | Views |
|---|---|
| Probe Direct Lighting | Probe Light Count, Cap Saturation, Visibility, Anchor Normal, Refine Band, Pixel Lights, Fallback, Set Coverage (Rendering.ProbeDirectLighting.DebugLightIndex picks the light) |
| ReSTIR Direct Lighting | History Length, Weight, Selected Light (Rendering.ReSTIRDI.DebugLightIndex), Visibility, Boiling, Remap Misses, Penumbra, Grid Cell, Target Pdf, Rays, Candidates, Raw Diffuse, Denoised Diffuse, Denoiser History |
| Guided Lighting | Raw Samples, Light Complexity, List Fill, Sample Outcome, Hidden Share, Pick Probability, History Length, Shading Confidence, Temporal Variance, History Rejection, Reference Error, Reference |
The stats Renderer/ProbeDirectLighting/Status, Renderer/ReSTIRDI/Status and Renderer/GuidedLighting/Status say whether a mode is active and, if not, why. The Active stat next to each is 1 while the mode runs.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| Changing the mode has no visible effect | The mode is unavailable and the classic path is used. Check the Status stat: no hardware ray tracing, Rendering.RT.Enable off, or GI on the software backend. For mode 2, Rendering.ReSTIRDI.Enable must be on too. |
| The mode switches back when the camera enters an area | A post process volume with OverrideRTDI sets its own DirectLightingMode (Probe Cached by default). |
| Transparent objects or particles lose their shadows in modes 1–2 | The ray-traced modes stop rendering shadow maps for the lights they handle. Turn on TransparentShadows on the lights that need shadows on transparents. |
| Shadows are noisy or lag behind moving lights (ReSTIR, guided) | Expected for a short time after a change. Raise the candidates or samples per cell, or more spatial passes; lower Rendering.ReSTIRDI.MaxHistory for less lag. |
| The sun's shadow does not change between modes | The sun stays on shadow maps unless Rendering.ProbeDirectLighting.Directional or Rendering.ReSTIRDI.Directional is on. |
| A light has no contact shadow in a ray-traced mode | Lights that ReSTIR or guided lighting trace get no contact-shadow slot; their rays resolve contact. See Contact Shadows. |