r.Lumen.Reflections.MaxRoughnessToTrace

r.Lumen.Reflections.MaxRoughnessToTrace

#Overview

name: r.Lumen.Reflections.MaxRoughnessToTrace

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.MaxRoughnessToTrace is to control the maximum roughness value for which Lumen will trace dedicated reflection rays in the rendering system. This setting is part of Unreal Engine 5’s Lumen global illumination system, specifically for the reflection component.

This setting variable is primarily used in the Lumen Reflections subsystem of Unreal Engine’s rendering module. Based on the callsites, it’s implemented in the LumenReflections.cpp file, which is part of the Renderer module.

The value of this variable is set through a console variable (CVarLumenReflectionMaxRoughnessToTrace) with a default value of -1.0f. It can be modified at runtime through console commands or programmatically.

This variable interacts with the Post Process Volume settings. When set to a value greater than or equal to 0, it overrides the Post Process Volume settings for the maximum roughness to trace.

Developers must be aware that:

  1. The default value (-1.0f) means it doesn’t override Post Process Volume settings.
  2. Setting this value affects performance and visual quality. Higher values allow for more accurate reflections on rougher surfaces but at a higher computational cost.
  3. This setting is render thread safe, meaning it can be changed during runtime without causing thread-related issues.

Best practices when using this variable include:

  1. Use it to fine-tune reflection quality vs. performance trade-offs.
  2. Consider the target hardware when adjusting this value, as higher values may impact performance on less powerful systems.
  3. Test thoroughly with different values to find the optimal balance between visual quality and performance for your specific use case.

Regarding the associated variable CVarLumenReflectionMaxRoughnessToTrace:

This is the actual console variable that controls the r.Lumen.Reflections.MaxRoughnessToTrace setting. It’s defined using TAutoConsoleVariable, which allows it to be modified at runtime.

The purpose of this variable is the same as r.Lumen.Reflections.MaxRoughnessToTrace, as it’s the implementation of that setting.

It’s used in the LumenReflections::SetupCompositeParameters function to set the MaxRoughnessToTrace parameter when its value is greater than or equal to 0.

Developers should be aware that this variable is checked on the render thread (GetValueOnRenderThread()), which ensures thread-safe access to its value.

Best practices for this variable are the same as for r.Lumen.Reflections.MaxRoughnessToTrace, as they represent the same setting. Additionally, when modifying this value programmatically, ensure it’s done in a thread-safe manner, preferably through the appropriate Unreal Engine functions for modifying console variables.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflections.cpp:67

Scope: file

Source code excerpt:


TAutoConsoleVariable<float> CVarLumenReflectionMaxRoughnessToTrace(
	TEXT("r.Lumen.Reflections.MaxRoughnessToTrace"),
	-1.0f,
	TEXT("Max roughness value for which Lumen still traces dedicated reflection rays. Overrides Post Process Volume settings when set to anything >= 0."),
	ECVF_RenderThreadSafe
);

TAutoConsoleVariable<float> CVarLumenReflectionMaxRoughnessToTraceClamp(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflections.cpp:66

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<float> CVarLumenReflectionMaxRoughnessToTrace(
	TEXT("r.Lumen.Reflections.MaxRoughnessToTrace"),
	-1.0f,
	TEXT("Max roughness value for which Lumen still traces dedicated reflection rays. Overrides Post Process Volume settings when set to anything >= 0."),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenReflections.cpp:320

Scope (from outer to inner):

file
function     void LumenReflections::SetupCompositeParameters

Source code excerpt:

	OutParameters.MaxRoughnessToTraceForFoliage = CVarLumenReflectionsMaxRoughnessToTraceForFoliage.GetValueOnRenderThread();

	if (CVarLumenReflectionMaxRoughnessToTrace.GetValueOnRenderThread() >= 0.0f)
	{
		OutParameters.MaxRoughnessToTrace = CVarLumenReflectionMaxRoughnessToTrace.GetValueOnRenderThread();
	}
}

TRefCountPtr<FRDGPooledBuffer> GVisualizeReflectionTracesData;

FRDGBufferRef SetupVisualizeReflectionTraces(FRDGBuilder& GraphBuilder, FLumenReflectionsVisualizeTracesParameters& VisualizeTracesParameters)