r.Substrate.AllocationMode

r.Substrate.AllocationMode

#Overview

name: r.Substrate.AllocationMode

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

• type: Var
• help: Substrate resource allocation mode. \n 0: Allocate resources based on view requirement, \n 1: Allocate resources based on view requirement, but can only grow over frame to minimize resources reallocation and hitches, \n 2: Allocate resources based on platform settings.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Substrate.AllocationMode is to control the resource allocation mode for the Substrate system in Unreal Engine’s rendering pipeline. This setting variable is used to determine how resources are allocated for the Substrate rendering technique.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, specifically the Substrate component of the rendering system. This can be seen from the file location where the variable is defined: Engine/Source/Runtime/Renderer/Private/Substrate/Substrate.cpp.

The value of this variable is set through a console variable (CVarSubstrateAllocationMode) with a default value of 1. It can be changed at runtime through console commands or programmatically.

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

Developers must be aware that this variable has three possible values, each with different behaviors: 0: Allocate resources based on view requirement 1: Allocate resources based on view requirement, but can only grow over frame to minimize resource reallocation and hitches 2: Allocate resources based on platform settings

The best practices when using this variable include:

1. Understanding the performance implications of each mode
2. Using mode 1 (the default) for a balance between flexibility and performance
3. Consider using mode 2 for more predictable resource allocation on specific platforms
4. Use mode 0 only if dynamic resource allocation is necessary and the potential performance hit is acceptable

Regarding the associated variable CVarSubstrateAllocationMode:

• It is an instance of TAutoConsoleVariable, which allows for runtime modification of the value
• It is used in the GetMaterialBufferAllocationMode() function to retrieve the current allocation mode
• The value is clamped between 0 and 2 to ensure valid modes are used

Developers should use the GetMaterialBufferAllocationMode() function to retrieve the current allocation mode value in their code, rather than accessing CVarSubstrateAllocationMode directly. This ensures that the value is properly clamped and consistent throughout the engine.

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarSubstrateAllocationMode(
	TEXT("r.Substrate.AllocationMode"),
	1,
	TEXT("Substrate resource allocation mode. \n 0: Allocate resources based on view requirement, \n 1: Allocate resources based on view requirement, but can only grow over frame to minimize resources reallocation and hitches, \n 2: Allocate resources based on platform settings."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateTileCoord8Bits(
	TEXT("r.Substrate.TileCoord8bits"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateAllocationMode(
	TEXT("r.Substrate.AllocationMode"),
	1,
	TEXT("Substrate resource allocation mode. \n 0: Allocate resources based on view requirement, \n 1: Allocate resources based on view requirement, but can only grow over frame to minimize resources reallocation and hitches, \n 2: Allocate resources based on platform settings."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateTileCoord8Bits(

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

Scope (from outer to inner):

file
namespace    Substrate
function     uint32 GetMaterialBufferAllocationMode

Source code excerpt:

uint32 GetMaterialBufferAllocationMode()
{
	return FMath::Clamp(CVarSubstrateAllocationMode.GetValueOnAnyThread(), 0, 2);
}

bool UsesSubstrateClosureCountFromMaterialData() 
{
	return CVarSubstrateUseClosureCountFromMaterial.GetValueOnRenderThread() > 0;
}