r.ShaderCompiler.PreprocessedJobCache

r.ShaderCompiler.PreprocessedJobCache

#Overview

name: r.ShaderCompiler.PreprocessedJobCache

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

• type: Var
• help: If enabled will shader compile jobs will be preprocessed at submission time in the cook process (when the job is queued) and generate job input hashes based on preprocessed source.

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ShaderCompiler.PreprocessedJobCache is to enable preprocessing of shader compile jobs during the cook process, specifically at the time when the job is queued for compilation. This setting is primarily used in the shader compilation system of Unreal Engine 5.

This setting variable is relied upon by the shader compilation subsystem within Unreal Engine. Specifically, it’s used in the ShaderCompiler module, which is part of the Engine’s rendering system.

The value of this variable is set through a console variable (CVar) system. It’s defined as a TAutoConsoleVariable with a default value of true, meaning it’s enabled by default.

The associated variable CVarPreprocessedJobCache interacts directly with r.ShaderCompiler.PreprocessedJobCache. They share the same value and are used interchangeably in the code.

Developers should be aware that when this variable is enabled, it affects how shader compilation jobs are processed and how their input hashes are generated. Specifically, the input hashes will be based on the preprocessed source rather than the raw source.

Best practices when using this variable include:

1. Understanding its impact on shader compilation performance and caching behavior.
2. Considering its effect on the development and iteration cycle, especially when working on shaders.
3. Being aware of its potential impact on the size and content of shader caches.

Regarding the associated variable CVarPreprocessedJobCache:

The purpose of CVarPreprocessedJobCache is to provide a programmatic way to access and control the r.ShaderCompiler.PreprocessedJobCache setting within C++ code.

This variable is used directly in the shader compilation process, specifically in the GlobalBeginCompileShader function. When enabled, it sets the bCachePreprocessed flag on shader compiler input, indicating that the preprocessed version of the shader should be cached.

The value of CVarPreprocessedJobCache is set automatically based on the r.ShaderCompiler.PreprocessedJobCache console variable.

Developers should be aware that changes to CVarPreprocessedJobCache will directly affect the shader compilation process. It’s important to understand its implications on compilation time, cache size, and potentially shader behavior if preprocessing introduces any unexpected changes.

Best practices for using CVarPreprocessedJobCache include:

1. Using it consistently with r.ShaderCompiler.PreprocessedJobCache to avoid confusion.
2. Considering its impact on shader compilation performance in different scenarios (development, shipping, etc.).
3. Monitoring its effects on cache sizes and compilation times when enabled or disabled.

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

Scope: file

Source code excerpt:

static TAutoConsoleVariable<bool> CVarPreprocessedJobCache(
	TEXT("r.ShaderCompiler.PreprocessedJobCache"),
	true,
	TEXT("If enabled will shader compile jobs will be preprocessed at submission time in the cook process (when the job is queued) and generate job input hashes based on preprocessed source."),
	ECVF_Default
);

static TAutoConsoleVariable<bool> CVarJobCacheDDC(

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/Shader.cpp:2228

Scope (from outer to inner):

file
function     void ShaderMapAppendKeyString

Source code excerpt:

	{
		static const auto CVar = IConsoleManager::Get().FindTConsoleVariableDataBool(TEXT("r.ShaderCompiler.PreprocessedJobCache"));
		if (CVar && CVar->GetValueOnAnyThread())
		{
			KeyString += TEXT("_PJC");
		}
	}

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<bool> CVarPreprocessedJobCache(
	TEXT("r.ShaderCompiler.PreprocessedJobCache"),
	true,
	TEXT("If enabled will shader compile jobs will be preprocessed at submission time in the cook process (when the job is queued) and generate job input hashes based on preprocessed source."),
	ECVF_Default
);

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

Scope (from outer to inner):

file
function     void GlobalBeginCompileShader

Source code excerpt:

	Format->ModifyShaderCompilerInput(Input);

	if (ShaderCompiler::IsJobCacheEnabled() && CVarPreprocessedJobCache.GetValueOnAnyThread())
	{
		Input.bCachePreprocessed = true;
	}

	// Allow the GBuffer and other shader defines to cause dependend environment changes, but minimizing the #ifdef magic in the shaders, which
	// is nearly impossible to debug when it goes wrong.