MotionDatabase.h

浏览该文件的文档.

#pragma once
#include "common/Export.h"
 
#include "animation/AnimPose.h"
#include "common/Result.h"
 
#include <string>
#include <memory>
#include <vector>
#include <span>
#include <cstddef>
 
namespace eve::animation {
 
class AnimClip;
class AnimSkeleton;
class MotionMatcher;
struct MotionFeatureLayout;
namespace detail { struct MotionSchemaState; }
 
struct MotionNormalizationRange {
    int clipIndex = 0;
    float start = 0.f;
    float end = 0.f;
};
 
class EVENGINE_API_WORLD MotionDatabase {
public:
    explicit MotionDatabase(AnimSkeleton* skeleton);
    ~MotionDatabase();
 
    MotionDatabase(const MotionDatabase&)            = delete;
    MotionDatabase& operator=(const MotionDatabase&) = delete;
 
    AnimSkeleton* getSkeleton() const { return skeleton_; }
 
    void addFeatureBone(int boneIndex);
    void addFeatureBoneByName(const std::string& name);
 
    [[nodiscard]] eve::Result<void> setLocomotionFeatures(int leftFoot, int rightFoot, int pelvis);
    bool hasLocomotionFeatures() const { return locomotionFeatures_; }
 
    [[nodiscard]] eve::Result<void> setFeatureLayout(const MotionFeatureLayout& layout);
    bool hasFeatureLayout() const;
    [[nodiscard]] eve::Result<void> setFeatureCurves(std::span<const std::byte> bytes,
                                                     std::span<const std::string> sources);
    [[nodiscard]] eve::Result<int> setFeatureNormalizationRanges(std::span<const MotionNormalizationRange> ranges);
 
    void setRootBone(int boneIndex);
    int  getRootBone() const { return rootBone_; }
    void setRootBoneByName(const std::string& name);
 
    void addClip(AnimClip* clip);
    int  getClipCount() const { return static_cast<int>(clips_.size()); }
 
    void bake();
    bool isBaked() const { return baked_; }
 
    int getFrameCount() const { return static_cast<int>(frames_.size()); }
    int getFeatureSize() const { return featureSize_; }
 
    float     getFrameTime(int frameIndex) const;
    int       getFrameClipIndex(int frameIndex) const;
    AnimClip* getClip(int clipIndex) const;
 
    int getFeatureBoneCount() const { return static_cast<int>(featureBones_.size()); }
    int getFeatureBone(int index) const;
 
    void getFeature(int frameIndex, float* out, int outCount) const;
    void normalizeFeature(std::vector<float>& feature) const;
 
    struct Frame {
        int                clipIndex = 0;
        float              time      = 0.f;
        std::vector<float> feature;
        // Cached root for trajectory reconstruction helpers.
        float rootX = 0.f, rootZ = 0.f, rootYaw = 0.f;
        float velX = 0.f, velZ = 0.f;
        // Sum of unnormalized trajectory-velocity channel magnitudes, retained
        // before feature normalization for UE-compatible play-rate estimation.
        float trajectorySpeed = 0.f;
    };
 
    const Frame& frameAt(int index) const;
 
private:
    struct SchemaSampler;
    friend class MotionMatcher;
    float schemaTrajectorySpeed(std::span<const float> feature) const;
    void extractSchemaFeature(AnimClip* clip, float time, std::vector<float>& out, float& rootX,
                              float& rootZ, float& rootYaw, float& velX, float& velZ) const;
    void normalizeSchemaFeatures();
    void extractLocomotionFeature(AnimClip* clip, float time, std::vector<float>& out, float& rootX, float& rootZ,
                                  float& rootYaw, float& velX, float& velZ) const;
    void normalizeLocomotionFeatures();
    void requireBaked() const;
    void computeFeatureSize();
    void extractFeature(AnimClip* clip, float time, float dtSample, std::vector<float>& out, float& rootX, float& rootZ,
                        float& rootYaw, float& velX, float& velZ) const;
    static float yawFromQuat(float x, float y, float z, float w);
 
    AnimSkeleton*          skeleton_ = nullptr;
    std::vector<AnimClip*> clips_;
    std::vector<int>       featureBones_;
    std::vector<Frame>     frames_;
    // Contiguous baked-frame span for each clip; size is clips_.size() + 1.
    std::vector<int>       clipFrameOffsets_;
    int                    featureSize_ = 0;
    int                    rootBone_    = 0;
    bool                   baked_       = false;
    bool                   locomotionFeatures_ = false;
    std::vector<float>     featureMean_;
    std::vector<float>     featureInvStd_;
    mutable AnimPose       scratchPose_;
    std::unique_ptr<detail::MotionSchemaState> schema_;
    std::vector<MotionNormalizationRange> normalizationRanges_;
};
 
}  // namespace eve::animation