AvatarInstance.h

浏览该文件的文档.

#pragma once
#include "common/Export.h"
 
 
#include "common/AttachmentPoint.h"
#include "common/AnimationEventSource.h"
 
#include <array>
#include <functional>
#include <memory>
#include <string>
#include <unordered_map>
#include <utility>
#include <vector>
 
namespace eve::graphics {
struct DrawItem2D;
class Mesh;
class Material;
class Renderable2D;
class Renderable3D;
class Texture;
}  // namespace eve::graphics
 
namespace eve::image {
class ImageData;
}
 
namespace eve::model3d {
class ModelData;
}
 
namespace eve::scene {
class Scene;
}
 
namespace eve::inventory {
class EquipmentSet;
}
 
namespace eve::animation {
class AnimClip;
class AnimPlayer;
class AnimLayerMixer;
class AnimConstraintStack;
class AnimPose;
class AnimSkin;
class AnimSkeleton;
class AnimStateMachine;
class DynamicBoneSolver;
class FootIKSolver;
class Tween;
}
 
namespace eve::avatar {
 
class VrmRuntime;
 
enum class EquipmentVisualChange {
    Applied,
    Unchanged,
    Removed,
    Rejected,
};
 
enum class SkinnedPartUpdateMode {
    Unavailable = 0,
    Gpu         = 1,
    Cpu         = 2,
};
 
class ILive2DBackend {
public:
    virtual ~ILive2DBackend() = default;
    virtual std::string getName() const = 0;
    virtual bool  isRuntimeAvailable() const { return true; }
    virtual bool loadModel(const std::string &path) = 0;
    virtual void update(float dt) = 0;
    virtual void setParameter(const std::string &name, float value) = 0;
    virtual float getParameter(const std::string &name) const = 0;
    virtual bool setExpression(const std::string &name) = 0;
    virtual bool setMotion(const std::string &name) = 0;
    virtual void setTransform(float /*x*/, float /*y*/, float /*sx*/, float /*sy*/) {}
    virtual void setVisible(bool /*visible*/) {}
    virtual void setLayer(int /*layer*/) {}
    virtual void collectDrawItems(std::vector<graphics::DrawItem2D> & /*out*/) {}
};
 
using Live2DBackendFactory = ILive2DBackend *(*)();
 
class EVENGINE_API_DOMAINS AvatarInstance : public eve::IAttachmentPointSource, public eve::IAnimationEventSource {
public:
    using DestroyHook = std::function<void(AvatarInstance *)>;
 
    explicit AvatarInstance(std::string kind);
    ~AvatarInstance();
 
    AvatarInstance(const AvatarInstance &) = delete;
    AvatarInstance &operator=(const AvatarInstance &) = delete;
 
    std::string getKind() const { return kind_; }
 
    void setPosition(float x, float y);
    float getX() const { return x_; }
    float getY() const { return y_; }
 
    void setScale(float sx, float sy);
    float getScaleX() const { return sx_; }
    float getScaleY() const { return sy_; }
 
    void setVisible(bool visible);
    bool isVisible() const { return visible_; }
 
    void setLayer(int layer);
    int getLayer() const { return layer_; }
 
    void setExpression(const std::string &name);
    std::string getExpression() const { return expression_; }
 
    void setMotion(const std::string &name);
    std::string getMotion() const { return motion_; }
 
    void setParameter(const std::string &name, float value);
    float getParameter(const std::string &name) const;
    bool hasParameter(const std::string &name) const;
    int getParameterCount() const;
    std::string getParameterName(int index) const;
    bool defineParameter(const std::string& name, float defaultValue, float minimum, float maximum);
    float getParameterDefault(const std::string& name) const;
    float getParameterMinimum(const std::string& name) const;
    float getParameterMaximum(const std::string& name) const;
 
    void update(float dt);
    void sync();
 
    void release();
 
    size_t addDestroyHook(DestroyHook hook);
    void removeDestroyHook(size_t id);
 
    // ---- image kind ----
    bool addLayer(const std::string &name, graphics::Texture *texture, int zIndex);
    bool setLayerTexture(const std::string &name, graphics::Texture *texture);
    bool setLayerVisible(const std::string &name, bool visible);
    bool setLayerOffset(const std::string &name, float ox, float oy);
    bool setLayerColor(const std::string &name, float r, float g, float b, float a);
    bool setLayerZ(const std::string &name, int zIndex);
    bool setLayerSize(const std::string &name, float w, float h);
    int getLayerCount() const;
    std::string getLayerName(int index) const;
    bool hasLayer(const std::string &name) const;
    graphics::Renderable2D* getLayerRenderable(const std::string& name);
    bool defineExpression(const std::string &name, const std::string &spec);
    bool removeExpression(const std::string& name);
    int getExpressionCount() const;
    std::string getExpressionName(int index) const;
    bool applyExpression(const std::string &name);
    bool transitionExpression(const std::string& name, float duration);
 
    // ---- live2d kind ----
    bool loadLive2DModel(const std::string &path);
    std::string getLive2DBackendName() const;
    bool hasLive2DBackend() const;
    void collectLive2DDrawItems(std::vector<graphics::DrawItem2D>& out);
 
    // ---- vroid kind ----
    [[nodiscard]] eve::Result<void> loadVroidModel(std::string_view path);
    bool loadVroidModelPath(const std::string &path);
    int getVroidMeshCount() const;
    int getVroidSpringCount() const;
    std::string getVroidVersion() const;
    [[nodiscard]] eve::Result<void> setHumanoidBoneRotation(std::string_view semantic, float yaw, float pitch,
                                                            float roll);
    bool bindVroidModelData(model3d::ModelData *data);
    int loadMorphNamesFromModel(int meshIndex = 0);
    void setMesh(graphics::Mesh *mesh);
    void setTexture(graphics::Texture *texture);
    void setPosition3D(float x, float y, float z);
    void setRotation3D(float yaw, float pitch, float roll);
    void setScale3D(float sx, float sy, float sz);
    graphics::Renderable3D* getRenderable3D() const;
    graphics::Mesh *getBoundMesh() const;
    std::string getVroidModelPath() const { return vroidPath_; }
    bool bakeMorphs();
 
    // ---- skeletal animation ----
    bool bindAnimPlayer(animation::AnimPlayer* player);
    bool bindAnimStateMachine(animation::AnimStateMachine* machine);
    bool bindAnimLayerMixer(animation::AnimLayerMixer* mixer);
    void setAnimConstraintStack(animation::AnimConstraintStack* stack);
    animation::AnimConstraintStack* getAnimConstraintStack() const { return animConstraintStack_.get(); }
    void setFootIKSolver(animation::FootIKSolver* solver);
    animation::FootIKSolver* getFootIKSolver() const { return footIKSolver_.get(); }
    void setDynamicBoneSolver(animation::DynamicBoneSolver* solver);
    animation::DynamicBoneSolver* getDynamicBoneSolver() const { return dynamicBoneSolver_.get(); }
    bool bindAnimSkin(animation::AnimSkin* skin);
    EquipmentVisualChange bindSkinnedPart(int partIndex, const std::string& partName,
                                          graphics::Mesh* mesh, graphics::Material* material,
                                          animation::AnimSkin* skin);
    EquipmentVisualChange unbindSkinnedPart(int partIndex);
    SkinnedPartUpdateMode getSkinnedPartUpdateMode(int partIndex) const;
    bool registerMotion(const std::string& name, animation::AnimClip* clip);
    bool unregisterMotion(const std::string& name);
    int getMotionCount() const;
    std::string getMotionName(int index) const;
    animation::AnimClip* getMotionClip(const std::string& name) const;
    void setMotionBlendTime(float seconds);
    void setApplyRootMotion(bool enabled);
    bool getApplyRootMotion() const { return applyRootMotion_; }
    float getRootMotionDeltaX() const { return rootMotionDeltaX_; }
    float getRootMotionDeltaZ() const { return rootMotionDeltaZ_; }
    int getAnimationEventCount() const;
    std::string getAnimationEventLayer(int index) const;
    std::string getAnimationEventName(int index) const;
    std::string getAnimationEventPayload(int index) const;
    [[nodiscard]] std::size_t animationEventCount() const noexcept override;
    [[nodiscard]] std::string animationEventName(std::size_t index) const override;
    bool mapHumanoidBone(const std::string& semantic, const std::string& boneName);
    int autoMapHumanoidBones();
    std::string getHumanoidBoneName(const std::string& semantic) const;
    bool mapViseme(const std::string& viseme, const std::string& morphName);
    bool setViseme(const std::string& viseme, float weight);
    bool setLookAtTarget(float x, float y, float z);
    void setLookAtWeight(float weight);
    void clearLookAtTarget();
    bool attachToBone(const std::string& name, const std::string& boneSemanticOrName,
                      graphics::Renderable3D* renderable, float ox = 0.f, float oy = 0.f, float oz = 0.f);
    bool detachAttachment(const std::string& name);
    int getAttachmentCount() const { return static_cast<int>(attachments_.size()); }
    [[nodiscard]] eve::Result<eve::AttachmentPoint> sampleAttachmentPoint(
        std::string_view name, eve::AttachmentPoint localOffset = {}) const override;
    bool linkSceneNode(scene::Scene* scene, const std::string& nodeId);
    bool isSceneLinked() const { return sceneLinked_; }
 
    // ---- equipment appearance projection ----
    EquipmentVisualChange bindEquipment(inventory::EquipmentSet* equipment);
    EquipmentVisualChange unbindEquipment();
    EquipmentVisualChange defineEquipmentVisual2D(const std::string& itemId,
                                                   const std::string& equipmentSlot,
                                                   const std::string& layerName,
                                                   graphics::Texture* texture, int zIndex);
    EquipmentVisualChange defineEquipmentVisual3D(const std::string& itemId,
                                                   const std::string& equipmentSlot,
                                                   graphics::Renderable3D* renderable,
                                                   const std::string& boneSemanticOrName,
                                                   float ox = 0.f, float oy = 0.f, float oz = 0.f);
    EquipmentVisualChange defineEquipmentSkinnedVisual3D(
        const std::string& itemId, const std::string& equipmentSlot, int partIndex,
        const std::string& partName, graphics::Mesh* mesh, graphics::Material* material,
        animation::AnimSkin* skin);
    EquipmentVisualChange defineEquipmentLayer(const std::string& name, int order,
                                                const std::string& parent = {});
    EquipmentVisualChange addEquipmentLayerOcclusion(const std::string& outerLayer,
                                                      const std::string& innerLayer);
    EquipmentVisualChange setEquipmentVisualLayer(const std::string& itemId,
                                                  const std::string& equipmentSlot,
                                                  const std::string& wearLayer,
                                                  int withinLayerOrder = 0);
    EquipmentVisualChange syncEquipmentAppearance();
    std::string getEquipmentVisualItem(const std::string& equipmentSlot) const;
    int getEquipmentRenderStackCount() const;
    std::string getEquipmentRenderStackItem(int index) const;
    std::string getEquipmentRenderStackLayer(int index) const;
 
    // ---- animation tween binding ----
    void bindTween(animation::Tween *tween);
    void unbindTween();
    animation::Tween *getBoundTween() const { return tween_; }
 
private:
    struct Layer {
        std::string name;
        graphics::Renderable2D *entity = nullptr;
        int zIndex = 0;
        bool visible = true;
        bool                    autoSize = true;
        float ox = 0.f, oy = 0.f;
        float                   appliedParentRotation = 0.f;
    };
 
    Layer *findLayer(const std::string &name);
    const Layer *findLayer(const std::string &name) const;
    void syncImageLayers();
    void syncVroid();
    void destroyLayers();
    void destroyVroid();
    bool applyExpressionSpec(const std::string &spec);
 
    std::string kind_;
    float x_ = 0.f, y_ = 0.f;
    float sx_ = 1.f, sy_ = 1.f;
    bool visible_ = true;
    int layer_ = 100;
    std::string expression_;
    std::string motion_;
    std::unordered_map<std::string, float> parameters_;
    std::vector<std::string> parameterOrder_;
    struct ParameterMetadata {
        float defaultValue = 0.f;
        float minimum      = 0.f;
        float maximum      = 1.f;
    };
    std::unordered_map<std::string, ParameterMetadata> parameterMetadata_;
 
    // image
    std::vector<Layer> layers_;
    std::unordered_map<std::string, std::string> expressionDefs_;
    std::unordered_map<std::string, float>       expressionBlendFrom_;
    std::unordered_map<std::string, float>       expressionBlendTo_;
    float                                        expressionBlendElapsed_  = 0.f;
    float                                        expressionBlendDuration_ = 0.f;
    std::vector<std::pair<size_t, DestroyHook>> destroyHooks_;
    size_t nextDestroyHookId_ = 0;
 
    // live2d
    ILive2DBackend *live2d_ = nullptr;
 
    // vroid
    std::unique_ptr<VrmRuntime> vrm_;
    std::string vroidPath_;
    model3d::ModelData *vroidData_ = nullptr;
    graphics::Renderable3D *renderable3d_ = nullptr;
    graphics::Renderable2D* sceneAnchor2d_ = nullptr;
    graphics::Mesh *boundMesh_ = nullptr;
    float x3_ = 0.f, y3_ = 0.f, z3_ = 0.f;
    float yaw_ = 0.f, pitch_ = 0.f, roll_ = 0.f;
    float sx3_ = 1.f, sy3_ = 1.f, sz3_ = 1.f;
 
    animation::Tween *tween_ = nullptr;
    animation::AnimPlayer*                                animPlayer_       = nullptr;
    animation::AnimLayerMixer*                            animLayerMixer_   = nullptr;
    animation::AnimStateMachine*                          animStateMachine_ = nullptr;
    std::unique_ptr<animation::AnimConstraintStack>       animConstraintStack_;
    std::unique_ptr<animation::FootIKSolver>              footIKSolver_;
    std::unique_ptr<animation::DynamicBoneSolver>         dynamicBoneSolver_;
    animation::AnimSkin*                                  animSkin_         = nullptr;
    animation::AnimSkeleton*                              animSkeleton_     = nullptr;
    std::vector<std::array<float, 16>>                    attachmentPoseMatrices_;
    std::unordered_map<std::string, animation::AnimClip*> motions_;
    std::unordered_map<std::string, std::string>          humanoidBones_;
    std::unordered_map<std::string, std::string>          visemeMorphs_;
    std::string                                           activeViseme_;
    struct Attachment {
        std::string             name;
        std::string             boneName;
        graphics::Renderable3D* renderable = nullptr;
        float                   ox = 0.f, oy = 0.f, oz = 0.f;
    };
    std::vector<Attachment> attachments_;
    struct SkinnedPart {
        int                      partIndex = -1;
        std::string              partName;
        graphics::Mesh*          mesh     = nullptr;
        graphics::Material*      material = nullptr;
        animation::AnimSkin*     skin     = nullptr;
        std::vector<float>       cpuPositions;
        bool                     active = true;
        SkinnedPartUpdateMode    updateMode = SkinnedPartUpdateMode::Unavailable;
    };
    std::vector<SkinnedPart> skinnedParts_;
    struct EquipmentVisual {
        std::string             itemId;
        std::string             equipmentSlot;
        std::string             layerName;
        graphics::Texture*      texture    = nullptr;
        graphics::Renderable3D* renderable = nullptr;
        graphics::Mesh*         skinnedMesh     = nullptr;
        graphics::Material*     skinnedMaterial = nullptr;
        animation::AnimSkin*    skinnedSkin     = nullptr;
        int                     partIndex       = -1;
        std::vector<float>      cpuPositions;
        SkinnedPartUpdateMode   updateMode = SkinnedPartUpdateMode::Unavailable;
        std::string             boneName;
        std::string             wearLayer;
        int                     zIndex = 0;
        int                     withinLayerOrder = 0;
        float                   ox = 0.f, oy = 0.f, oz = 0.f;
    };
    inventory::EquipmentSet*                 equipment_ = nullptr;
    std::vector<EquipmentVisual>             equipmentVisuals_;
    std::unordered_map<std::string, std::string> projectedEquipment_;
    std::string                              equipmentSignature_;
    struct EquipmentLayer {
        std::string              parent;
        int                      order = 0;
        std::vector<std::string> occludes;
    };
    struct EquipmentRenderEntry {
        std::string itemId;
        std::string wearLayer;
        int         order = 0;
    };
    std::unordered_map<std::string, EquipmentLayer> equipmentLayers_;
    std::vector<EquipmentRenderEntry>                equipmentRenderStack_;
    float                   lookAtX_ = 0.f, lookAtY_ = 0.f, lookAtZ_ = 1.f;
    float                   lookAtWeight_  = 1.f;
    bool                    lookAtEnabled_ = false;
    bool                    lookAtApplied_ = false;
    float                   lookAtBaseQx_ = 0.f, lookAtBaseQy_ = 0.f, lookAtBaseQz_ = 0.f, lookAtBaseQw_ = 1.f;
    float                   lookAtPostQx_ = 0.f, lookAtPostQy_ = 0.f, lookAtPostQz_ = 0.f, lookAtPostQw_ = 1.f;
    std::vector<float>      skinnedPositions_;
    float                   motionBlendTime_  = 0.2f;
    float                   rootMotionDeltaX_ = 0.f, rootMotionDeltaZ_ = 0.f;
    float                   previousRootX_ = 0.f, previousRootZ_ = 0.f;
    bool                    applyRootMotion_     = false;
    bool                    hasPreviousRoot_     = false;
    int                     rootMotionLoopCount_ = 0;
    bool                    sceneLinked_         = false;
 
    void ensureParameter(const std::string &name, float value = 0.f);
    void applyTweenTracks();
    void syncMorphWeightsToMesh();
    animation::AnimPose* updateSkeletalAnimation(float dt);
    void                 updateRootMotion(animation::AnimPose* pose);
    void                 updateSkin(animation::AnimPose* pose);
    SkinnedPartUpdateMode updateSkinnedMesh(animation::AnimSkin* skin, graphics::Mesh* mesh,
                                            animation::AnimPose* pose,
                                            std::vector<float>& cpuPositions);
    void                 updateAttachments(animation::AnimPose* pose);
    void                 applyLookAt(animation::AnimPose* pose);
    void                 updateExpressionTransition(float dt);
    void                 hideEquipmentVisuals();
    int                  equipmentLayerOrder(const std::string& name) const;
 
    bool released_ = false;
};
 
}  // namespace eve::avatar