AnimClip.h

浏览该文件的文档.

#pragma once
#include "common/Export.h"
 
 
#include "animation/AnimMath.h"
#include "animation/AnimSmr.h"
#include "common/Result.h"
 
#include <memory>
#include <string>
#include <string_view>
#include <vector>
 
namespace eve::animation {
 
class AnimPose;
class AnimSkeleton;
 
class EVENGINE_API_WORLD AnimRetargetProfile {
public:
    void addBoneMapping(const std::string& sourceBone, const std::string& targetBone);
    void clearBoneMappings();
    void setNormalizedNameMatching(bool enabled) { normalizedNameMatching_ = enabled; }
    bool getNormalizedNameMatching() const { return normalizedNameMatching_; }
 
    void setRootBones(const std::string& sourceBone, const std::string& targetBone);
    void setAutoRootScale(bool enabled) { autoRootScale_ = enabled; }
    bool getAutoRootScale() const { return autoRootScale_; }
    void setRootTranslationScale(float horizontal, float vertical);
    float getRootHorizontalScale() const { return rootHorizontalScale_; }
    float getRootVerticalScale() const { return rootVerticalScale_; }
    void setUseSkeletonSpaceRotation(bool enabled) { skeletonSpaceRotation_ = enabled; }
    bool getUseSkeletonSpaceRotation() const { return skeletonSpaceRotation_; }
 
    void setSkinnedInteractionPreserve(bool enabled) { skinnedInteractionPreserve_ = enabled; }
    bool getSkinnedInteractionPreserve() const { return skinnedInteractionPreserve_; }
    void setInteractionContactThreshold(float distance);
    float getInteractionContactThreshold() const { return interactionContactThreshold_; }
    void setInteractionCorrectionWeight(float weight);
    float getInteractionCorrectionWeight() const { return interactionCorrectionWeight_; }
    void addInteractionIkChain(const std::string& rootBone, const std::string& midBone, const std::string& tipBone);
    void clearInteractionIkChains();
    int getInteractionCorrectionCount() const { return interactionCorrectionCount_; }
 
    void setNeuralModelPath(const std::string& path) { neuralModelPath_ = path; }
    const std::string& getNeuralModelPath() const { return neuralModelPath_; }
    void setNeuralRetargetEnabled(bool enabled) { neuralRetargetEnabled_ = enabled; }
    bool getNeuralRetargetEnabled() const { return neuralRetargetEnabled_; }
    void setNeuralBackend(const std::string& backend) { neuralBackend_ = backend; }
    const std::string& getNeuralBackend() const { return neuralBackend_; }
    int getNeuralInferenceCount() const { return neuralInferenceCount_; }
 
    int getMatchedBoneCount() const { return matchedBoneCount_; }
    int getUnmatchedBoneCount() const { return static_cast<int>(unmatchedTargetBones_.size()); }
    std::string getUnmatchedTargetBone(int index) const;
 
private:
    friend class AnimClip;
    friend int smrRefineRetargetedClip(const AnimClip&, AnimClip&, const AnimSkeleton*, const AnimSkeleton*,
                                       AnimRetargetProfile&);
    struct Mapping {
        std::string source, target;
    };
    std::vector<Mapping>        mappings_;
    std::string                 sourceRoot_;
    std::string                 targetRoot_;
    bool                        normalizedNameMatching_      = true;
    bool                        autoRootScale_               = true;
    bool                        skeletonSpaceRotation_       = true;
    bool                        skinnedInteractionPreserve_  = false;
    bool                        neuralRetargetEnabled_       = false;
    float                       rootHorizontalScale_         = 1.f;
    float                       rootVerticalScale_           = 1.f;
    float                       interactionContactThreshold_ = 0.f;
    float                       interactionCorrectionWeight_ = 1.f;
    int                         matchedBoneCount_            = 0;
    int                         interactionCorrectionCount_  = 0;
    int                         neuralInferenceCount_        = 0;
    std::string                 neuralModelPath_;
    std::string                 neuralBackend_ = "auto";
    std::vector<std::string>    unmatchedTargetBones_;
    std::vector<AnimSmrIkChain> interactionIkChains_;
};
 
class EVENGINE_API_WORLD AnimClip {
public:
    explicit AnimClip(std::string name = "");
    ~AnimClip();
 
    AnimClip(const AnimClip&)            = delete;
    AnimClip& operator=(const AnimClip&) = delete;
 
    void        setName(const std::string& name) { name_ = name; }
    std::string getName() const { return name_; }
 
    void  setDuration(float seconds);
    float getDuration() const { return duration_; }
 
    void setLoop(bool loop) { loop_ = loop; }
    bool getLoop() const { return loop_; }
 
    void  setSampleRate(float hz);
    float getSampleRate() const { return sampleRate_; }
 
    void addPositionKey(int boneIndex, float time, float x, float y, float z);
    void addRotationKey(int boneIndex, float time, float x, float y, float z, float w);
    void addScaleKey(int boneIndex, float time, float x, float y, float z);
    bool setPositionKey(int boneIndex, int keyIndex, float time, float x, float y, float z);
    bool setRotationKey(int boneIndex, int keyIndex, float time, float x, float y, float z, float w);
    bool setScaleKey(int boneIndex, int keyIndex, float time, float x, float y, float z);
    bool removePositionKey(int boneIndex, int keyIndex);
    bool removeRotationKey(int boneIndex, int keyIndex);
    bool removeScaleKey(int boneIndex, int keyIndex);
    bool clearTrack(int boneIndex);
    int getTrackCount() const { return static_cast<int>(tracks_.size()); }
    void addEvent(float time, const std::string& name, const std::string& payload = "");
    bool setEvent(int index, float time, const std::string& name, const std::string& payload = "");
    bool removeEvent(int index);
    int getEventCount() const { return static_cast<int>(events_.size()); }
    float getEventTime(int index) const;
    std::string getEventName(int index) const;
    std::string getEventPayload(int index) const;
    [[nodiscard]] bool hasEvent(std::string_view name) const noexcept;
    [[nodiscard]] eve::Result<void> validateNotifyContract(const std::vector<std::string>& requiredNames) const;
 
    void addSyncMarker(float time, const std::string& name);
    bool setSyncMarker(int index, float time, const std::string& name);
    bool removeSyncMarker(int index);
    int getSyncMarkerCount() const { return static_cast<int>(syncMarkers_.size()); }
    float getSyncMarkerTime(int index) const;
    std::string getSyncMarkerName(int index) const;
    bool hasCompatibleSyncMarkers(const AnimClip* target) const;
    float mapSyncTimeTo(float time, const AnimClip* target) const;
 
    int getPositionKeyCount(int boneIndex) const;
    int getRotationKeyCount(int boneIndex) const;
    int getScaleKeyCount(int boneIndex) const;
 
    float getPositionKeyTime(int boneIndex, int keyIndex) const;
    float getPositionKeyX(int boneIndex, int keyIndex) const;
    float getPositionKeyY(int boneIndex, int keyIndex) const;
    float getPositionKeyZ(int boneIndex, int keyIndex) const;
 
    float getRotationKeyTime(int boneIndex, int keyIndex) const;
    float getRotationKeyX(int boneIndex, int keyIndex) const;
    float getRotationKeyY(int boneIndex, int keyIndex) const;
    float getRotationKeyZ(int boneIndex, int keyIndex) const;
    float getRotationKeyW(int boneIndex, int keyIndex) const;
 
    float getScaleKeyTime(int boneIndex, int keyIndex) const;
    float getScaleKeyX(int boneIndex, int keyIndex) const;
    float getScaleKeyY(int boneIndex, int keyIndex) const;
    float getScaleKeyZ(int boneIndex, int keyIndex) const;
 
    void applyPlanarRootMotion(int boneIndex, float speedX, float speedZ);
 
    int compress(float positionError = 0.001f, float rotationErrorDegrees = 0.1f, float scaleError = 0.001f);
 
    AnimClip* retarget(const AnimSkeleton* sourceSkeleton, const AnimSkeleton* targetSkeleton) const;
 
    AnimClip* retargetWithProfile(const AnimSkeleton* sourceSkeleton, const AnimSkeleton* targetSkeleton,
                                  AnimRetargetProfile* profile) const;
 
    void sample(float time, AnimPose* out, const AnimSkeleton* skeleton = nullptr) const;
    void sampleLod(float time, AnimPose* out, const AnimSkeleton* skeleton, int lodLevel) const;
 
    float wrapTime(float time) const;
 
    [[nodiscard]] std::unique_ptr<AnimClip> clone() const;
 
    void adopt(AnimClip& other);
    void collectEvents(float previousTime, float currentTime, bool loop, std::vector<std::string>& out) const;
 
private:
    friend class AnimPlayer;
    friend class MotionDatabase;
    friend class AnimClipBinaryAccess;
    struct Vec3Key {
        float t = 0.f, x = 0.f, y = 0.f, z = 0.f;
    };
    struct QuatKey {
        float t = 0.f, x = 0.f, y = 0.f, z = 0.f, w = 1.f;
    };
    struct BoneTrack {
        std::vector<Vec3Key> positions;
        std::vector<QuatKey> rotations;
        std::vector<Vec3Key> scales;
    };
    struct EventMarker {
        float       t = 0.f;
        std::string name;
        std::string payload;
    };
    struct SyncMarker {
        float       t = 0.f;
        std::string name;
    };
 
    void         ensureBone(int boneIndex);
    TransformTRS sampleBone(int boneIndex, float time, const TransformTRS& fallback) const;
    void         sampleClamped(float time, AnimPose* out, const AnimSkeleton* skeleton) const;
 
    static void sampleVec3(const std::vector<Vec3Key>& keys, float time, float& x, float& y, float& z, bool& ok);
    static void sampleQuat(const std::vector<QuatKey>& keys, float time, float& x, float& y, float& z, float& w,
                           bool& ok);
 
    std::string              name_;
    float                    duration_   = 0.f;
    bool                     loop_       = true;
    float                    sampleRate_ = 30.f;
    std::vector<BoneTrack>   tracks_;
    std::vector<EventMarker> events_;
    std::vector<SyncMarker>  syncMarkers_;
};
 
}  // namespace eve::animation