r.ManyLights.ScreenTraces.RelativeDepthThickness

r.ManyLights.ScreenTraces.RelativeDepthThickness

#Overview

name: r.ManyLights.ScreenTraces.RelativeDepthThickness

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.ManyLights.ScreenTraces.RelativeDepthThickness is to determine the depth thickness of objects hit by Hierarchical Z-Buffer (HZB) tracing, expressed as a relative depth threshold. This setting is primarily used in the rendering system, specifically in the Many Lights rendering module of Unreal Engine 5.

This setting variable is relied upon by the Unreal Engine’s rendering subsystem, particularly the Many Lights module. It’s used in the ray tracing process for light samples, which is part of the engine’s advanced lighting system.

The value of this variable is set as a console variable with a default value of 0.005f. It can be adjusted at runtime through the console or programmatically.

The associated variable CVarManyLightsScreenTraceRelativeDepthThreshold interacts directly with r.ManyLights.ScreenTraces.RelativeDepthThickness. They share the same value and are used interchangeably in the code.

Developers must be aware that this variable affects the precision of light sample ray tracing. A lower value will result in more precise depth testing but may increase computational cost, while a higher value might improve performance at the cost of accuracy.

Best practices when using this variable include:

  1. Adjusting it based on the specific needs of your scene and the desired balance between performance and visual quality.
  2. Testing different values to find the optimal setting for your particular use case.
  3. Considering the impact on different hardware configurations, as the performance impact may vary.

Regarding the associated variable CVarManyLightsScreenTraceRelativeDepthThreshold:

The purpose of CVarManyLightsScreenTraceRelativeDepthThreshold is the same as r.ManyLights.ScreenTraces.RelativeDepthThickness. It’s used internally in the C++ code to access and modify the value of the console variable.

This variable is used in the ManyLights::RayTraceLightSamples function, where it’s multiplied by the view’s per-projection depth thickness scale to calculate the final relative depth thickness used in the ray tracing process.

The value of this variable is set and accessed using the TAutoConsoleVariable template class, which allows for runtime modification of the value.

Developers should be aware that changes to this variable will directly affect the ray tracing process for light samples. It’s important to consider the performance implications when modifying this value, especially in performance-critical scenarios.

Best practices for using this variable include:

  1. Using it in conjunction with other Many Lights settings to achieve the desired balance of performance and visual quality.
  2. Profiling the impact of different values on your specific scenes and hardware targets.
  3. Considering exposing this setting to artists or implementing adaptive adjustment based on scene complexity or performance metrics.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarManyLightsScreenTraceRelativeDepthThreshold(
	TEXT("r.ManyLights.ScreenTraces.RelativeDepthThickness"),
	0.005f,
	TEXT("Determines depth thickness of objects hit by HZB tracing, as a relative depth threshold."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<int32> CVarManyLightsWorldSpaceTraces(

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarManyLightsScreenTraceRelativeDepthThreshold(
	TEXT("r.ManyLights.ScreenTraces.RelativeDepthThickness"),
	0.005f,
	TEXT("Determines depth thickness of objects hit by HZB tracing, as a relative depth threshold."),
	ECVF_Scalability | ECVF_RenderThreadSafe
);

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

Scope (from outer to inner):

file
function     void ManyLights::RayTraceLightSamples

Source code excerpt:

		PassParameters->HZBScreenTraceParameters = SetupHZBScreenTraceParameters(GraphBuilder, View, SceneTextures, /*bBindLumenHistory*/ false);
		PassParameters->MaxHierarchicalScreenTraceIterations = CVarManyLightsScreenTracesMaxIterations.GetValueOnRenderThread();
		PassParameters->RelativeDepthThickness = CVarManyLightsScreenTraceRelativeDepthThreshold.GetValueOnRenderThread() * View.ViewMatrices.GetPerProjectionDepthThicknessScale();
		PassParameters->HistoryDepthTestRelativeThickness = 0.0f;
		PassParameters->MinimumTracingThreadOccupancy = CVarManyLightsScreenTracesMinimumOccupancy.GetValueOnRenderThread();

		FScreenSpaceRayTraceLightSamplesCS::FPermutationDomain PermutationVector;
		PermutationVector.Set<FScreenSpaceRayTraceLightSamplesCS::FDebugMode>(bDebug);
		auto ComputeShader = View.ShaderMap->GetShader<FScreenSpaceRayTraceLightSamplesCS>(PermutationVector);