ControlRig.Hierarchy.TraceCallstack

ControlRig.Hierarchy.TraceCallstack

#Overview

name: ControlRig.Hierarchy.TraceCallstack

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

• type: Var
• help: if nonzero we will record the callstack for any trace entry.\nOnly works if(ControlRig.Hierarchy.TraceEnabled != 0)

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of ControlRig.Hierarchy.TraceCallstack is to enable callstack recording for trace entries in the Control Rig Hierarchy system of Unreal Engine 5. This setting is specifically designed for debugging and performance analysis of the Control Rig animation system.

• The Control Rig plugin, which is part of Unreal Engine’s animation system, relies on this setting variable.
• The value of this variable is set through a console variable (CVar) named CVarControlRigHierarchyTraceCallstack. It is initialized with a default value of 0, meaning callstack tracing is disabled by default.
• This variable interacts closely with ControlRig.Hierarchy.TraceAlways. The callstack tracing only works if ControlRig.Hierarchy.TraceEnabled is non-zero.
• Developers must be aware that enabling this variable can have performance implications, as recording callstacks for each trace entry can be computationally expensive.
• Best practices for using this variable include:
  1. Only enable it when necessary for debugging or performance analysis.
  2. Disable it in production builds to avoid performance overhead.
  3. Use in conjunction with ControlRig.Hierarchy.TraceAlways for comprehensive debugging.

Regarding the associated variable CVarControlRigHierarchyTraceCallstack:

• This is the actual console variable that controls the behavior described above.
• It is defined as a static TAutoConsoleVariable, allowing it to be changed at runtime through console commands.
• The variable is used in the URigHierarchy::PushTransformToStack function to determine whether to capture and record the callstack.
• When using this variable, developers can enable or disable callstack tracing by setting its value to non-zero or zero, respectively.
• It’s important to note that this variable’s effect is conditional on the tracing system being enabled (IsTracingChanges() must return true).

In summary, these variables provide a powerful debugging tool for the Control Rig system, allowing developers to trace transform changes and capture callstacks when needed, but should be used judiciously due to potential performance impacts.

#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:44

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;
static TCHAR sRigHierarchyTraceFormat[16];

#Associated Variable and Callsites

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

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

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;
static TCHAR sRigHierarchyTraceFormat[16];

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

Scope (from outer to inner):

file
function     void URigHierarchy::PushTransformToStack

Source code excerpt:

	TArray<FString> Callstack;
	if(IsTracingChanges() && (CVarControlRigHierarchyTraceCallstack->GetInt() != 0))
	{
		FString JoinedCallStack;
		RigHierarchyCaptureCallStack(JoinedCallStack, 1);
		JoinedCallStack.ReplaceInline(TEXT("\r"), TEXT(""));

		FString Left, Right;