r.UniformExpressionCacheAsyncUpdates

r.UniformExpressionCacheAsyncUpdates

#Overview

name: r.UniformExpressionCacheAsyncUpdates

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.UniformExpressionCacheAsyncUpdates is to control whether async updates of uniform expression caches are allowed in the rendering system of Unreal Engine 5.

This setting variable is primarily used in the rendering system, specifically in the material rendering subsystem. It is referenced in the Engine module, within the Materials subdirectory.

The value of this variable is set through the console variable system. It is initialized with a default value of 1, indicating that async updates are enabled by default.

The associated variable GUniformExpressionCacheAsyncUpdates interacts directly with r.UniformExpressionCacheAsyncUpdates. They share the same value, with GUniformExpressionCacheAsyncUpdates being the actual integer variable used in the code.

Developers must be aware that this variable affects the performance and behavior of uniform expression cache updates. When enabled (value > 0), it allows for asynchronous updates, which can potentially improve performance by allowing these updates to occur in parallel with other operations.

Best practices when using this variable include:

  1. Leave it enabled (default value of 1) unless specific issues are encountered.
  2. If experiencing rendering artifacts or inconsistencies, consider disabling it (set to 0) for debugging purposes.
  3. Profile the application with both enabled and disabled states to determine the optimal setting for your specific use case.

Regarding the associated variable GUniformExpressionCacheAsyncUpdates:

The purpose of GUniformExpressionCacheAsyncUpdates is to serve as the actual integer variable that controls the behavior of async updates for uniform expression caches in the code.

This variable is used directly in the Engine module, specifically in the material rendering system. It’s checked in the IsEnabled() function of the FUniformExpressionCacheAsyncUpdateTask class to determine if async updates should be performed.

The value of GUniformExpressionCacheAsyncUpdates is set through the console variable system, linked to r.UniformExpressionCacheAsyncUpdates.

Other conditions interact with this variable in determining whether async updates are enabled, such as the ReferenceCount and the state of GRHICommandList.Bypass().

Developers should be aware that this variable is used in conjunction with other conditions to determine if async updates are enabled. It’s not a simple on/off switch but part of a more complex decision process.

Best practices include:

  1. Avoid directly modifying GUniformExpressionCacheAsyncUpdates in code. Instead, use the console variable r.UniformExpressionCacheAsyncUpdates to change its value.
  2. When debugging issues related to uniform expression cache updates, check the value of this variable along with the other conditions in the IsEnabled() function.
  3. Consider the impact on both performance and rendering correctness when modifying this variable’s value.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/MaterialRenderProxy.cpp:27

Scope: file

Source code excerpt:

int32 GUniformExpressionCacheAsyncUpdates = 1;
FAutoConsoleVariableRef CVarUniformExpressionCacheAsyncUpdates(
	TEXT("r.UniformExpressionCacheAsyncUpdates"),
	GUniformExpressionCacheAsyncUpdates,
	TEXT("Whether to allow async updates of uniform expression caches."),
	ECVF_RenderThreadSafe);

FUniformExpressionCache::~FUniformExpressionCache()
{

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/MaterialRenderProxy.cpp:25

Scope: file

Source code excerpt:

);

int32 GUniformExpressionCacheAsyncUpdates = 1;
FAutoConsoleVariableRef CVarUniformExpressionCacheAsyncUpdates(
	TEXT("r.UniformExpressionCacheAsyncUpdates"),
	GUniformExpressionCacheAsyncUpdates,
	TEXT("Whether to allow async updates of uniform expression caches."),
	ECVF_RenderThreadSafe);

FUniformExpressionCache::~FUniformExpressionCache()
{
	ResetAllocatedVTs();

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/MaterialRenderProxy.cpp:58

Scope (from outer to inner):

file
class        class FUniformExpressionCacheAsyncUpdateTask
function     bool IsEnabled

Source code excerpt:

	bool IsEnabled() const
	{
		return ReferenceCount > 0 && GUniformExpressionCacheAsyncUpdates > 0 && !GRHICommandList.Bypass();
	}

	void SetTask(const UE::Tasks::FTask& InTask)
	{
		check(IsEnabled());
		Task = InTask;