r.Lumen.Reflections.MaxBounces

r.Lumen.Reflections.MaxBounces

#Overview

name: r.Lumen.Reflections.MaxBounces

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.Reflections.MaxBounces is to control the maximum number of recursive reflection bounces in the Lumen global illumination system of Unreal Engine 5. This setting is specifically for the rendering system, particularly for the reflection component of Lumen.

This setting variable is primarily used by the Lumen reflection tracing subsystem within the Renderer module of Unreal Engine 5. It’s particularly relevant for Hardware Ray Tracing with Hit Lighting.

The value of this variable is set through a console variable (CVar) system. It can be modified at runtime or set in configuration files. The default value is 0, which means it defers to the Post Process Volume settings.

This variable interacts with the Post Process Volume settings. When set to a value greater than 0, it overrides the LumenMaxReflectionBounces setting in the Post Process Volume.

Developers must be aware that:

  1. This setting is only fully supported with Hardware Ray Tracing and Hit Lighting.
  2. A value of 1 means a single reflection ray, with no secondary reflections in mirrors.
  3. The actual number of bounces is clamped between 1 and 64.

Best practices when using this variable include:

  1. Use it to fine-tune performance vs. visual quality, as higher values will increase rendering cost.
  2. Consider the hardware capabilities of your target platforms, as ray tracing is computationally expensive.
  3. Use in conjunction with other Lumen settings for optimal results.

Regarding the associated variable CVarLumenReflectionsMaxBounces:

This is the actual console variable that stores and manages the r.Lumen.Reflections.MaxBounces setting. It’s defined as a TAutoConsoleVariable, which means it’s an integer value that can be changed at runtime.

The purpose of CVarLumenReflectionsMaxBounces is to provide a programmatic interface to the r.Lumen.Reflections.MaxBounces setting within the engine’s code.

This variable is used in the LumenReflections::GetMaxReflectionBounces function to determine the actual number of reflection bounces to use. If the CVar is set to 0 or less, the function falls back to the View’s FinalPostProcessSettings.LumenMaxReflectionBounces value.

Developers should be aware that changes to this CVar will take effect on the render thread, as indicated by the ECVF_RenderThreadSafe flag in its definition.

Best practices for using CVarLumenReflectionsMaxBounces include:

  1. Use GetValueOnRenderThread() when accessing its value in render thread code.
  2. Remember that changes to this variable will override Post Process Volume settings when set to values greater than 0.
  3. Consider exposing this setting in your game’s graphics options menu to allow users to balance visual quality and performance.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflectionTracing.cpp:133

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarLumenReflectionsMaxBounces(
	TEXT("r.Lumen.Reflections.MaxBounces"),
	0,
	TEXT("Sets the maximum number of recursive reflection bounces. Values above 0 override Post Process Volume settings. 1 means a single reflection ray (no secondary reflections in mirrors). Currently only supported by Hardware Ray Tracing with Hit Lighting."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarLumenReflectionsVisualizeTraces(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflectionTracing.cpp:132

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarLumenReflectionsMaxBounces(
	TEXT("r.Lumen.Reflections.MaxBounces"),
	0,
	TEXT("Sets the maximum number of recursive reflection bounces. Values above 0 override Post Process Volume settings. 1 means a single reflection ray (no secondary reflections in mirrors). Currently only supported by Hardware Ray Tracing with Hit Lighting."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflectionTracing.cpp:161

Scope (from outer to inner):

file
function     uint32 LumenReflections::GetMaxReflectionBounces

Source code excerpt:

uint32 LumenReflections::GetMaxReflectionBounces(const FViewInfo& View)
{
	int32 MaxBounces = CVarLumenReflectionsMaxBounces.GetValueOnRenderThread();
	if (MaxBounces <= 0)
	{
		MaxBounces = View.FinalPostProcessSettings.LumenMaxReflectionBounces;
	}
	return FMath::Clamp(MaxBounces, 1, 64);
}