CameraController.h

浏览该文件的文档.

#pragma once
#include "common/Export.h"
 
 
#include "action/ActionCameraBlock.h"
#include "common/Module.h"
#include "common/Result.h"
#include "common/PcgPhotoModeApply.h"
 
#include <glm/glm.hpp>
 
#include <string>
#include <cstdint>
#include <deque>
#include <vector>
 
namespace eve::graphics {
class Camera3D;
}
namespace eve::platform_event {
class PlatformEvent;
}
namespace eve::scene {
class SceneNodeRef;
}
 
namespace eve::camera {
 
struct PcgPhotoModePostFxState {
    float postFxExposure = 13.5f;
    int64_t postFxExposureMode = 0;
    bool depthOfFieldActive = true;
    bool autoDepthOfFieldFocus = true;
    float focusDistance = 100.f;
    float aperture = 16.f;
    float focalLength = 50.f;
    int64_t kernelSize = 1;
    int64_t savedFocusMode = 0;
    int64_t focusModeHdrp = 0;
    int64_t focusModeUrp = 0;
    int64_t qualityHdrp = 1;
    float nearBlurStart = 0.f;
    float nearBlurEnd = 0.1f;
    float farBlurStart = 200.f;
    float farBlurEnd = 2000.f;
    float blurStartUrp = 2.f;
    float blurEndUrp = 1000.f;
    float maximumBlurRadius = 1.f;
    bool highQualityUrp = false;
};
 
class EVENGINE_API_WORLD CameraController : public action::IActionCameraCueSink, public IPhotoModeFieldSink {
public:
    CameraController();
    ~CameraController() override;
 
    void setActionCuesEnabled(bool enabled);
    [[nodiscard]] bool getActionCuesEnabled() const;
    [[nodiscard]] bool supports(const LogicalId& cue) const noexcept override;
    [[nodiscard]] Result<void> trigger(const action::ActionCameraCueBinding& binding,
                                       const action::ActionNotifyContext& context) override;
 
    // --- 绑定要驱动的摄像机 ---
    void                setCamera(graphics::Camera3D* cam);
    graphics::Camera3D* getCamera() const;
 
    // --- 目标 / 观察锚点 ---
    void setTarget(float x, float y, float z);
    void  setTargetNode(scene::SceneNodeRef* node);
    float getTargetX() const;
    float getTargetY() const;
    float getTargetZ() const;
    void setOffset(float x, float y, float z);
    void setLookAhead(float x, float y, float z);
    void setSecondaryTarget(float x, float y, float z);
    void clearSecondaryTarget();
    [[nodiscard]] bool hasSecondaryTarget() const noexcept { return hasSecondaryTarget_; }
    float              getSecondaryTargetX() const;
    float              getSecondaryTargetY() const;
    float              getSecondaryTargetZ() const;
 
    // --- 视角模式 ---
    void        setMode(const std::string& mode);
    std::string getMode() const;
 
    // --- orbit / topdown 参数 ---
    void setRadius(float r);              // orbit 半径 / topdown 高度
    [[nodiscard]] Result<void> setRadiusLimits(float minimum, float maximum);
    void setAzimuth(float deg);           // orbit 方位角
    void setElevation(float deg);         // orbit 仰角
    void setOrbitSpeed(float degPerSec);  // 自动盘旋转速
 
    // --- firstperson 参数 ---
    void setYaw(float deg);
    void setPitch(float deg);
    void addInput(float yawDeltaDeg, float pitchDeltaDeg, float zoomDelta);
 
    void setPhotoModeAuthority(bool enabled);
    bool getPhotoModeAuthority() const noexcept{return photoModeAuthority_;}
    PhotoModeFieldAcceptance acceptsPhotoModeField(const PhotoModeAssignment& assignment) const noexcept override;
    [[nodiscard]] Result<void> applyPhotoModeField(const PhotoModeAssignment& assignment) override;
    [[nodiscard]] Result<void> setCameraRoll(float degrees);
    float getCameraRoll() const noexcept{return cameraRollDeg_;}
    float getPcgCullingDistance() const noexcept{return pcgCullingDistance_;}
    const PcgPhotoModePostFxState& getPcgPostFxState() const noexcept{return pcgPostFxState_;}
    // --- framing / lens ---
    void setComposition(float screenX, float screenY);
    void  setDeadZone(float radius);
    void  setFov(float degrees);
    float getFov() const;
 
    // --- 平滑 ---
    void setSmooth(float damping);  // 每秒指数阻尼，越大越跟手
    void setPositionSmooth(float damping);
    void setTargetSmooth(float damping);
    void setMaxSpeed(float unitsPerSec);  // 0 = 不限速
    void snap();                          // 立即应用当前目标视角
 
    // --- obstruction / collision ---
    void setCollisionEnabled(bool enabled);
    void setCollisionRadius(float radius);
    void setCollisionRecovery(float damping);
    void setCollisionMask(uint64_t maskBits);
    void setCollisionIgnoredBody(int bodyId);
    void clearCollisionBoxes();
    void addCollisionBox(float minX, float minY, float minZ, float maxX, float maxY, float maxZ);
    bool isObstructed() const;
    int  getCollisionBodyId() const;
 
    // --- camera rigs / director ---
    bool addRig(const std::string& name, const std::string& mode, int priority);
    bool removeRig(const std::string& name);
    bool setRigPriority(const std::string& name, int priority);
    bool setRigEnabled(const std::string& name, bool enabled);
    bool        saveRigState(const std::string& name);
    bool        activateRig(const std::string& name, float blendTime);
    std::string getActiveRig() const;
 
    // --- additive modifiers ---
    void addImpulse(float positionAmplitude, float rotationAmplitude, float duration, unsigned int seed = 0);
    void addFovImpulse(float degrees, float duration);
    void clearImpulses();
 
    // --- cinematic / 自动切换视角 ---
    void addView(const std::string& name, float ex, float ey, float ez, float tx, float ty, float tz);
    bool switchTo(const std::string& name, float blendTime);
    void playSequence(float stepTime);  // 每隔 stepTime 秒切换到下一个 View
    void stopSequence();
    bool isPlaying() const;
 
    // --- timeline / events ---
    void        clearTimeline();
    bool        addTimelineCut(float time, const std::string& rigName, float blendTime);
    bool        addTimelineEvent(float time, const std::string& name, const std::string& data);
    bool        addTimelineFloat(float time, const std::string& property, float value);
    void        setEventSink(platform_event::PlatformEvent* sink);
    void        playTimeline(bool loop);
    void        pauseTimeline();
    void        stopTimeline();
    void        seekTimeline(float time, bool fireEvents = false);
    bool        isTimelinePlaying() const;
    float       getTimelineTime() const;
    std::string consumeTimelineEvent();
    std::string getTimelineEventData() const;
    int         getPendingTimelineEventCount() const;
    float       getTimelineDuration() const;
    int         getRigCount() const;
    std::string serializeAsset() const;
    bool        deserializeAsset(const std::string& json);
 
    // --- 每帧驱动 ---
    void update(float dt);
 
private:
    struct View {
        std::string name;
        glm::vec3   eye{0.f};
        glm::vec3   target{0.f};
        float       fov = 60.f;
    };
 
    struct Rig {
        std::string name;
        std::string mode;
        int         priority = 0;
        bool        enabled  = true;
        glm::vec3   target{0.f};
        glm::vec3   offset{0.f, 2.f, 6.f};
        glm::vec3   lookAhead{0.f};
        glm::vec2   composition{0.f};
        float       radius    = 10.f;
        float       azimuth   = 45.f;
        float       elevation = 30.f;
        float       yaw       = 0.f;
        float       pitch     = 0.f;
        float       fov       = 60.f;
        float       smooth    = 6.f;
        float       maxSpeed  = 0.f;
    };
 
    struct CollisionBox {
        glm::vec3 min{0.f};
        glm::vec3 max{0.f};
    };
    struct Impulse {
        float        positionAmplitude = 0.f;
        float        rotationAmplitude = 0.f;
        float        duration          = 0.f;
        float        age               = 0.f;
        unsigned int seed              = 0;
        float        fovAmplitude      = 0.f;
    };
    struct TimelineCut {
        float       time = 0.f;
        std::string rig;
        float       blend = 0.f;
        bool        fired = false;
    };
    struct TimelineEvent {
        float       time = 0.f;
        std::string name;
        std::string data;
        bool        fired = false;
    };
    struct TimelineFloat {
        float       time = 0.f;
        std::string property;
        float       value = 0.f;
    };
 
    View        desired() const;
    void        applyView(const View& v);
    void        easeToward(const View& v, float dt);
    void        updateTrackedTarget();
    void        updateDirector();
    void        applyCollision(View& v, float dt);
    void        applyModifiers(View& v, float dt);
    void        updateTimeline(float dt);
    void        evaluateTimelineFloats();
    void        emitTimelineEvent(const TimelineEvent& marker);
    static bool validMode(const std::string& mode);
    [[nodiscard]] Result<void> applyPcgPostFx(const PhotoModeAssignment& assignment);
    void projectPcgPostFx();
 
    graphics::Camera3D* cam_ = nullptr;
    bool photoModeAuthority_ = false;
    float cameraRollDeg_ = 0.f;
    float pcgCullingDistance_ = 0.f;
    PcgPhotoModePostFxState pcgPostFxState_{};
 
    std::string mode_ = "follow";
 
    glm::vec3   target_{0.f, 0.f, 0.f};
    std::string targetNodeHost_;
    std::string targetNodeId_;
    glm::vec3   offset_{0.f, 2.f, 6.f};
    glm::vec3   lookAhead_{0.f, 0.f, 0.f};
    glm::vec3   secondaryTarget_{0.f};
    bool        hasSecondaryTarget_ = false;
 
    float radius_        = 10.f;
    float minimumRadius_ = 0.01f;
    float maximumRadius_ = 100000.f;
    float azimuthDeg_    = 45.f;
    float elevationDeg_  = 30.f;
    float orbitSpeedDeg_ = 20.f;
 
    float     yawDeg_   = 0.f;
    float     pitchDeg_ = 0.f;
    glm::vec2 composition_{0.f};
    float     deadZone_ = 0.f;
    glm::vec3 deadZoneTarget_{0.f};
    bool      deadZoneInitialized_ = false;
    float     fovDeg_              = 60.f;
 
    float smooth_         = 6.f;
    float positionSmooth_ = 6.f;
    float targetSmooth_   = 6.f;
    float maxSpeed_       = 0.f;
    bool  initialized_    = false;
    View  cur_{};
 
    bool                      collisionEnabled_  = false;
    float                     collisionRadius_   = 0.25f;
    float                     collisionRecovery_ = 4.f;
    float                     collisionDistance_ = -1.f;
    bool                      obstructed_        = false;
    uint64_t                  collisionMask_     = UINT64_MAX;
    int                       collisionIgnoredBody_ = -1;
    int                       collisionBodyId_      = -1;
    std::vector<CollisionBox> collisionBoxes_;
 
    std::vector<Rig>     rigs_;
    std::string          activeRig_;
    bool                 directorEnabled_ = false;
    std::vector<Impulse> impulses_;
 
    // cinematic
    std::vector<View> views_;
    int               viewIndex_ = -1;
    bool              playing_   = false;
    float             stepTime_  = 3.f;
    float             timer_     = 0.f;
    bool              blending_  = false;
    View              blendFrom_{};
    View              blendTo_{};
    float             blendT_   = 0.f;
    float             blendDur_ = 1.f;
 
    std::vector<TimelineCut>   timelineCuts_;
    std::vector<TimelineEvent> timelineEvents_;
    std::vector<TimelineFloat> timelineFloats_;
    platform_event::PlatformEvent*                  eventSink_        = nullptr;
    float                      timelineTime_     = 0.f;
    float                      timelineDuration_ = 0.f;
    bool                       timelinePlaying_  = false;
    bool                       timelineLoop_     = false;
    std::deque<std::pair<std::string, std::string>> pendingTimelineEvents_;
    std::string                consumedTimelineEventData_;
};
 
class Camera : public Module {
public:
    Module_REG(Camera);
    Camera()           = default;
    ~Camera() override = default;
};
 
}  // namespace eve::camera