r.Substrate.Debug.PeelLayersAboveDepth

r.Substrate.Debug.PeelLayersAboveDepth

#Overview

name: r.Substrate.Debug.PeelLayersAboveDepth

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

• type: Var
• help: Substrate debug control to progressively peel off materials layer by layer.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Substrate.Debug.PeelLayersAboveDepth is to provide a debug control mechanism for the Substrate rendering system in Unreal Engine 5. It allows developers to progressively peel off material layers for visualization and debugging purposes.

This setting variable is primarily used by the Substrate rendering system, which is part of Unreal Engine 5’s rendering module. Based on the callsites, it’s clear that this variable is utilized within the Renderer subsystem, specifically in the Substrate-related functionality.

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 by default, no layers are peeled off.

The associated variable CVarSubstrateDebugPeelLayersAboveDepth interacts directly with r.Substrate.Debug.PeelLayersAboveDepth. They share the same value and purpose, with CVarSubstrateDebugPeelLayersAboveDepth being the actual C++ variable used in the code to access the console variable’s value.

Developers should be aware that this is a debug-only feature and should not be used in production builds. It’s designed to help visualize and understand the layering system in Substrate rendering.

Best practices when using this variable include:

1. Only enable it during debugging sessions.
2. Start with lower values and gradually increase to understand the layer structure.
3. Use in conjunction with other Substrate debug tools for a comprehensive understanding.
4. Remember to disable it before final builds or performance testing.

Regarding the associated variable CVarSubstrateDebugPeelLayersAboveDepth:

Its purpose is to provide programmatic access to the r.Substrate.Debug.PeelLayersAboveDepth console variable within the C++ code.

This variable is used directly in the Substrate rendering system, specifically in the InitialiseSubstrateFrameSceneData function.

The value of this variable is set by the console variable system and can be accessed using the GetValueOnRenderThread() method.

It interacts with the FSubstrateFrameSceneData structure, setting the PeelLayersAboveDepth member.

Developers should be aware that this variable is render thread safe (ECVF_RenderThreadSafe) and should only be accessed on the render thread.

Best practices include using GetValueOnRenderThread() to access its value safely, and ensuring any modifications to the variable are done through the console variable system rather than directly modifying the C++ variable.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Substrate/Substrate.cpp:34

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarSubstrateDebugPeelLayersAboveDepth(
	TEXT("r.Substrate.Debug.PeelLayersAboveDepth"),
	0,
	TEXT("Substrate debug control to progressively peel off materials layer by layer."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateDebugRoughnessTracking(
	TEXT("r.Substrate.Debug.RoughnessTracking"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Substrate/Substrate.cpp:33

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateDebugPeelLayersAboveDepth(
	TEXT("r.Substrate.Debug.PeelLayersAboveDepth"),
	0,
	TEXT("Substrate debug control to progressively peel off materials layer by layer."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateDebugRoughnessTracking(

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/Substrate/Substrate.cpp:476

Scope (from outer to inner):

file
namespace    Substrate
function     void InitialiseSubstrateFrameSceneData

Source code excerpt:

	Out.bRoughDiffuse = IsRoughDiffuseEnabled();

	Out.PeelLayersAboveDepth = FMath::Max(CVarSubstrateDebugPeelLayersAboveDepth.GetValueOnRenderThread(), 0);
	Out.bRoughnessTracking = CVarSubstrateDebugRoughnessTracking.GetValueOnRenderThread() > 0 ? 1 : 0;

	// SUBSTRATE_TODO allocate a slice for StoringDebugSubstrate only if SUBSTRATE_ADVANCED_DEBUG_ENABLED is enabled 
	Out.SliceStoringDebugSubstrateTreeData				= SliceCount - SliceCountAdvDebug;										// When we read, there is no slices excluded
	Out.SliceStoringDebugSubstrateTreeDataWithoutMRT	= SliceCount - SliceCountAdvDebug - SUBSTRATE_BASE_PASS_MRT_OUTPUT_COUNT;	// The UAV skips the first slices set as render target