r.AsyncPipelineCompile

r.AsyncPipelineCompile

#Overview

name: r.AsyncPipelineCompile

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

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.AsyncPipelineCompile is to control the asynchronous compilation of Pipeline State Objects (PSOs) in Unreal Engine’s rendering system. It allows developers to fine-tune how PSOs are created and compiled, which can impact rendering performance and load times.

This setting variable is primarily used by the RHI (Rendering Hardware Interface) module of Unreal Engine, specifically within the pipeline state caching system. The RHI is a crucial part of the engine’s rendering subsystem, providing an abstraction layer between the engine and various graphics APIs.

The value of this variable is set through a console variable (CVar) system, which allows it to be changed at runtime. It’s defined as a TAutoConsoleVariable named GCVarAsyncPipelineCompile.

The variable interacts closely with the EPSOCompileAsyncMode enum, which defines the different modes of asynchronous PSO compilation. It also interacts with the GRHISupportsAsyncPipelinePrecompile variable, which indicates whether the current RHI supports asynchronous pipeline precompilation.

Developers should be aware that this variable can significantly impact rendering performance and loading times. Asynchronous compilation can help reduce hitches and improve frame rates, but it may also increase overall load times in some scenarios.

Best practices for using this variable include:

  1. Using the default value (1 - All) for most scenarios, as it provides a good balance of performance and load times.
  2. Consider setting it to 2 (Precompile only) for cases where you want to prioritize precompiled shaders.
  3. Use 3 (Non-precompiled only) if you want to focus on runtime-compiled shaders.
  4. Only set it to 0 (Synchronous compilation) if you’re experiencing specific issues with asynchronous compilation or for debugging purposes.

Regarding the associated variable GCVarAsyncPipelineCompile:

This is the actual console variable that stores the value of r.AsyncPipelineCompile. It’s an instance of TAutoConsoleVariable, which is Unreal Engine’s way of creating a console variable that can be changed at runtime.

The purpose of GCVarAsyncPipelineCompile is to provide a way to access and modify the r.AsyncPipelineCompile setting from C++ code. It’s used internally by the engine to determine the current async compilation mode and adjust behavior accordingly.

This variable is primarily used within the RHI module, specifically in the pipeline state caching system. It’s typically accessed using the GetValueOnAnyThread() method, which returns the current value of the console variable.

Developers should be aware that changes to this variable will immediately affect the engine’s PSO compilation behavior. It’s important to use the provided console command (r.AsyncPipelineCompile) to modify this value rather than attempting to change it directly in code.

Best practices for using GCVarAsyncPipelineCompile include:

  1. Use it for read-only purposes in most cases, relying on the console command for changes.
  2. If you need to modify it programmatically, ensure you understand the implications and use appropriate thread-safe access methods.
  3. Consider caching the value if you need to check it frequently, as calling GetValueOnAnyThread() repeatedly could have a performance impact.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/PipelineStateCache.cpp:123

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> GCVarAsyncPipelineCompile(
	TEXT("r.AsyncPipelineCompile"),
	(int32)EPSOCompileAsyncMode::All,
	TEXT("0 to Create PSOs at the moment they are requested\n")
	TEXT("1 to Create Pipeline State Objects asynchronously(default)\n")
	TEXT("2 to Create Only precompile PSOs asynchronously\n")
	TEXT("3 to Create Only non-precompile PSOs asynchronously")
	,

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/PipelineStateCache.cpp:122

Scope: file

Source code excerpt:

};

static TAutoConsoleVariable<int32> GCVarAsyncPipelineCompile(
	TEXT("r.AsyncPipelineCompile"),
	(int32)EPSOCompileAsyncMode::All,
	TEXT("0 to Create PSOs at the moment they are requested\n")
	TEXT("1 to Create Pipeline State Objects asynchronously(default)\n")
	TEXT("2 to Create Only precompile PSOs asynchronously\n")
	TEXT("3 to Create Only non-precompile PSOs asynchronously")

#Loc: <Workspace>/Engine/Source/Runtime/RHI/Private/PipelineStateCache.cpp:2223

Scope (from outer to inner):

file
function     static bool IsAsyncCompilationAllowed

Source code excerpt:

static bool IsAsyncCompilationAllowed(FRHIComputeCommandList& RHICmdList, bool bIsPrecompileRequest)
{
	const EPSOCompileAsyncMode PSOCompileAsyncMode = (EPSOCompileAsyncMode)GCVarAsyncPipelineCompile.GetValueOnAnyThread();

	const bool bCVarAllowsAsyncCreate = PSOCompileAsyncMode == EPSOCompileAsyncMode::All
		|| (PSOCompileAsyncMode == EPSOCompileAsyncMode::Precompile && bIsPrecompileRequest)
		|| (PSOCompileAsyncMode == EPSOCompileAsyncMode::NonPrecompiled && !bIsPrecompileRequest);

	return GRHISupportsAsyncPipelinePrecompile &&