r.Lumen.ScreenProbeGather.IrradianceFormat

r.Lumen.ScreenProbeGather.IrradianceFormat

#Overview

name: r.Lumen.ScreenProbeGather.IrradianceFormat

The value of this variable can be defined or overridden in .ini config files. 3 .ini config files referencing this setting variable.

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.IrradianceFormat is to control the prefilter irradiance format used in Lumen’s screen probe gathering process. This setting variable is part of Unreal Engine 5’s Lumen global illumination system, specifically the screen probe gathering component.

The Lumen subsystem within the Renderer module relies on this setting variable. It’s used in the LumenScreenProbeGather namespace, which suggests it’s specific to the screen probe gathering process in Lumen.

The value of this variable is set through the console variable system (CVarLumenScreenProbeIrradianceFormat). It’s initialized with a default value of 1, but can be changed at runtime.

This variable interacts with GLumenScreenProbeIrradianceFormat, which is the actual integer variable that stores the setting value. They share the same value, with r.Lumen.ScreenProbeGather.IrradianceFormat being the console-accessible name.

Developers must be aware that this variable has two possible values: 0 - SH3 (Spherical Harmonics 3), which is slower 1 - Octahedral probe, which is faster but reverts to SH3 when ShortRangeAO.ApplyDuringIntegration is enabled

The best practices when using this variable include:

  1. Use the octahedral probe (value 1) for better performance in most cases.
  2. Consider using SH3 (value 0) if you need higher quality and performance is not a critical issue.
  3. Be aware that when using the octahedral probe, it may revert to SH3 under certain conditions (when ShortRangeAO.ApplyDuringIntegration is enabled).
  4. Use this variable in conjunction with other Lumen settings to fine-tune the balance between performance and quality.

Regarding the associated variable GLumenScreenProbeIrradianceFormat:

The purpose of GLumenScreenProbeIrradianceFormat is to store the actual integer value of the irradiance format setting. It’s the backend variable that r.Lumen.ScreenProbeGather.IrradianceFormat modifies.

This variable is used directly in the LumenScreenProbeGather namespace, specifically in the GetScreenProbeIrradianceFormat function. This function returns the current irradiance format as an enum value, clamped between 0 and 1.

The value of GLumenScreenProbeIrradianceFormat is set initially to 1 and can be modified through the r.Lumen.ScreenProbeGather.IrradianceFormat console variable.

Developers should be aware that this variable is used directly in the code to determine the irradiance format, so changing r.Lumen.ScreenProbeGather.IrradianceFormat will affect the behavior of functions that use GLumenScreenProbeIrradianceFormat.

Best practices for GLumenScreenProbeIrradianceFormat include:

  1. Don’t modify this variable directly in code; instead, use the r.Lumen.ScreenProbeGather.IrradianceFormat console variable to change its value.
  2. When reading this variable in code, consider using the GetScreenProbeIrradianceFormat function, which applies proper clamping to the value.
  3. Be aware of the performance and quality implications of the chosen format when using this variable in rendering code.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseScalability.ini:281, section: [GlobalIlluminationQuality@2]

Location: <Workspace>/Engine/Config/BaseScalability.ini:304, section: [GlobalIlluminationQuality@3]

Location: <Workspace>/Engine/Config/BaseScalability.ini:328, section: [GlobalIlluminationQuality@Cine]

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

Scope: file

Source code excerpt:

int32 GLumenScreenProbeIrradianceFormat = 1;
FAutoConsoleVariableRef CVarLumenScreenProbeIrradianceFormat(
	TEXT("r.Lumen.ScreenProbeGather.IrradianceFormat"),
	GLumenScreenProbeIrradianceFormat,
	TEXT("Prefilter irradiance format\n")
	TEXT("0 - SH3 slower\n")
	TEXT("1 - Octahedral probe. Faster, but reverts to SH3 when ShortRangeAO.ApplyDuringIntegration is enabled"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	);

int32 GLumenScreenProbeIrradianceFormat = 1;
FAutoConsoleVariableRef CVarLumenScreenProbeIrradianceFormat(
	TEXT("r.Lumen.ScreenProbeGather.IrradianceFormat"),
	GLumenScreenProbeIrradianceFormat,
	TEXT("Prefilter irradiance format\n")
	TEXT("0 - SH3 slower\n")
	TEXT("1 - Octahedral probe. Faster, but reverts to SH3 when ShortRangeAO.ApplyDuringIntegration is enabled"),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
namespace    LumenScreenProbeGather
function     EScreenProbeIrradianceFormat GetScreenProbeIrradianceFormat

Source code excerpt:

		}

		return (EScreenProbeIrradianceFormat)FMath::Clamp(GLumenScreenProbeIrradianceFormat, 0, 1);
	}

	float GetScreenProbeFullResolutionJitterWidth(const FViewInfo& View)
	{
		return GLumenScreenProbeFullResolutionJitterWidth * (View.FinalPostProcessSettings.LumenFinalGatherQuality >= 4.0f ? .5f : 1.0f);
	}