r.Lumen.ScreenProbeGather.SpatialFilterMaxRadianceHitAngle

r.Lumen.ScreenProbeGather.SpatialFilterMaxRadianceHitAngle

#Overview

name: r.Lumen.ScreenProbeGather.SpatialFilterMaxRadianceHitAngle

This variable is created as a Console Variable (cvar).

• type: Var
• help: In Degrees. Larger angles allow more filtering but lose contact shadows.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.SpatialFilterMaxRadianceHitAngle is to control the spatial filtering of screen probes in Unreal Engine 5’s Lumen global illumination system. It specifically defines the maximum angle (in degrees) for filtering radiance hits during the screen probe gathering process.

This setting variable is primarily used by the Lumen subsystem within Unreal Engine’s rendering module. Based on the callsites, it’s clear that this variable is utilized in the screen probe filtering process, which is a crucial part of Lumen’s global illumination calculations.

The value of this variable is set through the Unreal Engine console variable system. It’s defined as an FAutoConsoleVariableRef, which allows it to be adjusted at runtime through console commands or configuration files.

The associated variable GLumenScreenProbeFilterMaxRadianceHitAngle directly interacts with this console variable. They share the same value, with GLumenScreenProbeFilterMaxRadianceHitAngle being the C++ variable that’s actually used in the rendering code.

Developers must be aware that this variable is measured in degrees and directly impacts the trade-off between filtering quality and preservation of contact shadows. As the comment suggests, larger angles allow for more filtering but at the cost of losing detail in contact shadows.

Best practices when using this variable include:

1. Carefully balancing the value to achieve the desired visual quality without overly compromising performance or shadow detail.
2. Testing different values in various lighting scenarios to understand its impact on your specific scenes.
3. Considering the performance implications of higher values, as more filtering can be computationally expensive.

Regarding the associated variable GLumenScreenProbeFilterMaxRadianceHitAngle:

The purpose of GLumenScreenProbeFilterMaxRadianceHitAngle is to store the actual value used in the rendering calculations. It’s the C++ representation of the console variable.

This variable is used directly in the Lumen screen probe filtering process, specifically in the FilterScreenProbes function. It’s converted from degrees to radians and clamped between 0 and π before being passed to the shader.

The value of this variable is set by the console variable system and can be modified at runtime.

It interacts directly with the console variable r.Lumen.ScreenProbeGather.SpatialFilterMaxRadianceHitAngle, reflecting any changes made to that variable.

Developers should be aware that this variable is used in radians in the actual rendering code, despite being set in degrees through the console variable.

Best practices include ensuring that any direct modifications to this variable (if allowed in your project setup) are consistent with the console variable settings to avoid confusion or unexpected behavior.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeFiltering.cpp:32

Scope: file

Source code excerpt:

float GLumenScreenProbeFilterMaxRadianceHitAngle = 10.0f;
FAutoConsoleVariableRef GVarLumenScreenProbeFilterMaxRadianceHitAngle(
	TEXT("r.Lumen.ScreenProbeGather.SpatialFilterMaxRadianceHitAngle"),
	GLumenScreenProbeFilterMaxRadianceHitAngle,
	TEXT("In Degrees.  Larger angles allow more filtering but lose contact shadows."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenScreenFilterPositionWeightScale = 1000.0f;

#Associated Variable and Callsites

This variable is associated with another variable named GLumenScreenProbeFilterMaxRadianceHitAngle. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeFiltering.cpp:30

Scope: file

Source code excerpt:

);

float GLumenScreenProbeFilterMaxRadianceHitAngle = 10.0f;
FAutoConsoleVariableRef GVarLumenScreenProbeFilterMaxRadianceHitAngle(
	TEXT("r.Lumen.ScreenProbeGather.SpatialFilterMaxRadianceHitAngle"),
	GLumenScreenProbeFilterMaxRadianceHitAngle,
	TEXT("In Degrees.  Larger angles allow more filtering but lose contact shadows."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenScreenFilterPositionWeightScale = 1000.0f;
FAutoConsoleVariableRef GVarLumenScreenFilterPositionWeightScale(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeFiltering.cpp:560

Scope (from outer to inner):

file
function     void FilterScreenProbes

Source code excerpt:

			PassParameters->ScreenProbeHitDistance = ScreenProbeHitDistance;
			PassParameters->ScreenProbeMoving = ScreenProbeMoving;
			PassParameters->SpatialFilterMaxRadianceHitAngle = FMath::Clamp<float>(GLumenScreenProbeFilterMaxRadianceHitAngle * PI / 180.0f, 0.0f, PI);
			PassParameters->SpatialFilterPositionWeightScale = GLumenScreenFilterPositionWeightScale;
			PassParameters->SpatialFilterHalfKernelSize = GLumenScreenProbeSpatialFilterHalfKernelSize;
			PassParameters->View = View.ViewUniformBuffer;
			PassParameters->ScreenProbeParameters = ScreenProbeParameters;

			auto ComputeShader = View.ShaderMap->GetShader<FScreenProbeFilterGatherTracesCS>(0);