UDocumentation UE5.7 10.02.2026 (Source)
API documentation for Unreal Engine 5.7
AnimationRuntime.h
Go to the documentation of this file.
1// Copyright Epic Games, Inc. All Rights Reserved.
2
3/*=============================================================================
4 AnimationRuntime.h: Skeletal mesh animation utilities
5 Should only contain functions needed for runtime animation, no tools.
6=============================================================================*/
7
8#pragma once
9
10#include "CoreMinimal.h"
11#include "Misc/EnumClassFlags.h"
12#include "BoneIndices.h"
13#include "Animation/AnimTypes.h"
18#include "BonePose.h"
20
21class UBlendSpace;
22class USkeletalMeshComponent;
24class UMorphTarget;
25struct FA2CSPose;
26struct FA2Pose;
27struct FInputBlendPose;
30
31namespace UE { namespace Anim { struct FStackAttributeContainer; }}
32
34
36// Templated Transform Blend Functionality
37
39{
45}
46
47template<int32>
48ENGINE_API void BlendTransform(const FTransform& Source, FTransform& Dest, const float BlendWeight);
49
50template<>
51inline void BlendTransform<ETransformBlendMode::Overwrite>(const FTransform& Source, FTransform& Dest, const float BlendWeight)
52{
53 const ScalarRegister VBlendWeight(BlendWeight);
54 Dest = Source * VBlendWeight;
55}
56
57template<>
58inline void BlendTransform<ETransformBlendMode::Accumulate>(const FTransform& Source, FTransform& Dest, const float BlendWeight)
59{
60 const ScalarRegister VBlendWeight(BlendWeight);
62}
63
64ENGINE_API void BlendCurves(const TArrayView<const FBlendedCurve> SourceCurves, const TArrayView<const float> SourceWeights, FBlendedCurve& OutCurve);
65void ENGINE_API BlendCurves(const TArrayView<const FBlendedCurve* const> SourceCurves, const TArrayView<const float> SourceWeights, FBlendedCurve& OutCurve);
66ENGINE_API void BlendCurves(const TArrayView<const FBlendedCurve* const> SourceCurves, const TArrayView<const float> SourceWeights, FBlendedCurve& OutCurve, ECurveBlendOption::Type BlendOption);
67
68
70
74{
75public:
77
82
83 // There may be times when the implementation can pre-calculate data needed for GetPerBoneInterpolationIndex, as the
84 // latter is often called multiple times whilst iterating over a skeleton.
86
87 UE_DEPRECATED(5.0, "Please use the overload that takes a FCompactPoseBoneIndex")
89 int32 BoneIndex, const FBoneContainer& RequiredBones, const FPerBoneInterpolationData* Data) const;
90
91 // Implementation should return the index into the PerBoneBlendData array that would be required when looking
92 // up/blending BoneIndex. This call will be passed the results of GetPerBoneInterpolationData, so the two functions
93 // should be matched.
95
96 // Implementation should return the index into the PerBoneBlendData array that would be required when looking
97 // up/blending BoneIndex. This call will be passed the results of GetPerBoneInterpolationData, so the two functions
98 // should be matched.
100};
101
105{
106public:
107 static ENGINE_API void NormalizeRotations(const FBoneContainer& RequiredBones, /*inout*/ FTransformArrayA2& Atoms);
108 static ENGINE_API void NormalizeRotations(FTransformArrayA2& Atoms);
109
110 static ENGINE_API void InitializeTransform(const FBoneContainer& RequiredBones, /*inout*/ FTransformArrayA2& Atoms);
111#if DO_GUARD_SLOW
113#endif
114
124 UE_DEPRECATED(4.26, "Use BlendPosesTogether with other signature")
125 static ENGINE_API void BlendPosesTogether(
128 TArrayView<const float> SourceWeights,
129 /*out*/ FCompactPose& ResultPose,
130 /*out*/ FBlendedCurve& ResultCurve);
131
132 static ENGINE_API void BlendPosesTogether(
136 TArrayView<const float> SourceWeights,
138
150 UE_DEPRECATED(4.26, "Use BlendPosesTogether with other signature")
151 static ENGINE_API void BlendPosesTogether(
154 TArrayView<const float> SourceWeights,
156 /*out*/ FCompactPose& ResultPose,
157 /*out*/ FBlendedCurve& ResultCurve);
158
159 static ENGINE_API void BlendPosesTogether(
163 TArrayView<const float> SourceWeights,
166 );
167
177 UE_DEPRECATED(4.26, "Use BlendPosesTogetherIndirect with other signature")
178 static ENGINE_API void BlendPosesTogetherIndirect(
179 TArrayView<const FCompactPose* const> SourcePoses,
180 TArrayView<const FBlendedCurve* const> SourceCurves,
181 TArrayView<const float> SourceWeights,
182 /*out*/ FCompactPose& ResultPose,
183 /*out*/ FBlendedCurve& ResultCurve);
184
185 static ENGINE_API void BlendPosesTogetherIndirect(
186 TArrayView<const FCompactPose* const> SourcePoses,
187 TArrayView<const FBlendedCurve* const> SourceCurves,
188 TArrayView<const UE::Anim::FStackAttributeContainer* const> SourceAttributes,
189 TArrayView<const float> SourceWeights,
191
200 UE_DEPRECATED(4.26, "Use BlendTwoPosesTogether with other signature")
201 static ENGINE_API void BlendTwoPosesTogether(
206 const float WeightOfPose1,
207 /*out*/ FCompactPose& ResultPose,
208 /*out*/ FBlendedCurve& ResultCurve);
209
210 static ENGINE_API void BlendTwoPosesTogether(
213 const float WeightOfPoseOne,
215
224 UE_DEPRECATED(4.26, "Use BlendTwoPosesTogether with other signature")
225 static ENGINE_API void BlendTwoPosesTogetherPerBone(
230 const TArray<float>& WeightsOfSource2,
231 /*out*/ FCompactPose& ResultPose,
232 /*out*/ FBlendedCurve& ResultCurve);
233
234 static ENGINE_API void BlendTwoPosesTogetherPerBone(
237 const TArray<float>& WeightsOfSource2,
239
240 static ENGINE_API void BlendTwoPosesTogetherPerBone(
243 const TArray<float>& WeightsOfSource2,
245
254 UE_DEPRECATED(4.26, "Use BlendPosesTogetherPerBone with other signature")
255 static ENGINE_API void BlendPosesTogetherPerBone(
256 TArrayView<const FCompactPose> SourcePoses,
257 TArrayView<const FBlendedCurve> SourceCurves,
259 TArrayView<const FBlendSampleData> BlendSampleDataCache,
260 /*out*/ FCompactPose& ResultPose,
261 /*out*/ FBlendedCurve& ResultCurve);
262
263 static ENGINE_API void BlendPosesTogetherPerBone(
264 TArrayView<const FCompactPose> SourcePoses,
265 TArrayView<const FBlendedCurve> SourceCurves,
266 TArrayView<const UE::Anim::FStackAttributeContainer> SourceAttributes,
268 TArrayView<const FBlendSampleData> BlendSampleDataCache,
270
271 static ENGINE_API void BlendPosesTogetherPerBoneRemapped(
272 TArrayView<const FCompactPose> SourcePoses,
273 TArrayView<const FBlendedCurve> SourceCurves,
274 TArrayView<const UE::Anim::FStackAttributeContainer> SourceAttributes,
276 TArrayView<const FBlendSampleData> BlendSampleDataCache,
280
281
291 UE_DEPRECATED(4.26, "Use BlendPosesTogetherPerBone with other signature")
292 static ENGINE_API void BlendPosesTogetherPerBone(
293 TArrayView<const FCompactPose> SourcePoses,
294 TArrayView<const FBlendedCurve> SourceCurves,
296 TArrayView<const FBlendSampleData> BlendSampleDataCache,
298 /*out*/ FCompactPose& ResultPose,
299 /*out*/ FBlendedCurve& ResultCurve);
300
301 static ENGINE_API void BlendPosesTogetherPerBone(
302 TArrayView<const FCompactPose> SourcePoses,
303 TArrayView<const FBlendedCurve> SourceCurves,
304 TArrayView<const UE::Anim::FStackAttributeContainer> SourceAttributes,
306 TArrayView<const FBlendSampleData> BlendSampleDataCache,
309
321 UE_DEPRECATED(4.26, "Use BlendPosesTogetherPerBone with other signature")
322 static ENGINE_API void BlendPosesTogetherPerBoneInMeshSpace(
323 TArrayView<FCompactPose> SourcePoses,
324 TArrayView<const FBlendedCurve> SourceCurves,
325 const UBlendSpace* BlendSpace,
326 TArrayView<const FBlendSampleData> BlendSampleDataCache,
329
340 static ENGINE_API void BlendPosesTogetherPerBoneInMeshSpace(
341 TArrayView<FCompactPose> SourcePoses,
342 TArrayView<const FBlendedCurve> SourceCurves,
343 TArrayView<const UE::Anim::FStackAttributeContainer> SourceAttributes,
344 const UBlendSpace* BlendSpace,
345 TArrayView<const FBlendSampleData> BlendSampleDataCache,
347
350 {
351 None = 0,
352 MeshSpaceRotation = (1 << 0),
353 MeshSpaceScale = (1 << 1),
354 RootSpaceRotation = (1 << 2),
355 };
356
370 static ENGINE_API void BlendPosesPerBoneFilter(
371 FCompactPose& BasePose,
372 const TConstArrayView<FCompactPose> BlendPoses,
378 const TArrayView<FPerBoneBlendWeight> BoneBlendWeights,
379 EBlendPosesPerBoneFilterFlags BlendFlags,
380 enum ECurveBlendOption::Type CurveBlendOption);
381
382 static ENGINE_API void UpdateDesiredBoneWeight(
385 const TArrayView<float> BlendWeights);
386
393 static ENGINE_API void CreateMaskWeights(
394 TArray<FPerBoneBlendWeight>& BoneBlendWeights,
396 const USkeleton* Skeleton);
397
402 static ENGINE_API void CreateMaskWeights(
403 TArray<FPerBoneBlendWeight>& BoneBlendWeights,
404 const TArray<class UBlendProfile*>& BlendMasks,
405 const USkeleton* Skeleton);
406
407 static ENGINE_API void CombineWithAdditiveAnimations(
410 const float* SourceAdditiveWeights,
411 const FBoneContainer& RequiredBones,
412 /*inout*/ FTransformArrayA2& Atoms);
413
415 static ENGINE_API FTransform GetComponentSpaceRefPose(const FCompactPoseBoneIndex& CompactPoseBoneIndex, const FBoneContainer& BoneContainer);
416
418 static ENGINE_API void FillWithRefPose(TArray<FTransform>& OutAtoms, const FBoneContainer& RequiredBones);
419
421 static ENGINE_API void ConvertPoseToMeshSpace(const TArray<FTransform>& LocalTransforms, TArray<FTransform>& MeshSpaceTransforms, const FBoneContainer& RequiredBones);
422
424 static ENGINE_API void ConvertPoseToAdditive(FCompactPose& TargetPose, const FCompactPose& BasePose);
425
427 static ENGINE_API void ConvertTransformToAdditive(FTransform& TargetTrasnform, const FTransform& BaseTransform);
428
430 static ENGINE_API void ConvertPoseToMeshRotation(FCompactPose& LocalPose);
431
433 static ENGINE_API void ConvertMeshRotationPoseToLocalSpace(FCompactPose& Pose);
434
436 UE_DEPRECATED(4.26, "Use AccumulateAdditivePose with other signature")
437 static ENGINE_API void AccumulateAdditivePose(FCompactPose& BasePose, const FCompactPose& AdditivePose, FBlendedCurve& BaseCurve, const FBlendedCurve& AdditiveCurve, float Weight, enum EAdditiveAnimationType AdditiveType);
438
440
441private:
443 static ENGINE_API void AccumulateLocalSpaceAdditivePoseInternal(FCompactPose& BasePose, const FCompactPose& AdditivePose, float Weight);
444
446 static ENGINE_API void AccumulateMeshSpaceRotationAdditiveToLocalPoseInternal(FCompactPose& BasePose, const FCompactPose& MeshSpaceRotationAdditive, float Weight);
447
449 static ENGINE_API void AccumulateRootSpaceAdditivePoseInternal(FCompactPose& BasePose, const FCompactPose& RootSpaceAdditivePose, float Weight);
450
451public:
452
454 UE_DEPRECATED(4.26, "Use AccumulateAdditivePose with other signature")
455 static ENGINE_API void AccumulateLocalSpaceAdditivePose(FCompactPose& BasePose, const FCompactPose& AdditivePose, FBlendedCurve& BaseCurve, const FBlendedCurve& AdditiveCurve, float Weight);
456
458
460 UE_DEPRECATED(4.26, "Use AccumulateAdditivePose with other signature")
461 static ENGINE_API void AccumulateMeshSpaceRotationAdditiveToLocalPose(FCompactPose& BasePose, const FCompactPose& MeshSpaceRotationAdditive, FBlendedCurve& BaseCurve, const FBlendedCurve& AdditiveCurve, float Weight);
462
463 static ENGINE_API void AccumulateMeshSpaceRotationAdditiveToLocalPose(FAnimationPoseData& BaseAnimationPoseData, const FAnimationPoseData& MeshSpaceRotationAdditiveAnimationPoseData, float Weight);
464
465 static ENGINE_API void AccumulateRootSpaceRotationAdditiveToLocalPose(FAnimationPoseData& BaseAnimationPoseData, const FAnimationPoseData& MeshSpaceRotationAdditiveAnimationPoseData, float Weight);
466
469
473 static ENGINE_API void LerpPosesPerBone(FCompactPose& PoseA, const FCompactPose& PoseB, FBlendedCurve& CurveA, const FBlendedCurve& CurveB, float Alpha, const TArray<float>& PerBoneWeights);
474
478 static ENGINE_API void LerpPosesWithBoneIndexList(FCompactPose& PoseA, const FCompactPose& PoseB, FBlendedCurve& CurveA, const FBlendedCurve& CurveB, float Alpha, const TArray<FCompactPoseBoneIndex>& BoneIndices);
479
486 static ENGINE_API void LerpBoneTransforms(TArray<FTransform>& A, const TArray<FTransform>& B, float Alpha, const TArray<FBoneIndexType>& RequiredBonesArray);
487
493 UE_DEPRECATED(4.26.0, "Please use BlendTransform() for weighted blending")
494 static ENGINE_API void BlendTransformsByWeight(FTransform& OutTransform, const TArray<FTransform>& Transforms, const TArray<float>& Weights);
495
504 static ENGINE_API void MirrorCurves(FBlendedCurve& Curves, const UMirrorDataTable& MirrorDataTable);
505
512 static ENGINE_API FVector MirrorVector(const FVector& V, EAxis::Type MirrorAxis);
513
520 static ENGINE_API FQuat MirrorQuat(const FQuat& Q, EAxis::Type MirrorAxis);
521
530 static ENGINE_API void MirrorPose(FCompactPose& Pose, const UMirrorDataTable& MirrorDataTable);
531
539 static ENGINE_API void MirrorPose(FCompactPose& Pose, EAxis::Type MirrorAxis, const TArray<FCompactPoseBoneIndex>& CompactPoseMirrorBones, const TCustomBoneIndexArray<FQuat, FCompactPoseBoneIndex>& ComponentSpaceRefRotations);
540
547 static ENGINE_API ETypeAdvanceAnim AdvanceTime(const bool bAllowLooping, const float MoveDelta, float& InOutTime, const float EndTime);
548
549 static ENGINE_API void TickBlendWeight(float DeltaTime, float DesiredWeight, float& Weight, float& BlendTime);
554 static ENGINE_API void ApplyWeightToTransform(const FBoneContainer& RequiredBones, /*inout*/ FTransformArrayA2& Atoms, float Weight);
555
564 static ENGINE_API void GetKeyIndicesFromTime(int32& OutKeyIndex1, int32& OutKeyIndex2, float& OutAlpha, const double Time, const int32 NumKeys, const double SequenceLength, double FramesPerSecond=-1.0);
565
567 static ENGINE_API void GetKeyIndicesFromTime(int32& OutKeyIndex1, int32& OutKeyIndex2, float& OutAlpha, const double Time, const FFrameRate& FrameRate, const int32 NumberOfKeys);
568
574 static ENGINE_API void EnsureParentsPresent(TArray<FBoneIndexType>& BoneIndices, const FReferenceSkeleton& RefSkeleton);
575
576 static ENGINE_API void ExcludeBonesWithNoParents(const TArray<int32>& BoneIndices, const FReferenceSkeleton& RefSkeleton, TArray<int32>& FilteredRequiredBones);
577
586 static ENGINE_API void ConvertCSTransformToBoneSpace(const FTransform& ComponentTransform, FCSPose<FCompactPose>& MeshBases, FTransform& InOutCSBoneTM, FCompactPoseBoneIndex BoneIndex, EBoneControlSpace Space);
587
596 static ENGINE_API void ConvertBoneSpaceTransformToCS(const FTransform& ComponentTransform, FCSPose<FCompactPose>& MeshBases, FTransform& InOutBoneSpaceTM, FCompactPoseBoneIndex BoneIndex, EBoneControlSpace Space);
597
598 // FA2Pose/FA2CSPose Interfaces for template functions
599 static ENGINE_API FTransform GetSpaceTransform(FA2Pose& Pose, int32 Index);
600 static ENGINE_API FTransform GetSpaceTransform(FA2CSPose& Pose, int32 Index);
601 static ENGINE_API void SetSpaceTransform(FA2Pose& Pose, int32 Index, FTransform& NewTransform);
602 static ENGINE_API void SetSpaceTransform(FA2CSPose& Pose, int32 Index, FTransform& NewTransform);
603 // space bases
604 static ENGINE_API FTransform GetComponentSpaceTransformRefPose(const FReferenceSkeleton& RefSkeleton, int32 BoneIndex);
606 static ENGINE_API void FillUpComponentSpaceTransforms(const FReferenceSkeleton& RefSkeleton, const TArrayView<const FTransform> &BoneSpaceTransforms, TArray<FTransform> &ComponentSpaceTransforms);
607 static ENGINE_API void MakeSkeletonRefPoseFromMesh(const USkeletalMesh* InMesh, const USkeleton* InSkeleton, TArray<FTransform>& OutBoneBuffer);
608
622 static ENGINE_API EBoneTranslationRetargetingMode::Type GetBoneTranslationRetargetingMode(const bool bUseSourceRetargetModes, const int32 SourceSkeletonBoneIndex, const int32 TargetSkeletonBoneIndex, const USkeleton* SourceSkeleton, const USkeleton* TargetSkeleton, const bool bDisableRetargeting);
623
635
636#if WITH_EDITOR
637 static ENGINE_API void FillUpComponentSpaceTransformsRefPose(const USkeleton* Skeleton, TArray<FTransform> &ComponentSpaceTransforms);
638#endif
639
640 /* Weight utility functions */
641 static inline bool IsFullWeight(float Weight) { return FAnimWeight::IsFullWeight(Weight); }
642 static inline bool HasWeight(float Weight) { return FAnimWeight::IsRelevant(Weight); }
643
648
659 static ENGINE_API void RetargetBoneTransform(const USkeleton* SourceSkeleton, const FName& RetargetSource, FTransform& BoneTransform, const int32 SkeletonBoneIndex, const FCompactPoseBoneIndex& BoneIndex, const FBoneContainer& RequiredBones, const bool bIsBakedAdditive);
660 static ENGINE_API void RetargetBoneTransform(const USkeleton* MySkeleton, const FName& SourceName, const TArray<FTransform>& RetargetTransforms, FTransform& BoneTransform, const int32 SkeletonBoneIndex, const FCompactPoseBoneIndex& BoneIndex, const FBoneContainer& RequiredBones, const bool bIsBakedAdditive);
667 static ENGINE_API int32 GetStringDistance(const FString& First, const FString& Second);
668};
669
671
672#if UE_ENABLE_INCLUDE_ORDER_DEPRECATED_IN_5_6
674#endif
bool ContainsNaN(const TArray< FBoneTransform > &BoneTransforms)
Definition AnimNode_SkeletalControlBase.cpp:119
ETypeAdvanceAnim
Definition AnimSequenceBase.h:23
EBoneControlSpace
Definition AnimTypes.h:60
EAdditiveAnimationType
Definition AnimTypes.h:575
void BlendTransform< ETransformBlendMode::Overwrite >(const FTransform &Source, FTransform &Dest, const float BlendWeight)
Definition AnimationRuntime.h:51
ENGINE_API void BlendTransform(const FTransform &Source, FTransform &Dest, const float BlendWeight)
TArray< FTransform > FTransformArrayA2
Definition AnimationRuntime.h:33
void BlendTransform< ETransformBlendMode::Accumulate >(const FTransform &Source, FTransform &Dest, const float BlendWeight)
Definition AnimationRuntime.h:58
ENGINE_API void BlendCurves(const TArrayView< const FBlendedCurve > SourceCurves, const TArrayView< const float > SourceWeights, FBlendedCurve &OutCurve)
Definition AnimationRuntime.cpp:243
uint16 FBoneIndexType
Definition BoneIndices.h:7
#define UE_DEPRECATED(Version, Message)
Definition CoreMiscDefines.h:302
FPlatformTypes::int32 int32
A 32-bit signed integer.
Definition Platform.h:1125
UE_FORCEINLINE_HINT TSharedRef< CastToType, Mode > StaticCastSharedRef(TSharedRef< CastFromType, Mode > const &InSharedRef)
Definition SharedPointer.h:127
#define ENUM_CLASS_FLAGS(Enum)
Definition EnumClassFlags.h:6
FTransform GetComponentSpaceTransform(TArray< uint8 > &ComponentSpaceFlags, TArray< FTransform > &ComponentSpaceTransforms, FReferenceSkeleton &RefSkeleton, int32 TargetIndex)
Definition ReferenceSkeleton.cpp:87
#define ScalarRegister
Definition ScalarRegister.h:239
uint32_t uint32
Definition binka_ue_file_header.h:6
Definition AnimationRuntime.h:105
static bool IsFullWeight(float Weight)
Definition AnimationRuntime.h:641
static bool HasWeight(float Weight)
Definition AnimationRuntime.h:642
EBlendPosesPerBoneFilterFlags
Definition AnimationRuntime.h:350
Definition NameTypes.h:617
Definition AnimationRuntime.h:74
virtual TSharedPtr< FPerBoneInterpolationData > GetPerBoneInterpolationData(const USkeleton *Skeleton) const
Definition AnimationRuntime.h:85
~IInterpolationIndexProvider()=default
virtual ENGINE_API int32 GetPerBoneInterpolationIndex(int32 BoneIndex, const FBoneContainer &RequiredBones, const FPerBoneInterpolationData *Data) const
Definition AnimationRuntime.cpp:3192
Definition ArrayView.h:139
Definition Array.h:670
Definition SharedPointer.h:692
Definition BlendSpace.h:467
Definition CustomBoneIndexArray.h:43
Definition MirrorDataTable.h:102
Definition MorphTarget.h:230
Definition SkeletalMesh.h:440
Definition Skeleton.h:295
Definition Axis.h:9
Definition Skeleton.h:72
Type
Definition AnimTypes.h:589
Definition AnimationRuntime.h:39
Type
Definition AnimationRuntime.h:41
@ Accumulate
Definition AnimationRuntime.h:43
@ Overwrite
Definition AnimationRuntime.h:42
Definition AdvancedWidgetsModule.cpp:13
U16 Index
Definition radfft.cpp:71
Definition AnimInstance.h:138
Definition AnimInstance.h:126
static bool IsFullWeight(float InWeight)
Definition AnimTypes.h:672
static bool IsRelevant(float InWeight)
Definition AnimTypes.h:666
Definition AnimationPoseData.h:16
Definition AnimationAsset.h:122
Definition AnimCurveTypes.h:1041
Definition BoneContainer.h:192
Definition BonePose.h:408
Definition BoneIndices.h:63
Definition BonePose.h:347
Definition FrameRate.h:21
Definition BoneMaskFilter.h:31
Definition ReferenceSkeleton.h:100
Definition BoneIndices.h:79
Definition SkeletonRemapping.h:11
virtual ~FPerBoneInterpolationData()
Definition AnimationRuntime.h:80
Definition AttributesRuntime.h:40
void AccumulateWithShortestRotation(const TTransform< T > &DeltaAtom, FReal BlendWeight)
Definition TransformNonVectorized.h:979