r.Lumen.ScreenProbeGather.TemporalFilterProbes.HistoryDistanceThreshold

r.Lumen.ScreenProbeGather.TemporalFilterProbes.HistoryDistanceThreshold

#Overview

name: r.Lumen.ScreenProbeGather.TemporalFilterProbes.HistoryDistanceThreshold

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.TemporalFilterProbes.HistoryDistanceThreshold is to set a threshold value for the distance used in temporal filtering of screen probes in the Lumen lighting system. This setting is part of Unreal Engine 5’s rendering system, specifically the Lumen global illumination feature.

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

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 30 and can be modified at runtime using console commands or through configuration files.

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

Developers should be aware that this variable affects the temporal stability and quality of the Lumen global illumination. A higher value may result in more stable lighting but could potentially introduce more ghosting or lag in lighting changes, while a lower value might make lighting more responsive but potentially noisier.

Best practices when using this variable include:

  1. Experimenting with different values to find the right balance between temporal stability and responsiveness for your specific scene.
  2. Considering the performance impact of changes, as it may affect the filtering process.
  3. Testing in various lighting conditions and with dynamic objects to ensure the chosen value works well in different scenarios.

Regarding the associated variable GLumenScreenProbeTemporalFilterProbesHistoryDistanceThreshold:

The purpose of this variable is to store the actual value of the history distance threshold used in the screen probe temporal filtering process. It’s a float variable that directly corresponds to the console variable r.Lumen.ScreenProbeGather.TemporalFilterProbes.HistoryDistanceThreshold.

This variable is used in the Lumen subsystem of the rendering module, specifically in the screen probe filtering process. It’s referenced in the FilterScreenProbes function, where it’s assigned to a shader parameter (PassParameters->HistoryDistanceThreshold).

The value of this variable is set by the console variable system when r.Lumen.ScreenProbeGather.TemporalFilterProbes.HistoryDistanceThreshold is modified.

Developers should be aware that modifying r.Lumen.ScreenProbeGather.TemporalFilterProbes.HistoryDistanceThreshold will directly affect this variable, and consequently, the behavior of the screen probe temporal filtering.

Best practices include:

  1. Using the console variable for runtime adjustments rather than modifying this variable directly in code.
  2. Considering the impact on both visual quality and performance when adjusting this value.
  3. Documenting any custom values used in your project for easier tuning and debugging.

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

Scope: file

Source code excerpt:

float GLumenScreenProbeTemporalFilterProbesHistoryDistanceThreshold = 30;
FAutoConsoleVariableRef CVarLumenScreenProbeTemporalFilterProbesHistoryDistanceThreshold(
	TEXT("r.Lumen.ScreenProbeGather.TemporalFilterProbes.HistoryDistanceThreshold"),
	GLumenScreenProbeTemporalFilterProbesHistoryDistanceThreshold,
	TEXT(""),
	ECVF_RenderThreadSafe
	);

float GLumenScreenProbeTemporalFilterProbesHistoryWeight = .5f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GLumenScreenProbeTemporalFilterProbesHistoryDistanceThreshold = 30;
FAutoConsoleVariableRef CVarLumenScreenProbeTemporalFilterProbesHistoryDistanceThreshold(
	TEXT("r.Lumen.ScreenProbeGather.TemporalFilterProbes.HistoryDistanceThreshold"),
	GLumenScreenProbeTemporalFilterProbesHistoryDistanceThreshold,
	TEXT(""),
	ECVF_RenderThreadSafe
	);

float GLumenScreenProbeTemporalFilterProbesHistoryWeight = .5f;
FAutoConsoleVariableRef CVarLumenScreenProbeTemporalFilterProbesHistoryWeight(

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

Scope (from outer to inner):

file
function     void FilterScreenProbes

Source code excerpt:

			(ScreenProbeGatherState.ProbeHistoryViewRect.Max.Y - 0.5f) * InvBufferSize.Y);

		PassParameters->HistoryDistanceThreshold = GLumenScreenProbeTemporalFilterProbesHistoryDistanceThreshold;
		PassParameters->HistoryScreenProbeRadiance = GraphBuilder.RegisterExternalTexture(ScreenProbeGatherState.ProbeHistoryScreenProbeRadiance);
		PassParameters->HistoryScreenProbeSceneDepth = GraphBuilder.RegisterExternalTexture(ScreenProbeGatherState.HistoryScreenProbeSceneDepth);
		PassParameters->HistoryScreenProbeTranslatedWorldPosition = GraphBuilder.RegisterExternalTexture(ScreenProbeGatherState.HistoryScreenProbeTranslatedWorldPosition);
		PassParameters->ProbeTemporalFilterHistoryWeight = GLumenScreenProbeTemporalFilterProbesHistoryWeight;

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