r.Lumen.ScreenProbeGather.ImportanceSample.NumLevels

r.Lumen.ScreenProbeGather.ImportanceSample.NumLevels

#Overview

name: r.Lumen.ScreenProbeGather.ImportanceSample.NumLevels

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

• type: Var
• help: Number of refinement levels to use for screen probe importance sampling. Currently only supported by the serial reference path in ScreenProbeGenerateRaysCS.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.ImportanceSample.NumLevels is to control the number of refinement levels used for screen probe importance sampling in the Lumen global illumination system of Unreal Engine 5.

This setting variable is primarily used in the Lumen rendering system, specifically for screen probe gathering and importance sampling. It’s part of the Renderer module in Unreal Engine 5.

The value of this variable is set through the console variable system, as indicated by the FAutoConsoleVariableRef declaration. It can be modified at runtime or set in configuration files.

The associated variable GLumenScreenProbeImportanceSamplingNumLevels directly interacts with it, sharing the same value. This internal variable is used in the C++ code to determine the maximum octahedron resolution for importance sampling.

Developers should be aware that:

1. This variable affects the quality and performance of screen probe importance sampling.
2. It’s currently only supported by the serial reference path in ScreenProbeGenerateRaysCS.
3. Increasing the number of levels will increase the resolution and potentially the quality of importance sampling, but at the cost of performance.

Best practices when using this variable include:

1. Adjusting it based on the specific needs of your project, balancing quality and performance.
2. Testing different values to find the optimal setting for your scene.
3. Considering the impact on performance, especially on lower-end hardware.

Regarding the associated variable GLumenScreenProbeImportanceSamplingNumLevels:

• Its purpose is to store the actual value used in the C++ code for importance sampling calculations.
• It’s used to calculate the MaxImportanceSamplingOctahedronResolution, which affects the resolution of the importance sampling.
• The value is set directly from the console variable.
• Developers should be aware that modifying this variable directly in code (rather than through the console variable) could lead to inconsistencies.
• Best practice is to always use the console variable to modify this value, ensuring consistency between the console variable and the internal C++ variable.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeImportanceSampling.cpp:24

Scope: file

Source code excerpt:

int32 GLumenScreenProbeImportanceSamplingNumLevels = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeImportanceSamplingNumLevels(
	TEXT("r.Lumen.ScreenProbeGather.ImportanceSample.NumLevels"),
	GLumenScreenProbeImportanceSamplingNumLevels,
	TEXT("Number of refinement levels to use for screen probe importance sampling.  Currently only supported by the serial reference path in ScreenProbeGenerateRaysCS."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeImportanceSampleIncomingLighting = 1;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeImportanceSampling.cpp:22

Scope: file

Source code excerpt:

);

int32 GLumenScreenProbeImportanceSamplingNumLevels = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeImportanceSamplingNumLevels(
	TEXT("r.Lumen.ScreenProbeGather.ImportanceSample.NumLevels"),
	GLumenScreenProbeImportanceSamplingNumLevels,
	TEXT("Number of refinement levels to use for screen probe importance sampling.  Currently only supported by the serial reference path in ScreenProbeGenerateRaysCS."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeImportanceSampleIncomingLighting = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeImportanceSampleIncomingLighting(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenScreenProbeImportanceSampling.cpp:294

Scope (from outer to inner):

file
function     void GenerateImportanceSamplingRays

Source code excerpt:

	ERDGPassFlags ComputePassFlags)
{
	const uint32 MaxImportanceSamplingOctahedronResolution = ScreenProbeParameters.ScreenProbeTracingOctahedronResolution * (1 << GLumenScreenProbeImportanceSamplingNumLevels);
	ScreenProbeParameters.ImportanceSampling.MaxImportanceSamplingOctahedronResolution = MaxImportanceSamplingOctahedronResolution;

	const bool bImportanceSampleLighting = GLumenScreenProbeImportanceSampleIncomingLighting != 0;

	FRDGTextureRef LightingProbabilityDensityFunction = nullptr;