r.Lumen.ScreenProbeGather.SpatialFilterHalfKernelSize

r.Lumen.ScreenProbeGather.SpatialFilterHalfKernelSize

#Overview

name: r.Lumen.ScreenProbeGather.SpatialFilterHalfKernelSize

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.SpatialFilterHalfKernelSize is to control the spatial filtering of screen probes in the Lumen global illumination system within Unreal Engine 5’s rendering pipeline. This setting variable is specifically used for the screen probe gathering process, which is a crucial part of Lumen’s real-time global illumination solution.

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 part of Lumen’s screen-space global illumination technique.

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.

The associated variable GLumenScreenProbeSpatialFilterHalfKernelSize directly interacts with this setting. They share the same value, with GLumenScreenProbeSpatialFilterHalfKernelSize being the actual integer variable used in the C++ code.

Developers must be aware that this variable affects the performance and quality of Lumen’s screen probe gathering. A larger value will increase the spatial filter kernel size, potentially improving quality but at the cost of performance. It’s marked as “Experimental” in the code, suggesting that its behavior or implementation may change in future engine versions.

Best practices when using this variable include:

  1. Carefully balancing quality and performance based on the target hardware.
  2. Testing different values to find the optimal setting for specific scenes or use cases.
  3. Being cautious when modifying it, as it’s marked experimental.
  4. Considering its interaction with other Lumen settings for optimal results.

Regarding the associated variable GLumenScreenProbeSpatialFilterHalfKernelSize:

The purpose of GLumenScreenProbeSpatialFilterHalfKernelSize is to store the actual value of the spatial filter half kernel size used in the screen probe filtering process. It’s an integer variable that directly controls the size of the spatial filter kernel in the implementation.

This variable is used within the Lumen subsystem of Unreal Engine’s rendering module, specifically in the screen probe filtering process.

The value of this variable is set by the console variable system through the r.Lumen.ScreenProbeGather.SpatialFilterHalfKernelSize setting.

It interacts directly with the console variable and is used in conditional statements and parameter assignments in the filtering process.

Developers should be aware that this variable directly affects the behavior of the screen probe spatial filter. A value of 0 or less will disable the filter entirely.

Best practices include monitoring this variable’s value when debugging or optimizing Lumen’s performance, and understanding its impact on the spatial filtering process in relation to other Lumen parameters.

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

Scope: file

Source code excerpt:

int32 GLumenScreenProbeSpatialFilterHalfKernelSize = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeSpatialFilterHalfKernelSize(
	TEXT("r.Lumen.ScreenProbeGather.SpatialFilterHalfKernelSize"),
	GLumenScreenProbeSpatialFilterHalfKernelSize,
	TEXT("Experimental"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenScreenProbeFilterMaxRadianceHitAngle = 10.0f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenScreenProbeSpatialFilterHalfKernelSize = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeSpatialFilterHalfKernelSize(
	TEXT("r.Lumen.ScreenProbeGather.SpatialFilterHalfKernelSize"),
	GLumenScreenProbeSpatialFilterHalfKernelSize,
	TEXT("Experimental"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenScreenProbeFilterMaxRadianceHitAngle = 10.0f;
FAutoConsoleVariableRef GVarLumenScreenProbeFilterMaxRadianceHitAngle(

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

Scope (from outer to inner):

file
function     void FilterScreenProbes

Source code excerpt:

	}

	if (LumenScreenProbeGather::UseProbeSpatialFilter() && GLumenScreenProbeSpatialFilterHalfKernelSize > 0)
	{
		for (int32 PassIndex = 0; PassIndex < GLumenScreenProbeSpatialFilterNumPasses; PassIndex++)
		{
			FRDGTextureRef FilteredScreenProbeRadiance = GraphBuilder.CreateTexture(ScreenProbeRadianceDesc, TEXT("Lumen.ScreenProbeGather.ScreenProbeFilteredRadiance"));

			FScreenProbeFilterGatherTracesCS::FParameters* PassParameters = GraphBuilder.AllocParameters<FScreenProbeFilterGatherTracesCS::FParameters>();

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

Scope (from outer to inner):

file
function     void FilterScreenProbes

Source code excerpt:

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

			FComputeShaderUtils::AddPass(