r.SubstrateBackCompatibility

r.SubstrateBackCompatibility

#Overview

name: r.SubstrateBackCompatibility

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

• type: Var
• help: Disables Substrate multiple scattering and replaces Chan diffuse by Lambert.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.SubstrateBackCompatibility is to control the backward compatibility mode for the Substrate rendering system in Unreal Engine 5. Specifically, it disables Substrate multiple scattering and replaces Chan diffuse with Lambert when enabled.

This setting variable is primarily used by the rendering system, particularly the Substrate rendering module. Based on the callsites, it’s part of the RenderCore module in Unreal Engine.

The value of this variable is set through a console variable (CVar) system. It’s defined as a TAutoConsoleVariable with an initial value of 0, meaning the back compatibility mode is disabled by default.

The associated variable CVarSubstrateBackCompatibility directly interacts with r.SubstrateBackCompatibility. They share the same value and purpose.

Developers must be aware that this variable is marked as ECVF_ReadOnly and ECVF_RenderThreadSafe. This means:

1. It can only be set at startup or through console commands, not during runtime via C++ code.
2. It’s safe to read from any thread, including the render thread.

Best practices when using this variable include:

1. Only enable it when absolutely necessary for compatibility with older content or systems.
2. Be aware that enabling it may impact visual quality and performance, as it disables advanced features like multiple scattering.
3. Use it in conjunction with thorough testing to ensure desired rendering results.

Regarding the associated variable CVarSubstrateBackCompatibility:

• It’s the C++ representation of the r.SubstrateBackCompatibility console variable.
• It’s used in the IsBackCompatibilityEnabled() function within the Substrate namespace to check if the back compatibility mode is enabled.
• When working with C++ code, developers should use CVarSubstrateBackCompatibility.GetValueOnAnyThread() to safely read the current value of this setting from any thread.
• Changes to this variable will affect the behavior of the Substrate rendering system, potentially altering the appearance of materials in the scene.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<int32> CVarSubstrateBackCompatibility(
	TEXT("r.SubstrateBackCompatibility"),
	0,
	TEXT("Disables Substrate multiple scattering and replaces Chan diffuse by Lambert."),
	ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateOpaqueMaterialRoughRefraction(
	TEXT("r.Substrate.OpaqueMaterialRoughRefraction"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateBackCompatibility(
	TEXT("r.SubstrateBackCompatibility"),
	0,
	TEXT("Disables Substrate multiple scattering and replaces Chan diffuse by Lambert."),
	ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateOpaqueMaterialRoughRefraction(

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

Scope (from outer to inner):

file
namespace    Substrate
function     bool IsBackCompatibilityEnabled

Source code excerpt:

	bool IsBackCompatibilityEnabled()
	{
		return CVarSubstrateBackCompatibility.GetValueOnAnyThread() > 0 ? 1 : 0;
	}
	
	bool IsRoughDiffuseEnabled()
	{
		return CVarSubstrateRoughDiffuse.GetValueOnAnyThread() > 0;
	}