r.Lumen.ScreenProbeGather.ImportanceSample.IncomingLighting

r.Lumen.ScreenProbeGather.ImportanceSample.IncomingLighting

#Overview

name: r.Lumen.ScreenProbeGather.ImportanceSample.IncomingLighting

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

• type: Var
• help: Whether to Importance Sample incoming lighting to generate probe trace directions. When disabled, only the BRDF will be importance sampled.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.ImportanceSample.IncomingLighting is to control whether incoming lighting is importance sampled when generating probe trace directions in Lumen’s screen probe gathering process. This setting is part of Unreal Engine 5’s Lumen global illumination system.

This setting variable is primarily used in the Lumen rendering subsystem, specifically in the screen probe gathering and importance sampling modules. It’s referenced in the LumenScreenProbeImportanceSampling.cpp file, which is part of the Renderer module.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 1 (enabled) and can be changed at runtime.

The associated variable GLumenScreenProbeImportanceSampleIncomingLighting directly interacts with this console variable. It holds the actual value used in the code logic.

Developers should be aware that:

1. When enabled (set to 1), both incoming lighting and BRDF will be importance sampled for generating probe trace directions.
2. When disabled (set to 0), only the BRDF will be importance sampled.
3. This setting can affect the quality and performance of global illumination in scenes using Lumen.

Best practices when using this variable:

1. Keep it enabled by default for better lighting quality.
2. Consider disabling it if performance is a concern and the loss in lighting quality is acceptable.
3. Test your scenes with both settings to find the right balance between quality and performance.

Regarding the associated variable GLumenScreenProbeImportanceSampleIncomingLighting:

• It’s an integer variable that directly reflects the value of the console variable.
• It’s used in the GenerateImportanceSamplingRays function to determine whether to create and use a LightingProbabilityDensityFunction.
• When using this variable, developers should treat it as a boolean, where any non-zero value is considered true.
• It’s important to note that changes to the console variable will be reflected in this associated variable, allowing for runtime adjustments of the importance sampling behavior.

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

Scope: file

Source code excerpt:

int32 GLumenScreenProbeImportanceSampleIncomingLighting = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeImportanceSampleIncomingLighting(
	TEXT("r.Lumen.ScreenProbeGather.ImportanceSample.IncomingLighting"),
	GLumenScreenProbeImportanceSampleIncomingLighting,
	TEXT("Whether to Importance Sample incoming lighting to generate probe trace directions.  When disabled, only the BRDF will be importance sampled."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeImportanceSampleProbeRadianceHistory = 1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenScreenProbeImportanceSampleIncomingLighting = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeImportanceSampleIncomingLighting(
	TEXT("r.Lumen.ScreenProbeGather.ImportanceSample.IncomingLighting"),
	GLumenScreenProbeImportanceSampleIncomingLighting,
	TEXT("Whether to Importance Sample incoming lighting to generate probe trace directions.  When disabled, only the BRDF will be importance sampled."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeImportanceSampleProbeRadianceHistory = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeImportanceSampleProbeRadianceHistory(

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

Scope (from outer to inner):

file
function     void GenerateImportanceSamplingRays

Source code excerpt:

	ScreenProbeParameters.ImportanceSampling.MaxImportanceSamplingOctahedronResolution = MaxImportanceSamplingOctahedronResolution;

	const bool bImportanceSampleLighting = GLumenScreenProbeImportanceSampleIncomingLighting != 0;

	FRDGTextureRef LightingProbabilityDensityFunction = nullptr;

	if (bImportanceSampleLighting)
	{
		FIntPoint LightingProbabilityDensityFunctionBufferSize = ScreenProbeParameters.ScreenProbeAtlasBufferSize * ScreenProbeParameters.ScreenProbeTracingOctahedronResolution;