r.AllowCachedUniformExpressions

r.AllowCachedUniformExpressions

#Overview

name: r.AllowCachedUniformExpressions

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

• type: Var
• help: Allow uniform expressions to be cached.

It is referenced in 5 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.AllowCachedUniformExpressions is to control whether uniform expressions in material shaders can be cached. This setting is primarily used in the rendering system of Unreal Engine 5.

The Unreal Engine subsystem that relies on this setting variable is the Renderer module, specifically the material shader system. This can be seen from the file locations where the variable is referenced, all within the Renderer module.

The value of this variable is set through a console variable (CVar) system. It’s initialized to true by default, as seen in the associated variable bAllowCachedUniformExpressions.

The associated variable bAllowCachedUniformExpressions interacts directly with r.AllowCachedUniformExpressions. They share the same value, with bAllowCachedUniformExpressions being used in the actual code logic.

Developers must be aware that this variable affects shader performance and memory usage. When enabled, it allows for caching of uniform expressions, which can improve performance by reducing redundant calculations. However, it may also increase memory usage.

Best practices when using this variable include:

1. Keep it enabled (true) for better performance in most scenarios.
2. Consider disabling it if memory usage becomes a concern or if you need to ensure that uniform expressions are always re-evaluated.
3. Be cautious when modifying this variable during runtime, as it may affect shader behavior and performance.

Regarding the associated variable bAllowCachedUniformExpressions:

• Its purpose is to serve as the actual boolean flag used in the code to determine whether caching of uniform expressions is allowed.
• It’s used within the FMaterialShader class in the Renderer module.
• Its value is set by the r.AllowCachedUniformExpressions console variable.
• It interacts with the UniformExpressionCache system, controlling whether caching occurs.
• Developers should be aware that this variable directly affects the behavior of material shaders and their performance.
• Best practices include not modifying this variable directly, but instead using the r.AllowCachedUniformExpressions console variable to control its value.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShaderBaseClasses.cpp:23

Scope: file

Source code excerpt:

/** Console variable ref to toggle cached uniform expressions. */
FAutoConsoleVariableRef FMaterialShader::CVarAllowCachedUniformExpressions(
	TEXT("r.AllowCachedUniformExpressions"),
	bAllowCachedUniformExpressions,
	TEXT("Allow uniform expressions to be cached."),
	ECVF_RenderThreadSafe);

void FMeshMaterialShaderElementData::InitializeMeshMaterialData()
{

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShaderBaseClasses.cpp:19

Scope: file

Source code excerpt:

/** If true, cached uniform expressions are allowed. */
int32 FMaterialShader::bAllowCachedUniformExpressions = true;

/** Console variable ref to toggle cached uniform expressions. */
FAutoConsoleVariableRef FMaterialShader::CVarAllowCachedUniformExpressions(
	TEXT("r.AllowCachedUniformExpressions"),
	bAllowCachedUniformExpressions,
	TEXT("Allow uniform expressions to be cached."),
	ECVF_RenderThreadSafe);

void FMeshMaterialShaderElementData::InitializeMeshMaterialData()
{
	FadeUniformBuffer = GDistanceCullFadedInUniformBuffer.GetUniformBufferRHI();

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShaderBaseClasses.cpp:275

Scope (from outer to inner):

file
function     void FMaterialShader::SetParameters

Source code excerpt:

#if !(UE_BUILD_TEST || UE_BUILD_SHIPPING || !WITH_EDITOR)
	if (bAllowCachedUniformExpressions)
	{
		// UE-46061 - Workaround for a rare crash with an outdated cached shader map
		if (UniformExpressionCache->CachedUniformExpressionShaderMap != ShaderMap)
		{
			UMaterialInterface* MtlInterface = Material.GetMaterialInterface();
			UMaterialInterface* ProxyInterface = MaterialRenderProxy->GetMaterialInterface();

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/ShaderBaseClasses.cpp:297

Scope (from outer to inner):

file
function     void FMaterialShader::SetParameters

Source code excerpt:

#endif

	if (!bAllowCachedUniformExpressions || UniformExpressionCache->CachedUniformExpressionShaderMap != ShaderMap)
	{
		FMaterialRenderContext MaterialRenderContext(MaterialRenderProxy, Material, &View);
		bUniformExpressionCacheNeedsDelete = true;
		UniformExpressionCache = new FUniformExpressionCache();
		MaterialRenderProxy->EvaluateUniformExpressions(FRHICommandListImmediate::Get(), *UniformExpressionCache, MaterialRenderContext);
	}

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Public/MaterialShader.h:117

Scope (from outer to inner):

file
class        class FMaterialShader : public FShader

Source code excerpt:

private:
	/** If true, cached uniform expressions are allowed. */
	static RENDERER_API int32 bAllowCachedUniformExpressions;
	/** Console variable ref to toggle cached uniform expressions. */
	static RENDERER_API FAutoConsoleVariableRef CVarAllowCachedUniformExpressions;

#if !(UE_BUILD_TEST || UE_BUILD_SHIPPING || !WITH_EDITOR)
	RENDERER_API void VerifyExpressionAndShaderMaps(const FMaterialRenderProxy* MaterialRenderProxy, const FMaterial& Material, const FUniformExpressionCache* UniformExpressionCache) const;
#endif