r.Lumen.IrradianceFieldGather

r.Lumen.IrradianceFieldGather

#Overview

name: r.Lumen.IrradianceFieldGather

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

• type: Var
• help: Whether to use the Irradiance Field Final Gather, an experimental opaque final gather that interpolates from pre-calculated irradiance in probes for cheaper, but lower quality GI.

It is referenced in 8 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.IrradianceFieldGather is to control the usage of the Irradiance Field Final Gather in Unreal Engine 5’s Lumen global illumination system. This is an experimental feature that interpolates pre-calculated irradiance in probes to provide cheaper, but lower quality global illumination.

This setting variable is primarily used in the Lumen subsystem of Unreal Engine’s rendering module. It’s specifically related to the global illumination and final gathering processes within Lumen.

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

The main associated variable is GLumenIrradianceFieldGather, which directly shares the value set by r.Lumen.IrradianceFieldGather. This internal variable is used throughout the codebase to check whether the Irradiance Field Final Gather should be used.

Developers should be aware that:

1. This is an experimental feature, so it may not be fully optimized or bug-free.
2. Enabling this feature will result in cheaper but lower quality global illumination.
3. It affects the rendering pipeline, specifically the final gathering stage of Lumen.

Best practices when using this variable include:

1. Testing the visual quality and performance impact when enabling or disabling this feature.
2. Using it in conjunction with other Lumen settings to find the best balance between performance and visual quality.
3. Being cautious about enabling it in production builds due to its experimental nature.

Regarding the associated variable GLumenIrradianceFieldGather:

• It’s an internal representation of the console variable.
• It’s used in various parts of the Lumen system to conditionally execute code related to the Irradiance Field Final Gather.
• Developers should not modify this variable directly, but instead use the console variable r.Lumen.IrradianceFieldGather to control its value.
• It’s used in conditions to determine whether to render certain lighting effects or use specific gathering techniques.

When working with GLumenIrradianceFieldGather, developers should be aware that changing its value can have wide-ranging effects on the rendering pipeline, particularly in how global illumination is calculated and applied.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenIrradianceFieldGather.cpp:15

Scope: file

Source code excerpt:

int32 GLumenIrradianceFieldGather = 0;
FAutoConsoleVariableRef CVarLumenIrradianceFieldGather(
	TEXT("r.Lumen.IrradianceFieldGather"),
	GLumenIrradianceFieldGather,
	TEXT("Whether to use the Irradiance Field Final Gather, an experimental opaque final gather that interpolates from pre-calculated irradiance in probes for cheaper, but lower quality GI."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenIrradianceFieldNumClipmaps = 4;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenDiffuseIndirect.cpp:284

Scope (from outer to inner):

file
function     bool ShouldRenderLumenDirectLighting

Source code excerpt:

	return ShouldRenderLumenDiffuseGI(Scene, View)
		&& GLumenGatherCvars.DirectLighting
		&& !GLumenIrradianceFieldGather;
}

bool ShouldRenderAOWithLumenGI()
{
	extern int32 GLumenShortRangeAmbientOcclusion;
	return GLumenDiffuseIndirectApplySSAO != 0 && GLumenShortRangeAmbientOcclusion == 0;

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenIrradianceFieldGather.cpp:13

Scope: file

Source code excerpt:

#include "LumenReflections.h"

int32 GLumenIrradianceFieldGather = 0;
FAutoConsoleVariableRef CVarLumenIrradianceFieldGather(
	TEXT("r.Lumen.IrradianceFieldGather"),
	GLumenIrradianceFieldGather,
	TEXT("Whether to use the Irradiance Field Final Gather, an experimental opaque final gather that interpolates from pre-calculated irradiance in probes for cheaper, but lower quality GI."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

int32 GLumenIrradianceFieldNumClipmaps = 4;
FAutoConsoleVariableRef CVarLumenIrradianceFieldNumClipmaps(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenIrradianceFieldGather.cpp:255

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenIrradianceFieldGather

Source code excerpt:

	RDG_GPU_STAT_SCOPE(GraphBuilder, LumenIrradianceFieldGather);

	check(GLumenIrradianceFieldGather != 0);

	const LumenRadianceCache::FRadianceCacheInputs RadianceCacheInputs = LumenIrradianceFieldGather::SetupRadianceCacheInputs();

	FMarkUsedRadianceCacheProbes Callbacks;
	Callbacks.AddLambda([&SceneTextures, ComputePassFlags](
		FRDGBuilder& GraphBuilder,

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenFinalGather

Source code excerpt:

	LumenRadianceCache::FRadianceCacheInterpolationParameters TranslucencyVolumeRadianceCacheParameters;

	if (GLumenIrradianceFieldGather != 0)
	{
		Outputs = RenderLumenIrradianceFieldGather(GraphBuilder, SceneTextures, FrameTemporaries, View, TranslucencyVolumeRadianceCacheParameters, ComputePassFlags);
	}
	else if (Lumen::UseReSTIRGather(*View.Family, ShaderPlatform))
	{
		Outputs = RenderLumenReSTIRGather(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenTracingUtils.h:184

Scope: file

Source code excerpt:

	bool bBindLumenHistory = true);

extern int32 GLumenIrradianceFieldGather;

namespace LumenIrradianceFieldGather
{
	LumenRadianceCache::FRadianceCacheInputs SetupRadianceCacheInputs();
}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualize.cpp:718

Scope (from outer to inner):

file
function     LumenRadianceCache::FRadianceCacheInputs GetFinalGatherRadianceCacheInputsForVisualize

Source code excerpt:

LumenRadianceCache::FRadianceCacheInputs GetFinalGatherRadianceCacheInputsForVisualize(const FViewInfo& View)
{
	if (GLumenIrradianceFieldGather)
	{
		return LumenIrradianceFieldGather::SetupRadianceCacheInputs();
	}
	else
	{
		return LumenScreenProbeGatherRadianceCache::SetupRadianceCacheInputs(View);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenVisualizeRadianceCache.cpp:115

Scope: file

Source code excerpt:

	else
	{
		if (GLumenIrradianceFieldGather)
		{
			return LumenIrradianceFieldGather::SetupRadianceCacheInputs();
		}
		else
		{
			return LumenScreenProbeGatherRadianceCache::SetupRadianceCacheInputs(View);