a.ParallelAnimUpdate

a.ParallelAnimUpdate

#Overview

name: a.ParallelAnimUpdate

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

It is referenced in 4 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of a.ParallelAnimUpdate is to control whether animation updates, including blend tree updates, native updates, asset players, and montages, are processed on worker threads or on the game thread in Unreal Engine 5.

This setting variable is primarily used by the animation system within Unreal Engine’s runtime. It’s referenced in the SkeletalMeshComponent and AnimInstance modules, which are core parts of the engine’s animation pipeline.

The value of this variable is set as a console variable, with a default value of 1 (enabled). It can be changed at runtime through the console or programmatically.

This variable interacts closely with several other animation-related variables, including:

  1. CVarUseParallelAnimationEvaluation
  2. CVarForceUseParallelAnimUpdate
  3. CVarUseParallelAnimationInterpolation

Developers should be aware that this variable affects performance and thread utilization. When enabled (value != 0), it allows for parallel processing of animations, which can improve performance, especially in scenarios with many animated objects.

Best practices for using this variable include:

  1. Testing performance with both parallel and non-parallel configurations to determine the optimal setting for your specific game.
  2. Consider disabling it for debugging purposes, as parallel execution can make debugging more challenging.
  3. Be aware of potential thread safety issues when enabling parallel animation updates, especially if custom animation code interacts with other game systems.

Regarding the associated variable CVarUseParallelAnimUpdate:

The purpose of CVarUseParallelAnimUpdate is the same as a.ParallelAnimUpdate. It’s an internal representation of the console variable within the C++ code.

This variable is used directly in the AnimInstance module to determine whether parallel animation updates should be performed. It’s checked in the NeedsImmediateUpdate function of the UAnimInstance class to decide if immediate (non-parallel) updates are required.

The value of CVarUseParallelAnimUpdate is set by the console variable system and can be accessed using the GetValueOnGameThread() method.

Developers should be aware that this variable is used in conjunction with other factors (like debugging state and delta time) to determine the update behavior of animations.

Best practices for using CVarUseParallelAnimUpdate include:

  1. Use it in conjunction with the other parallel animation variables for consistent behavior.
  2. Be cautious when modifying its value at runtime, as it can affect the performance and behavior of the entire animation system.
  3. When implementing custom animation logic, consider checking this variable to maintain consistency with the engine’s parallelization decisions.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/SkeletalMeshComponent.cpp:53

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarUseParallelAnimationEvaluation(TEXT("a.ParallelAnimEvaluation"), 1, TEXT("If 1, animation evaluation will be run across the task graph system. If 0, evaluation will run purely on the game thread"));
TAutoConsoleVariable<int32> CVarUseParallelAnimUpdate(TEXT("a.ParallelAnimUpdate"), 1, TEXT("If != 0, then we update animation blend tree, native update, asset players and montages (is possible) on worker threads."));
TAutoConsoleVariable<int32> CVarForceUseParallelAnimUpdate(TEXT("a.ForceParallelAnimUpdate"), 0, TEXT("If != 0, then we update animations on worker threads regardless of the setting on the project or anim blueprint."));
TAutoConsoleVariable<int32> CVarUseParallelAnimationInterpolation(TEXT("a.ParallelAnimInterpolation"), 1, TEXT("If 1, animation interpolation will be run across the task graph system. If 0, interpolation will run purely on the game thread"));

static TAutoConsoleVariable<float> CVarStallParallelAnimation(
	TEXT("CriticalPathStall.ParallelAnimation"),
	0.0f,

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Animation/AnimInstance.cpp:87

Scope: file

Source code excerpt:

#define LOCTEXT_NAMESPACE "AnimInstance"

extern TAutoConsoleVariable<int32> CVarUseParallelAnimUpdate;
extern TAutoConsoleVariable<int32> CVarUseParallelAnimationEvaluation;
extern TAutoConsoleVariable<int32> CVarForceUseParallelAnimUpdate;

ENGINE_API float RK4_SPRING_INTERPOLATOR_UPDATE_RATE = 60.f;
static FAutoConsoleVariableRef CVarRK4SpringInterpolatorUpdateRate(TEXT("p.RK4SpringInterpolator.UpdateRate"), RK4_SPRING_INTERPOLATOR_UPDATE_RATE, TEXT("RK4 Spring Interpolator's rate of update"), ECVF_Default);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Animation/AnimInstance.cpp:794

Scope (from outer to inner):

file
function     bool UAnimInstance::NeedsImmediateUpdate

Source code excerpt:

		(Blueprint && Blueprint->GetObjectBeingDebugged() == this) ||
#endif
		CVarUseParallelAnimUpdate.GetValueOnGameThread() == 0 ||
		CVarUseParallelAnimationEvaluation.GetValueOnGameThread() == 0 ||
		!bUseParallelUpdateAnimation ||
		DeltaSeconds == 0.0f;
}

bool UAnimInstance::NeedsUpdate() const

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/Components/SkeletalMeshComponent.cpp:53

Scope: file

Source code excerpt:


TAutoConsoleVariable<int32> CVarUseParallelAnimationEvaluation(TEXT("a.ParallelAnimEvaluation"), 1, TEXT("If 1, animation evaluation will be run across the task graph system. If 0, evaluation will run purely on the game thread"));
TAutoConsoleVariable<int32> CVarUseParallelAnimUpdate(TEXT("a.ParallelAnimUpdate"), 1, TEXT("If != 0, then we update animation blend tree, native update, asset players and montages (is possible) on worker threads."));
TAutoConsoleVariable<int32> CVarForceUseParallelAnimUpdate(TEXT("a.ForceParallelAnimUpdate"), 0, TEXT("If != 0, then we update animations on worker threads regardless of the setting on the project or anim blueprint."));
TAutoConsoleVariable<int32> CVarUseParallelAnimationInterpolation(TEXT("a.ParallelAnimInterpolation"), 1, TEXT("If 1, animation interpolation will be run across the task graph system. If 0, interpolation will run purely on the game thread"));

static TAutoConsoleVariable<float> CVarStallParallelAnimation(
	TEXT("CriticalPathStall.ParallelAnimation"),
	0.0f,