nmWTAI-Platform/Include/nmNum/nmRender/nmVTKCameraController.h

#ifndef NMVTKCAMERACONTROLLER_H
#define NMVTKCAMERACONTROLLER_H

#include "nmRender_global.h"

class vtkRenderer;

/**
 * @brief 无业务含义的 VTK 相机控制器。
 *
 * 控制器不拥有 Renderer，也不主动 Render。操作成功后由容器统一渲染一次。
 * 无 Renderer、无可见 Prop 或边界无效时，各操作返回 false 且不移动相机。
 */
class NM_RENDER_EXPORT nmVTKCameraController
{
public:
    /** @brief 绑定 Renderer 非所有权指针；允许传入 nullptr 延后初始化。 */
    explicit nmVTKCameraController(vtkRenderer* pRenderer = nullptr);
    /** @brief 只解除 Renderer 引用，不修改相机和场景。 */
    ~nmVTKCameraController();

    /** @brief 切换非所有权 Renderer；传入 nullptr 表示解除。 */
    void setRenderer(vtkRenderer* pRenderer);
    /** @brief 返回当前 Renderer 非所有权指针。 */
    vtkRenderer* getRenderer() const;

    /** @brief 复制并启用主内容边界；参数有限且各轴最小值不大于最大值。 */
    bool setPrimaryViewBounds(const double dBounds[6]);
    /** @brief 清除主内容边界，使相机操作重新使用全部可见 Prop。 */
    void clearPrimaryViewBounds();

    /** @brief 恢复透视投影并适配主内容或当前可见边界。 */
    bool resetCamera();
    /** @brief 按固定倍率 1.2 放大当前视图，保持观察方向和投影方式。 */
    bool zoomIn();
    /** @brief 按固定倍率 1.0 / 1.2 缩小当前视图。 */
    bool zoomOut();
    /** @brief 保持当前观察方向和投影方式，仅适配主内容或可见边界。 */
    bool fitView();
    /** @brief 沿 +Z 方向设置正交顶视图。 */
    bool setTopView();
    /** @brief 沿 -Y 方向设置正交前视图。 */
    bool setFrontView();
    /** @brief 沿 +X 方向设置正交右视图。 */
    bool setRightView();
    /** @brief 设置透视等轴视图。 */
    bool setIsometricView();
    /** @brief 保存独立世界坐标旋转中心，不修改相机参数。 */
    bool setRotationCenter(double dX, double dY, double dZ);
    /** @brief 将独立旋转中心恢复为主内容或可见边界中心，不修改画面。 */
    bool resetRotationCenter();
    /** @brief 返回是否已经设置有效的独立旋转中心。 */
    bool hasRotationCenter() const;
    /** @brief 复制当前独立旋转中心；未设置或参数无效时返回 false。 */
    bool getRotationCenter(double dCenter[3]) const;
    /** @brief 清除独立旋转中心状态，不修改相机。 */
    void clearRotationCenter();

private:
    Q_DISABLE_COPY(nmVTKCameraController)

    /** @brief 优先返回主内容边界，未设置时回退到可见 Prop 边界。 */
    bool getViewBounds(double dBounds[6]) const;
    /** @brief 读取并验证当前可见 Prop 的有限包围盒。 */
    bool getVisibleBounds(double dBounds[6]) const;
    /** @brief 优先按全部可见 Prop 更新裁剪面，无可见边界时使用构图边界。 */
    void resetClippingRange(const double dViewBounds[6]);
    /** @brief 设置观察方向和投影方式，再按主内容或可见边界适配相机。 */
    bool applyStandardView(double dDirectionX,
                           double dDirectionY,
                           double dDirectionZ,
                           double dViewUpX,
                           double dViewUpY,
                           double dViewUpZ,
                           bool bParallelProjection);
    /** @brief 按给定倍率调整透视距离或正交投影比例。 */
    bool zoom(double dFactor);

    vtkRenderer* m_pRenderer; ///< 非所有权指针，由渲染容器持有。
    bool m_bHasPrimaryViewBounds;
    double m_dPrimaryViewBounds[6]; ///< 由业务控制器提供的主几何边界副本。
    bool m_bHasRotationCenter;
    double m_dRotationCenter[3]; ///< 独立于 vtkCamera::FocalPoint 的世界坐标。
};

#endif // NMVTKCAMERACONTROLLER_H