r.DeferUpdateRenderStates

r.DeferUpdateRenderStates

#Overview

name: r.DeferUpdateRenderStates

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.DeferUpdateRenderStates is to control the timing of render state updates for material parameter collections in Unreal Engine 5. This setting is primarily used in the rendering system, specifically for optimizing the update process of material parameter collections.

The Engine module relies on this setting variable, particularly within the Materials subsystem. This can be seen from the file location “Engine/Source/Runtime/Engine/Private/Materials/ParameterCollection.cpp”.

The value of this variable is set through the console variable system in Unreal Engine. It’s initialized with a default value of 1 (true) and can be changed at runtime using console commands or through project settings.

The associated variable GDeferUpdateRenderStates directly interacts with r.DeferUpdateRenderStates. They share the same value and are used interchangeably in the code.

Developers must be aware that when this variable is set to 1 (true), the engine will defer updating the render states of material parameter collections until a rendering command requires them to be up-to-date. This can improve performance by reducing the number of updates, especially when multiple parameter changes occur within a single frame.

Best practices when using this variable include:

  1. Keep it enabled (set to 1) for most scenarios, as it improves performance.
  2. If immediate updates are required for specific use cases, consider temporarily disabling it or forcing updates using the bRecreateUniformBuffer parameter.
  3. Be mindful of the potential delay in render state updates when debugging material parameter collection behavior.

Regarding the associated variable GDeferUpdateRenderStates:

The purpose of GDeferUpdateRenderStates is to serve as the C++ representation of the r.DeferUpdateRenderStates console variable. It’s used directly in the C++ code to control the deferral of render state updates.

This variable is used in the Engine module, specifically in the Materials subsystem, as evident from its usage in the UMaterialParameterCollectionInstance::UpdateRenderState function.

The value of GDeferUpdateRenderStates is set through the console variable system, mirroring the value of r.DeferUpdateRenderStates.

It directly interacts with the logic controlling render state updates for material parameter collections.

Developers should be aware that modifying GDeferUpdateRenderStates directly in C++ code is not recommended. Instead, they should use the console variable r.DeferUpdateRenderStates to change its value.

Best practices for GDeferUpdateRenderStates include:

  1. Treat it as a read-only variable in most cases, relying on the console variable system for modifications.
  2. When implementing new features or optimizations related to material parameter collections, consider the current state of this variable to ensure consistent behavior with the engine’s deferral system.
  3. Use it in conditional statements to determine whether to perform immediate updates or defer them, following the pattern established in the UpdateRenderState function.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/ParameterCollection.cpp:14

Scope: file

Source code excerpt:

int32 GDeferUpdateRenderStates = 1;
FAutoConsoleVariableRef CVarDeferUpdateRenderStates(
	TEXT("r.DeferUpdateRenderStates"),
	GDeferUpdateRenderStates,
	TEXT("Whether to defer updating the render states of material parameter collections when a paramter is changed until a rendering command needs them up to date.  Deferring updates is more efficient because multiple SetVectorParameterValue and SetScalarParameterValue calls in a frame will only result in one update."),
	ECVF_RenderThreadSafe
);

TMultiMap<FGuid, FMaterialParameterCollectionInstanceResource*> GDefaultMaterialParameterCollectionInstances;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/ParameterCollection.cpp:12

Scope: file

Source code excerpt:

#include "Misc/App.h"

int32 GDeferUpdateRenderStates = 1;
FAutoConsoleVariableRef CVarDeferUpdateRenderStates(
	TEXT("r.DeferUpdateRenderStates"),
	GDeferUpdateRenderStates,
	TEXT("Whether to defer updating the render states of material parameter collections when a paramter is changed until a rendering command needs them up to date.  Deferring updates is more efficient because multiple SetVectorParameterValue and SetScalarParameterValue calls in a frame will only result in one update."),
	ECVF_RenderThreadSafe
);

TMultiMap<FGuid, FMaterialParameterCollectionInstanceResource*> GDefaultMaterialParameterCollectionInstances;

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Materials/ParameterCollection.cpp:763

Scope (from outer to inner):

file
function     void UMaterialParameterCollectionInstance::UpdateRenderState

Source code excerpt:

	World->SetMaterialParameterCollectionInstanceNeedsUpdate();

	if (!GDeferUpdateRenderStates || bRecreateUniformBuffer)
	{
		DeferredUpdateRenderState(bRecreateUniformBuffer);
	}
}

void UMaterialParameterCollectionInstance::DeferredUpdateRenderState(bool bRecreateUniformBuffer)