r.Lumen.ScreenProbeGather.Temporal.MaxRayDirections

r.Lumen.ScreenProbeGather.Temporal.MaxRayDirections

#Overview

name: r.Lumen.ScreenProbeGather.Temporal.MaxRayDirections

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.Temporal.MaxRayDirections is to control the number of possible random directions per pixel in Lumen’s Screen Probe Gather process. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically for the temporal aspect of screen probe gathering.

This setting variable is primarily used in the Lumen subsystem, which is part of Unreal Engine 5’s rendering module. Based on the callsites, it’s clear that this variable is utilized in the LumenScreenProbeGather.cpp file, which is responsible for handling screen probe gathering in the Lumen global illumination system.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 8, but can be changed at runtime or through configuration files.

This variable interacts closely with the MaxFramesAccumulated setting, as indicated by the comment in the source code. Developers should be aware that adjusting this value may require tweaking the MaxFramesAccumulated setting as well for optimal results.

When using this variable, developers should consider the following:

  1. Higher values will increase the variety of ray directions, potentially improving image quality at the cost of performance.
  2. The value should be balanced with MaxFramesAccumulated for best results.
  3. The actual value used is clamped between 1 and 128, as seen in the usage code.

Best practices for using this variable include:

  1. Start with the default value (8) and adjust based on visual quality and performance needs.
  2. Monitor performance impact when increasing this value, especially on lower-end hardware.
  3. Consider the interaction with other Lumen settings, particularly MaxFramesAccumulated.

Regarding the associated variable CVarLumenScreenProbeTemporalMaxRayDirections:

This is the actual console variable object that controls the r.Lumen.ScreenProbeGather.Temporal.MaxRayDirections setting. It’s defined using the TAutoConsoleVariable template, which allows it to be adjusted at runtime.

The purpose of this variable is the same as r.Lumen.ScreenProbeGather.Temporal.MaxRayDirections, as they represent the same setting in different forms.

This variable is used directly in the code to retrieve the current value of the setting, as seen in the RenderLumenScreenProbeGather function.

When working with this variable, developers should be aware that:

  1. It’s marked with ECVF_Scalability and ECVF_RenderThreadSafe flags, indicating it’s safe to modify on the render thread and can be used for scalability settings.
  2. The GetValueOnRenderThread() method should be used to retrieve its value safely in render thread code.

Best practices for using this variable include:

  1. Use the console command system to adjust this value for testing and debugging.
  2. Consider exposing this setting in user-facing graphics options for performance scaling.
  3. When reading the value in code, always use GetValueOnRenderThread() to ensure thread safety.

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

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarLumenScreenProbeTemporalMaxRayDirections(
	TEXT("r.Lumen.ScreenProbeGather.Temporal.MaxRayDirections"),
	8,
	TEXT("Number of possible random directions per pixel. Should be tweaked based on MaxFramesAccumulated."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

float GLumenScreenProbeTemporalHistoryNormalThreshold = 45.0f;
FAutoConsoleVariableRef CVarLumenScreenProbeTemporalHistoryNormalThreshold(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	);

TAutoConsoleVariable<int32> CVarLumenScreenProbeTemporalMaxRayDirections(
	TEXT("r.Lumen.ScreenProbeGather.Temporal.MaxRayDirections"),
	8,
	TEXT("Number of possible random directions per pixel. Should be tweaked based on MaxFramesAccumulated."),
	ECVF_Scalability | ECVF_RenderThreadSafe);

float GLumenScreenProbeTemporalHistoryNormalThreshold = 45.0f;

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

Scope (from outer to inner):

file
function     FSSDSignalTextures FDeferredShadingSceneRenderer::RenderLumenScreenProbeGather

Source code excerpt:

		StateFrameIndex = ScreenProbeParameters.FixedJitterIndex;
	}
	ScreenProbeParameters.ScreenProbeRayDirectionFrameIndex = StateFrameIndex % FMath::Clamp(CVarLumenScreenProbeTemporalMaxRayDirections.GetValueOnRenderThread(), 1, 128);

	FRDGTextureDesc DownsampledDepthDesc(FRDGTextureDesc::Create2D(ScreenProbeParameters.ScreenProbeAtlasBufferSize, PF_R32_UINT, FClearValueBinding::Black, TexCreate_ShaderResource | TexCreate_UAV));
	ScreenProbeParameters.ScreenProbeSceneDepth = GraphBuilder.CreateTexture(DownsampledDepthDesc, TEXT("Lumen.ScreenProbeGather.ScreenProbeSceneDepth"));

	FRDGTextureDesc DownsampledNormalDesc(FRDGTextureDesc::Create2D(ScreenProbeParameters.ScreenProbeAtlasBufferSize, PF_R8G8, FClearValueBinding::Black, TexCreate_ShaderResource | TexCreate_UAV));
	ScreenProbeParameters.ScreenProbeWorldNormal = GraphBuilder.CreateTexture(DownsampledNormalDesc, TEXT("Lumen.ScreenProbeGather.ScreenProbeWorldNormal"));