r.Lumen.RadianceCache.NumFramesToKeepCachedProbes

r.Lumen.RadianceCache.NumFramesToKeepCachedProbes

#Overview

name: r.Lumen.RadianceCache.NumFramesToKeepCachedProbes

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

• type: Var
• help: Number of frames to keep unused probes in cache. Higher values enable more reuse between frames, but too high values will cause filtering from stale probes.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.RadianceCache.NumFramesToKeepCachedProbes is to control the number of frames for which unused probes are kept in the Lumen Radiance Cache. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically the Radiance Cache component.

This setting variable is primarily used in the Renderer module, specifically within the Lumen subsystem. It’s utilized in the LumenRadianceCache namespace, which is responsible for managing the Radiance Cache in the Lumen global illumination system.

The value of this variable is set through a console variable (CVar) system. It’s defined with a default value of 8 frames, but can be adjusted at runtime or through configuration files.

The associated variable CVarRadianceCacheNumFramesToKeepCachedProbes directly interacts with r.Lumen.RadianceCache.NumFramesToKeepCachedProbes. They essentially represent the same setting, with the CVar providing a programmatic interface to access and modify the value.

Developers must be aware that this variable affects the trade-off between performance and lighting accuracy. Higher values allow for more reuse of probes between frames, potentially improving performance, but may lead to using outdated lighting information if set too high.

Best practices when using this variable include:

1. Adjusting it based on the specific needs of the scene and performance targets.
2. Testing different values to find the optimal balance between performance and visual quality.
3. Being cautious about setting very high values, as this could lead to stale lighting information being used.

Regarding the associated variable CVarRadianceCacheNumFramesToKeepCachedProbes:

• Its purpose is to provide a programmatic way to access and modify the r.Lumen.RadianceCache.NumFramesToKeepCachedProbes setting.
• It’s used within the Renderer module, specifically in the Lumen Radiance Cache system.
• The value is set when the CVar is initialized and can be modified at runtime.
• It directly interacts with r.Lumen.RadianceCache.NumFramesToKeepCachedProbes, essentially representing the same setting.
• Developers should be aware that modifying this CVar will affect the Radiance Cache behavior in the same way as adjusting r.Lumen.RadianceCache.NumFramesToKeepCachedProbes.
• Best practices include using the appropriate Unreal Engine console variable functions to read or modify this value, and considering the same performance vs. accuracy trade-offs mentioned earlier.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenRadianceCache.cpp:28

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarRadianceCacheNumFramesToKeepCachedProbes(
	TEXT("r.Lumen.RadianceCache.NumFramesToKeepCachedProbes"),
	8,
	TEXT("Number of frames to keep unused probes in cache. Higher values enable more reuse between frames, but too high values will cause filtering from stale probes."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GRadianceCacheOverrideCacheOcclusionLighting = 0;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenRadianceCache.cpp:27

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarRadianceCacheNumFramesToKeepCachedProbes(
	TEXT("r.Lumen.RadianceCache.NumFramesToKeepCachedProbes"),
	8,
	TEXT("Number of frames to keep unused probes in cache. Higher values enable more reuse between frames, but too high values will cause filtering from stale probes."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenRadianceCache.cpp:1465

Scope (from outer to inner):

file
namespace    LumenRadianceCache
function     void UpdateRadianceCaches

Source code excerpt:

					PassParameters->RadianceCacheParameters = RadianceCacheParameters;
					PassParameters->FrameNumber = View.ViewState->GetFrameIndex();
					PassParameters->NumFramesToKeepCachedProbes = FMath::Max(CVarRadianceCacheNumFramesToKeepCachedProbes.GetValueOnRenderThread(), 0);
					PassParameters->MaxNumProbes = MaxNumProbes;

					for (int32 ClipmapIndex = 0; ClipmapIndex < Setup.LastFrameClipmaps.Num(); ++ClipmapIndex)
					{
						const FRadianceCacheClipmap& Clipmap = Setup.LastFrameClipmaps[ClipmapIndex];