r.Lumen.RadianceCache.ForceUniformTraceTileLevel

r.Lumen.RadianceCache.ForceUniformTraceTileLevel

#Overview

name: r.Lumen.RadianceCache.ForceUniformTraceTileLevel

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.RadianceCache.ForceUniformTraceTileLevel is to control the trace tile level in Lumen’s Radiance Cache system for debugging purposes. It allows forcing a uniform trace tile level, overriding the default BRDF importance sampling behavior.

This setting variable is primarily used by the Lumen rendering system, specifically within the Radiance Cache module. It’s part of Unreal Engine’s advanced rendering features and is utilized in the Renderer module.

The value of this variable is set through the console variable system (CVarLumenRadianceCacheForceUniformTraceTileLevel). It’s associated with the C++ variable GLumenRadianceCacheForceUniformTraceTileLevel.

The variable interacts with the BRDF importance sampling system. When set to a value >= 0, it overrides the normal BRDF importance sampling behavior.

Developers must be aware that:

  1. This is primarily a debugging tool and should not be used in production builds.
  2. Valid values range from 0 to 2, where 0 = half resolution, 1 = full resolution, and 2 = supersampled.
  3. Setting this variable affects rendering performance and quality.

Best practices when using this variable include:

  1. Use it only for debugging purposes.
  2. Reset it to -1 (default) after debugging to re-enable normal BRDF importance sampling.
  3. Be cautious when using in performance-sensitive scenarios, as it can impact rendering efficiency.

Regarding the associated variable GLumenRadianceCacheForceUniformTraceTileLevel:

The purpose of GLumenRadianceCacheForceUniformTraceTileLevel is to store the value set by the console variable r.Lumen.RadianceCache.ForceUniformTraceTileLevel within the C++ code.

This variable is used directly in the Lumen Radiance Cache system, specifically in the UpdateRadianceCaches function and the ShouldImportanceSampleBRDF function.

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

It interacts with the BRDF importance sampling system and affects the trace tile level selection.

Developers should be aware that:

  1. The default value is -1, which means no forcing of uniform trace tile level.
  2. When set to a value >= 0, it overrides normal behavior and should be used cautiously.

Best practices for using this variable in C++ code include:

  1. Check if the value is >= 0 before applying it to ensure normal behavior when not explicitly set.
  2. Use the FMath::Clamp function to ensure the value stays within the valid range of 0-2 when applying it.
  3. Consider the performance implications when using non-default values in performance-critical code paths.

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

Scope: file

Source code excerpt:

int32 GLumenRadianceCacheForceUniformTraceTileLevel = -1;
FAutoConsoleVariableRef CVarLumenRadianceCacheForceUniformTraceTileLevel(
	TEXT("r.Lumen.RadianceCache.ForceUniformTraceTileLevel"),
	GLumenRadianceCacheForceUniformTraceTileLevel,
	TEXT("When set to >= 0, forces a uniform trace tile level for debugging, and overrides trace tile BRDF importance sampling.  Valid range is [0, 2].  0 = half res, 1 = full res, 2 = supersampled"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenRadianceCacheSupersampleTileBRDFThreshold = .1f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenRadianceCacheForceUniformTraceTileLevel = -1;
FAutoConsoleVariableRef CVarLumenRadianceCacheForceUniformTraceTileLevel(
	TEXT("r.Lumen.RadianceCache.ForceUniformTraceTileLevel"),
	GLumenRadianceCacheForceUniformTraceTileLevel,
	TEXT("When set to >= 0, forces a uniform trace tile level for debugging, and overrides trace tile BRDF importance sampling.  Valid range is [0, 2].  0 = half res, 1 = full res, 2 = supersampled"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenRadianceCacheSupersampleTileBRDFThreshold = .1f;
FAutoConsoleVariableRef CVarLumenRadianceCacheSupersampleTileBRDFThreshold(

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

Scope (from outer to inner):

file
namespace    LumenRadianceCache
function     bool ShouldImportanceSampleBRDF

Source code excerpt:

bool ShouldImportanceSampleBRDF(const FUpdateInputs& Inputs)
{
	return Inputs.ScreenProbeParameters && Inputs.BRDFProbabilityDensityFunctionSH && GLumenRadianceCacheForceUniformTraceTileLevel < 0;
}

float GetSupersampleDistanceFromCamera(const FUpdateInputs& Inputs)
{
	return GLumenRadianceCacheSupersampleDistanceFromCamera;
}

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

Scope (from outer to inner):

file
namespace    LumenRadianceCache
function     void UpdateRadianceCaches

Source code excerpt:

				PassParameters->SupersampleDistanceFromCameraSq = GLumenRadianceCacheSupersampleDistanceFromCamera * GLumenRadianceCacheSupersampleDistanceFromCamera;
				PassParameters->DownsampleDistanceFromCameraSq = GLumenRadianceCacheDownsampleDistanceFromCamera * GLumenRadianceCacheDownsampleDistanceFromCamera;
				PassParameters->ForcedUniformLevel = GLumenRadianceCacheForceUniformTraceTileLevel >= 0 ? FMath::Clamp<int32>(GLumenRadianceCacheForceUniformTraceTileLevel, 0, 2) : 1;

				PassParameters->RWDebugBRDFProbabilityDensityFunction = GraphBuilder.CreateUAV(FRDGTextureUAVDesc(DebugBRDFProbabilityDensityFunction));
				PassParameters->DebugProbeBRDFOctahedronResolution = DebugProbeBRDFOctahedronResolution;

				PassParameters->View = View.ViewUniformBuffer;
				PassParameters->RadianceCacheParameters = RadianceCacheParameters;