r.Lumen.ScreenProbeGather.ImportanceSample

r.Lumen.ScreenProbeGather.ImportanceSample

#Overview

name: r.Lumen.ScreenProbeGather.ImportanceSample

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.ScreenProbeGather.ImportanceSample is to control whether Importance Sampling is used to generate probe trace directions in the Lumen lighting system. This setting is part of Unreal Engine 5’s global illumination solution, specifically within the Screen Probe Gather component of Lumen.

The Lumen rendering subsystem relies on this setting variable. It is used in the Screen Probe Importance Sampling module, which is part of the larger Lumen global illumination system.

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 modified at runtime through console commands or project settings.

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

Developers should be aware that this variable affects the quality and performance of the Lumen global illumination system. Enabling importance sampling can potentially improve the quality of lighting calculations but may also impact performance.

Best practices when using this variable include:

  1. Testing the impact on both visual quality and performance when enabling or disabling it.
  2. Considering the target hardware capabilities, as importance sampling may be more beneficial on higher-end systems.
  3. Using it in conjunction with other Lumen settings to achieve the desired balance between quality and performance.

Regarding the associated variable GLumenScreenProbeImportanceSampling:

The purpose of GLumenScreenProbeImportanceSampling is to serve as the actual integer value that controls whether importance sampling is used in the Lumen Screen Probe Gather process.

It is used directly in the Lumen rendering subsystem, specifically in the Screen Probe Importance Sampling module.

The value of this variable is set through the console variable system, mirroring the value of r.Lumen.ScreenProbeGather.ImportanceSample.

It interacts directly with the UseImportanceSampling function, which determines whether importance sampling should be applied based on the value of GLumenScreenProbeImportanceSampling and other conditions.

Developers should be aware that this variable is used in performance-critical rendering code, and its value can significantly impact the behavior of the Lumen system.

Best practices include:

  1. Avoiding direct modification of GLumenScreenProbeImportanceSampling in code, instead using the console variable system to ensure consistency.
  2. Considering the impact on different hardware configurations when deciding whether to enable or disable importance sampling.
  3. Profiling the performance impact of enabling this feature in various scenarios to make informed decisions about its usage.

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

Scope: file

Source code excerpt:

int32 GLumenScreenProbeImportanceSampling = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherImportanceSampling(
	TEXT("r.Lumen.ScreenProbeGather.ImportanceSample"),
	GLumenScreenProbeImportanceSampling,
	TEXT("Whether to use Importance Sampling to generate probe trace directions."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeImportanceSamplingNumLevels = 1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

#include "DistanceFieldAmbientOcclusion.h"

int32 GLumenScreenProbeImportanceSampling = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherImportanceSampling(
	TEXT("r.Lumen.ScreenProbeGather.ImportanceSample"),
	GLumenScreenProbeImportanceSampling,
	TEXT("Whether to use Importance Sampling to generate probe trace directions."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenScreenProbeImportanceSamplingNumLevels = 1;
FAutoConsoleVariableRef GVarLumenScreenProbeImportanceSamplingNumLevels(

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

Scope (from outer to inner):

file
namespace    LumenScreenProbeGather
function     bool UseImportanceSampling

Source code excerpt:

		// Shader permutations only created for these resolutions
		const int32 TracingResolution = GetTracingOctahedronResolution(View);
		return GLumenScreenProbeImportanceSampling != 0 && IsProbeTracingResolutionSupportedForImportanceSampling(TracingResolution);
	}
}

void GenerateBRDF_PDF(
	FRDGBuilder& GraphBuilder, 
	const FViewInfo& View,