Skip to main content
Version: Next (dev)

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:

ValueModeShadows fromCost grows withPresets
0ClassicShadow maps (virtual or cascaded) for lights with CastShadows, plus contact shadows.The number of overlapping and shadow-casting lights.Low, Medium, High
1Probe cachedShadow rays traced on a sparse grid of screen probes and reused by the pixels around them.Mostly fixed: a fixed ray budget per probe.–
2ReSTIR DIOne resampled light sample per pixel, traced, reused across frames and neighbours, then denoised.Fixed per pixel, independent of the light count.Max
3GuidedAbout 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.Directional is on.
  • Lights it handles stop requesting shadow maps (Rendering.ProbeDirectLighting.SuppressShadowMaps). Transparent objects and particles then see those lights unshadowed, unless the light has TransparentShadows on.
  • Point and spot lights are hard point sources unless Rendering.ProbeDirectLighting.PointSourceRadius gives them a radius.

Good for scenes with many shadow-casting local lights, where classic shadow maps would cost too much.

CVarDefaultDescription
Rendering.ProbeDirectLighting.EnabletrueSwitch for the pass while the mode is 1.
Rendering.ProbeDirectLighting.ProbeSpacing8Probe spacing in pixels. About 8 is the optimum for typical content.
Rendering.ProbeDirectLighting.RayBudget32Rays per probe per frame. Same in every preset.
Rendering.ProbeDirectLighting.MaxLightsPerProbe16Most lights a probe caches. A probe that runs out shades its pixels with the full loop.
Rendering.ProbeDirectLighting.DominantLights4Shadowed lights per probe.
Rendering.ProbeDirectLighting.RefinetrueRe-traces shadow edges per pixel.
Rendering.ProbeDirectLighting.DirectionalfalseTraces the sun too, instead of its shadow maps.
Rendering.ProbeDirectLighting.SunAngularRadius0.5Angular radius of the sun in degrees, for soft sun shadows when it is traced.
Rendering.ProbeDirectLighting.AreaSamples8Most emitter samples per area light per probe.
Rendering.ProbeDirectLighting.SuppressShadowMapstrueLights 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.Directional is on.
  • Lights it handles stop requesting shadow maps (Rendering.ReSTIRDI.SuppressShadowMaps); transparent objects keep a shadow map only for lights with TransparentShadows.
  • 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 (CameraCutDistance 2 m, CameraCutAngle 45°) 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.

CVarDefaultDescription
Rendering.ReSTIRDI.EnabletrueSwitch 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.HalfResfalseHalf-resolution reuse. On in Max.
Rendering.ReSTIRDI.GridCandidates, FroxelCandidates, EmissiveCandidates8, 4, 2Candidates per pixel from the world-space grid, the froxel light list and the emissive tiles. Set by the presets.
Rendering.ReSTIRDI.SpatialTaps5Neighbours of the first spatial reuse pass. 0 disables it.
Rendering.ReSTIRDI.MaxHistory20Temporal history cap. Higher converges further and lags more.
Rendering.ReSTIRDI.AreaSamples2Extra emitter rays where a penumbra is wider than a pixel.
Rendering.ReSTIRDI.DirectionalfalseTraces the sun (one ray per pixel, SunAngularRadius 0.5°) instead of its shadow maps.
Rendering.ReSTIRDI.PointSourceRadius0Minimum radius of point and spot emitters. Each light uses its PenumbraSize when that is larger.
Rendering.ReSTIRDI.EmissiveThreshold0.05Emissive luminance above which an object's triangles become lights.
Rendering.ReSTIRDI.EmissiveTwoSidedfalseEmissive triangles radiate from both faces. Turn on for single-quad panels.
Rendering.ReSTIRDI.Denoiser10 = raw, 1 = NRD ReLAX, 2 = built-in.
Rendering.ReSTIRDI.FireflyClamp8Clamps bright outliers while a pixel's history is short. 0 disables.
Rendering.ReSTIRDI.ReferenceModefalseNo 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).

CVarDefaultDescription
Rendering.GuidedLighting.EnabletrueSwitch for the pass while the mode is 3.
Rendering.GuidedLighting.SamplesPerCell4Light samples per cell, 1–16. With half resolution, 4 is about one ray per pixel.
Rendering.GuidedLighting.HalfRestrue2×2 pixel cells. Off = one cell per pixel, four times the rays.
Rendering.GuidedLighting.HiddenCandidates8Lights per cell evaluated from outside last frame's visible list. More finds newly visible lights sooner.
Rendering.GuidedLighting.Denoiser00 = built-in, 1 = NRD ReLAX, 2 = off.
Rendering.GuidedLighting.Denoise.SpatialPasses3Spatial filter passes, 0–5. More flickers less and blurs more.
Rendering.GuidedLighting.PointSourceRadius0Minimum radius of point and spot lights. Each light uses its PenumbraSize when that is larger.
Rendering.GuidedLighting.ReferencefalseRuns 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.

PropertyDefaultDescription
OverrideRTDIOffApplies this group.
DirectLightingModeProbe CachedClassic, Probe Cached, ReSTIR, Guided. Note that the default is not the presets' choice: set it before you turn the override on.
RTDIEnabledOnRendering.ProbeDirectLighting.Enable.
RTDIDirectionalOffProbe cached: trace the sun.
RTDIProbeSpacing8Probe spacing in pixels, 4–32.
RTDIRayBudget32Rays per probe, 1–256.
RTDIMaxLightsPerProbe161–48.
RTDIDominantLights4Shadowed lights per probe, 1–48.
RTDIRefine, RTDIRefineSoftLights, RTDIRefineDominantOn, On, OffPer-pixel refinement of shadow edges, of soft lights, and of each pixel's strongest light.
RTDISpatialFilter, RTDISpatialMaxRadiusOn, 16Spatial filter of soft shadow edges and its largest radius in pixels.
RTDITemporalJitterOffPixel-level temporal accumulation of soft shadows.
RTDIAreaSamples8Most emitter samples per area light per probe.
RTDISunAngularRadius0.5Angular radius of the traced sun in degrees.
RTDIPointSourceRadius0Radius of point and spot lights for soft shadows.
RTDIShadeSelectedOnly, RTDITailSpecularOn, OnShade only the selected lights plus one combined term; give that term a highlight.
RTDIProbeHistory8Frames of reuse for area-light estimates.
RTDIRefineBudget, RTDIRefineThreshold8, 0.005Refinement 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"):

SubmenuViews
Probe Direct LightingProbe Light Count, Cap Saturation, Visibility, Anchor Normal, Refine Band, Pixel Lights, Fallback, Set Coverage (Rendering.ProbeDirectLighting.DebugLightIndex picks the light)
ReSTIR Direct LightingHistory 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 LightingRaw 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​

SymptomCause and fix
Changing the mode has no visible effectThe 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 areaA post process volume with OverrideRTDI sets its own DirectLightingMode (Probe Cached by default).
Transparent objects or particles lose their shadows in modes 1–2The 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 modesThe 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 modeLights that ReSTIR or guided lighting trace get no contact-shadow slot; their rays resolve contact. See Contact Shadows.

See Also​