r.Substrate.Debug.RoughnessTracking

r.Substrate.Debug.RoughnessTracking

#Overview

name: r.Substrate.Debug.RoughnessTracking

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

• type: Var
• help: Substrate debug control to disable roughness tracking, e.g. top layer roughness affecting bottom layer roughness to simulate light scattering.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Substrate.Debug.RoughnessTracking is to control the debug functionality for roughness tracking in the Substrate rendering system. It specifically affects the simulation of light scattering by allowing or disabling the influence of top layer roughness on bottom layer roughness.

This setting variable is primarily used in the Unreal Engine’s Renderer module, specifically within the Substrate subsystem. The Substrate system is part of the advanced rendering capabilities in Unreal Engine 5, focusing on realistic material rendering.

The value of this variable is set through a console variable (CVar) system, which allows for runtime configuration. It is initialized with a default value of 1, enabling roughness tracking by default.

The associated variable CVarSubstrateDebugRoughnessTracking directly interacts with r.Substrate.Debug.RoughnessTracking. They share the same value and purpose, with CVarSubstrateDebugRoughnessTracking being the C++ representation of the console variable.

Developers should be aware that this variable is intended for debugging purposes. Modifying it may affect the visual fidelity of materials in the scene, particularly those utilizing the Substrate system. It’s important to note that this variable is marked as ECVF_RenderThreadSafe, meaning it can be safely modified on the render thread.

Best practices when using this variable include:

1. Use it primarily for debugging and testing purposes.
2. Be cautious when disabling roughness tracking in production builds, as it may impact the realism of rendered materials.
3. Consider the performance implications of enabling or disabling this feature, especially in complex scenes.

Regarding the associated variable CVarSubstrateDebugRoughnessTracking:

• Its purpose is to provide programmatic access to the r.Substrate.Debug.RoughnessTracking setting within the C++ code.
• It is used in the Renderer module, specifically in the Substrate subsystem initialization and processing.
• Its value is set through the CVar system and can be accessed using the GetValueOnRenderThread() method.
• It directly controls the bRoughnessTracking flag in the Substrate frame scene data.
• Developers should be aware that changes to this variable will take effect on the render thread, which may not be immediate in all scenarios.
• Best practices include using this variable for conditional compilation or runtime behavior adjustments related to roughness tracking in the Substrate system.

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarSubstrateDebugRoughnessTracking(
	TEXT("r.Substrate.Debug.RoughnessTracking"),
	1,
	TEXT("Substrate debug control to disable roughness tracking, e.g. top layer roughness affecting bottom layer roughness to simulate light scattering."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateAsyncClassification(
	TEXT("r.Substrate.AsyncClassification"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateDebugRoughnessTracking(
	TEXT("r.Substrate.Debug.RoughnessTracking"),
	1,
	TEXT("Substrate debug control to disable roughness tracking, e.g. top layer roughness affecting bottom layer roughness to simulate light scattering."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateAsyncClassification(

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

Scope (from outer to inner):

file
namespace    Substrate
function     void InitialiseSubstrateFrameSceneData

Source code excerpt:

	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

	Out.FirstSliceStoringSubstrateSSSData				= SliceCount - SliceCountSSS - SliceCountAdvDebug;										// When we read, there is no slices excluded