r.ManyLights.ScreenTraces

r.ManyLights.ScreenTraces

#Overview

name: r.ManyLights.ScreenTraces

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.ManyLights.ScreenTraces is to control whether screen space tracing is used for shadow rays in the Many Lights rendering system. This setting variable is part of Unreal Engine 5’s rendering system, specifically related to the Many Lights technique for efficient lighting calculations.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, particularly the Many Lights ray tracing component. This can be seen from the file location: Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLightsRayTracing.cpp.

The value of this variable is set using a console variable (CVarManyLightsScreenTraces) with a default value of 1, meaning screen space tracing for shadow rays is enabled by default. Developers can modify this value at runtime using console commands or through project settings.

This variable interacts closely with other Many Lights related variables, such as CVarManyLightsScreenTracesMaxIterations, which is defined immediately after it in the source code.

Developers must be aware that this variable affects the performance and quality of shadow rendering in scenes with many lights. Enabling screen space tracing (value 1) may provide better performance but could potentially result in some visual artifacts or limitations compared to full ray tracing.

Best practices when using this variable include:

  1. Testing the visual quality and performance impact with both enabled (1) and disabled (0) states.
  2. Considering the target hardware capabilities when deciding whether to use screen space tracing or full ray tracing.
  3. Balancing this setting with other Many Lights related settings for optimal performance and visual quality.

Regarding the associated variable CVarManyLightsScreenTraces:

The purpose of CVarManyLightsScreenTraces is to provide a runtime-modifiable way to control the r.ManyLights.ScreenTraces setting. It is implemented as a TAutoConsoleVariable, which allows for easy integration with Unreal Engine’s console system.

This variable is used in the Renderer module, specifically in the ManyLights namespace functions. It’s accessed using the GetValueOnRenderThread() method, ensuring thread-safe access to its value.

The value of CVarManyLightsScreenTraces is set when the engine initializes, but can be changed at runtime through console commands or project settings.

It interacts directly with the r.ManyLights.ScreenTraces setting, effectively controlling the same functionality.

Developers should be aware that changes to this variable will take effect on the render thread, which may not be immediate depending on the current frame state.

Best practices for using CVarManyLightsScreenTraces include:

  1. Using it for debugging or performance testing during development.
  2. Considering exposing it as a user-configurable setting in shipping builds if dynamic adjustment of this feature is desired.
  3. Being cautious about frequently changing this value, as it may impact rendering performance and consistency.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLightsRayTracing.cpp:7

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarManyLightsScreenTraces(
	TEXT("r.ManyLights.ScreenTraces"),
	1,
	TEXT("Whether to use screen space tracing for shadow rays."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarManyLightsScreenTracesMaxIterations(

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLightsRayTracing.cpp:6

Scope: file

Source code excerpt:

#include "BasePassRendering.h"

static TAutoConsoleVariable<int32> CVarManyLightsScreenTraces(
	TEXT("r.ManyLights.ScreenTraces"),
	1,
	TEXT("Whether to use screen space tracing for shadow rays."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLightsRayTracing.cpp:127

Scope (from outer to inner):

file
namespace    ManyLights
function     bool IsUsingClosestHZB

Source code excerpt:

	bool IsUsingClosestHZB()
	{
		return IsEnabled() && CVarManyLightsScreenTraces.GetValueOnRenderThread() != 0;
	}

	bool IsUsingGlobalSDF()
	{
		return IsEnabled() && CVarManyLightsWorldSpaceTraces.GetValueOnRenderThread() != 0 && !UseHardwareRayTracing();
	}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ManyLights/ManyLightsRayTracing.cpp:512

Scope (from outer to inner):

file
function     void ManyLights::RayTraceLightSamples

Source code excerpt:

	const bool bDebug = ManyLights::GetDebugMode() != 0;

	if (CVarManyLightsScreenTraces.GetValueOnRenderThread() != 0)
	{
		FCompactedTraceParameters CompactedTraceParameters = ManyLights::CompactManyLightsTraces(
			View,
			GraphBuilder,
			SampleBufferSize,
			LightSamples,