r.RayTracing.DebugTraversalScale.Cluster

r.RayTracing.DebugTraversalScale.Cluster

#Overview

name: r.RayTracing.DebugTraversalScale.Cluster

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.RayTracing.DebugTraversalScale.Cluster is to provide a scaling factor for cluster traversal heat map visualization in the ray tracing debug system of Unreal Engine 5. This setting is specifically used for debugging and visualizing the performance of ray tracing cluster traversal.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically within the ray tracing debug system. It’s part of the ray tracing visualization and debugging tools, which are crucial for optimizing ray tracing performance.

The value of this variable is set as a console variable with a default value of 2500.0f. It can be modified at runtime through the console or through configuration files.

The variable interacts with other debug visualization settings, particularly other traversal scale variables for different aspects of ray tracing (such as box traversal and triangle traversal). It’s used in conjunction with these other variables to provide a comprehensive debug visualization of ray tracing performance.

Developers must be aware that this is a debug visualization tool and should not be used in production builds. It’s intended for performance analysis and optimization of ray tracing in development environments.

Best practices when using this variable include:

  1. Use it in conjunction with other ray tracing debug variables for a complete picture of performance.
  2. Adjust the scale as needed to make the visualization more or less sensitive to traversal costs.
  3. Remember that this is a development tool and should be disabled in shipping builds.

Regarding the associated variable CVarRayTracingDebugTraversalClusterScale:

This is the actual C++ variable that holds the console variable. It’s an instance of TAutoConsoleVariable, which is Unreal Engine’s way of exposing settings to the console and configuration system.

The purpose of this variable is the same as r.RayTracing.DebugTraversalScale.Cluster - it’s the internal representation of the console variable.

This variable is used directly in the code to retrieve the current value of the setting. For example, in the RenderRayTracingDebug function, it’s accessed using GetValueOnAnyThread() to set the TraversalClusterScale parameter for the debug visualization.

Developers should be aware that changes to the console variable will be reflected in this C++ variable, and vice versa. When accessing the value in C++ code, always use the GetValueOnAnyThread() method to ensure you’re getting the most up-to-date value, as it may have been changed through the console or configuration files.

Best practices for using this variable in C++ code include:

  1. Always access it through GetValueOnAnyThread() to get the current value.
  2. Don’t cache the value for long periods, as it can be changed at runtime.
  3. Consider performance implications of frequently accessing this value in performance-critical code paths.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingDebug.cpp:60

Scope: file

Source code excerpt:


static TAutoConsoleVariable<float> CVarRayTracingDebugTraversalClusterScale(
	TEXT("r.RayTracing.DebugTraversalScale.Cluster"),
	2500.0f,
	TEXT("Scaling factor for cluster traversal heat map visualization. (default = 2500)\n")
);

static TAutoConsoleVariable<float> CVarRayTracingDebugInstanceOverlapScale(
	TEXT("r.RayTracing.Debug.InstanceOverlap.Scale"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingDebug.cpp:59

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<float> CVarRayTracingDebugTraversalClusterScale(
	TEXT("r.RayTracing.DebugTraversalScale.Cluster"),
	2500.0f,
	TEXT("Scaling factor for cluster traversal heat map visualization. (default = 2500)\n")
);

static TAutoConsoleVariable<float> CVarRayTracingDebugInstanceOverlapScale(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/RayTracing/RayTracingDebug.cpp:1372

Scope (from outer to inner):

file
function     void FDeferredShadingSceneRenderer::RenderRayTracingDebug

Source code excerpt:

		PassParameters->VisualizationMode = DebugVisualizationMode;
		PassParameters->TraversalBoxScale = CVarRayTracingDebugTraversalBoxScale.GetValueOnAnyThread();
		PassParameters->TraversalClusterScale = CVarRayTracingDebugTraversalClusterScale.GetValueOnAnyThread();
		PassParameters->TraversalTriangleScale = CVarRayTracingDebugTraversalTriangleScale.GetValueOnAnyThread();

		PassParameters->RTDebugVisualizationNaniteCutError = 0.0f;

		RaytracingTraversalStatistics::FTraceRayInlineStatisticsData TraversalData;
		if (bPrintTraversalStats)