r.DeferUniformExpressionCaching

r.DeferUniformExpressionCaching

#Overview

name: r.DeferUniformExpressionCaching

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.DeferUniformExpressionCaching is to control the timing of uniform expression caching in Unreal Engine’s rendering system. This setting variable is primarily used in the material rendering subsystem.

The Unreal Engine rendering system, specifically the material rendering module, relies on this setting variable. It is used to optimize the performance of material parameter updates by deferring the caching of uniform expressions.

The value of this variable is set through the console variable system. It is initialized with a default value of 1 (enabled) and can be changed at runtime using console commands.

The r.DeferUniformExpressionCaching variable interacts directly with the GDeferUniformExpressionCaching global variable. They share the same value, with r.DeferUniformExpressionCaching being the console-accessible name and GDeferUniformExpressionCaching being the C++ variable used in the code.

Developers must be aware that enabling this variable (which is the default) can improve performance by reducing the number of uniform expression updates. When enabled, multiple SetVectorParameterValue calls in a single frame will result in only one update, which is more efficient.

Best practices when using this variable include:

  1. Leaving it enabled (default value of 1) for most scenarios to benefit from the performance optimization.
  2. If experiencing issues with material parameter updates not being applied immediately, consider disabling this feature temporarily for debugging purposes.
  3. Be cautious when changing this value in shipping builds, as it may affect rendering performance.

Regarding the associated variable GDeferUniformExpressionCaching:

The purpose of GDeferUniformExpressionCaching is to serve as the internal C++ representation of the r.DeferUniformExpressionCaching console variable. It is used directly in the engine’s C++ code to control the behavior of uniform expression caching.

This variable is used in the material rendering system, specifically in the FMaterialRenderProxy class, to determine whether to defer the caching of uniform expressions.

The value of GDeferUniformExpressionCaching is set through the console variable system, mirroring the value of r.DeferUniformExpressionCaching.

GDeferUniformExpressionCaching interacts with the FMaterialRenderProxy::CacheUniformExpressions function, controlling whether immediate caching occurs or if it’s deferred.

Developers should be aware that this variable directly affects the behavior of material parameter updates and can impact rendering performance.

Best practices for using GDeferUniformExpressionCaching include:

  1. Avoid modifying this variable directly in C++ code; instead, use the r.DeferUniformExpressionCaching console variable to ensure consistency.
  2. When debugging material parameter update issues, check the value of this variable to understand the current caching behavior.
  3. Consider the implications on rendering performance and material parameter update frequency when modifying this variable’s behavior.

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

Scope: file

Source code excerpt:

int32 GDeferUniformExpressionCaching = 1;
FAutoConsoleVariableRef CVarDeferUniformExpressionCaching(
	TEXT("r.DeferUniformExpressionCaching"),
	GDeferUniformExpressionCaching,
	TEXT("Whether to defer caching of uniform expressions until a rendering command needs them up to date.  Deferring updates is more efficient because multiple SetVectorParameterValue calls in a frame will only result in one update."),
	ECVF_RenderThreadSafe
);

int32 GUniformExpressionCacheAsyncUpdates = 1;

#Associated Variable and Callsites

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

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

Scope: file

Source code excerpt:

#endif

int32 GDeferUniformExpressionCaching = 1;
FAutoConsoleVariableRef CVarDeferUniformExpressionCaching(
	TEXT("r.DeferUniformExpressionCaching"),
	GDeferUniformExpressionCaching,
	TEXT("Whether to defer caching of uniform expressions until a rendering command needs them up to date.  Deferring updates is more efficient because multiple SetVectorParameterValue calls in a frame will only result in one update."),
	ECVF_RenderThreadSafe
);

int32 GUniformExpressionCacheAsyncUpdates = 1;
FAutoConsoleVariableRef CVarUniformExpressionCacheAsyncUpdates(

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

Scope (from outer to inner):

file
function     void FMaterialRenderProxy::CacheUniformExpressions

Source code excerpt:

	InvalidateUniformExpressionCache(bRecreateUniformBuffer);

	if (!GDeferUniformExpressionCaching)
	{
		FMaterialRenderProxy::UpdateDeferredCachedUniformExpressions(RHICmdList);
	}
}

void FMaterialRenderProxy::CacheUniformExpressions(bool bRecreateUniformBuffer)