NumUnusedShaderCompilingThreadsDuringGame

NumUnusedShaderCompilingThreadsDuringGame

#Overview

name: NumUnusedShaderCompilingThreadsDuringGame

The value of this variable can be defined or overridden in .ini config files. 1 .ini config file referencing this setting variable.

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of NumUnusedShaderCompilingThreadsDuringGame is to control the number of CPU threads that should remain unused for shader compilation during gameplay. This setting is part of Unreal Engine’s shader compilation system, which is a critical component of the rendering pipeline.

This setting variable is primarily used by the shader compiler subsystem within Unreal Engine’s rendering module. It’s specifically referenced in the ShaderCompiler.cpp file, which is part of the Engine’s runtime.

The value of this variable is set from the game’s configuration file (GEngineIni) in the “DevOptions.Shaders” section. It’s read using the GConfig->GetInt() function.

NumUnusedShaderCompilingThreadsDuringGame interacts with several other variables:

  1. NumUnusedShaderCompilingThreads
  2. NumVirtualCores
  3. NumShaderCompilingThreadsDuringGame

Developers must be aware that this variable directly affects the performance balance between shader compilation and gameplay. Setting it too high might result in slower shader compilation, while setting it too low could potentially impact game performance.

Best practices when using this variable include:

  1. Adjusting it based on the target hardware specifications. For machines with more cores, you can afford to leave more threads unused for shader compilation.
  2. Consider the game’s requirements. If your game requires frequent shader compilation during gameplay, you might want to allow more threads for compilation.
  3. Test different values to find the optimal balance between shader compilation speed and game performance.
  4. For machines with 4 or fewer cores, the engine automatically adjusts to prioritize compilation latency over editor performance.
  5. Keep in mind that on build machines, all cores may be used for shader compiling regardless of this setting.

#Setting Variables

#References In INI files

Location: <Workspace>/Engine/Config/BaseEngine.ini:1954, section: [DevOptions.Shaders]

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

Scope (from outer to inner):

file
function     void FShaderCompilingManager::CalculateNumberOfCompilingThreads

Source code excerpt:

	verify(GConfig->GetInt(TEXT("DevOptions.Shaders"), TEXT("NumUnusedShaderCompilingThreads"), NumUnusedShaderCompilingThreads, GEngineIni));

	int32 NumUnusedShaderCompilingThreadsDuringGame;
	verify(GConfig->GetInt(TEXT("DevOptions.Shaders"), TEXT("NumUnusedShaderCompilingThreadsDuringGame"), NumUnusedShaderCompilingThreadsDuringGame, GEngineIni));

	int32 ShaderCompilerCoreCountThreshold;
	verify(GConfig->GetInt(TEXT("DevOptions.Shaders"), TEXT("ShaderCompilerCoreCountThreshold"), ShaderCompilerCoreCountThreshold, GEngineIni));

	bool bForceUseSCWMemoryPressureLimits = false;
	GConfig->GetBool(TEXT("DevOptions.Shaders"), TEXT("bForceUseSCWMemoryPressureLimits"), bForceUseSCWMemoryPressureLimits, GEngineIni);

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

Scope (from outer to inner):

file
function     void FShaderCompilingManager::CalculateNumberOfCompilingThreads

Source code excerpt:


		NumUnusedShaderCompilingThreads = FMath::CeilToInt(NumVirtualCores * PercentageUnusedShaderCompilingThreads);
		NumUnusedShaderCompilingThreadsDuringGame = NumUnusedShaderCompilingThreads;
	}

	// Use all the cores on the build machines.
	if (GForceAllCoresForShaderCompiling != 0)
	{
		NumUnusedShaderCompilingThreads = 0;

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

Scope (from outer to inner):

file
function     void FShaderCompilingManager::CalculateNumberOfCompilingThreads

Source code excerpt:


	// Make sure there's at least one worker allowed to be active when compiling during the game
	NumShaderCompilingThreadsDuringGame = (bAllowCompilingThroughWorkers && NumVirtualCores > NumUnusedShaderCompilingThreadsDuringGame) ? (NumVirtualCores - NumUnusedShaderCompilingThreadsDuringGame) : 1;

	// On machines with few cores, each core will have a massive impact on compile time, so we prioritize compile latency over editor performance during the build
	if (NumVirtualCores <= 4)
	{
		NumShaderCompilingThreads = NumVirtualCores - 1;
		NumShaderCompilingThreadsDuringGame = NumVirtualCores - 1;