r.Lumen.Reflections.HardwareRayTracing.Translucent.MaxRefractionBounces

r.Lumen.Reflections.HardwareRayTracing.Translucent.MaxRefractionBounces

#Overview

name: r.Lumen.Reflections.HardwareRayTracing.Translucent.MaxRefractionBounces

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.HardwareRayTracing.Translucent.MaxRefractionBounces is to control the maximum number of refraction events to trace in the Lumen reflections system when using hardware ray tracing for translucent objects.

This setting variable is primarily used by the Lumen reflections subsystem within Unreal Engine’s rendering module. It specifically affects the hardware ray tracing behavior for translucent objects in reflections.

The value of this variable is set through a console variable (CVar) system, which allows it to be modified at runtime. It’s defined with a default value of 0, but can be changed through console commands or configuration files.

This variable interacts with the View.FinalPostProcessSettings.LumenMaxRefractionBounces setting. If the CVar value is set to 0 or less, the engine will use the value from LumenMaxRefractionBounces in the post-process settings instead.

Developers should be aware that this variable directly impacts rendering performance and quality. Higher values will increase the accuracy of refractions in reflections but at the cost of performance. The actual number of bounces used is always at least 1, and is clamped to a maximum of 64.

Best practices when using this variable include:

  1. Start with lower values and increase gradually to find the best balance between visual quality and performance.
  2. Consider using the post-process setting (LumenMaxRefractionBounces) for more fine-grained control per-view.
  3. Be mindful of the performance impact on different hardware configurations.

The associated variable CVarLumenReflectionsHardwareRayTracingTranslucentMaxRefractionBounces is the actual console variable that stores and provides access to this setting. It’s defined with the ECVF_Scalability and ECVF_RenderThreadSafe flags, indicating that it can be adjusted for different scalability presets and is safe to modify from the render thread.

This associated variable is used in the LumenReflections::GetMaxRefractionBounces function to determine the actual number of refraction bounces to use. The function adds 1 to the value to account for the first mandatory reflection, and clamps the result between 1 and 64.

When working with this associated variable, developers should:

  1. Access its value using GetValueOnRenderThread() to ensure thread-safety.
  2. Remember that a value of 0 or less will cause the system to fall back to the post-process setting.
  3. Be aware that the actual number of bounces used will always be at least 1 more than the value set, due to the addition in GetMaxRefractionBounces.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarLumenReflectionsHardwareRayTracingTranslucentMaxRefractionBounces(
	TEXT("r.Lumen.Reflections.HardwareRayTracing.Translucent.MaxRefractionBounces"),
	0,
	TEXT("The maximum count of refraction event to trace."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

float LumenReflections::GetSampleSceneColorNormalTreshold()

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarLumenReflectionsHardwareRayTracingTranslucentMaxRefractionBounces(
	TEXT("r.Lumen.Reflections.HardwareRayTracing.Translucent.MaxRefractionBounces"),
	0,
	TEXT("The maximum count of refraction event to trace."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     uint32 LumenReflections::GetMaxRefractionBounces

Source code excerpt:

uint32 LumenReflections::GetMaxRefractionBounces(const FViewInfo& View)
{
	int32 LumenMaxRefractionBounces = CVarLumenReflectionsHardwareRayTracingTranslucentMaxRefractionBounces.GetValueOnRenderThread();
	if (LumenMaxRefractionBounces <= 0)
	{
		LumenMaxRefractionBounces = View.FinalPostProcessSettings.LumenMaxRefractionBounces;
	}
	return FMath::Clamp(1 + LumenMaxRefractionBounces, 1, 64);	// we add one to account for the first loop in the shader that is mandatory to at least get reflection.
}