ControlRig.Hierarchy.TraceAlways

ControlRig.Hierarchy.TraceAlways

#Overview

name: ControlRig.Hierarchy.TraceAlways

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 ControlRig.Hierarchy.TraceAlways is to enable the recording of all transform changes in the Control Rig hierarchy system. This setting variable is primarily used for debugging and performance analysis purposes within the Control Rig plugin of Unreal Engine 5.

This setting variable is utilized by the Control Rig subsystem, specifically within the RigHierarchy module. Based on the callsites, it’s clear that this variable is part of the animation system, particularly the Control Rig plugin used for advanced animation control.

The value of this variable is set as a console variable (CVar) with an initial value of 0. It can be changed at runtime through the console or programmatically.

Several other variables interact with ControlRig.Hierarchy.TraceAlways:

  1. CVarControlRigHierarchyTraceCallstack: Records the callstack for trace entries when ControlRig.Hierarchy.TraceAlways is non-zero.
  2. CVarControlRigHierarchyTracePrecision: Sets the number of digits in a float when tracing hierarchies.
  3. CVarControlRigHierarchyTraceOnSpawn: Sets the number of frames to trace when a new hierarchy is spawned.

Developers must be aware that this variable is primarily intended for debugging purposes. Enabling it in production builds may have performance implications due to the overhead of recording all transform changes.

Best practices when using this variable include:

  1. Only enable it when necessary for debugging or performance analysis.
  2. Be mindful of the performance impact when enabled.
  3. Use in conjunction with other trace-related variables for comprehensive debugging.
  4. Disable in production builds to avoid unnecessary overhead.

The associated variable CVarControlRigHierarchyTraceAlways is the actual console variable implementation of ControlRig.Hierarchy.TraceAlways. It’s an integer variable that determines whether transform changes should be recorded. When its value is non-zero, tracing is enabled.

This variable is used in the IsTracingChanges function of the URigHierarchy class to determine if changes should be traced. It’s important to note that this functionality is only available in editor builds (#if WITH_EDITOR preprocessor condition).

When using CVarControlRigHierarchyTraceAlways, developers should:

  1. Use it for debugging purposes in editor builds.
  2. Be aware that it affects the behavior of the IsTracingChanges function.
  3. Consider the interaction with TraceFramesLeft, another condition for tracing changes.
  4. Remember that changes to this variable will immediately affect the tracing behavior of the Control Rig system.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Animation/ControlRig/Source/ControlRig/Private/Rigs/RigHierarchy.cpp:43

Scope: file

Source code excerpt:


// CVar to record all transform changes 
static TAutoConsoleVariable<int32> CVarControlRigHierarchyTraceAlways(TEXT("ControlRig.Hierarchy.TraceAlways"), 0, TEXT("if nonzero we will record all transform changes."));
static TAutoConsoleVariable<int32> CVarControlRigHierarchyTraceCallstack(TEXT("ControlRig.Hierarchy.TraceCallstack"), 0, TEXT("if nonzero we will record the callstack for any trace entry.\nOnly works if(ControlRig.Hierarchy.TraceEnabled != 0)"));
static TAutoConsoleVariable<int32> CVarControlRigHierarchyTracePrecision(TEXT("ControlRig.Hierarchy.TracePrecision"), 3, TEXT("sets the number digits in a float when tracing hierarchies."));
static TAutoConsoleVariable<int32> CVarControlRigHierarchyTraceOnSpawn(TEXT("ControlRig.Hierarchy.TraceOnSpawn"), 0, TEXT("sets the number of frames to trace when a new hierarchy is spawned"));
TAutoConsoleVariable<bool> CVarControlRigHierarchyEnableRotationOrder(TEXT("ControlRig.Hierarchy.EnableRotationOrder"), true, TEXT("enables the rotation order for controls"));
TAutoConsoleVariable<bool> CVarControlRigHierarchyEnableModules(TEXT("ControlRig.Hierarchy.Modules"), true, TEXT("enables the modular rigging functionality"));
static int32 sRigHierarchyLastTrace = INDEX_NONE;

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Animation/ControlRig/Source/ControlRig/Private/Rigs/RigHierarchy.cpp:43

Scope: file

Source code excerpt:


// CVar to record all transform changes 
static TAutoConsoleVariable<int32> CVarControlRigHierarchyTraceAlways(TEXT("ControlRig.Hierarchy.TraceAlways"), 0, TEXT("if nonzero we will record all transform changes."));
static TAutoConsoleVariable<int32> CVarControlRigHierarchyTraceCallstack(TEXT("ControlRig.Hierarchy.TraceCallstack"), 0, TEXT("if nonzero we will record the callstack for any trace entry.\nOnly works if(ControlRig.Hierarchy.TraceEnabled != 0)"));
static TAutoConsoleVariable<int32> CVarControlRigHierarchyTracePrecision(TEXT("ControlRig.Hierarchy.TracePrecision"), 3, TEXT("sets the number digits in a float when tracing hierarchies."));
static TAutoConsoleVariable<int32> CVarControlRigHierarchyTraceOnSpawn(TEXT("ControlRig.Hierarchy.TraceOnSpawn"), 0, TEXT("sets the number of frames to trace when a new hierarchy is spawned"));
TAutoConsoleVariable<bool> CVarControlRigHierarchyEnableRotationOrder(TEXT("ControlRig.Hierarchy.EnableRotationOrder"), true, TEXT("enables the rotation order for controls"));
TAutoConsoleVariable<bool> CVarControlRigHierarchyEnableModules(TEXT("ControlRig.Hierarchy.Modules"), true, TEXT("enables the modular rigging functionality"));
static int32 sRigHierarchyLastTrace = INDEX_NONE;

#Loc: <Workspace>/Engine/Plugins/Animation/ControlRig/Source/ControlRig/Private/Rigs/RigHierarchy.cpp:4740

Scope (from outer to inner):

file
function     bool URigHierarchy::IsTracingChanges

Source code excerpt:

{
#if WITH_EDITOR
	return (CVarControlRigHierarchyTraceAlways->GetInt() != 0) || (TraceFramesLeft > 0);
#else
	return false;
#endif
}

#if WITH_EDITOR