SimCallbackObject.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
#pragma once
 
#include "Containers/TransactionallySafeSpscQueue.h"
#include "Chaos/Defines.h"
#include "Chaos/SimCallbackInput.h"
#include "Chaos/CollisionResolutionTypes.h"
#include "Chaos/GeometryParticlesfwd.h"
#include "ChaosStats.h"
#include "Chaos/PhysicsObject.h"
 
// Enable through build or just here in code to cause an untracked callback to fail to compile
// Untracked callbacks will show up a such in profiling sessions and this can help track them down
#ifndef UE_CHAOS_UNTRACKED_CALLBACK_IS_ERROR
#define UE_CHAOS_UNTRACKED_CALLBACK_IS_ERROR 0
#endif
 
namespace Chaos
{
class FPhysicsSolverBase;
class FMidPhaseModifierAccessor;
class FCCDModifierAccessor;
class FStrainModifierAccessor;
class FCollisionContactModifier;
class FSingleParticlePhysicsProxy;
 
namespace Utilities
{
    CHAOS_API FReal GetSolverPhysicsResultsTime(const FPhysicsSolverBase*);
}
 
enum class ESimCallbackOptions : uint16
{
    None                    = 0,
    Presimulate             = 1 << 0,
    MidPhaseModification    = 1 << 1,
    CCDModification         = 1 << 2,
    ContactModification     = 1 << 3,
    StrainModification      = 1 << 5,
    ParticleRegister        = 1 << 6,
    ParticleUnregister      = 1 << 7,
    RunOnFrozenGameThread   = 1 << 8,
    Rewind                  = 1 << 9,
    PhysicsObjectUnregister = 1 << 10,
    PreIntegrate            = 1 << 11,
    PostIntegrate           = 1 << 12,
    PreSolve                = 1 << 13,
    PostSolve               = 1 << 14,
};
ENUM_CLASS_FLAGS(ESimCallbackOptions)
 
 
class ISimCallbackObject
{
public:
 
    //Destructor called on internal thread.
    virtual ~ISimCallbackObject() = default;
    ISimCallbackObject(const ISimCallbackObject&) = delete; //not copyable
 
    FReal GetSimTime_Internal() const { return SimTime_Internal; }
 
    FReal GetDeltaTime_Internal() const { return DeltaTime_Internal; }
 
    virtual bool IsFAsyncObjectManagerCallback() const { return false;}
 
    void PostInitialize_Internal()
    {
        OnPostInitialize_Internal();
    }
 
    void PreSimulate_Internal()
    {
        OnPreSimulate_Internal();
    }
 
    void PreIntegrate_Internal()
    {
        OnPreIntegrate_Internal();
    }
 
    void PostIntegrate_Internal()
    {
        OnPostIntegrate_Internal();
    }
 
    void MidPhaseModification_Internal(FMidPhaseModifierAccessor& Modifier)
    {
        OnMidPhaseModification_Internal(Modifier);
    }
 
    void CCDModification_Internal(FCCDModifierAccessor& Modifier)
    {
        OnCCDModification_Internal(Modifier);
    }
 
    void StrainModification_Internal(FStrainModifierAccessor& Modifier)
    {
        OnStrainModification_Internal(Modifier);
    }
 
    void ContactModification_Internal(FCollisionContactModifier& Modifier)
    {
        OnContactModification_Internal(Modifier);
    }
 
    void PreSolve_Internal()
    {
        OnPreSolve_Internal();
    }
 
    void PostSolve_Internal()
    {
        OnPostSolve_Internal();
    }
 
    void FinalizeOutputData_Internal()
    {
        if(CurrentOutput_Internal)
        {
            OnFinalizeOutputData_Internal(CurrentOutput_Internal);
            CurrentOutput_Internal = nullptr;
        }
    }
 
    virtual void FreeOutputData_External(FSimCallbackOutput* Output) = 0;
 
    virtual void FreeInputData_Internal(FSimCallbackInput* Input) = 0;
 
#if STATS
    TStatId GetStatId() const
    {
        static TStatId StatId = FDynamicStats::CreateStatId<FStatGroup_STATGROUP_Chaos>(GetFNameForStatId());
        return StatId;
    };
#endif
 
#if UE_CHAOS_UNTRACKED_CALLBACK_IS_ERROR
    virtual FName GetFNameForStatId() const = 0;
#else
    virtual FName GetFNameForStatId() const
    {
        const static FLazyName StaticName("Untracked Physics Callback");
        return StaticName;
    }
#endif
 
    FPhysicsSolverBase* GetSolver()
    { 
        return Solver; 
    }
    
    const FPhysicsSolverBase* GetSolver() const 
    { 
        return Solver; 
    }
 
    UE_DEPRECATED(5.5, "This callback was never called. Instead look at either ISimCallbackObject::ProcessInputs_External or FNetworkPhysicsCallback::InjectInputsExternal.")
    virtual void InjectInputs_External(int32 PhysicsStep, int32 NumSteps) {}
 
    virtual void ProcessInputs_Internal(int32 PhysicsStep) {}
 
    virtual void ProcessInputs_External(int32 PhysicsStep) {}
    
    virtual int32 TriggerRewindIfNeeded_Internal(int32 LastCompletedStep)
    {
        return INDEX_NONE;
    }
    
    virtual void ApplyCorrections_Internal(int32 PhysicsStep, FSimCallbackInput* Input)
    {
        ensure(false);
    }
    
    virtual void FirstPreResimStep_Internal(int32 PhysicsStep)
    {}
 
    bool HasOption(const ESimCallbackOptions Option) const
    {
        return (Options & Option) == Option;
    }
 
    UE_DEPRECATED(5.1, "Use HasOption(ESimCallbackOptions::RunOnFrozenGameThread) instead.")
    bool RunOnFrozenGameThread() const 
    {
        return HasOption(ESimCallbackOptions::RunOnFrozenGameThread);
    }
 
protected:
 
    ISimCallbackObject(const ESimCallbackOptions InOptions = ESimCallbackOptions::Presimulate)
        : bPendingDelete(false)
        , bPendingDelete_External(false)
        , CurrentExternalInput_External(nullptr)
        , Solver(nullptr)
        , CurrentOutput_Internal(nullptr)
        , CurrentInput_Internal(nullptr)
        , Options(InOptions)
    { }
    
 
 
    CHAOS_API FSimCallbackInput* GetProducerInputData_External();
 
    void SetCurrentInput_Internal(FSimCallbackInput* NewInput)
    {
        CurrentInput_Internal = NewInput;
    }
 
    void SetSimAndDeltaTime_Internal(const FReal InSimTime, const FReal InDeltaTime)
    {
        SimTime_Internal = InSimTime;
        DeltaTime_Internal = InDeltaTime;
    }
 
private:
    
    virtual FSimCallbackInput* AllocateInputData_External() = 0;
 
    virtual void OnPostInitialize_Internal() { }
 
    virtual void OnPreSimulate_Internal()
    {
        check(false);
    }
 
    virtual void OnPreIntegrate_Internal()
    { 
        check(false);
    }
 
    virtual void OnPostIntegrate_Internal()
    {
        check(false);
    }
 
    virtual void OnMidPhaseModification_Internal(FMidPhaseModifierAccessor& Modifier)
    {
        check(false);
    }
 
    virtual void OnCCDModification_Internal(FCCDModifierAccessor& Modifier)
    {
        check(false);
    }
 
    virtual void OnStrainModification_Internal(FStrainModifierAccessor& Modifier)
    {
        check(false);
    }
 
    virtual void OnContactModification_Internal(FCollisionContactModifier& Modifier)
    {
        //registered for contact modification, but implementation is missing
        check(false);
    }
 
    virtual void OnPreSolve_Internal()
    {
        check(false);
    }
 
    virtual void OnPostSolve_Internal()
    {
        check(false);
    }
 
    virtual void OnParticlesRegistered_Internal(TArray<FSingleParticlePhysicsProxy*>& RegisteredProxies)
    {
        check(false);
    }
 
    virtual void OnParticleUnregistered_Internal(TArray<TTuple<Chaos::FUniqueIdx, FSingleParticlePhysicsProxy*>>& UnregisteredProxies)
    {
        check(false);
    }
 
    virtual void OnPhysicsObjectUnregistered_Internal(FConstPhysicsObjectHandle PhysicsObject)
    {
        check(false);
    }
 
    virtual void OnFinalizeOutputData_Internal(FSimCallbackOutput* CurOutput)
    {
        check(false);   //wrote to output but not finalizing it. Typically this is pushed into some kind of thread safe queue
    }
 
    friend class FPBDRigidsSolver;
    friend class FPhysicsSolverBase;
    friend class FChaosMarshallingManager;
    friend struct FPushPhysicsData;
 
    bool bPendingDelete;    //used internally for more efficient deletion. Callbacks do not need to check this
    bool bPendingDelete_External;   //used for efficient deletion. Callbacks do not need to check this
 
    FSimCallbackInput* CurrentExternalInput_External;   //the input currently being filled out by external thread
    FPhysicsSolverBase* Solver;
 
    //putting this here so that user classes don't have to bother with non-default constructor
    void SetSolver_External(FPhysicsSolverBase* InSolver)
    {
        Solver = InSolver;
    }
    
    UE_DEPRECATED(5.1, "Do not change options after creation of the callback object - instead, specify them using the TOptions template parameter.")
    void SetContactModification(bool InContactModification)
    {
        Options = Options | ESimCallbackOptions::ContactModification;
    }
 
protected:
    FSimCallbackOutput* CurrentOutput_Internal; //the output currently being written to in this sim step
 
    const FSimCallbackInput* GetCurrentInput_Internal() const 
    { 
        return CurrentInput_Internal; 
    }
 
private:
    FSimCallbackInput* CurrentInput_Internal;           //the input associated with the step we are executing.
 
    FReal SimTime_Internal;
    FReal DeltaTime_Internal;
 
    // TODO: Make this const and remove the "friend class FPhysicsSolverBase"
    // once FPhysicsSolverBase::CreateAndRegisterSimCallbackObject_External(bool, bool)
    // has been deprecated.
    ESimCallbackOptions Options;
    friend class FPhysicsSolverBase;
};
 
class FSimCallbackCommandObject : public ISimCallbackObject
{
public:
    FSimCallbackCommandObject(TUniqueFunction<void()>&& InFunc, int32 Step = INDEX_NONE)
        : Func(MoveTemp(InFunc))
        , Func2(nullptr)
        , bFuncHasTimeParameters(false)
        , ExecuteOnStep(Step)
    {
        ensureMsgf(Func, TEXT("Created a sim callback object with an unbound function. This command will not be executed."));
    }
 
    FSimCallbackCommandObject(TUniqueFunction<void(FReal DeltaTime, FReal SimTime)>&& InFunc, int32 Step = INDEX_NONE)
        : Func(nullptr)
        , Func2(MoveTemp(InFunc))
        , bFuncHasTimeParameters(true)
        , ExecuteOnStep(Step)
    {
        ensureMsgf(Func2, TEXT("Created a sim callback object with an unbound function. This command will not be executed."));
    }
 
    virtual void FreeOutputData_External(FSimCallbackOutput* Output)
    {
        //data management handled by command passed in (data should be copied by value as commands run async and memory lifetime is hard to predict)
        check(false);
    }
 
    virtual FName GetFNameForStatId() const override
    {
        const static FLazyName StaticName("FSimCallbackCommandObject");
        return StaticName;
    }
 
    const bool ShouldExecute(const int32 Step, const bool bIsResim) const
    {
        return bIsResim ? ExecuteOnStep == Step : ExecuteOnStep <= Step;
    }
 
    const bool ShouldDelay(const int32 Step, const bool bIsResim) const
    {
        return !bIsResim && ExecuteOnStep > Step;
    }
 
    const int32 GetExecuteOnStep() const
    {
        return ExecuteOnStep;
    }
 
private:
 
    virtual FSimCallbackInput* AllocateInputData_External()
    {
        //data management handled by command passed in (data should be copied by value as commands run async and memory lifetime is hard to predict)
        check(false);
        return nullptr;
    }
 
    virtual void FreeInputData_Internal(FSimCallbackInput* Input)
    {
        //data management handled by command passed in (data should be copied by value as commands run async and memory lifetime is hard to predict)
        check(false);
    }
 
    virtual void OnPreSimulate_Internal() override
    {
        if (!bFuncHasTimeParameters)
        {
            if (ensureMsgf(Func, TEXT("The function of this sim callback object became unbound. This should not happen. This command will not be executed.")))
            {
                Func();
            }
        }
        else
        {
            if (ensureMsgf(Func2, TEXT("The function of this sim callback object became unbound. This should not happen. This command will not be executed.")))
            {
                Func2(GetDeltaTime_Internal(), GetSimTime_Internal());
            }
        }
        
    }
 
    // Those two function could be in an union 
    TUniqueFunction<void()> Func;
    TUniqueFunction<void(FReal deltaTime, FReal SimTime)> Func2;
 
    bool bFuncHasTimeParameters;
    int32 ExecuteOnStep;
 
    friend struct FSimCallbackInput;
};
 
template <typename TInputType = FSimCallbackNoInput, typename TOutputType = FSimCallbackNoOutput, ESimCallbackOptions TOptions = ESimCallbackOptions::Presimulate>
class TSimCallbackObject : public ISimCallbackObject
{
public:
 
    TSimCallbackObject()
        : ISimCallbackObject(TOptions)
        , CurrentOutput_External(nullptr)
    { }
 
    UE_DEPRECATED(5.1, "Use default constructor instead and specify RunFrozenOnGameThread using TOptions template parameter.")
    TSimCallbackObject(bool InRunOnFrozenGameThread)
        : ISimCallbackObject(InRunOnFrozenGameThread ? (TOptions | ESimCallbackOptions::RunOnFrozenGameThread) : TOptions)
        , CurrentOutput_External(nullptr)
    { }
 
    virtual void FreeOutputData_External(FSimCallbackOutput* Output) override
    {
        auto Concrete = static_cast<TOutputType*>(Output);
        Concrete->Reset();
        OutputPool.Enqueue(Concrete);
    }
 
    TInputType* GetProducerInputData_External()
    {
        return static_cast<TInputType*>(ISimCallbackObject::GetProducerInputData_External());
    }
 
    const TInputType* GetConsumerInput_Internal() const
    {
        return static_cast<const TInputType*>(GetCurrentInput_Internal());
    }
 
    TSimCallbackOutputHandle<TOutputType> PopOutputData_External()
    {
        const FReal ResultsTime = Utilities::GetSolverPhysicsResultsTime(GetSolver());
        if(!CurrentOutput_External)
        {
            OutputQueue.Dequeue(CurrentOutput_External);
        }
 
        if(CurrentOutput_External && CurrentOutput_External->InternalTime <= ResultsTime)
        {
            TOutputType* Output = CurrentOutput_External;
            CurrentOutput_External = nullptr;
            return TSimCallbackOutputHandle<TOutputType>(Output, this);
        }
        else
        {
            return TSimCallbackOutputHandle<TOutputType>();
        }
    }
 
    TSimCallbackOutputHandle<TOutputType> PopFutureOutputData_External()
    {
        if (!CurrentOutput_External)
        {
            OutputQueue.Dequeue(CurrentOutput_External);
        }
        
        TOutputType* Output = CurrentOutput_External;
        CurrentOutput_External = nullptr;
        return TSimCallbackOutputHandle<TOutputType>(Output, this);
    }
 
    bool IsOutputQueueEmpty_External() const
    {
        return OutputQueue.IsEmpty();
    }
 
    TOutputType& GetProducerOutputData_Internal()
    {
        if(!CurrentOutput_Internal)
        {
            CurrentOutput_Internal = NewOutputData_Internal(GetSimTime_Internal());
        }
 
        return static_cast<TOutputType&>(*CurrentOutput_Internal);
    }
 
private:
 
    TOutputType* NewOutputData_Internal(const FReal InternalTime)
    {
        auto NewOutput = NewDataHelper(OutputBacking, OutputPool);
        NewOutput->InternalTime = InternalTime;
        return NewOutput;
    }
 
    template <typename T>
    T* NewDataHelper(TArray<TUniquePtr<T>>& Backing, TTransactionallySafeSpscQueue<T*>& Queue)
    {
        T* Result;
        if (!Queue.Dequeue(Result))
        {
            Backing.Emplace(new T());
            Result = Backing.Last().Get();
        }
 
        return Result;
    }
 
    virtual void FreeInputData_Internal(FSimCallbackInput* Input) override
    {
        auto Concrete = static_cast<TInputType*>(Input);
        Concrete->Reset();
        InputPool.Enqueue(Concrete);
    }
 
    TInputType* NewInputData_External()
    {
        return NewDataHelper(InputBacking, InputPool);
    }
 
    virtual FSimCallbackInput* AllocateInputData_External() override
    {
        return NewInputData_External();
    }
 
    void OnFinalizeOutputData_Internal(FSimCallbackOutput* BaseOutput) override
    {
        OutputQueue.Enqueue(static_cast<TOutputType*>(BaseOutput));
    }
 
    TTransactionallySafeSpscQueue<TInputType*> InputPool;
    TArray<TUniquePtr<TInputType>> InputBacking;
 
    TTransactionallySafeSpscQueue<TOutputType*> OutputPool;
    TArray<TUniquePtr<TOutputType>> OutputBacking;
    TTransactionallySafeSpscQueue<TOutputType*> OutputQueue;    //holds the outputs in order
 
    TOutputType* CurrentOutput_External;    //the earliest output we can consume
};
 
struct FSimCallbackInputAndObject
{
    ISimCallbackObject* CallbackObject;
    FSimCallbackInput* Input;
};
 
inline void FSimCallbackInput::Release_Internal(ISimCallbackObject& CallbackObj)
{
    //free once all steps are done with this input
    ensure(NumSteps);
    if(--NumSteps == 0)
    {
        CallbackObj.FreeInputData_Internal(this);
    }
}
 
inline void FSimCallbackOutputHandle::Free_External()
{
    if (SimCallbackOutput)
    {
        SimCallbackObject->FreeOutputData_External(SimCallbackOutput);
    }
}
 
}; // namespace Chaos