Sequencer.ThreadedEvaluation.EntityThreshold

Sequencer.ThreadedEvaluation.EntityThreshold

#Overview

name: Sequencer.ThreadedEvaluation.EntityThreshold

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 Sequencer.ThreadedEvaluation.EntityThreshold is to define a threshold for the number of entities that need to exist in the Sequencer system to justify using threaded evaluation.

This setting variable is primarily used in the MovieScene module of Unreal Engine, specifically within the entity system of the Sequencer. The Sequencer is a powerful tool in Unreal Engine for creating cinematic sequences and animations.

The value of this variable is set through the Unreal Engine’s console variable system. It’s defined as an FAutoConsoleVariableRef, which means it can be adjusted at runtime through console commands or configuration files.

The associated variable GThreadedEvaluationEntityThreshold interacts directly with Sequencer.ThreadedEvaluation.EntityThreshold. They share the same value, with GThreadedEvaluationEntityThreshold being the actual integer variable used in the code.

Developers must be aware that this variable affects the performance and behavior of the Sequencer system. If the number of entities in the Sequencer exceeds this threshold, the system will switch to threaded evaluation, which can improve performance for complex sequences but may also introduce additional complexity.

Best practices when using this variable include:

  1. Adjusting it based on the complexity of your sequences and the capabilities of your target hardware.
  2. Profiling your sequences with different threshold values to find the optimal setting.
  3. Being cautious when lowering the threshold, as excessive threading for simple sequences could potentially harm performance.

Regarding the associated variable GThreadedEvaluationEntityThreshold:

The purpose of GThreadedEvaluationEntityThreshold is to serve as the actual integer value used in the code to determine when to switch to threaded evaluation in the Sequencer system.

This variable is used directly in the MovieScene module, specifically in the FEntityManager class. It’s used in the ComputeThreadingModel() function to determine whether to use task graph threading or no threading for entity evaluation.

The value of GThreadedEvaluationEntityThreshold is set by the console variable system through Sequencer.ThreadedEvaluation.EntityThreshold.

It interacts with another variable, GThreadedEvaluationAllocationThreshold, in determining whether to use threaded evaluation. The system will use threading if either the number of entity allocations or the number of entity locations exceeds their respective thresholds.

Developers should be aware that this variable directly affects the performance characteristics of the Sequencer system. Changing its value can significantly impact how the system behaves with different numbers of entities.

Best practices for using GThreadedEvaluationEntityThreshold include:

  1. Coordinating any changes with the Sequencer.ThreadedEvaluation.EntityThreshold console variable.
  2. Considering the interaction with GThreadedEvaluationAllocationThreshold when optimizing performance.
  3. Testing thoroughly after any adjustments to ensure desired performance across various sequence complexities.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/EntitySystem/MovieSceneEntityManager.cpp:47

Scope (from outer to inner):

file
namespace    UE
namespace    MovieScene

Source code excerpt:

int32 GThreadedEvaluationEntityThreshold = 256;
FAutoConsoleVariableRef CVarThreadedEvaluationEntityThreshold(
	TEXT("Sequencer.ThreadedEvaluation.EntityThreshold"),
	GThreadedEvaluationEntityThreshold,
	TEXT("(Default: 256) Defines the number of entities that need to exist to justify threaded evaluation.\n"),
	ECVF_Default
);

FEntityManager* GEntityManagerForDebuggingVisualizers = nullptr;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/EntitySystem/MovieSceneEntityManager.cpp:45

Scope (from outer to inner):

file
namespace    UE
namespace    MovieScene

Source code excerpt:

	ECVF_Default
);
int32 GThreadedEvaluationEntityThreshold = 256;
FAutoConsoleVariableRef CVarThreadedEvaluationEntityThreshold(
	TEXT("Sequencer.ThreadedEvaluation.EntityThreshold"),
	GThreadedEvaluationEntityThreshold,
	TEXT("(Default: 256) Defines the number of entities that need to exist to justify threaded evaluation.\n"),
	ECVF_Default
);

FEntityManager* GEntityManagerForDebuggingVisualizers = nullptr;

#Loc: <Workspace>/Engine/Source/Runtime/MovieScene/Private/EntitySystem/MovieSceneEntityManager.cpp:554

Scope (from outer to inner):

file
namespace    UE
namespace    MovieScene
function     EEntityThreadingModel FEntityManager::ComputeThreadingModel

Source code excerpt:

	const bool bShouldThread = bCanThread &&
		(EntityAllocations.Num() >= GThreadedEvaluationAllocationThreshold ||
		EntityLocations.Num() >= GThreadedEvaluationEntityThreshold);

	return bShouldThread ? EEntityThreadingModel::TaskGraph : EEntityThreadingModel::NoThreading;
}

EEntityThreadingModel FEntityManager::GetThreadingModel() const
{