MovieScenePlaybackCapabilities.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
#pragma once
 
#include "CoreTypes.h"
#include "Evaluation/IMovieScenePlaybackCapability.h"
#include "EntitySystem/RelativePtr.h"
#include "MovieSceneFwd.h"
#include "Templates/AlignmentTemplates.h"
#include "Templates/PointerIsConvertibleFromTo.h"
#include <type_traits>
 
class IMovieScenePlayer;
class IMovieScenePlaybackClient;
 
namespace UE::MovieScene
{
 
enum class EPlaybackCapabilityStorageMode : uint8
{
    Inline = 0,
    RawPointer,
    SharedPointer
};
 
struct FPlaybackCapabilityPtr
{
    void* Ptr = 0;
    EPlaybackCapabilityStorageMode StorageMode;
 
    template<typename T>
    T* ResolveOptional() const
    {
        if (Ptr)
        {
            switch (StorageMode)
            {
                case EPlaybackCapabilityStorageMode::Inline:
                    return static_cast<T*>(Ptr);
                case EPlaybackCapabilityStorageMode::RawPointer:
                    return *static_cast<T**>(Ptr);
                case EPlaybackCapabilityStorageMode::SharedPointer:
                    return static_cast<TSharedPtr<T>*>(Ptr)->Get();
                default:
                    checkf(false, TEXT("Unexpected playback capability storage mode"));
                    return nullptr;
            }
        }
        return nullptr;
    }
 
    template<typename T>
    T& ResolveChecked() const
    {
        check(Ptr);
        switch (StorageMode)
        {
            case EPlaybackCapabilityStorageMode::Inline:
                return *static_cast<T*>(Ptr);
            case EPlaybackCapabilityStorageMode::RawPointer:
                return **static_cast<T**>(Ptr);
            case EPlaybackCapabilityStorageMode::SharedPointer:
                return *static_cast<TSharedPtr<T>*>(Ptr)->Get();
            default:
                checkf(false, TEXT("Unexpected playback capability storage mode"));
                // Nothing reasonable to do, let's just proceed as if it was inline
                return *static_cast<T*>(Ptr);
        }
    }
};
 
// Utility callbacks for the concrete capability objects we have in a container.
using FPlaybackCapabilityInterfaceCastHelper = IPlaybackCapability*(*)(void* Ptr);
using FPlaybackCapabilityDestructionHelper = void(*)(void* Ptr);
 
// Callback for casting a stored capabilty object to an IPlaybackCapability pointer if possible.
template<typename StorageType>
struct TPlaybackCapabilityInterfaceCast
{
    static IPlaybackCapability* InterfaceCast(void* Ptr)
    {
        if constexpr (TPointerIsConvertibleFromTo<StorageType, IPlaybackCapability>::Value)
        {
            return static_cast<IPlaybackCapability*>((StorageType*)Ptr);
        }
        else
        {
            return nullptr;
        }
    }
};
template<typename PointedType>
struct TPlaybackCapabilityInterfaceCast<PointedType*>
{
    static IPlaybackCapability* InterfaceCast(void* Ptr) 
    {
        if constexpr (TPointerIsConvertibleFromTo<PointedType, IPlaybackCapability>::Value)
        {
            PointedType* TypedPtr = *(PointedType**)Ptr;
            return static_cast<IPlaybackCapability*>(TypedPtr);
        }
        else
        {
            return nullptr;
        }
    };
};
template<typename PointedType>
struct TPlaybackCapabilityInterfaceCast<TSharedPtr<PointedType>>
{
    static IPlaybackCapability* InterfaceCast(void* Ptr) 
    {
        if constexpr (TPointerIsConvertibleFromTo<PointedType, IPlaybackCapability>::Value)
        {
            TSharedPtr<PointedType>& TypedPtr = *(TSharedPtr<PointedType>*)Ptr;
            return static_cast<IPlaybackCapability*>(TypedPtr.Get());
        }
        else
        {
            return nullptr;
        }
    };
};
 
// Callback for destroying the stored capability object, whether that's the capability itself
// (when stored inline), or a shared pointer, or whatever else.
template<typename StorageType>
struct TPlaybackCapabilityDestructor
{
    static void Destroy(void* Ptr)
    {
        StorageType* StoragePtr = (StorageType*)Ptr;
        StoragePtr->~StorageType();
    }
};
 
// Helper callbacks for managing the lifetime of a capability.
struct FPlaybackCapabilityHelpers
{
    FPlaybackCapabilityInterfaceCastHelper InterfaceCast = nullptr;
    FPlaybackCapabilityDestructionHelper Destructor = nullptr;
};
 
template<typename StorageType>
struct TPlaybackCapabilityHelpers
{
    static FPlaybackCapabilityHelpers GetHelpers()
    {
        FPlaybackCapabilityHelpers Helpers;
        Helpers.InterfaceCast = &TPlaybackCapabilityInterfaceCast<StorageType>::InterfaceCast;
        Helpers.Destructor = &TPlaybackCapabilityDestructor<StorageType>::Destroy;
        return Helpers;
    }
};
 
// Storage traits for playback capabilities, only for internal use.
template<typename StorageType, typename CapabilityType, typename=void>
struct TPlaybackCapabilityStorageTraits;
 
template<typename StorageType, typename CapabilityType>
struct TPlaybackCapabilityStorageTraits<StorageType, CapabilityType, typename TEnableIf<TPointerIsConvertibleFromTo<StorageType, CapabilityType>::Value>::Type>
{
    static EPlaybackCapabilityStorageMode GetStorageMode() { return EPlaybackCapabilityStorageMode::Inline; }
 
    static uint8 ComputePointerOffset(StorageType* StoragePtr)
    {
        const uint64 PointerOffset =
            reinterpret_cast<uint64>(static_cast<CapabilityType*>(StoragePtr))
            -
            reinterpret_cast<uint64>(StoragePtr);
        check(PointerOffset <= TNumericLimits<uint8>::Max());
        return static_cast<uint8>(PointerOffset);
    }
};
 
template<typename CapabilityType>
struct TPlaybackCapabilityStorageTraits<CapabilityType*, CapabilityType, void>
{
    static EPlaybackCapabilityStorageMode GetStorageMode() { return EPlaybackCapabilityStorageMode::RawPointer; }
 
    static uint8 ComputePointerOffset(CapabilityType** StoragePtr) { return 0; }
};
 
template<typename CapabilityType>
struct TPlaybackCapabilityStorageTraits<TSharedPtr<CapabilityType>, CapabilityType, void>
{
    static EPlaybackCapabilityStorageMode GetStorageMode() { return EPlaybackCapabilityStorageMode::SharedPointer; }
 
    static uint8 ComputePointerOffset(TSharedPtr<CapabilityType>* StoragePtr) { return 0; }
};
 
struct FPlaybackCapabilityHeader
{
#if UE_MOVIESCENE_ENTITY_DEBUG
    // Extra debugging field.
    IPlaybackCapabilityDebuggingTypedPtr* DebugPtr = nullptr;
#endif
 
    // 2 Bytes
    TRelativePtr<void, uint16> Capability;
 
    // 2 Bytes
    uint16 Sizeof = 0;
 
    // 1 Byte
    uint8 Alignment = 0;
 
    // 1 Byte
    uint8 PointerOffset = 0;
 
    // 1 Byte
    EPlaybackCapabilityStorageMode StorageMode = EPlaybackCapabilityStorageMode::Inline;
 
    FPlaybackCapabilityPtr Resolve(void* InMemory) const
    {
        void* DerivedPointer = Capability.Resolve(InMemory);
        return FPlaybackCapabilityPtr{ (void*)((uint8*)DerivedPointer + PointerOffset), StorageMode };
    }
};
 
struct FPlaybackCapabilitiesImpl
{
protected:
 
    FPlaybackCapabilitiesImpl() = default;
 
    FPlaybackCapabilitiesImpl(const FPlaybackCapabilitiesImpl&) = delete;
    FPlaybackCapabilitiesImpl& operator=(const FPlaybackCapabilitiesImpl&) = delete;
 
    FPlaybackCapabilitiesImpl(FPlaybackCapabilitiesImpl&&) = delete;
    FPlaybackCapabilitiesImpl& operator=(FPlaybackCapabilitiesImpl&&) = delete;
 
    bool HasCapability(uint32 CapabilityBit) const
    {
        return (AllCapabilities & CapabilityBit) != 0;
    }
 
    FPlaybackCapabilityPtr FindCapability(uint32 CapabilityBit) const
    {
        if (HasCapability(CapabilityBit))
        {
            const int32 Index = GetCapabilityIndex(CapabilityBit);
            check(Index >= 0 && Index < 255);
            return GetHeader(static_cast<uint8>(Index)).Resolve(Memory);
        }
 
        return FPlaybackCapabilityPtr();
    }
 
    FPlaybackCapabilityPtr GetCapabilityChecked(uint32 CapabilityBit) const
    {
        const int32 Index = GetCapabilityIndex(CapabilityBit);
        check(Index >= 0 && Index < 255);
        return GetHeader(static_cast<uint8>(Index)).Resolve(Memory);
    }
 
    template<typename StorageType, typename CapabilityType, typename ...ArgTypes>
    FPlaybackCapabilityPtr AddCapability(uint32 CapabilityBit, ArgTypes&&... InArgs)
    {
        checkf((AllCapabilities & CapabilityBit) == 0, TEXT("Capability already exists!"));
 
        // Add the enum entry
        AllCapabilities |= CapabilityBit;
 
        // Find the index of the new capability by counting how many bits are set before it
        // For example, given CapabilityBit=0b00010000 and AllCapabilities=0b00011011:
        //                      (CapabilityBit-1) = 0b00001111
        //    AllCapabilities & (CapabilityBit-1) = 0b00001011
        //                  CountBits(0b00001011) = 3
        const int32 NewCapabilityIndex = static_cast<int32>(FMath::CountBits(AllCapabilities & (CapabilityBit-1u)));
 
        const FPlaybackCapabilityHeader* ExistingHeaders = reinterpret_cast<const FPlaybackCapabilityHeader*>(Memory);
 
        uint64 RequiredAlignment = FMath::Max(alignof(StorageType), alignof(FPlaybackCapabilityHeader));
 
        const int32 ExistingNum = static_cast<int32>(Num);
 
        // Compute our required alignment for the allocation
        {
            for (int32 Index = 0; Index < ExistingNum; ++Index)
            {
                RequiredAlignment = FMath::Max(RequiredAlignment, (uint64)ExistingHeaders[Index].Alignment);
            }
        }
 
        // We'll keep track of where all our new capabilities will go, relative to the buffer start
        TArray<uint16, TInlineAllocator<16>> NewCapabilityOffsets;
        NewCapabilityOffsets.SetNum(ExistingNum + 1);
 
        // Compute the required size of our allocation
        uint64 RequiredSizeof = 0u;
 
        {
            // Allocate space for headers
            RequiredSizeof += (ExistingNum + 1) * sizeof(FPlaybackCapabilityHeader);
 
            int32 Index = 0;
 
            // Count up the sizes and alignments of pre-existing capabilities that exist before this new entry
            for (; Index < NewCapabilityIndex; ++Index)
            {
                RequiredSizeof = Align(RequiredSizeof, (uint64)ExistingHeaders[Index].Alignment);
                NewCapabilityOffsets[Index] = static_cast<uint16>(RequiredSizeof);
                RequiredSizeof += ExistingHeaders[Index].Sizeof;
            }
 
            // Count up the size and alignment for the new capability
            RequiredSizeof = Align(RequiredSizeof, alignof(StorageType));
            NewCapabilityOffsets[Index] = static_cast<uint16>(RequiredSizeof);
            RequiredSizeof += sizeof(StorageType);
            ++Index;
 
            // Now count up the sizes and alignments of pre-existing capabilities that exist after this new entry
            for (; Index < ExistingNum+1; ++Index)
            {
                RequiredSizeof = Align(RequiredSizeof, (uint64)ExistingHeaders[Index-1].Alignment);
                NewCapabilityOffsets[Index] = static_cast<uint16>(RequiredSizeof);
                RequiredSizeof += ExistingHeaders[Index-1].Sizeof;
            }
        }
 
        check( RequiredAlignment <= 0XFF );
 
 
        uint8* OldMemory = Memory;
 
        // Make a new allocation if necessary
        const bool bNeedsReallocation = RequiredAlignment > Alignment || RequiredSizeof > Capacity;
        if (bNeedsReallocation)
        {
            // Use the greater of the required size or double the current size to allow some additional capcity
            Capacity = static_cast<uint16>(FMath::Max(RequiredSizeof, uint64(Capacity)*2));
            Memory = reinterpret_cast<uint8*>(FMemory::Malloc(Capacity, RequiredAlignment));
        }
 
        // We now have an extra entry
        ++Num;
 
        // We now need to re-arrange memory carefully, going back to front in order to avoid overlaps.
        // For instance we can only move headers at the end of the whole operation, otherwise they could overwrite
        // the memory of the first couple capabilities before we've had a chance to move them. So we do:
        // 
        // 1) Relocate capabilities from the last one up to where the new one will go
        // 2) Allocate the new capability
        // 3) Relocate capabilities from the one just before the new one, down to the first one
        // 4) Relocate headers from the last one up to where the new one will go
        // 5) Allocate the new header
        // 6) Relocate headers from the one just before the new header, down to the first one
        //
        // In order to set the new capability pointers (obtained in steps 1-3) on the new headers (obtained in
        // steps 4-6), we save these pointers in a temporary array.
 
        const FPlaybackCapabilityHeader* OldHeaders = ExistingHeaders; // Better named variable for the rest of the steps...
 
        auto RelocateCapability = [this, OldMemory, OldHeaders, &NewCapabilityOffsets](int32 OldIndex, int32 NewIndex)
        {
            void* NewCapabilityPtr = this->Memory + NewCapabilityOffsets[NewIndex];
            void* OldCapabilityPtr = OldHeaders[OldIndex].Capability.Resolve(OldMemory);
            FMemory::Memmove(NewCapabilityPtr, OldCapabilityPtr, OldHeaders[OldIndex].Sizeof);
        };
 
        // Step 1
        int32 Index = static_cast<int32>(Num) - 1;
        for (; Index > NewCapabilityIndex; --Index)
        {
            RelocateCapability(Index - 1, Index);
        }
 
        // Step 2
        {
            void* NewCapabilityPtr = this->Memory + NewCapabilityOffsets[Index];
            StorageType* NewCapabilityTypedPtr = reinterpret_cast<StorageType*>(NewCapabilityPtr);
            new (NewCapabilityTypedPtr) StorageType (Forward<ArgTypes>(InArgs)...);
        }
        --Index;
        
        // Step 3
        for (; Index >= 0; --Index)
        {
            RelocateCapability(Index, Index);
        }
        
        FPlaybackCapabilityHeader* NewHeaders = reinterpret_cast<FPlaybackCapabilityHeader*>(Memory);
 
        auto RelocateHeader = [this, OldHeaders, NewHeaders, &NewCapabilityOffsets](int32 OldIndex, int32 NewIndex)
        {
            const FPlaybackCapabilityHeader& OldHeader(OldHeaders[OldIndex]);
            FPlaybackCapabilityHeader* NewHeaderPtr = &NewHeaders[NewIndex];
            new (NewHeaderPtr) FPlaybackCapabilityHeader(OldHeader);
 
            // Re-create the relative capability pointer, since the offset has changed (it's one capability
            // further down), and the base pointer may have changed too (if we re-allocated the buffer)
            void* NewCapabilityPtr = this->Memory + NewCapabilityOffsets[NewIndex];
            NewHeaderPtr->Capability = TRelativePtr<void, uint16>(this->Memory, NewCapabilityPtr);
 
            // The new header will share its debugging pointer with the old header at this point. But the old
            // header will be gone when we free the entire old memory buffer after step 6.
        };
 
        // Step 4
        Index = static_cast<int32>(Num) - 1;
        for (; Index > NewCapabilityIndex; --Index)
        {
            RelocateHeader(Index - 1, Index);
        }
 
        // Step 5
        FPlaybackCapabilityHeader* NewHeaderPtr = &NewHeaders[Index];
        {
            using FStorageTraits = TPlaybackCapabilityStorageTraits<StorageType, CapabilityType>;
            static_assert(alignof(StorageType) < 0x7F, "Required alignment of capability must fit in 7 bytes");
 
            void* NewCapabilityPtr = Memory + NewCapabilityOffsets[Index];
            StorageType* NewCapabilityTypedPtr = reinterpret_cast<StorageType*>(NewCapabilityPtr);
 
            static_assert(sizeof(StorageType) <= MAX_uint16, "Can't store a playback capability with a size above 65535 bits. Store it as a raw or shared pointer.");
            static_assert(alignof(StorageType) <= MAX_uint8, "Can't store a playback capability with an alignment above 255 bits. Store it as a raw or shared pointer.");
 
            new (NewHeaderPtr) FPlaybackCapabilityHeader(); // Reset to default constructor
 
            NewHeaderPtr->Capability.Reset(Memory, NewCapabilityPtr);
            NewHeaderPtr->Sizeof = static_cast<uint16>(sizeof(StorageType));
            NewHeaderPtr->Alignment = static_cast<uint8>(alignof(StorageType));
            NewHeaderPtr->StorageMode = FStorageTraits::GetStorageMode();
            // The pointer offset is whatever we need to add to the capability pointer in order to get
            // a pointer to capability type itself (in case the storage type is a sub-class of it)
            // We only need it if the capability object is stored inline inside our memory buffer.
            NewHeaderPtr->PointerOffset = FStorageTraits::ComputePointerOffset(NewCapabilityTypedPtr);
 
#if UE_MOVIESCENE_ENTITY_DEBUG
            // Set the debug pointer.
            NewHeaderPtr->DebugPtr = new TPlaybackCapabilityDebuggingTypedPtr<StorageType>(NewCapabilityTypedPtr);
#endif
        }
        --Index;
 
        // Step 6
        for (; Index >= 0; --Index)
        {
            RelocateHeader(Index, Index);
        }
 
 
        // Tidy up the old allocation. We do not call destructors here because we relocated everything.
        if (bNeedsReallocation && OldMemory)
        {
            FMemory::Free(OldMemory);
        }
 
        // Insert the helpers for the new capability.
        Helpers.Insert(TPlaybackCapabilityHelpers<StorageType>::GetHelpers(), NewCapabilityIndex);
 
        // Return the new capability pointer. We call the header's Resolve method here because returning 
        // the pointer of the stored capability would return the derived type pointer. 
        // We want the base (capability) pointer.
        return NewHeaderPtr->Resolve(Memory);
    }
 
    template<typename StorageType, typename CapabilityType, typename ...ArgTypes>
    bool OverwriteCapability(uint32 CapabilityBit, ArgTypes&&... InArgs)
    {
        if (!ensureMsgf(HasCapability(CapabilityBit), TEXT("The given capability does not exist in this container")))
        {
            return false;
        }
 
        // Get the header for this capability
        const int32 Index = GetCapabilityIndex(CapabilityBit);
        FPlaybackCapabilityHeader& Header = GetHeader(static_cast<uint8>(Index));
 
        // Check that we are overwriting the same storage mode
        using FStorageTraits = TPlaybackCapabilityStorageTraits<StorageType, CapabilityType>;
        EPlaybackCapabilityStorageMode GivenStorageMode = FStorageTraits::GetStorageMode();
        if (!ensureMsgf(GivenStorageMode == Header.StorageMode, TEXT("The given capability storage mode does not match the existing one")))
        {
            return false;
        }
 
        // Check that the types and alignments match
        size_t GivenSizeof = sizeof(StorageType);
        uint16 GivenAlignment = alignof(StorageType);
        if (!ensureMsgf(
                    (GivenSizeof == Header.Sizeof && GivenAlignment == Header.Alignment),
                    TEXT("The given capability size and alignment do not match the existing one")))
        {
            return false;
        }
 
        // Don't use the header's Resolve method, we don't want to offset the pointer, we want
        // the actual pointer to the actual stored capability.
        void* CapabilityPtr = Header.Capability.Resolve(Memory);
 
        // Call the destructor on the previous capability, which is important if it was stored inline or as
        // a shared pointer.
        Helpers[Index].Destructor(CapabilityPtr);
 
        // Allocate the new capability.
        StorageType* TypedCapabilityPtr = reinterpret_cast<StorageType*>(CapabilityPtr);
        new (TypedCapabilityPtr) StorageType(Forward<ArgTypes>(InArgs)...);
 
        // If we have inline storage, we could potentially have changed from a stored base-class to
        // a stored child-class, or vice-versa, or from one child-class to another child-class. In all these
        // cases, the helper functions (destructor, interface cast, etc) have changed, so let's store the 
        // new helper functions on the header.
        Helpers[Index] = TPlaybackCapabilityHelpers<StorageType>::GetHelpers();
 
#if UE_MOVIESCENE_ENTITY_DEBUG
        // Update the debug pointer.
        delete Header.DebugPtr;
        Header.DebugPtr = new TPlaybackCapabilityDebuggingTypedPtr<StorageType>(TypedCapabilityPtr);
#endif
 
        return true;
    }
 
    const FPlaybackCapabilityHeader& GetHeader(uint8 Index) const
    {
        check(Index < Num);
        return reinterpret_cast<FPlaybackCapabilityHeader*>(Memory)[Index];
    }
 
    FPlaybackCapabilityHeader& GetHeader(uint8 Index)
    {
        check(Index < Num);
        return reinterpret_cast<FPlaybackCapabilityHeader*>(Memory)[Index];
    }
 
    TArrayView<const FPlaybackCapabilityHeader> GetHeaders() const
    {
        return MakeArrayView(reinterpret_cast<FPlaybackCapabilityHeader*>(Memory), Num);
    }
 
    int32 GetCapabilityIndex(uint32 CapabilityBit) const
    {
        if ( (AllCapabilities & CapabilityBit) == 0)
        {
            return INDEX_NONE;
        }
        return FMath::CountBits(AllCapabilities & (CapabilityBit-1u));
    }
    
    // Schema:
    // [header_1|...|header_n|entry_0|...|entry_n]
    uint8* Memory = nullptr;
    uint16 Alignment = 0u;
    uint16 Capacity = 0u;
    uint8 Num = 0u;
    uint32 AllCapabilities = 0u;
 
    // Function pointers for invalidating, destroying, etc. capabilities.
    TArray<FPlaybackCapabilityHelpers> Helpers;
};
 
namespace Internal
{
 
template<typename T, typename = void>
struct TPlaybackCapabilityIDType {};
 
template<typename T>
struct TPlaybackCapabilityIDType<
    T,
    std::enable_if_t<
        std::is_assignable_v<FPlaybackCapabilityID, decltype(T::GetPlaybackCapabilityID())>
        >>
{
    using Type = std::decay_t<decltype(T::GetPlaybackCapabilityID())>;
 
    static Type Get() { return T::GetPlaybackCapabilityID(); }
};
 
template<typename T>
struct TPlaybackCapabilityIDType<
    T,
    std::enable_if_t<
        std::is_assignable_v<FPlaybackCapabilityID, decltype(T::ID)>
        >>
{
    using Type = std::decay_t<decltype(T::ID)>;
 
    static Type Get() { return T::ID; }
};
 
}  // namespace Internal
 
struct FPlaybackCapabilities : FPlaybackCapabilitiesImpl
{
    FPlaybackCapabilities() = default;
 
    FPlaybackCapabilities(const FPlaybackCapabilities&) = delete;
    FPlaybackCapabilities& operator=(const FPlaybackCapabilities&) = delete;
 
    MOVIESCENE_API FPlaybackCapabilities(FPlaybackCapabilities&&);
    MOVIESCENE_API FPlaybackCapabilities& operator=(FPlaybackCapabilities&&);
 
    MOVIESCENE_API ~FPlaybackCapabilities();
 
    template<typename T>
    bool HasCapability() const
    {
        uint32 CapabilityBit = 1 << Internal::TPlaybackCapabilityIDType<T>::Get().Index;
        return FPlaybackCapabilitiesImpl::HasCapability(CapabilityBit);
    }
 
    template<typename T>
    T* FindCapability() const
    {
        // T must be the base capability type, and not a sub-class, because we are returning a pointer to it,
        // and we can't check what sort of sub-class we have or not.
        using CapabilityIDType = typename Internal::TPlaybackCapabilityIDType<T>::Type;
        static_assert(std::is_same<T, typename CapabilityIDType::CapabilityType>::value, "You must pass the actual playback capability type as a template parameter, not a sub-class.");
 
        const TPlaybackCapabilityID<T> CapabilityID(Internal::TPlaybackCapabilityIDType<T>::Get());
        uint32 CapabilityBit = 1 << CapabilityID.Index;
        FPlaybackCapabilityPtr Ptr = FPlaybackCapabilitiesImpl::FindCapability(CapabilityBit);
        return Ptr.ResolveOptional<T>();
    }
 
    template<typename T>
    T& GetCapabilityChecked() const
    {
        // T must be the base capability type, and not a sub-class, because we are returning a reference to it,
        // and we can't check what sort of sub-class we have or not.
        using CapabilityIDType = typename Internal::TPlaybackCapabilityIDType<T>::Type;
        static_assert(std::is_same<T, typename CapabilityIDType::CapabilityType>::value, "You must pass the actual playback capability type as a template parameter, not a sub-class.");
 
        const TPlaybackCapabilityID<T> CapabilityID(Internal::TPlaybackCapabilityIDType<T>::Get());
        uint32 CapabilityBit = 1 << CapabilityID.Index;
        FPlaybackCapabilityPtr Ptr = FPlaybackCapabilitiesImpl::GetCapabilityChecked(CapabilityBit);
        return Ptr.ResolveChecked<T>();
    }
 
    template<typename T, typename ...ArgTypes>
    T& AddCapability(ArgTypes&&... InArgs)
    {
        using CapabilityIDType = typename Internal::TPlaybackCapabilityIDType<T>::Type;
        using CapabilityType = typename CapabilityIDType::CapabilityType;
 
        CapabilityType& NewCapability = DoAddCapability<T>(Internal::TPlaybackCapabilityIDType<T>::Get(), Forward<ArgTypes>(InArgs)...);
        return static_cast<T&>(NewCapability);
    }
 
    template<typename T, typename U, typename ...ArgTypes>
    T& AddCapability(const TPlaybackCapabilityID<U> CapabilityID, ArgTypes&&... InArgs)
    {
        U& NewCapability = DoAddCapability<T>(CapabilityID, Forward<ArgTypes>(InArgs)...);
        return static_cast<T&>(NewCapability);
    }
 
    template<typename T>
    T& AddCapabilityRaw(T* InPointer)
    {
        using CapabilityIDType = typename Internal::TPlaybackCapabilityIDType<T>::Type;
        using CapabilityType = typename CapabilityIDType::CapabilityType;
 
        CapabilityType& NewCapability = DoAddCapability<CapabilityType*>(Internal::TPlaybackCapabilityIDType<T>::Get(), static_cast<CapabilityType*>(InPointer));
        return static_cast<T&>(NewCapability);
    }
    
    template<typename T>
    T& AddCapabilityShared(TSharedRef<T> InSharedRef)
    {
        using CapabilityIDType = typename Internal::TPlaybackCapabilityIDType<T>::Type;
        using CapabilityType = typename CapabilityIDType::CapabilityType;
 
        CapabilityType& NewCapability = DoAddCapability<TSharedPtr<CapabilityType>>(Internal::TPlaybackCapabilityIDType<T>::Get(), StaticCastSharedRef<CapabilityType>(InSharedRef));
        return static_cast<T&>(NewCapability);
    }
 
    template<typename T, typename ...ArgTypes>
    T& OverwriteCapability(ArgTypes&&... InArgs)
    {
        using CapabilityIDType = typename Internal::TPlaybackCapabilityIDType<T>::Type;
        using CapabilityType = typename CapabilityIDType::CapabilityType;
 
        CapabilityType& NewCapability = DoOverwriteCapability<T>(Internal::TPlaybackCapabilityIDType<T>::Get(), Forward<ArgTypes>(InArgs)...);
        return static_cast<T&>(NewCapability);
    }
 
    template<typename T>
    T& OverwriteCapabilityRaw(T* InPointer)
    {
        using CapabilityIDType = typename Internal::TPlaybackCapabilityIDType<T>::Type;
        using CapabilityType = typename CapabilityIDType::CapabilityType;
 
        CapabilityType& NewCapability = DoOverwriteCapability<CapabilityType*>(Internal::TPlaybackCapabilityIDType<T>::Get(), static_cast<CapabilityType*>(InPointer));
        return static_cast<T&>(NewCapability);
    }
    
    template<typename T>
    T& OverwriteCapabilityShared(TSharedRef<T> InSharedRef)
    {
        using CapabilityIDType = typename Internal::TPlaybackCapabilityIDType<T>::Type;
        using CapabilityType = typename CapabilityIDType::CapabilityType;
 
        CapabilityType& NewCapability = DoOverwriteCapability<TSharedPtr<CapabilityType>>(Internal::TPlaybackCapabilityIDType<T>::Get(), StaticCastSharedRef<CapabilityType>(InSharedRef));
        return static_cast<T&>(NewCapability);
    }
 
public:
 
    void OnSubInstanceCreated(TSharedRef<const FSharedPlaybackState> Owner, const FInstanceHandle InstanceHandle);
 
    void InvalidateCachedData(UMovieSceneEntitySystemLinker* Linker);
 
private:
 
    template<typename Callback, typename ...ArgTypes>
    void ForEachCapabilityInterface(Callback&& InCallback, ArgTypes&&... InArgs)
    {
        TArrayView<const FPlaybackCapabilityHeader> Headers = GetHeaders();
        for (int32 Index = 0; Index < Headers.Num(); ++Index)
        {
            const FPlaybackCapabilityHeader& Header = Headers[Index];
            const FPlaybackCapabilityHelpers& ThisHelpers = Helpers[Index];
            check(ThisHelpers.InterfaceCast != nullptr);
            {
                void* Ptr = Header.Capability.Resolve(Memory);
                if (IPlaybackCapability* Interface = (*ThisHelpers.InterfaceCast)(Ptr))
                {
                    InCallback(*Interface, Forward<ArgTypes>(InArgs)...);
                }
            }
        }
    }
 
    template<typename Impl, typename T, typename ...ArgTypes>
    T& DoAddCapability(TPlaybackCapabilityID<T> CapabilityID, ArgTypes&&... InArgs)
    {
        uint32 CapabilityBit = 1 << CapabilityID.Index;
        FPlaybackCapabilityPtr Ptr = FPlaybackCapabilitiesImpl::AddCapability<Impl, T>(CapabilityBit, Forward<ArgTypes>(InArgs)...);
        return Ptr.ResolveChecked<T>();
    }
 
    template<typename Impl, typename T, typename ...ArgTypes>
    T& DoOverwriteCapability(TPlaybackCapabilityID<T> CapabilityID, ArgTypes&&... InArgs)
    {
        uint32 CapabilityBit = 1 << CapabilityID.Index;
        FPlaybackCapabilitiesImpl::OverwriteCapability<Impl, T>(CapabilityBit, Forward<ArgTypes>(InArgs)...);
        return GetCapabilityChecked<T>();
    }
 
    void Destroy();
};
 
} // namespace UE::MovieScene