r.Lumen.ScreenProbeGather.DownsampleFactor

r.Lumen.ScreenProbeGather.DownsampleFactor

#Overview

name: r.Lumen.ScreenProbeGather.DownsampleFactor

The value of this variable can be defined or overridden in .ini config files. 3 .ini config files referencing this setting variable.

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

• type: Var
• help: Pixel size of the screen tile that a screen probe will be placed on.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.DownsampleFactor is to control the pixel size of the screen tile on which a screen probe will be placed in Lumen’s screen probe gather system. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically the screen probe gathering process.

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 used within the LumenScreenProbeGather namespace, which is part of the rendering system responsible for global illumination calculations.

The value of this variable is set through the Unreal Engine console variable system. It’s defined as an FAutoConsoleVariableRef, which means it can be adjusted at runtime through console commands or configuration files.

The associated variable GLumenScreenProbeDownsampleFactor interacts directly with r.Lumen.ScreenProbeGather.DownsampleFactor. They share the same value, with GLumenScreenProbeDownsampleFactor being the actual integer variable used in the C++ code.

Developers should be aware that this variable affects the performance and quality trade-off in Lumen’s global illumination system. A higher downsample factor means larger screen tiles, which can improve performance but may reduce the accuracy of lighting calculations.

Best practices when using this variable include:

1. Adjusting it based on the target hardware and desired performance/quality balance.
2. Testing different values to find the optimal setting for your specific scene.
3. Considering the relationship between this setting and other Lumen quality settings.

Regarding GLumenScreenProbeDownsampleFactor:

• It’s the C++ variable that directly controls the downsample factor in the code.
• It’s initialized with a default value of 16.
• It’s used in the GetScreenDownsampleFactor function, where it’s further modified based on the LumenFinalGatherQuality setting.
• The final value is clamped between 4 and 64, ensuring it stays within a reasonable range.
• Developers should note that very high-quality settings (LumenFinalGatherQuality >= 6.0f) will effectively halve the downsample factor, potentially improving quality at the cost of performance.

When working with both variables, developers should remember that changing r.Lumen.ScreenProbeGather.DownsampleFactor through console commands or configuration will directly affect GLumenScreenProbeDownsampleFactor in the code.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseScalability.ini:279, section: [GlobalIlluminationQuality@2]

• INI Section: GlobalIlluminationQuality@2
• Raw value: 32
• Is Array: False

Location: <Workspace>/Engine/Config/BaseScalability.ini:302, section: [GlobalIlluminationQuality@3]

• INI Section: GlobalIlluminationQuality@3
• Raw value: 16
• Is Array: False

Location: <Workspace>/Engine/Config/BaseScalability.ini:326, section: [GlobalIlluminationQuality@Cine]

• INI Section: GlobalIlluminationQuality@Cine
• Raw value: 8
• Is Array: False

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

Scope: file

Source code excerpt:

int32 GLumenScreenProbeDownsampleFactor = 16;
FAutoConsoleVariableRef GVarLumenScreenProbeDownsampleFactor(
	TEXT("r.Lumen.ScreenProbeGather.DownsampleFactor"),
	GLumenScreenProbeDownsampleFactor,
	TEXT("Pixel size of the screen tile that a screen probe will be placed on."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

FAutoConsoleVariableRef CVarLumenScreenProbeGatherDirectLighting(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenScreenProbeDownsampleFactor = 16;
FAutoConsoleVariableRef GVarLumenScreenProbeDownsampleFactor(
	TEXT("r.Lumen.ScreenProbeGather.DownsampleFactor"),
	GLumenScreenProbeDownsampleFactor,
	TEXT("Pixel size of the screen tile that a screen probe will be placed on."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

FAutoConsoleVariableRef CVarLumenScreenProbeGatherDirectLighting(
	TEXT("r.Lumen.ScreenProbeGather.DirectLighting"),

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

Scope (from outer to inner):

file
namespace    LumenScreenProbeGather
function     int32 GetScreenDownsampleFactor

Source code excerpt:

		}

		return FMath::Clamp(GLumenScreenProbeDownsampleFactor / (View.FinalPostProcessSettings.LumenFinalGatherQuality >= 6.0f ? 2 : 1), 4, 64);
	}

	bool UseShortRangeAmbientOcclusion(const FEngineShowFlags& ShowFlags)
	{
		return GLumenScreenProbeGatherReferenceMode ? false : (GLumenShortRangeAmbientOcclusion != 0 && ShowFlags.LumenShortRangeAmbientOcclusion);
	}