r.ShaderPipelineCache.BackgroundBatchTime

r.ShaderPipelineCache.BackgroundBatchTime

#Overview

name: r.ShaderPipelineCache.BackgroundBatchTime

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

• type: Var
• help: The target time (in ms) to spend precompiling each frame when in the background or 0.0 to disable. When precompiling is faster the batch size will grow and when slower will shrink to attempt to occupy the full amount. Defaults to 0.0 (off).

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ShaderPipelineCache.BackgroundBatchTime is to control the amount of time spent precompiling shaders in the background for the shader pipeline cache system in Unreal Engine 5’s rendering subsystem.

This setting variable is primarily used by the RenderCore module of Unreal Engine, specifically within the shader pipeline cache system. It’s part of the rendering optimization features that aim to improve performance by precompiling shaders.

The value of this variable is set through the Unreal Engine console variable system. It’s defined as a TAutoConsoleVariable with a default value of 0.0f, which means it’s initially disabled.

This variable interacts closely with CVarPSOFileCacheBackgroundBatchSize, which controls the batch size for background precompilation. Together, these variables determine how aggressively the engine precompiles shaders in the background.

Developers must be aware that this variable affects performance and resource usage. Setting a non-zero value will cause the engine to spend time precompiling shaders in the background, which can improve runtime performance but may increase CPU usage when the game is not in focus.

Best practices for using this variable include:

1. Start with the default value (0.0f) and only increase it if shader compilation hitches are a problem.
2. Monitor CPU usage and adjust the value to find a balance between precompilation benefits and resource usage.
3. Consider different values for development and shipping builds.

The associated variable CVarPSOFileCacheBackgroundBatchTime is actually the console variable that directly controls this setting. It’s defined in the same file and is used to set the BatchTime member of the FShaderPipelineCache class. This variable is used in the SetBatchMode function to update the batch time when the batch mode changes, and in the FShaderPipelineCache constructor to initialize the batch time based on the current batch mode.

When using CVarPSOFileCacheBackgroundBatchTime, developers should consider the same points as for r.ShaderPipelineCache.BackgroundBatchTime, as they are effectively the same setting. The console variable allows for runtime adjustment of this setting, which can be useful for performance tuning and debugging.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderPipelineCache.cpp:76

Scope: file

Source code excerpt:

															 );
static TAutoConsoleVariable<float> CVarPSOFileCacheBackgroundBatchTime(
														  TEXT("r.ShaderPipelineCache.BackgroundBatchTime"),
														  0.0f,
														  TEXT("The target time (in ms) to spend precompiling each frame when in the background or 0.0 to disable. When precompiling is faster the batch size will grow and when slower will shrink to attempt to occupy the full amount. Defaults to 0.0 (off)."),
														  ECVF_Default | ECVF_RenderThreadSafe
														  );
static TAutoConsoleVariable<float> CVarPSOFileCacheBatchTime(
														   TEXT("r.ShaderPipelineCache.BatchTime"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderPipelineCache.cpp:75

Scope: file

Source code excerpt:

															 ECVF_Default | ECVF_RenderThreadSafe
															 );
static TAutoConsoleVariable<float> CVarPSOFileCacheBackgroundBatchTime(
														  TEXT("r.ShaderPipelineCache.BackgroundBatchTime"),
														  0.0f,
														  TEXT("The target time (in ms) to spend precompiling each frame when in the background or 0.0 to disable. When precompiling is faster the batch size will grow and when slower will shrink to attempt to occupy the full amount. Defaults to 0.0 (off)."),
														  ECVF_Default | ECVF_RenderThreadSafe
														  );
static TAutoConsoleVariable<float> CVarPSOFileCacheBatchTime(

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderPipelineCache.cpp:788

Scope (from outer to inner):

file
function     void FShaderPipelineCache::SetBatchMode

Source code excerpt:

			{
				ShaderPipelineCache->BatchSize = CVarPSOFileCacheBackgroundBatchSize.GetValueOnAnyThread();
				ShaderPipelineCache->BatchTime = CVarPSOFileCacheBackgroundBatchTime.GetValueOnAnyThread();
				break;
			}
		}
		UE_CLOG(PreviousBatchSize != ShaderPipelineCache->BatchSize || PreviousBatchTime != ShaderPipelineCache->BatchTime, LogRHI, Log,
			TEXT("ShaderPipelineCache: Batch mode changed (%d): Size: %d -> %d, Time: %f -> %f"), (uint32)Mode, PreviousBatchSize, ShaderPipelineCache->BatchSize, PreviousBatchTime, ShaderPipelineCache->BatchTime);
	}

#Loc: <Workspace>/Engine/Source/Runtime/RenderCore/Private/ShaderPipelineCache.cpp:1583

Scope (from outer to inner):

file
function     FShaderPipelineCache::FShaderPipelineCache

Source code excerpt:

		case 2:
			BatchSize = CVarPSOFileCacheBackgroundBatchSize.GetValueOnAnyThread();
			BatchTime = CVarPSOFileCacheBackgroundBatchTime.GetValueOnAnyThread();
			break;
		case 1:
		default:
			BatchSize = CVarPSOFileCacheBatchSize.GetValueOnAnyThread();
			BatchTime = CVarPSOFileCacheBatchTime.GetValueOnAnyThread();
			break;