r.Lumen.RadianceCache.DownsampleDistanceFromCamera

r.Lumen.RadianceCache.DownsampleDistanceFromCamera

#Overview

name: r.Lumen.RadianceCache.DownsampleDistanceFromCamera

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.RadianceCache.DownsampleDistanceFromCamera is to control the distance from the camera at which Lumen’s radiance cache probes are always downsampled. 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 Lumen subsystem of Unreal Engine’s rendering module. It’s referenced in the LumenRadianceCache namespace, indicating its specific use in the radiance caching part of Lumen.

The value of this variable is set using an FAutoConsoleVariableRef, which means it can be adjusted at runtime through console commands. Its default value is 4000.0 units.

This variable interacts closely with GLumenRadianceCacheDownsampleDistanceFromCamera, which is the C++ variable that actually stores the value. They share the same value, with the console variable acting as an interface to modify the C++ variable.

Developers should be aware that this variable affects performance and visual quality. Increasing the value will cause more distant probes to be downsampled, potentially improving performance at the cost of reduced lighting quality for distant objects.

Best practices when using this variable include:

  1. Adjusting it based on the scale and performance requirements of your scene.
  2. Testing different values to find the right balance between performance and visual quality.
  3. Considering it in conjunction with other Lumen settings for optimal results.

Regarding GLumenRadianceCacheDownsampleDistanceFromCamera:

This is the actual C++ variable that stores the downsample distance value. It’s used in several places within the LumenRadianceCache namespace:

  1. In the UpdateRadianceCaches function, it’s used to calculate DownsampleDistanceFromCameraSq, which is likely used to determine which probes should be downsampled.
  2. It’s squared and passed to various shader parameters, suggesting that distance checks in the shaders are done using squared distances for efficiency.

Developers should note that modifying GLumenRadianceCacheDownsampleDistanceFromCamera directly in code will be overwritten by the console variable at runtime. Always use the console variable (r.Lumen.RadianceCache.DownsampleDistanceFromCamera) to adjust this setting, unless you have a specific reason to modify the C++ variable directly.

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

Scope: file

Source code excerpt:

float GLumenRadianceCacheDownsampleDistanceFromCamera = 4000.0f;
FAutoConsoleVariableRef CVarLumenRadianceCacheDownsampleDistanceFromCamera(
	TEXT("r.Lumen.RadianceCache.DownsampleDistanceFromCamera"),
	GLumenRadianceCacheDownsampleDistanceFromCamera,
	TEXT("Probes further than this distance from the camera are always downsampled."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

namespace LumenRadianceCache

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

float GLumenRadianceCacheDownsampleDistanceFromCamera = 4000.0f;
FAutoConsoleVariableRef CVarLumenRadianceCacheDownsampleDistanceFromCamera(
	TEXT("r.Lumen.RadianceCache.DownsampleDistanceFromCamera"),
	GLumenRadianceCacheDownsampleDistanceFromCamera,
	TEXT("Probes further than this distance from the camera are always downsampled."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

namespace LumenRadianceCache
{

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

Scope (from outer to inner):

file
namespace    LumenRadianceCache
function     void UpdateRadianceCaches

Source code excerpt:

				PassParameters->FirstClipmapWorldExtentRcp = 1.0f / FMath::Max(RadianceCacheInputs.ClipmapWorldExtent, 1.0f);
				PassParameters->SupersampleDistanceFromCameraSq = GetSupersampleDistanceFromCamera(Inputs) * GetSupersampleDistanceFromCamera(Inputs);
				PassParameters->DownsampleDistanceFromCameraSq = GLumenRadianceCacheDownsampleDistanceFromCamera * GLumenRadianceCacheDownsampleDistanceFromCamera;
				PassParameters->FrameNumber = View.ViewState ? View.ViewState->GetFrameIndex() : View.Family->FrameNumber;
				PassParameters->MaxNumProbes = MaxNumProbes;
				PassParameters->RadianceCacheParameters = RadianceCacheParameters;

				FAllocateUsedProbesCS::FPermutationDomain PermutationVector;
				PermutationVector.Set<FAllocateUsedProbesCS::FPersistentCache>(Setup.bPersistentCache);

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

Scope (from outer to inner):

file
namespace    LumenRadianceCache
function     void UpdateRadianceCaches

Source code excerpt:

				PassParameters->ProbeFreeList = Setup.bPersistentCache ? GraphBuilder.CreateSRV(FRDGBufferSRVDesc(ProbeFreeList[RadianceCacheIndex], PF_R32_UINT)) : nullptr;
				PassParameters->SupersampleDistanceFromCameraSq = GetSupersampleDistanceFromCamera(Inputs) * GetSupersampleDistanceFromCamera(Inputs);
				PassParameters->DownsampleDistanceFromCameraSq = GLumenRadianceCacheDownsampleDistanceFromCamera * GLumenRadianceCacheDownsampleDistanceFromCamera;
				PassParameters->FirstClipmapWorldExtentRcp = 1.0f / FMath::Max(RadianceCacheInputs.ClipmapWorldExtent, 1.0f);
				PassParameters->FrameNumber = View.ViewState ? View.ViewState->GetFrameIndex() : View.Family->FrameNumber;
				PassParameters->MaxNumProbes = MaxNumProbes;
				PassParameters->RadianceCacheParameters = RadianceCacheParameters;

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

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

Scope (from outer to inner):

file
namespace    LumenRadianceCache
function     void UpdateRadianceCaches

Source code excerpt:

				PassParameters->SupersampleTileBRDFThreshold = GLumenRadianceCacheSupersampleTileBRDFThreshold;
				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;