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

#ifndef NMVTKRENDERLAYER_H
#define NMVTKRENDERLAYER_H

#include "nmRender_global.h"

#include <QString>
#include <vtkSmartPointer.h>

class vtkProp;
class vtkRenderer;
class nmVTKScene;

/**
 * @brief VTK 图层抽象基类。
 *
 * 图层 ID 在构造后保持不变。图层拥有自己的主 Prop，Renderer 仅在 attach
 * 到 detach 之间持有该 Prop 的引用。成功加入 Scene 后，同一图层不能再被
 * 其他 Scene 接管。所有接口只能在 Qt GUI 线程调用。
 */
class NM_RENDER_EXPORT nmVTKRenderLayer
{
public:
    /** @brief 析构时执行幂等 detach，确保 Renderer 不保留 Prop。 */
    virtual ~nmVTKRenderLayer() = 0;

    /** @brief 返回不可翻译的稳定图层 ID。 */
    QString getLayerId() const;

    /**
     * @brief 将图层挂载到 Renderer；重复挂载同一 Renderer 直接成功。
     * @return Renderer 和主 Prop 均有效时返回 true。
     */
    bool attach(vtkRenderer* pRenderer);

    /** @brief 从当前 Renderer 移除 Prop；未挂载时安全返回。 */
    void detach();

    /** @brief 修改图层可见性，不主动触发 Render。 */
    void setVisible(bool bVisible);
    /** @brief 返回调用方最后设置的可见状态。 */
    bool isVisible() const;
    /** @brief 返回主 Prop 当前是否已加入某个 Renderer。 */
    bool isAttached() const;

protected:
    /** @param sLayerId 不可翻译且在图层生命周期内保持不变的稳定 ID。 */
    explicit nmVTKRenderLayer(const QString& sLayerId);

    /**
     * @brief 注册该图层的主 Prop。
     * @note 只能由派生层在未挂载时调用；智能指针会共享该 Prop 的 VTK 引用。
     */
    bool setRenderProp(vtkProp* pProp);
    /** @brief 返回本图层主 Prop 的非所有权指针。 */
    vtkProp* getRenderProp() const;
    /** @brief 返回当前挂载的 Renderer 非所有权指针。 */
    vtkRenderer* getAttachedRenderer() const;

private:
    Q_DISABLE_COPY(nmVTKRenderLayer)

    friend class nmVTKScene;

    /** @brief 由 Scene 在挂载前认领所有权；已有所属 Scene 时拒绝。 */
    bool claimSceneOwnership(nmVTKScene* pScene);
    /** @brief 仅允许当前所属 Scene 在删除图层前释放所有权。 */
    bool releaseSceneOwnership(nmVTKScene* pScene);

    const QString m_sLayerId; ///< 不参与翻译和界面显示的稳定查找键。
    bool m_bVisible; ///< 在未挂载期间也保留调用方要求的可见状态。
    vtkSmartPointer<vtkProp> m_pRenderProp; ///< 图层持有的主 Prop VTK 引用。
    vtkRenderer* m_pRenderer; ///< 非所有权指针，仅在挂载期间有效。
    nmVTKScene* m_pOwningScene; ///< 非所有权指针，用于阻止多个 Scene 重复接管。
};

#endif // NMVTKRENDERLAYER_H