r.Lumen.ScreenProbeGather.TracingOctahedronResolution

r.Lumen.ScreenProbeGather.TracingOctahedronResolution

#Overview

name: r.Lumen.ScreenProbeGather.TracingOctahedronResolution

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.TracingOctahedronResolution is to control the resolution of the tracing octahedron in Lumen’s screen probe gathering process. This setting variable is part of Unreal Engine 5’s Lumen global illumination system, specifically for the screen probe gathering component.

This setting variable is primarily used in the Lumen rendering subsystem, which is part of Unreal Engine’s rendering module. Based on the callsites, it’s clear that this variable is used in the LumenScreenProbeGather namespace, indicating its specific role in the screen probe gathering process of Lumen.

The value of this variable is set through the Unreal Engine console variable system. It’s initialized with a default value of 8 and can be modified at runtime using console commands or through project settings.

The associated variable GLumenScreenProbeTracingOctahedronResolution directly interacts with this console variable. They share the same value, with GLumenScreenProbeTracingOctahedronResolution being the actual integer used in the code logic.

Developers should be aware that this variable determines the number of traces done per probe in the screen probe gathering process. A higher resolution will result in more accurate lighting but at the cost of increased performance overhead.

Best practices when using this variable include:

  1. Balancing between quality and performance based on the target hardware.
  2. Considering the overall scene complexity and lighting requirements.
  3. Testing different values to find the optimal setting for specific scenes or use cases.

Regarding the associated variable GLumenScreenProbeTracingOctahedronResolution:

The purpose of GLumenScreenProbeTracingOctahedronResolution is to store the actual integer value used in the Lumen screen probe tracing calculations. It’s the in-memory representation of the console variable.

This variable is used directly in the LumenScreenProbeGather namespace, specifically in the GetTracingOctahedronResolution function. It’s multiplied by a quality factor derived from the view’s final post-process settings to determine the actual tracing octahedron resolution.

The value of this variable is set by the console variable system when r.Lumen.ScreenProbeGather.TracingOctahedronResolution is modified.

Developers should be aware that this variable is clamped between 4 and 16 in actual usage, regardless of the console variable’s set value. There’s also a check to ensure the resulting resolution is supported by importance sampling.

Best practices for this variable include:

  1. Understanding its relationship with the console variable and how it’s actually used in calculations.
  2. Being aware of the clamping behavior when making adjustments to the related console variable.
  3. Considering its interaction with other quality settings, such as LumenFinalGatherQuality, when tuning performance and quality.

#Setting Variables

#References In INI files

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

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

Location: <Workspace>/Engine/Config/BaseScalability.ini:327, 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:60

Scope: file

Source code excerpt:

int32 GLumenScreenProbeTracingOctahedronResolution = 8;
FAutoConsoleVariableRef GVarLumenScreenProbeTracingOctahedronResolution(
	TEXT("r.Lumen.ScreenProbeGather.TracingOctahedronResolution"),
	GLumenScreenProbeTracingOctahedronResolution,
	TEXT("Resolution of the tracing octahedron.  Determines how many traces are done per probe."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenScreenProbeGatherOctahedronResolutionScale = 1.0f;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

int32 GLumenScreenProbeTracingOctahedronResolution = 8;
FAutoConsoleVariableRef GVarLumenScreenProbeTracingOctahedronResolution(
	TEXT("r.Lumen.ScreenProbeGather.TracingOctahedronResolution"),
	GLumenScreenProbeTracingOctahedronResolution,
	TEXT("Resolution of the tracing octahedron.  Determines how many traces are done per probe."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float GLumenScreenProbeGatherOctahedronResolutionScale = 1.0f;
FAutoConsoleVariableRef GVarLumenScreenProbeGatherOctahedronResolutionScale(

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

Scope (from outer to inner):

file
namespace    LumenScreenProbeGather
function     int32 GetTracingOctahedronResolution

Source code excerpt:

	{
		const float SqrtQuality = FMath::Sqrt(FMath::Max(View.FinalPostProcessSettings.LumenFinalGatherQuality, 0.0f));
		const int32 TracingOctahedronResolution = FMath::Clamp(FMath::RoundToInt(SqrtQuality * GLumenScreenProbeTracingOctahedronResolution), 4, 16);
		ensureMsgf(IsProbeTracingResolutionSupportedForImportanceSampling(TracingOctahedronResolution), TEXT("Tracing resolution %u requested that is not supported by importance sampling"), TracingOctahedronResolution);
		return GLumenScreenProbeGatherReferenceMode ? 32 : TracingOctahedronResolution;
	}

	int32 GetGatherOctahedronResolution(int32 TracingOctahedronResolution)
	{