r.Lumen.ScreenProbeGather.SpatialFilterPositionWeightScale

r.Lumen.ScreenProbeGather.SpatialFilterPositionWeightScale

#Overview

name: r.Lumen.ScreenProbeGather.SpatialFilterPositionWeightScale

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

• type: Var
• help: Determines how far probes can be in world space while still filtering lighting

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.SpatialFilterPositionWeightScale is to control the spatial filtering of lighting in Unreal Engine 5’s Lumen global illumination system. Specifically, it determines the maximum distance in world space at which probes can still contribute to the filtered lighting result.

This setting variable is primarily used in the rendering system, particularly within the Lumen module, which is responsible for real-time global illumination in Unreal Engine 5.

The Unreal Engine subsystem that relies on this setting variable is the Renderer, specifically the Lumen component of the rendering pipeline. This can be seen from the file path where the variable is defined and used: “Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeFiltering.cpp”.

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

This variable interacts directly with GLumenScreenFilterPositionWeightScale, which is the C++ variable that stores the actual value used in the rendering code.

Developers should be aware that this variable affects the trade-off between lighting quality and performance. A higher value will allow lighting information to be gathered from further away, potentially improving quality but at the cost of performance.

Best practices when using this variable include:

1. Adjusting it based on the scale of your scene. Larger scenes might benefit from higher values.
2. Balancing it with other Lumen settings for optimal performance and quality.
3. Testing different values to find the sweet spot for your specific use case.

Regarding the associated variable GLumenScreenFilterPositionWeightScale:

The purpose of GLumenScreenFilterPositionWeightScale is to store the actual value used in the rendering code for the position weight scale in spatial filtering of screen probes.

This variable is used directly in the Lumen screen probe filtering process, specifically in the FilterScreenProbes function.

The value of this variable is set by the console variable r.Lumen.ScreenProbeGather.SpatialFilterPositionWeightScale.

It interacts with other parameters in the screen probe filtering process, such as SpatialFilterMaxRadianceHitAngle and SpatialFilterHalfKernelSize.

Developers should be aware that this variable directly affects the filtering of screen probes in the Lumen system, which can impact both the quality and performance of global illumination.

Best practices include monitoring this variable’s value when debugging lighting issues or performance problems related to Lumen, and considering its impact when adjusting related Lumen settings.

#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:40

Scope: file

Source code excerpt:

float GLumenScreenFilterPositionWeightScale = 1000.0f;
FAutoConsoleVariableRef GVarLumenScreenFilterPositionWeightScale(
	TEXT("r.Lumen.ScreenProbeGather.SpatialFilterPositionWeightScale"),
	GLumenScreenFilterPositionWeightScale,
	TEXT("Determines how far probes can be in world space while still filtering lighting"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeGatherNumMips = 1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GLumenScreenFilterPositionWeightScale = 1000.0f;
FAutoConsoleVariableRef GVarLumenScreenFilterPositionWeightScale(
	TEXT("r.Lumen.ScreenProbeGather.SpatialFilterPositionWeightScale"),
	GLumenScreenFilterPositionWeightScale,
	TEXT("Determines how far probes can be in world space while still filtering lighting"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeGatherNumMips = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherNumMips(

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

Scope (from outer to inner):

file
function     void FilterScreenProbes

Source code excerpt:

			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);