r.Substrate.UseClosureCountFromMaterial

r.Substrate.UseClosureCountFromMaterial

#Overview

name: r.Substrate.UseClosureCountFromMaterial

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.UseClosureCountFromMaterial is to control how the number of Lumen’s layers for multi-closure pixels is determined in the Substrate rendering system. This setting variable is part of Unreal Engine 5’s rendering system, specifically related to the Substrate subsystem.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, particularly the Substrate component within it. This can be seen from the file path where the variable is defined: Engine/Source/Runtime/Renderer/Private/Substrate/Substrate.cpp.

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

This variable interacts with another variable named r.Substrate.ClosuresPerPixel. When r.Substrate.UseClosureCountFromMaterial is enabled (set to 1), the system uses material data to scale the number of Lumen’s layers for multi-closure pixels. When disabled (set to 0), it uses the value from r.Substrate.ClosuresPerPixel instead.

Developers must be aware that this variable affects the rendering performance and quality, particularly for materials with multiple closures. Enabling this variable allows for more accurate rendering based on material properties, but it might have performance implications.

Best practices when using this variable include:

  1. Test the performance impact of enabling vs. disabling this feature in your specific use case.
  2. Consider the complexity of your materials and how they might benefit from material-based closure count scaling.
  3. Use in conjunction with r.Substrate.ClosuresPerPixel to fine-tune rendering quality and performance.

Regarding the associated variable CVarSubstrateUseClosureCountFromMaterial:

This is the actual C++ variable that represents the console variable r.Substrate.UseClosureCountFromMaterial. It’s used internally by the engine to store and retrieve the current value of the setting.

The purpose of CVarSubstrateUseClosureCountFromMaterial is to provide a programmatic interface for the r.Substrate.UseClosureCountFromMaterial setting within the C++ code.

This variable is used in the Renderer module, specifically in the Substrate component. It’s accessed through the GetValueOnRenderThread() method to determine whether to use the material-based closure count or not.

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

Developers should be aware that this variable is marked as ECVF_RenderThreadSafe, meaning it’s safe to access from the render thread. When accessing this variable in code, always use the GetValueOnRenderThread() method to ensure thread-safe access.

Best practices for using this variable in code include:

  1. Always access it using GetValueOnRenderThread() when in render thread code.
  2. Consider caching the value if it’s used frequently in performance-critical sections.
  3. Be aware of the performance implications of frequently checking this value in tight loops.

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarSubstrateUseClosureCountFromMaterial(
	TEXT("r.Substrate.UseClosureCountFromMaterial"),
	1,
	TEXT("When enable, scale the number of Lumen's layers for multi-closures pixels based on material data. Otherwise use r.Substrate.ClosuresPerPixel."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateDebugPeelLayersAboveDepth(
	TEXT("r.Substrate.Debug.PeelLayersAboveDepth"),

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateUseClosureCountFromMaterial(
	TEXT("r.Substrate.UseClosureCountFromMaterial"),
	1,
	TEXT("When enable, scale the number of Lumen's layers for multi-closures pixels based on material data. Otherwise use r.Substrate.ClosuresPerPixel."),
	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateDebugPeelLayersAboveDepth(

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

Scope (from outer to inner):

file
namespace    Substrate
function     bool UsesSubstrateClosureCountFromMaterialData

Source code excerpt:

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

uint32 GetSubstrateMaxClosureCount(const FViewInfo& View)
{
	uint32 Out = 1;
	if (Substrate::IsSubstrateEnabled())