r.Substrate.UseCmaskClear

r.Substrate.UseCmaskClear

#Overview

name: r.Substrate.UseCmaskClear

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.Substrate.UseCmaskClear is to control the use of CMask clear in the Substrate rendering system within Unreal Engine 5. This setting is part of the rendering subsystem, specifically related to the Substrate feature.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, as evidenced by its location in the Substrate.cpp file within the Runtime/Renderer/Private/Substrate directory.

The value of this variable is set through a console variable (CVarUseCmaskClear) with an initial value of 0. It can be changed at runtime through console commands or project settings.

This variable interacts with another variable named CVarUseCmaskClear, which is the actual TAutoConsoleVariable that stores and manages the setting’s value.

Developers must be aware that this variable is render thread safe (ECVF_RenderThreadSafe), meaning it can be safely accessed from the render thread. Its value affects the behavior of the SupportsCMask function, which determines whether CMask is supported for a given shader platform.

Best practices when using this variable include:

  1. Only modify it when necessary, as it affects rendering behavior.
  2. Be aware of potential performance implications when enabling CMask clear.
  3. Test thoroughly on target platforms after changing this setting, as it may interact with platform-specific rendering features.

Regarding the associated variable CVarUseCmaskClear:

The purpose of CVarUseCmaskClear is to store and manage the value of the r.Substrate.UseCmaskClear setting. It is defined as a TAutoConsoleVariable, which allows for runtime modification of the setting.

This variable is used directly in the Renderer module, specifically in the Substrate namespace.

The value of CVarUseCmaskClear is initially set to 0, but can be changed through console commands or project settings.

CVarUseCmaskClear interacts directly with the r.Substrate.UseCmaskClear setting, as they represent the same value.

Developers should be aware that this variable is accessed using GetValueOnRenderThread() in the SupportsCMask function, ensuring thread-safe access to its value.

Best practices for using CVarUseCmaskClear include:

  1. Use GetValueOnRenderThread() when accessing its value from render thread code.
  2. Consider the performance implications of frequently querying this value in performance-critical sections of code.
  3. When modifying the value, ensure that all related systems are updated accordingly to maintain consistency in the rendering pipeline.

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

Scope: file

Source code excerpt:

// The project setting for Substrate
static TAutoConsoleVariable<int32> CVarUseCmaskClear(
	TEXT("r.Substrate.UseCmaskClear"),
	0,
	TEXT("TEST."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateUseClosureCountFromMaterial(
	TEXT("r.Substrate.UseClosureCountFromMaterial"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:


// The project setting for Substrate
static TAutoConsoleVariable<int32> CVarUseCmaskClear(
	TEXT("r.Substrate.UseCmaskClear"),
	0,
	TEXT("TEST."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateUseClosureCountFromMaterial(

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

Scope (from outer to inner):

file
namespace    Substrate
function     bool SupportsCMask

Source code excerpt:

bool SupportsCMask(const FStaticShaderPlatform InPlatform)
{
	return CVarUseCmaskClear.GetValueOnRenderThread() > 0 && FDataDrivenShaderPlatformInfo::GetSupportsRenderTargetWriteMask(InPlatform);
}

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