nmWTAI-Platform/Include/nmNum/nmSubWxs/nmPebiResultSceneController.h

#ifndef NMPEBIRESULTSCENECONTROLLER_H
#define NMPEBIRESULTSCENECONTROLLER_H

#include "nmSubWxs_global.h"

#include <QSharedPointer>
#include <QString>
#include <QStringList>

class nmPebiResultSceneControllerPrivate;
class nmPebiResultSnapshot;
class nmWxVTKRenderContainerWidget;

/**
 * @brief 将不可变 PEBI 结果快照组合为独立的通用 VTK 场景。
 *
 * Scene 拥有 Mesh、ScalarBar 和平面比例网格图层；控制器独占活动
 * RenderAdapter 和快照强引用，并通过稳定 ID 校验所观察的图层身份。
 * 外部提前清空业务 Scene 时，控制器会丢弃活动结果而不会解引用旧图层。
 */
class NM_SUB_WXS_EXPORT nmPebiResultSceneController
{
public:
    /**
     * @param pContainer 非所有权指针，必须比控制器生命周期更长。
     * @note 析构会从业务 Scene 移除本控制器创建的稳定 ID 图层。
     */
    explicit nmPebiResultSceneController(
            nmWxVTKRenderContainerWidget* pContainer);
    /** @brief 断开活动管线并移除本控制器创建的稳定 ID 图层。 */
    ~nmPebiResultSceneController();

    /**
     * @brief 事务式绑定新快照，成功后恢复顶视图、适配网格并渲染一次。
     * @note 候选初始化失败时保留当前 Adapter、画面、范围和相机状态；
     *       若发现 Scene 已由外部清空，则采用一致的无快照状态。
     */
    bool setSnapshot(
            const QSharedPointer<const nmPebiResultSnapshot>& pSnapshot,
            QString* pError = nullptr);
    /** @brief 解除管线和快照引用并隐藏结果图层，不销毁 Scene。 */
    void clear();

    /**
     * @brief 原子切换同一快照内的属性和帧，成功时仅渲染一次。
     * @note 静态属性只接受帧 0；失败时恢复 Adapter、Mapper 和范围。
     */
    bool applyPropertyFrame(const QString& sPropertyId,
                            int nFrameIndex,
                            QString* pError = nullptr);

    /** @brief 设置结果网格显隐；偏好跨快照保留。 */
    void setMeshVisible(bool bVisible);
    /** @brief 设置色标显隐；阶段 5A 默认隐藏，偏好跨快照保留。 */
    void setScalarBarVisible(bool bVisible);
    /** @brief 设置平面比例网格显隐；偏好跨快照保留。 */
    void setScaleGridVisible(bool bVisible);
    /** @brief 设置单元边线显隐；偏好跨快照保留。 */
    void setCellEdgesVisible(bool bVisible);

    /** @brief 返回当前是否持有可用快照且稳定结果图层仍完整。 */
    bool hasSnapshot() const;
    /** @brief 返回当前快照稳定 ID；无可用快照时返回空字符串。 */
    QString getCurrentSnapshotId() const;
    /** @brief 按 Catalog 顺序返回当前快照真实存在的属性 ID。 */
    QStringList getAvailablePropertyIds() const;
    /** @brief 返回最后一次成功渲染的属性 ID。 */
    QString getCurrentPropertyId() const;
    /** @brief 返回最后一次成功渲染的零基帧；无快照时返回 -1。 */
    int getCurrentFrameIndex() const;
    /** @brief 判断当前快照中的指定属性是否为动态属性。 */
    bool isPropertyTimeDependent(const QString& sPropertyId) const;
    /** @brief 返回当前快照中指定属性的帧数，不可用时返回 0。 */
    int getPropertyFrameCount(const QString& sPropertyId) const;
    /**
     * @brief 返回动态属性指定帧的求解时间，单位固定为小时。
     * @note 查询失败时返回 false，且不修改 dTime。
     */
    bool getPropertyTimeAt(const QString& sPropertyId,
                           int nFrameIndex,
                           double& dTime) const;
    /** @brief 返回快照中的业务范围；常量属性保持 [c,c]。 */
    bool getCurrentPropertyRange(double dRange[2]) const;
    /** @brief 返回结果网格显示偏好，不要求当前存在快照。 */
    bool isMeshVisible() const;
    /** @brief 返回色标显示偏好，不要求当前存在快照。 */
    bool isScalarBarVisible() const;
    /** @brief 返回比例网格显示偏好，不要求当前存在快照。 */
    bool isScaleGridVisible() const;
    /** @brief 返回单元边线显示偏好，不要求当前存在快照。 */
    bool areCellEdgesVisible() const;

private:
    Q_DISABLE_COPY(nmPebiResultSceneController)

    /** @brief 独占实现对象，保存快照、Adapter 及 Scene 图层观察指针。 */
    nmPebiResultSceneControllerPrivate* m_pPrivate;
};

#endif // NMPEBIRESULTSCENECONTROLLER_H