r.Lumen.ScreenProbeGather.AdaptiveProbeMinDownsampleFactor

r.Lumen.ScreenProbeGather.AdaptiveProbeMinDownsampleFactor

#Overview

name: r.Lumen.ScreenProbeGather.AdaptiveProbeMinDownsampleFactor

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

• type: Var
• help: Screen probes will be placed where needed down to this downsample factor of the GBuffer.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.AdaptiveProbeMinDownsampleFactor is to control the minimum downsample factor for adaptive screen probe placement in the Lumen global illumination system.

This setting variable is part of Unreal Engine 5’s Lumen rendering system, specifically the screen probe gathering component. It is used in the Renderer module, as evidenced by its location in the LumenScreenProbeGather.cpp file.

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

This variable interacts closely with GLumenScreenProbeGatherAdaptiveProbeMinDownsampleFactor, which is the associated C++ variable that directly holds the value set by the console variable.

Developers should be aware that this variable affects the placement density of screen probes. A lower value will result in a higher density of probes, potentially improving lighting quality but at the cost of performance. The value is clamped between 1 and 64 in the code, so setting values outside this range will be automatically adjusted.

Best practices when using this variable include:

1. Balancing between quality and performance based on the target hardware.
2. Testing different values to find the optimal setting for your specific scene.
3. Considering the relationship between this variable and other Lumen settings for a holistic approach to lighting quality and performance.

Regarding the associated variable GLumenScreenProbeGatherAdaptiveProbeMinDownsampleFactor:

• It’s the actual integer variable that stores the value set by the console variable.
• It’s used directly in the rendering code to determine the minimum downsample factor for adaptive probe placement.
• The value is clamped using FMath::Clamp to ensure it’s within the valid range of 1 to 64.
• It’s compared against ScreenProbeParameters.ScreenProbeDownsampleFactor to determine if adaptive probe placement should occur.

When adjusting this setting, developers should consider the impact on both visual quality and performance, and test thoroughly across various scenes and hardware configurations.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:36

Scope: file

Source code excerpt:

int32 GLumenScreenProbeGatherAdaptiveProbeMinDownsampleFactor = 4;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherAdaptiveProbeMinDownsampleFactor(
	TEXT("r.Lumen.ScreenProbeGather.AdaptiveProbeMinDownsampleFactor"),
	GLumenScreenProbeGatherAdaptiveProbeMinDownsampleFactor,
	TEXT("Screen probes will be placed where needed down to this downsample factor of the GBuffer."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenScreenProbeGatherAdaptiveProbeAllocationFraction = .5f;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:34

Scope: file

Source code excerpt:

);

int32 GLumenScreenProbeGatherAdaptiveProbeMinDownsampleFactor = 4;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherAdaptiveProbeMinDownsampleFactor(
	TEXT("r.Lumen.ScreenProbeGather.AdaptiveProbeMinDownsampleFactor"),
	GLumenScreenProbeGatherAdaptiveProbeMinDownsampleFactor,
	TEXT("Screen probes will be placed where needed down to this downsample factor of the GBuffer."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenScreenProbeGatherAdaptiveProbeAllocationFraction = .5f;
FAutoConsoleVariableRef GVarAdaptiveProbeAllocationFraction(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeGather.cpp:1961

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenScreenProbeGather

Source code excerpt:

	AddClearUAVPass(GraphBuilder, GraphBuilder.CreateUAV(NumAdaptiveScreenProbes), 0, ComputePassFlags);

	const uint32 AdaptiveProbeMinDownsampleFactor = FMath::Clamp(GLumenScreenProbeGatherAdaptiveProbeMinDownsampleFactor, 1, 64);

	if (ScreenProbeParameters.MaxNumAdaptiveProbes > 0 && AdaptiveProbeMinDownsampleFactor < ScreenProbeParameters.ScreenProbeDownsampleFactor)
	{ 
		uint32 PlacementDownsampleFactor = ScreenProbeParameters.ScreenProbeDownsampleFactor;
		do
		{