AnimEncoding.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
/*=============================================================================
    AnimEncoding.h: Skeletal mesh animation compression.
=============================================================================*/ 
 
#pragma once
 
#include "CoreMinimal.h"
#include "Misc/MemStack.h"
#include "Animation/AnimTypes.h"
#include "Animation/AnimSequence.h"
#include "Animation/AnimSequenceDecompressionContext.h"
#include "AnimationCompression.h"
 
// switches to toggle subsets of the new animation codec system
#define USE_ANIMATION_CODEC_BATCH_SOLVER 1
 
// all past encoding package version numbers should be listed here
#define ANIMATION_ENCODING_PACKAGE_ORIGINAL 0
 
// the current animation encoding package version
#define CURRENT_ANIMATION_ENCODING_PACKAGE_VERSION ANIMATION_ENCODING_PACKAGE_ORIGINAL
 
class FMemoryWriter;
 
//
// Interfaces For Working With Encoded Animations
//
 
struct BoneTrackPair
{
    int32 AtomIndex;
    int32 TrackIndex;
 
    BoneTrackPair(){}
    BoneTrackPair(int32 Atom, int32 Track):AtomIndex(Atom),TrackIndex(Track){}
};
 
#define MAX_BONES 65536 // DesiredBones is passed to the decompression routines as a TArray<FBoneIndexType>, so we know this max is appropriate
typedef TArray<BoneTrackPair> BoneTrackArray;
 
 
typedef TArray< FTransform, TMemStackAllocator<> > FTransformArray;
 
 
ENGINE_API void AnimationFormat_GetStats(const FUECompressedAnimData& CompressedData, 
                                int32& NumTransTracks,
                                int32& NumRotTracks,
                                int32& NumScaleTracks,
                                int32& TotalNumTransKeys,
                                int32& TotalNumRotKeys,
                                int32& TotalNumScaleKeys,
                                float& TranslationKeySize,
                                float& RotationKeySize,
                                float& ScaleKeySize,
                                int32& OverheadSize,
                                int32& NumTransTracksWithOneKey,
                                int32& NumRotTracksWithOneKey,
                                int32& NumScaleTracksWithOneKey);
 
template<typename CompressedDataType>
void AnimationFormat_SetInterfaceLinks(CompressedDataType& CompressedData);
 
#if WITH_EDITORONLY_DATA
#define AC_UnalignedSwap( MemoryArchive, Data, Len )        \
    MemoryArchive.ByteOrderSerialize( (Data), (Len) );      \
    (Data) += (Len);
#else
    // No need to swap on consoles, as the cooker will have ordered bytes for the target platform.
#define AC_UnalignedSwap( MemoryArchive, Data, Len )        \
    MemoryArchive.Serialize( (Data), (Len) );               \
    (Data) += (Len);
#endif // !WITH_EDITORONLY_DATA
 
extern ENGINE_API const int32 CompressedTranslationStrides[ACF_MAX];
extern ENGINE_API const int32 CompressedTranslationNum[ACF_MAX];
extern ENGINE_API const int32 CompressedRotationStrides[ACF_MAX];
extern ENGINE_API const int32 CompressedRotationNum[ACF_MAX];
extern ENGINE_API const int32 CompressedScaleStrides[ACF_MAX];
extern ENGINE_API const int32 CompressedScaleNum[ACF_MAX];
extern ENGINE_API const uint8 PerTrackNumComponentTable[ACF_MAX*8];
 
class FMemoryWriter;
class FMemoryReader;
 
void PadMemoryWriter(FMemoryWriter* MemoryWriter, uint8*& TrackData, const int32 Alignment);
void PadMemoryReader(FMemoryReader* MemoryReader, uint8*& TrackData, const int32 Alignment);
 
 
class AnimEncoding
{
public:
    virtual void ByteSwapIn(
        FUECompressedAnimData& CompressedData,
        FMemoryReader& MemoryReader) PURE_VIRTUAL(AnimEncoding::ByteSwapIn,);
 
    virtual void ByteSwapOut(
        FUECompressedAnimData& CompressedData,
        FMemoryWriter& MemoryWriter) PURE_VIRTUAL(AnimEncoding::ByteSwapOut, );
 
#if USE_ANIMATION_CODEC_BATCH_SOLVER
 
    virtual void GetPoseRotations(
        TArrayView<FTransform>& Atoms,
        const BoneTrackArray& DesiredPairs,
        FAnimSequenceDecompressionContext& DecompContext) PURE_VIRTUAL(AnimEncoding::GetPoseRotations,);
 
    virtual void GetPoseTranslations(
        TArrayView<FTransform>& Atoms,
        const BoneTrackArray& DesiredPairs,
        FAnimSequenceDecompressionContext& DecompContext) PURE_VIRTUAL(AnimEncoding::GetPoseTranslations,);
 
    virtual void GetPoseScales(
        TArrayView<FTransform>& Atoms,
        const BoneTrackArray& DesiredPairs,
        FAnimSequenceDecompressionContext& DecompContext) PURE_VIRTUAL(AnimEncoding::GetPoseScales,);
#endif
 
protected:
 
    static float TimeToIndex(
        float SequenceLength,
        float RelativePos,
        int32 NumKeys,
        EAnimInterpolationType Interpolation,
        int32 &PosIndex0Out,
        int32 &PosIndex1Out);
 
    static float TimeToIndex(
        EAnimInterpolationType Interpolation,
        int32 NumberOfFrames,
        const uint8* FrameTable,
        float RelativePos,
        int32 NumKeys,
        int32 &PosIndex0Out,
        int32 &PosIndex1Out);
};
 
 
class AnimEncodingLegacyBase : public AnimEncoding
{
public:
    virtual void GetBoneAtomRotation(
        FTransform& OutAtom,
        const FAnimSequenceDecompressionContext& DecompContext,
        int32 TrackIndex) PURE_VIRTUAL(AnimEncoding::GetBoneAtomRotation,);
 
    virtual void GetBoneAtomTranslation(
        FTransform& OutAtom,
        const FAnimSequenceDecompressionContext& DecompContext,
        int32 TrackIndex) PURE_VIRTUAL(AnimEncoding::GetBoneAtomTranslation,);
 
    virtual void GetBoneAtomScale(
        FTransform& OutAtom,
        const FAnimSequenceDecompressionContext& DecompContext,
        int32 TrackIndex) PURE_VIRTUAL(AnimEncoding::GetBoneAtomScale,);
 
    virtual void ByteSwapIn(
        FUECompressedAnimData& CompressedData,
        FMemoryReader& MemoryReader) override;
 
    virtual void ByteSwapOut(
        FUECompressedAnimData& CompressedData,
        FMemoryWriter& MemoryWriter) override;
 
    virtual void ByteSwapRotationIn(
        FUECompressedAnimData& CompressedData,
        FMemoryReader& MemoryReader,
        uint8*& Stream,
        int32 NumKeys) PURE_VIRTUAL(AnimEncoding::ByteSwapRotationIn,);
 
    virtual void ByteSwapTranslationIn(
        FUECompressedAnimData& CompressedData,
        FMemoryReader& MemoryReader,
        uint8*& Stream,
        int32 NumKeys) PURE_VIRTUAL(AnimEncoding::ByteSwapTranslationIn,);
 
    virtual void ByteSwapScaleIn(
        FUECompressedAnimData& CompressedData,
        FMemoryReader& MemoryReader,
        uint8*& Stream,
        int32 NumKeys) PURE_VIRTUAL(AnimEncoding::ByteSwapScaleIn,);
 
    virtual void ByteSwapRotationOut(
        FUECompressedAnimData& CompressedData,
        FMemoryWriter& MemoryWriter,
        uint8*& Stream,
        int32 NumKeys) PURE_VIRTUAL(AnimEncoding::ByteSwapRotationOut,);
 
    virtual void ByteSwapTranslationOut(
        FUECompressedAnimData& CompressedData,
        FMemoryWriter& MemoryWriter,
        uint8*& Stream,
        int32 NumKeys) PURE_VIRTUAL(AnimEncoding::ByteSwapTranslationOut,);
 
    virtual void ByteSwapScaleOut(
        FUECompressedAnimData& CompressedData,
        FMemoryWriter& MemoryWriter,
        uint8*& Stream,
        int32 NumKeys) PURE_VIRTUAL(AnimEncoding::ByteSwapScaleOut,);
};
 
 
inline float AnimEncoding::TimeToIndex(
    float SequenceLength,
    float RelativePos,
    int32 NumKeys,
    EAnimInterpolationType Interpolation,
    int32 &PosIndex0Out,
    int32 &PosIndex1Out)
{
    float Alpha;
 
    if (NumKeys < 2)
    {
        checkSlow(NumKeys == 1); // check if data is empty for some reason.
        PosIndex0Out = 0;
        PosIndex1Out = 0;
        return 0.0f;
    }
    // Check for before-first-frame case.
    if( RelativePos <= 0.f )
    {
        PosIndex0Out = 0;
        PosIndex1Out = 0;
        Alpha = 0.0f;
    }
    else
    {
        NumKeys -= 1; // never used without the minus one in this case
        // Check for after-last-frame case.
        if( RelativePos >= 1.0f )
        {
            // If we're not looping, key n-1 is the final key.
            PosIndex0Out = NumKeys;
            PosIndex1Out = NumKeys;
            Alpha = 0.0f;
        }
        else
        {
            // For non-looping animation, the last frame is the ending frame, and has no duration.
            const float KeyPos = RelativePos * float(NumKeys);
            checkSlow(KeyPos >= 0.0f);
            const float KeyPosFloor = floorf(KeyPos);
            PosIndex0Out = FMath::Min( FMath::TruncToInt(KeyPosFloor), NumKeys );
            Alpha = (Interpolation == EAnimInterpolationType::Step) ? 0.0f : KeyPos - KeyPosFloor;
            PosIndex1Out = FMath::Min( PosIndex0Out + 1, NumKeys );
        }
    }
    return Alpha;
}
 
template <typename TABLE_TYPE>
inline int32 FindLowKeyIndex(
    const TABLE_TYPE* FrameTable, 
    int32 NumKeys, 
    int32 SearchFrame, 
    int32 KeyEstimate)
{
    const int32 LastKeyIndex = NumKeys-1;
    int32 LowKeyIndex = KeyEstimate;
 
    if (FrameTable[KeyEstimate] <= SearchFrame)
    {
        // unless we find something better, we'll default to the last key
        LowKeyIndex = LastKeyIndex;
 
        // search forward from the estimate for the first value greater than our search parameter
        // if found, this is the high key and we want the one just prior to it
        for (int32 i = KeyEstimate+1; i <= LastKeyIndex; ++i)
        {
            if (FrameTable[i] > SearchFrame)
            {
                LowKeyIndex= i-1;
                break;
            }
        }
    }
    else
    {
        // unless we find something better, we'll default to the first key
        LowKeyIndex = 0;
 
        // search backward from the estimate for the first value less than or equal to the search parameter
        // if found, this is the low key we are searching for
        for (int32 i = KeyEstimate-1; i > 0; --i)
        {
            if (FrameTable[i] <= SearchFrame)
            {
                LowKeyIndex= i;
                break;
            }
        }
    }
 
    return LowKeyIndex;
}
 
inline float AnimEncoding::TimeToIndex(
    EAnimInterpolationType Interpolation,
    int32 NumberOfFrames,
    const uint8* FrameTable,
    float RelativePos,
    int32 NumKeys,
    int32 &PosIndex0Out,
    int32 &PosIndex1Out)
{
    float Alpha = 0.0f;
 
    check(NumKeys != 0);
    
    const int32 LastKey= NumKeys-1;
    
    int32 TotalFrames = NumberOfFrames -1;
    int32 EndingKey = LastKey;
 
    if (NumKeys < 2 || RelativePos <= 0.f)
    {
        // return the first key
        PosIndex0Out = 0;
        PosIndex1Out = 0;
        Alpha = 0.0f;
    }
    else if( RelativePos >= 1.0f )
    {
        // return the ending key
        PosIndex0Out = EndingKey;
        PosIndex1Out = EndingKey;
        Alpha = 0.0f;
    }
    else
    {
        // find the proper key range to return
        const int32 LastFrame= TotalFrames-1;
        const float KeyPos = RelativePos * (float)LastKey;
        const float FramePos = RelativePos * (float)TotalFrames;
        const int32 FramePosFloor = FMath::Clamp(FMath::TruncToInt(FramePos), 0, LastFrame);
        const int32 KeyEstimate = FMath::Clamp(FMath::TruncToInt(KeyPos), 0, LastKey);
 
        int32 LowFrame = 0;
        int32 HighFrame = 0;
        
        // find the pair of keys which surround our target frame index
        if (NumberOfFrames > 0xFF)
        {
            const uint16* Frames= (uint16*)FrameTable;
            PosIndex0Out = FindLowKeyIndex<uint16>(Frames, NumKeys, FramePosFloor, KeyEstimate);
            LowFrame = Frames[PosIndex0Out];
 
            PosIndex1Out = PosIndex0Out + 1;
            if (PosIndex1Out > LastKey)
            {
                PosIndex1Out= EndingKey;
            }
            HighFrame= Frames[PosIndex1Out];
        }
        else
        {
            const uint8* Frames= (uint8*)FrameTable;
            PosIndex0Out = FindLowKeyIndex<uint8>(Frames, NumKeys, FramePosFloor, KeyEstimate);
            LowFrame = Frames[PosIndex0Out];
 
            PosIndex1Out = PosIndex0Out + 1;
            if (PosIndex1Out > LastKey)
            {
                PosIndex1Out= EndingKey;
            }
            HighFrame= Frames[PosIndex1Out];
        }
 
        // compute the blend parameters for the keys we have found
        int32 Delta= FMath::Max(HighFrame - LowFrame, 1);
        const float Remainder = (FramePos - (float)LowFrame);
        Alpha = Interpolation == EAnimInterpolationType::Step ? 0.f : (Remainder / (float)Delta);
    }
    
    return Alpha;
}