r.PathTracing.Substrate.CompileSimplifiedMaterials

r.PathTracing.Substrate.CompileSimplifiedMaterials

#Overview

name: r.PathTracing.Substrate.CompileSimplifiedMaterials

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

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.PathTracing.Substrate.CompileSimplifiedMaterials is to control the compilation of simplified representations of Substrate materials in the path tracing system of Unreal Engine 5. This setting is primarily used for debugging purposes within the rendering system.

This setting variable is primarily used in the path tracing subsystem of Unreal Engine’s rendering module. It specifically affects the compilation and use of Substrate materials in path tracing shaders.

The value of this variable is set through a console variable (CVarPathTracingSubstrateCompileSimplifiedMaterial) in the Engine/Source/Runtime/Renderer/Private/PathTracing.cpp file. It’s initialized with a default value of 0 (off).

This variable interacts closely with another variable, CVarPathTracingSubstrateUseSimplifiedMaterial, which controls the runtime usage of the simplified materials.

Developers must be aware of several important points when using this variable:

  1. Enabling this option doubles the number of path tracing shader permutations, which can increase compilation times and memory usage.
  2. It’s intended for debugging purposes and not for production use.
  3. It only has an effect if Substrate is enabled in the project.

Best practices for using this variable include:

  1. Keep it disabled (0) for normal development and production builds.
  2. Only enable it when debugging specific issues related to Substrate materials in path tracing.
  3. Be prepared for increased shader compilation times when enabled.

Regarding the associated variable CVarPathTracingSubstrateCompileSimplifiedMaterial:

The purpose of CVarPathTracingSubstrateCompileSimplifiedMaterial is the same as r.PathTracing.Substrate.CompileSimplifiedMaterials. It’s the actual console variable implementation of the setting.

This variable is used in the same subsystem (path tracing) within the rendering module. It’s directly checked in shader compilation decisions and runtime material selection for path tracing.

The value is set when the engine initializes the console variables, with a default of 0.

It interacts with CVarPathTracingSubstrateUseSimplifiedMaterial and is checked alongside Substrate::IsSubstrateEnabled() to determine whether to compile and use simplified Substrate materials.

Developers should be aware that this is a read-only variable (ECVF_ReadOnly flag), meaning it can’t be changed at runtime. It’s also marked as render thread safe (ECVF_RenderThreadSafe).

Best practices for this variable are the same as for r.PathTracing.Substrate.CompileSimplifiedMaterials, as they represent the same setting. It should generally be left at its default value (0) unless specifically needed for debugging Substrate materials in path tracing.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:365

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarPathTracingSubstrateCompileSimplifiedMaterial(
	TEXT("r.PathTracing.Substrate.CompileSimplifiedMaterials"),
	0,
	TEXT("Compile a simplified representation of Substrate materials which merges all slabs into one. This is mainly intended for debugging purposes. Enabling this double the number of path tracing shader permutations.\n")
	TEXT("0: off (default)\n")
	TEXT("1: on\n"),
	ECVF_RenderThreadSafe | ECVF_ReadOnly
);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:364

Scope: file

Source code excerpt:

);

TAutoConsoleVariable<int32> CVarPathTracingSubstrateCompileSimplifiedMaterial(
	TEXT("r.PathTracing.Substrate.CompileSimplifiedMaterials"),
	0,
	TEXT("Compile a simplified representation of Substrate materials which merges all slabs into one. This is mainly intended for debugging purposes. Enabling this double the number of path tracing shader permutations.\n")
	TEXT("0: off (default)\n")
	TEXT("1: on\n"),
	ECVF_RenderThreadSafe | ECVF_ReadOnly

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:1454

Scope (from outer to inner):

file
class        class TPathTracingMaterial : public FMeshMaterialShader
function     static bool ShouldCompilePermutation

Source code excerpt:

		else
		{
			if (SimplifySubstrate && (!Substrate::IsSubstrateEnabled() || CVarPathTracingSubstrateCompileSimplifiedMaterial.GetValueOnAnyThread() == 0))
			{
				// don't compile the extra Substrate permutation if:
				//    Substrate is not enabled on this project
				// or the user did not request the extra permutations to be compiled (default)
				return false;
			}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:1629

Scope (from outer to inner):

file
function     bool FRayTracingMeshProcessor::ProcessPathTracing

Source code excerpt:

				// In order to use Substrate simplified materials, Substrate has to be enabled, we have to have _compiled_ the extra permutations _and_ the runtime toggle must be true
				const bool bUseSimplifiedMaterial = Substrate::IsSubstrateEnabled() &&
					CVarPathTracingSubstrateCompileSimplifiedMaterial.GetValueOnRenderThread() != 0 &&
					CVarPathTracingSubstrateUseSimplifiedMaterial.GetValueOnRenderThread() != 0;
				if (NeedsAnyHitShader(MaterialResource))
				{
					if (bUseSimplifiedMaterial)
					{
						if (bUseProceduralPrimitive)

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PathTracing.cpp:2501

Scope: file

Source code excerpt:

	Config.LightShowFlags |= View.Family->EngineShowFlags.SubsurfaceScattering       ? 1 << 13 : 0;
	// the following affects which material shaders get used and therefore change the image
	if (Substrate::IsSubstrateEnabled() && CVarPathTracingSubstrateCompileSimplifiedMaterial.GetValueOnRenderThread() != 0)
	{
		Config.LightShowFlags |= CVarPathTracingSubstrateUseSimplifiedMaterial.GetValueOnRenderThread() != 0 ? 1 << 14 : 0;
	}

	PreparePathTracingData(Scene, View, Config.PathTracingData);