r.Substrate.BytesPerPixel

r.Substrate.BytesPerPixel

#Overview

name: r.Substrate.BytesPerPixel

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.BytesPerPixel is to control the amount of memory allocated per pixel for storing materials data in the Substrate rendering system of Unreal Engine 5. This setting variable is crucial for the rendering system, specifically for material representation and storage.

This setting variable is primarily used within the RenderCore module of Unreal Engine 5, as evidenced by its references in the RenderUtils.cpp file. The Substrate namespace, which is part of the rendering system, relies on this variable to determine the memory allocation for material data.

The value of this variable is set as a console variable with a default value of 80 bytes per pixel. It can be modified through the console or configuration files, but it’s marked as read-only and render thread safe, indicating that it shouldn’t be changed during runtime.

The associated variable CVarSubstrateBytesPerPixel interacts directly with r.Substrate.BytesPerPixel. They share the same value and purpose, with CVarSubstrateBytesPerPixel being the actual console variable implementation.

Developers must be aware that this variable directly impacts the complexity of materials that can be represented in the Substrate system. A higher value allows for more complex materials but also increases memory usage.

Best practices when using this variable include:

  1. Carefully balancing material complexity needs with memory constraints.
  2. Adjusting the value based on the target hardware capabilities.
  3. Considering the impact on performance, especially on lower-end devices.
  4. Not changing the value during runtime, as it’s marked as read-only.

Regarding the associated variable CVarSubstrateBytesPerPixel:

The purpose of CVarSubstrateBytesPerPixel is to provide a programmatic interface to the r.Substrate.BytesPerPixel setting. It’s implemented as a TAutoConsoleVariable, which allows for easy access and modification of the setting through the Unreal Engine console system.

This variable is used in the RenderCore module, specifically within the Substrate namespace. It’s accessed in the GetBytePerPixel functions to retrieve the current setting value.

The value of CVarSubstrateBytesPerPixel is set when the console variable is initialized, with the same default value of 80 as r.Substrate.BytesPerPixel.

CVarSubstrateBytesPerPixel directly interacts with r.Substrate.BytesPerPixel, effectively serving as its in-code representation.

Developers should be aware that while this variable provides an interface to the setting, it should still be treated as read-only during runtime due to its ECVF_ReadOnly flag.

Best practices for using CVarSubstrateBytesPerPixel include:

  1. Using GetValueOnAnyThread() to safely retrieve the value from any thread.
  2. Avoiding direct modification of the variable in code, instead using console commands or configuration files to change the value.
  3. Considering caching the value if it’s frequently accessed, to avoid potential performance overhead from repeated console variable lookups.

#References in C++ code

#Callsites

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

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

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarSubstrateBytesPerPixel(
	TEXT("r.Substrate.BytesPerPixel"),
	80,
	TEXT("Substrate allocated byte per pixel to store materials data. Higher value means more complex material can be represented."),
	ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateClosuresPerPixel(
	TEXT("r.Substrate.ClosuresPerPixel"),

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

Scope (from outer to inner):

file
namespace    Substrate
function     uint32 GetBytePerPixel

Source code excerpt:

	{
		// Variant for shader compilation per platform
		static FShaderPlatformCachedIniValue<int32> CVarByteBudget(TEXT("r.Substrate.BytesPerPixel"));
		return InternalGetBytePerPixel(CVarByteBudget.Get(InPlatform));
	}

	uint32 GetClosurePerPixel(EShaderPlatform InPlatform)
	{
		// Variant for shader compilation per platform

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

	ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateBytesPerPixel(
	TEXT("r.Substrate.BytesPerPixel"),
	80,
	TEXT("Substrate allocated byte per pixel to store materials data. Higher value means more complex material can be represented."),
	ECVF_ReadOnly | ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarSubstrateClosuresPerPixel(

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

Scope (from outer to inner):

file
namespace    Substrate
function     uint32 GetBytePerPixel

Source code excerpt:

	uint32 GetBytePerPixel()
	{
		return InternalGetBytePerPixel(CVarSubstrateBytesPerPixel.GetValueOnAnyThread());
	}

	uint32 GetBytePerPixel(EShaderPlatform InPlatform)
	{
		// Variant for shader compilation per platform
		static FShaderPlatformCachedIniValue<int32> CVarByteBudget(TEXT("r.Substrate.BytesPerPixel"));