r.Lumen.HardwareRayTracing

r.Lumen.HardwareRayTracing

#Overview

name: r.Lumen.HardwareRayTracing

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

This variable is created as a Console Variable (cvar).

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Lumen.HardwareRayTracing is to control the usage of Hardware Ray Tracing for Lumen features in Unreal Engine 5. It is primarily used for the rendering system, specifically for the Lumen global illumination system.

This setting variable is relied upon by the Renderer module, particularly in the Lumen subsystem. It’s used to determine whether Hardware Ray Tracing should be employed for Lumen features when available.

The value of this variable is set through the console variable system in Unreal Engine. It’s defined as a TAutoConsoleVariable with an initial value of 0, meaning it’s disabled by default.

The variable interacts closely with other ray tracing and Lumen-related variables, such as r.LumenScene.FarField. It’s also checked alongside hardware capabilities like GRHISupportsRayTracingShaders and GRHISupportsInlineRayTracing.

Developers must be aware that enabling Hardware Ray Tracing for Lumen can have significant performance implications, especially for scenes with more than 100,000 instances. The comment in the code explicitly warns about these scene update costs.

Best practices when using this variable include:

  1. Only enable it when targeting hardware that supports ray tracing.
  2. Be cautious when enabling it for scenes with a large number of instances.
  3. Test performance thoroughly when enabled, as it can have a significant impact.
  4. Consider the trade-off between visual quality and performance.

Regarding the associated variable CVarLumenUseHardwareRayTracing:

The purpose of CVarLumenUseHardwareRayTracing is to serve as the internal representation of the r.Lumen.HardwareRayTracing console variable. It’s used within the engine code to check the current state of the Hardware Ray Tracing setting for Lumen.

This variable is primarily used in the Renderer module, specifically in the Lumen subsystem’s implementation.

The value of CVarLumenUseHardwareRayTracing is set automatically by the console variable system when r.Lumen.HardwareRayTracing is modified.

It interacts directly with the Lumen::UseHardwareRayTracing function, which checks this variable along with other conditions to determine if Hardware Ray Tracing should be used.

Developers should be aware that this is an internal variable and should generally not be accessed directly. Instead, they should use the r.Lumen.HardwareRayTracing console variable to control this setting.

Best practices for this variable are similar to those for r.Lumen.HardwareRayTracing, as they represent the same setting. The main difference is that CVarLumenUseHardwareRayTracing is used internally by the engine code, while r.Lumen.HardwareRayTracing is the external-facing console variable.

#Setting Variables

#References In INI files

Location: <Workspace>/Projects/Lyra/Config/DefaultEngine.ini:123, section: [/Script/Engine.RendererSettings]

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenHardwareRayTracingCommon.cpp:11

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarLumenUseHardwareRayTracing(
	TEXT("r.Lumen.HardwareRayTracing"),
	0,
	TEXT("Uses Hardware Ray Tracing for Lumen features, when available.\n")
	TEXT("Lumen will fall back to Software Ray Tracing otherwise.\n")
	TEXT("Note: Hardware ray tracing has significant scene update costs for\n")
	TEXT("scenes with more than 100k instances."),
	FConsoleVariableDelegate::CreateLambda([](IConsoleVariable* InVariable)

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/PrimitiveSceneProxy.cpp:1610

Scope (from outer to inner):

file
function     void FPrimitiveSceneProxy::UpdateVisibleInLumenScene

Source code excerpt:

	bool bLumenUsesHardwareRayTracing = false;
#if RHI_RAYTRACING
	static const auto LumenUseHardwareRayTracingCVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.Lumen.HardwareRayTracing"));
	static const auto LumenUseFarFieldCVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.LumenScene.FarField"));
	bLumenUsesHardwareRayTracing = IsRayTracingEnabled()
		&& (GRHISupportsRayTracingShaders || GRHISupportsInlineRayTracing)
		&& LumenUseHardwareRayTracingCVar->GetValueOnAnyThread() != 0;
#endif

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenHardwareRayTracingCommon.cpp:10

Scope: file

Source code excerpt:

#include "LumenVisualize.h"

static TAutoConsoleVariable<int32> CVarLumenUseHardwareRayTracing(
	TEXT("r.Lumen.HardwareRayTracing"),
	0,
	TEXT("Uses Hardware Ray Tracing for Lumen features, when available.\n")
	TEXT("Lumen will fall back to Software Ray Tracing otherwise.\n")
	TEXT("Note: Hardware ray tracing has significant scene update costs for\n")
	TEXT("scenes with more than 100k instances."),

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Lumen/LumenHardwareRayTracingCommon.cpp:97

Scope (from outer to inner):

file
function     bool Lumen::UseHardwareRayTracing

Source code excerpt:

	return IsRayTracingEnabled(ViewFamily.GetShaderPlatform())
		&& (LumenHardwareRayTracing::IsInlineSupported() || LumenHardwareRayTracing::IsRayGenSupported())
		&& CVarLumenUseHardwareRayTracing.GetValueOnAnyThread() != 0
		// Lumen HWRT does not support split screen yet, but stereo views can be allowed
		&& (ViewFamily.Views.Num() == 1 || (ViewFamily.Views.Num() == 2 && IStereoRendering::IsStereoEyeView(*ViewFamily.Views[0])));
#else
	return false;
#endif
}