p.AnimDynamicsRestrictLOD

p.AnimDynamicsRestrictLOD

#Overview

name: p.AnimDynamicsRestrictLOD

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 p.AnimDynamicsRestrictLOD is to control the Level of Detail (LOD) at which the Anim Dynamics system is enabled in Unreal Engine 5. This setting variable is primarily used for performance optimization in the animation system.

This setting variable is mainly used by the Anim Dynamics system, which is part of the animation runtime module in Unreal Engine. Specifically, it’s used in the AnimGraphRuntime module, as seen in the file “AnimNode_AnimDynamics.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, which means Anim Dynamics is enabled on all LODs by default. The value can be changed at runtime using console commands.

This variable interacts closely with other Anim Dynamics-related variables, particularly CVarEnableDynamics and CVarLODThreshold. It’s used in conjunction with these variables to determine whether the Anim Dynamics system should be active for a given LOD.

Developers must be aware that setting this variable to a specific LOD value (0 or higher) will restrict Anim Dynamics to only that LOD level, which can significantly impact performance and visual fidelity across different LODs.

Best practices when using this variable include:

  1. Leave it at -1 (default) unless you have specific performance reasons to restrict it.
  2. If restricting, carefully consider the visual impact on different LOD levels.
  3. Use in conjunction with CVarLODThreshold for more granular control over performance vs. quality tradeoffs.

Regarding the associated variable CVarRestrictLod:

The purpose of CVarRestrictLod is to provide programmatic access to the p.AnimDynamicsRestrictLOD setting within the C++ code. It’s the actual console variable object that holds and manages the value of p.AnimDynamicsRestrictLOD.

This variable is used directly in the AnimGraphRuntime module, specifically in the FAnimNode_AnimDynamics class. It’s accessed in the IsAnimDynamicsSystemEnabledFor function to determine if the Anim Dynamics system should be active for a given LOD.

The value of CVarRestrictLod is set through the Unreal Engine console variable system, just like p.AnimDynamicsRestrictLOD.

CVarRestrictLod interacts closely with CVarEnableDynamics in the IsAnimDynamicsSystemEnabledFor function to determine the overall enablement of the Anim Dynamics system.

Developers should be aware that this variable is accessed using GetValueOnAnyThread(), which means its value might be read from any thread. This could potentially lead to race conditions if not properly managed.

Best practices for using CVarRestrictLod include:

  1. Use it in conjunction with other Anim Dynamics console variables for comprehensive control over the system.
  2. Be cautious when changing its value at runtime, as it can have immediate effects on performance and visual quality.
  3. Consider thread safety when accessing or modifying this variable in multithreaded contexts.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AnimGraphRuntime/Private/BoneControllers/AnimNode_AnimDynamics.cpp:18

Scope: file

Source code excerpt:

CSV_DECLARE_CATEGORY_MODULE_EXTERN(ENGINE_API, Animation);

TAutoConsoleVariable<int32> CVarRestrictLod(TEXT("p.AnimDynamicsRestrictLOD"), -1, TEXT("Forces anim dynamics to be enabled for only a specified LOD, -1 to enable on all LODs."));
TAutoConsoleVariable<int32> CVarLODThreshold(TEXT("p.AnimDynamicsLODThreshold"), -1, TEXT("Max LOD that anim dynamics is allowed to run on. Provides a global threshold that overrides per-node the LODThreshold property. -1 means no override."), ECVF_Scalability);
TAutoConsoleVariable<int32> CVarEnableDynamics(TEXT("p.AnimDynamics"), 1, TEXT("Enables/Disables anim dynamics node updates."), ECVF_Scalability);
TAutoConsoleVariable<int32> CVarEnableAdaptiveSubstep(TEXT("p.AnimDynamicsAdaptiveSubstep"), 0, TEXT("Enables/disables adaptive substepping. Adaptive substepping will substep the simulation when it is necessary and maintain a debt buffer for time, always trying to utilise as much time as possible."));
TAutoConsoleVariable<int32> CVarAdaptiveSubstepNumDebtFrames(TEXT("p.AnimDynamicsNumDebtFrames"), 5, TEXT("Number of frames to maintain as time debt when using adaptive substepping, this should be at least 1 or the time debt will never be cleared."));
TAutoConsoleVariable<int32> CVarEnableWind(TEXT("p.AnimDynamicsWind"), 1, TEXT("Enables/Disables anim dynamics wind forces globally."), ECVF_Scalability);
TAutoConsoleVariable<float> CVarComponentAppliedLinearAccClampOverride(TEXT("p.AnimDynamics.ComponentAppliedLinearAccClampOverride"), -1.0f, TEXT("Override the per asset setting for all axis (X,Y & Z) of ComponentAppliedLinearAccClamp for all Anim Dynamics Nodes. Negative values are ignored."));

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/AnimGraphRuntime/Private/BoneControllers/AnimNode_AnimDynamics.cpp:18

Scope: file

Source code excerpt:

CSV_DECLARE_CATEGORY_MODULE_EXTERN(ENGINE_API, Animation);

TAutoConsoleVariable<int32> CVarRestrictLod(TEXT("p.AnimDynamicsRestrictLOD"), -1, TEXT("Forces anim dynamics to be enabled for only a specified LOD, -1 to enable on all LODs."));
TAutoConsoleVariable<int32> CVarLODThreshold(TEXT("p.AnimDynamicsLODThreshold"), -1, TEXT("Max LOD that anim dynamics is allowed to run on. Provides a global threshold that overrides per-node the LODThreshold property. -1 means no override."), ECVF_Scalability);
TAutoConsoleVariable<int32> CVarEnableDynamics(TEXT("p.AnimDynamics"), 1, TEXT("Enables/Disables anim dynamics node updates."), ECVF_Scalability);
TAutoConsoleVariable<int32> CVarEnableAdaptiveSubstep(TEXT("p.AnimDynamicsAdaptiveSubstep"), 0, TEXT("Enables/disables adaptive substepping. Adaptive substepping will substep the simulation when it is necessary and maintain a debt buffer for time, always trying to utilise as much time as possible."));
TAutoConsoleVariable<int32> CVarAdaptiveSubstepNumDebtFrames(TEXT("p.AnimDynamicsNumDebtFrames"), 5, TEXT("Number of frames to maintain as time debt when using adaptive substepping, this should be at least 1 or the time debt will never be cleared."));
TAutoConsoleVariable<int32> CVarEnableWind(TEXT("p.AnimDynamicsWind"), 1, TEXT("Enables/Disables anim dynamics wind forces globally."), ECVF_Scalability);
TAutoConsoleVariable<float> CVarComponentAppliedLinearAccClampOverride(TEXT("p.AnimDynamics.ComponentAppliedLinearAccClampOverride"), -1.0f, TEXT("Override the per asset setting for all axis (X,Y & Z) of ComponentAppliedLinearAccClamp for all Anim Dynamics Nodes. Negative values are ignored."));

#Loc: <Workspace>/Engine/Source/Runtime/AnimGraphRuntime/Private/BoneControllers/AnimNode_AnimDynamics.cpp:253

Scope (from outer to inner):

file
function     bool FAnimNode_AnimDynamics::IsAnimDynamicsSystemEnabledFor

Source code excerpt:

bool FAnimNode_AnimDynamics::IsAnimDynamicsSystemEnabledFor(int32 InLOD)
{
	int32 RestrictToLOD = CVarRestrictLod.GetValueOnAnyThread();
	bool bEnabledForLod = RestrictToLOD >= 0 ? InLOD == RestrictToLOD : true;

	// note this doesn't check LODThreshold of global value here. That's checked in
	// GetLODThreshold per node
	return (CVarEnableDynamics.GetValueOnAnyThread() == 1 && bEnabledForLod);
}