r.Lumen.ScreenProbeGather.LightSampleResolutionXY

r.Lumen.ScreenProbeGather.LightSampleResolutionXY

#Overview

name: r.Lumen.ScreenProbeGather.LightSampleResolutionXY

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

• type: Var
• help: Number of light samples per screen probe, in one dimension. When the number of lights overlapping a pixel is larger, noise in the direct lighting will increase.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.LightSampleResolutionXY is to control the resolution of light samples for each screen probe in the Lumen Screen Probe Gather system. This variable is used to determine the number of light samples per screen probe in one dimension.

The Lumen Screen Probe Gather system is part of Unreal Engine 5’s global illumination solution. It relies on this setting to balance between lighting quality and performance.

Based on the code, the Lumen rendering subsystem in Unreal Engine 5 uses this variable. Specifically, it’s used in the screen probe gathering process, which is a crucial part of the Lumen global illumination system.

The value of this variable is set through the console variable system (CVarLumenScreenProbeLightSampleResolutionXY). It’s then clamped to a range between 1 and 8 and assigned to ScreenProbeParameters.ScreenProbeLightSampleResolutionXY.

This variable interacts with other screen probe parameters, such as ScreenProbeDownsampleFactor and ScreenProbeViewSize, to determine the final resolution and layout of the screen probes.

Developers should be aware that increasing this value will increase the number of light samples per probe, potentially improving lighting quality but at the cost of performance. Conversely, decreasing it may improve performance but could lead to lower quality lighting.

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 interaction with other Lumen settings, as they may affect the overall lighting quality and performance.

The associated variable GLumenScreenProbeLightSampleResolutionXY is an integer that stores the actual value of the console variable. It’s used directly in the code to set the ScreenProbeLightSampleResolutionXY parameter. This variable is initialized with a default value of 2, which means by default, each screen probe will have a 2x2 grid of light samples.

When adjusting this variable, developers should consider the impact on both the quality of lighting and the performance of the rendering system. Higher values will provide more detailed lighting information but will also increase the computational cost of the screen probe gather process.

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

Scope: file

Source code excerpt:

int32 GLumenScreenProbeLightSampleResolutionXY = 2;
FAutoConsoleVariableRef CVarLumenScreenProbeLightSampleResolutionXY(
	TEXT("r.Lumen.ScreenProbeGather.LightSampleResolutionXY"),
	GLumenScreenProbeLightSampleResolutionXY,
	TEXT("Number of light samples per screen probe, in one dimension.  When the number of lights overlapping a pixel is larger, noise in the direct lighting will increase."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeInjectLightsToProbes = 0;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenScreenProbeLightSampleResolutionXY = 2;
FAutoConsoleVariableRef CVarLumenScreenProbeLightSampleResolutionXY(
	TEXT("r.Lumen.ScreenProbeGather.LightSampleResolutionXY"),
	GLumenScreenProbeLightSampleResolutionXY,
	TEXT("Number of light samples per screen probe, in one dimension.  When the number of lights overlapping a pixel is larger, noise in the direct lighting will increase."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeInjectLightsToProbes = 0;
FAutoConsoleVariableRef CVarLumenScreenProbeInjectLightsToProbes(

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenScreenProbeGather

Source code excerpt:

	ScreenProbeParameters.ScreenProbeDownsampleFactor = LumenScreenProbeGather::GetScreenDownsampleFactor(View);

	ScreenProbeParameters.ScreenProbeLightSampleResolutionXY = FMath::Clamp<uint32>(GLumenScreenProbeLightSampleResolutionXY, 1, 8);

	ScreenProbeParameters.ScreenProbeViewSize = FIntPoint::DivideAndRoundUp(View.ViewRect.Size(), (int32)ScreenProbeParameters.ScreenProbeDownsampleFactor);
	ScreenProbeParameters.ScreenProbeAtlasViewSize = ScreenProbeParameters.ScreenProbeViewSize;
	ScreenProbeParameters.ScreenProbeAtlasViewSize.Y += FMath::TruncToInt(ScreenProbeParameters.ScreenProbeViewSize.Y * GLumenScreenProbeGatherAdaptiveProbeAllocationFraction);

	ScreenProbeParameters.ScreenProbeAtlasBufferSize = FIntPoint::DivideAndRoundUp(SceneTextures.Config.Extent, (int32)ScreenProbeParameters.ScreenProbeDownsampleFactor);