r.Substrate

r.Substrate

#Overview

name: r.Substrate

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.Substrate is to enable or disable Substrate materials, which is a beta feature in Unreal Engine 5. This setting variable is part of the rendering system, specifically related to material rendering.

Based on the callsites, the r.Substrate variable is primarily used in the RenderCore module and the UnrealEd module. It appears to be particularly relevant for the Lightmass system, which is responsible for global illumination calculations.

The value of this variable is set as a console variable (CVar) with an initial value of 0, meaning Substrate materials are disabled by default. It can be changed at runtime through the console or configuration files.

The r.Substrate variable interacts closely with its associated variable CVarSubstrate. They share the same value and purpose. The CVarSubstrate is used internally in the engine code to check if Substrate materials are enabled.

Developers must be aware that this feature is in beta, as indicated by the description “Enable Substrate materials (Beta).” This means it may not be fully stable or optimized for production use.

Best practices when using this variable include:

  1. Only enable it if you specifically need to use Substrate materials.
  2. Be prepared for potential instability or performance issues, as it’s a beta feature.
  3. Test thoroughly when enabling this feature, especially in relation to Lightmass and global illumination.
  4. Consider the impact on rendering performance and memory usage when enabling Substrate materials.

Regarding the associated variable CVarSubstrate:

The purpose of CVarSubstrate is to provide an internal representation of the r.Substrate console variable. It’s used within the engine code to check the state of Substrate materials.

CVarSubstrate is primarily used in the RenderCore module. It’s defined and accessed in the RenderUtils.cpp file.

The value of CVarSubstrate is set when the r.Substrate console variable is initialized. They share the same initial value and description.

CVarSubstrate interacts directly with r.Substrate, essentially serving as its internal counterpart. It’s used in functions like IsSubstrateEnabled() to determine if Substrate materials are active.

Developers should be aware that CVarSubstrate is marked with ECVF_ReadOnly and ECVF_RenderThreadSafe flags, indicating it’s intended to be read-only and safe for use on the render thread.

Best practices for CVarSubstrate include:

  1. Use the provided IsSubstrateEnabled() function to check the state of Substrate materials rather than accessing CVarSubstrate directly.
  2. Remember that changes to r.Substrate will be reflected in CVarSubstrate.
  3. Avoid attempting to modify CVarSubstrate directly, as it’s intended to be read-only.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:1734

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarSubstrate(
	TEXT("r.Substrate"),
	0,
	TEXT("Enable Substrate materials (Beta)."),
	ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateBytesPerPixel(
	TEXT("r.Substrate.BytesPerPixel"),

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Lightmass/LightmassRender.cpp:34

Scope (from outer to inner):

file
function     extern bool Lightmass_IsSubstrateEnabled

Source code excerpt:

extern bool Lightmass_IsSubstrateEnabled()
{
	static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.Substrate"));
	return CVar && CVar->GetValueOnAnyThread() > 0;
}

// FLightmassMaterialCompiler - A proxy compiler that overrides various compiler functions for potential problem expressions.
struct FLightmassMaterialCompiler : public FProxyMaterialCompiler
{

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:1733

Scope: file

Source code excerpt:

// Substrate settings interface

static TAutoConsoleVariable<int32> CVarSubstrate(
	TEXT("r.Substrate"),
	0,
	TEXT("Enable Substrate materials (Beta)."),
	ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateBytesPerPixel(

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/RenderUtils.cpp:1834

Scope (from outer to inner):

file
namespace    Substrate
function     bool IsSubstrateEnabled

Source code excerpt:

	bool IsSubstrateEnabled()
	{
		return CVarSubstrate.GetValueOnAnyThread() > 0;
	}

	static uint32 InternalGetBytePerPixel(uint32 InBytePerPixel)
	{
		auto RoundUpValueToUInt = [](uint32 Value)
		{