r.Substrate.AsyncClassification

r.Substrate.AsyncClassification

#Overview

name: r.Substrate.AsyncClassification

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

• type: Var
• help: Run Substrate material classification in async (with shadow).

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Substrate.AsyncClassification is to control whether the Substrate material classification process runs asynchronously (with shadow) in Unreal Engine’s rendering system.

This setting variable is primarily used by the Substrate rendering system, which is part of Unreal Engine’s renderer module. Based on the callsites, it’s specifically utilized in the Substrate.cpp file within the Runtime/Renderer/Private/Substrate directory.

The value of this variable is set through a console variable (CVar) system. It’s initialized with a default value of 1, meaning asynchronous classification is enabled by default. Developers can change this value at runtime using console commands.

The associated variable CVarSubstrateAsyncClassification directly interacts with r.Substrate.AsyncClassification. They share the same value and purpose.

Developers should be aware that this variable affects the performance and behavior of the Substrate material classification process. When enabled (value > 0), the classification runs asynchronously, which can improve performance but may introduce a slight delay in updating material classifications.

Best practices when using this variable include:

1. Keep it enabled (default value of 1) for better performance in most scenarios.
2. Consider disabling it (setting to 0) if you notice visual artifacts or if immediate material classification updates are crucial for your specific use case.
3. Profile your application with both settings to determine the optimal configuration for your specific project.

Regarding the associated variable CVarSubstrateAsyncClassification:

The purpose of CVarSubstrateAsyncClassification is identical to r.Substrate.AsyncClassification. It’s the actual console variable object used in the C++ code to control the asynchronous classification feature.

This variable is used directly in the Substrate rendering system, specifically in the IsClassificationAsync() function, which determines whether the classification should run asynchronously based on the variable’s value.

The value of CVarSubstrateAsyncClassification is set through the console variable system and can be modified at runtime.

As it’s directly tied to r.Substrate.AsyncClassification, the same considerations and best practices apply. Developers should be aware that changing this variable’s value will immediately affect the Substrate material classification process.

When working with CVarSubstrateAsyncClassification, developers should use the provided GetValueOnRenderThread() method to safely access its value from the render thread, as demonstrated in the IsClassificationAsync() function.

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarSubstrateAsyncClassification(
	TEXT("r.Substrate.AsyncClassification"),
	1,
	TEXT("Run Substrate material classification in async (with shadow)."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateDBufferPassDedicatedTiles(
	TEXT("r.Substrate.DBufferPass.DedicatedTiles"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateAsyncClassification(
	TEXT("r.Substrate.AsyncClassification"),
	1,
	TEXT("Run Substrate material classification in async (with shadow)."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateDBufferPassDedicatedTiles(

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

Scope (from outer to inner):

file
namespace    Substrate
function     bool IsClassificationAsync

Source code excerpt:

bool IsClassificationAsync()
{
	return CVarSubstrateAsyncClassification.GetValueOnRenderThread() > 0;
}

static EPixelFormat GetClassificationTileFormat(const FIntPoint& InResolution, uint32 InTileEncoding)
{
	return InTileEncoding == SUBSTRATE_TILE_ENCODING_16BITS ? PF_R32_UINT : PF_R16_UINT;
}