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

#ifndef NMVTKMESHLAYER_H
#define NMVTKMESHLAYER_H

#include "nmVTKRenderLayer.h"

#include <QByteArray>
#include <vtkSmartPointer.h>

class vtkActor;
class vtkDataArray;
class vtkDataSet;
class vtkDataSetMapper;
class vtkLookupTable;

/**
 * @brief 通用数据集表面图层，不包含任何业务属性名称。
 *
 * 图层共享输入数据集的 VTK 引用，独占 Mapper、Actor 和 LookupTable。
 * 所有修改只更新管线状态，不主动触发 Render。
 */
class NM_RENDER_EXPORT nmVTKMeshLayer : public nmVTKRenderLayer
{
public:
    enum DisplayMode
    {
        DisplayMode_Surface = 0, ///< 只显示填充表面。
        DisplayMode_SurfaceWithEdges ///< 同时显示表面和单元边线。
    };

    enum ScalarAssociation
    {
        ScalarAssociation_CellData = 0, ///< 从 CellData 选择标量数组。
        ScalarAssociation_PointData ///< 从 PointData 选择标量数组。
    };

    /** @brief 创建空数据图层并建立默认表面渲染管线。 */
    explicit nmVTKMeshLayer(const QString& sLayerId);
    /** @brief 先解除 Renderer，再释放共享数据引用。 */
    virtual ~nmVTKMeshLayer();

    /**
     * @brief 共享传入数据集的 VTK 引用，不执行 DeepCopy。
     * @return 数据集非空且原标量选择在新数据集中仍有效时返回 true；没有
     *         原标量选择时只要求数据集非空。返回 false 时无效标量状态已清除。
     */
    bool setDataSet(vtkDataSet* pDataSet);
    /** @brief 返回当前共享数据集的非所有权指针。 */
    vtkDataSet* getDataSet() const;

    /** @brief 设置表面或表面加边线显示模式。 */
    void setDisplayMode(DisplayMode eMode);
    /** @brief 返回当前显示模式。 */
    DisplayMode getDisplayMode() const;
    /** @brief 直接控制表面边线，供不暴露双显示模式的组合视图使用。 */
    void setEdgeVisibility(bool bVisible);
    bool isEdgeVisible() const;

    /** @return 透明度为有限数时返回 true，并限制到 [0, 1]。 */
    bool setOpacity(double dOpacity);
    /** @brief 返回 Actor 当前透明度。 */
    double getOpacity() const;

    /** @brief 打开或关闭 Mapper 的标量着色。 */
    void setScalarVisibility(bool bVisible);
    /** @brief 返回 Mapper 当前是否启用标量着色。 */
    bool isScalarVisible() const;

    /**
     * @brief 选择 CellData 或 PointData 数组作为标量来源。
     * @return 数据集和指定数组存在，且自动范围有效时返回 true；失败时保留
     *         原数组选择和 Mapper 状态。
     */
    bool setScalarArray(const QString& sArrayName,
                        ScalarAssociation eAssociation);
    /** @brief 返回当前选中的数组名称。 */
    QString getScalarArrayName() const;
    /** @brief 返回当前数组来自 CellData 还是 PointData。 */
    ScalarAssociation getScalarAssociation() const;

    /** @brief 设置显式标量范围；不读取数据集。 */
    bool setScalarRange(double dMinimum, double dMaximum);
    /** @brief 从当前选中数组恢复数据范围。 */
    bool restoreDataScalarRange();
    /** @brief 返回当前范围是否由调用方显式指定。 */
    bool isUsingExplicitScalarRange() const;

    /** 以下访问函数均返回图层持有对象的非所有权指针。 */
    vtkDataSetMapper* getMapper() const;
    vtkActor* getActor() const;
    vtkLookupTable* getLookupTable() const;

private:
    Q_DISABLE_COPY(nmVTKMeshLayer)

    /** @brief 从当前数据集解析已记录的数组选择。 */
    vtkDataArray* getSelectedScalarArray() const;
    /** @brief 校验数组范围并同步到 Mapper 和 LookupTable。 */
    bool applyDataScalarRange();
    /** @brief 清除失效数组选择、关闭标量着色并恢复默认范围。 */
    void clearInvalidScalarState();

    vtkSmartPointer<vtkDataSet> m_pDataSet; ///< 共享输入数据，不执行深拷贝。
    vtkSmartPointer<vtkDataSetMapper> m_pMapper; ///< 图层独占的映射器。
    vtkSmartPointer<vtkActor> m_pActor; ///< 图层主 Prop，由基类同步持有。
    vtkSmartPointer<vtkLookupTable> m_pLookupTable; ///< 图层独占的颜色表。
    DisplayMode m_eDisplayMode;
    ScalarAssociation m_eScalarAssociation;
    QByteArray m_aScalarArrayName; ///< 供 VTK 7.1 接口使用的 UTF-8 数组名。
    bool m_bUsingExplicitScalarRange; ///< 为 true 时更换数据不覆盖调用方范围。
};

#endif // NMVTKMESHLAYER_H