r.ShaderCompiler.PerShaderDDCAsync

r.ShaderCompiler.PerShaderDDCAsync

#Overview

name: r.ShaderCompiler.PerShaderDDCAsync

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

• type: Var
• help: if != 0, Per-shader DDC queries will run async, instead of in the SubmitJobs task.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ShaderCompiler.PerShaderDDCAsync is to control the asynchronous execution of per-shader DDC (Derived Data Cache) queries in the shader compilation process. This setting variable is primarily used in the shader compilation system of Unreal Engine 5.

The Unreal Engine subsystem that relies on this setting variable is the shader compiler, which is part of the rendering system. It’s specifically used in the ShaderCompiler module, as evidenced by its implementation in the ShaderCompiler.cpp file.

The value of this variable is set through a console variable (CVar) named CVarShaderCompilerPerShaderDDCAsync. It’s initialized with a default value of true, meaning asynchronous DDC queries are enabled by default.

This variable interacts with GShaderCompilerPerShaderDDCGlobal, which is an integer variable that seems to be related to the same functionality. However, the exact relationship between these two variables is not clear from the provided code snippets.

Developers must be aware that this variable affects the performance and behavior of shader compilation. When enabled (set to true), it allows per-shader DDC queries to run asynchronously, which can potentially improve performance by allowing these queries to be processed in parallel with other tasks.

Best practices when using this variable include:

1. Consider the target platform’s capabilities, as the code checks for multithreading support before applying the async behavior.
2. Be aware of its impact on cook commandlets, where it can affect the priority of derived data requests.
3. Monitor performance metrics to ensure that enabling this feature actually benefits your specific use case.

Regarding the associated variable CVarShaderCompilerPerShaderDDCAsync:

The purpose of CVarShaderCompilerPerShaderDDCAsync is to provide a runtime-configurable way to control the r.ShaderCompiler.PerShaderDDCAsync setting. It’s implemented as a console variable, which allows for easy modification during development or runtime.

This variable is used directly in the shader compiler code to determine whether to use asynchronous DDC queries. It’s queried using the GetValueOnAnyThread() method, which suggests that it’s designed to be safely accessed from multiple threads.

The value of this variable can be changed through the console or configuration files, providing flexibility for different development and runtime scenarios.

Developers should be aware that changes to this variable will immediately affect the behavior of shader compilation, potentially impacting performance and resource usage.

Best practices for using CVarShaderCompilerPerShaderDDCAsync include:

1. Use it for debugging and performance tuning during development.
2. Consider exposing it as a configurable option for end-users if shader compilation performance is critical for your application.
3. Be cautious when changing its value in a shipping build, as it could have unforeseen consequences on performance and stability.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:200

Scope: file

Source code excerpt:

static TAutoConsoleVariable<bool> CVarShaderCompilerPerShaderDDCAsync(
	TEXT("r.ShaderCompiler.PerShaderDDCAsync"),
	true,
	TEXT("if != 0, Per-shader DDC queries will run async, instead of in the SubmitJobs task."),
	ECVF_Default
);

int32 GShaderCompilerPerShaderDDCGlobal = 1;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:199

Scope: file

Source code excerpt:

	ECVF_ReadOnly);

static TAutoConsoleVariable<bool> CVarShaderCompilerPerShaderDDCAsync(
	TEXT("r.ShaderCompiler.PerShaderDDCAsync"),
	true,
	TEXT("if != 0, Per-shader DDC queries will run async, instead of in the SubmitJobs task."),
	ECVF_Default
);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/ShaderCompiler/ShaderCompiler.cpp:10784

Scope (from outer to inner):

file
function     FShaderJobCacheRef FShaderJobCache::FindOrAdd

Source code excerpt:

			UE::DerivedData::FRequestOwner* RequestOwner;

			static const bool PerShaderDDCAsync = CVarShaderCompilerPerShaderDDCAsync.GetValueOnAnyThread();
			if (PerShaderDDCAsync && FGenericPlatformProcess::SupportsMultithreading())
			{
				if (IsRunningCookCommandlet())
				{
					DerivedDataPriority = UE::DerivedData::EPriority::Highest;
				}