0029902: Data Exchange, XCAF - provide extended Material definition for visualization...
[occt.git] / src / XCAFDoc / XCAFDoc_VisMaterialTool.hxx
1 // Copyright (c) 2019 OPEN CASCADE SAS
2 //
3 // This file is part of Open CASCADE Technology software library.
4 //
5 // This library is free software; you can redistribute it and/or modify it under
6 // the terms of the GNU Lesser General Public License version 2.1 as published
7 // by the Free Software Foundation, with special exception defined in the file
8 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
9 // distribution for complete text of the license and disclaimer of any warranty.
10 //
11 // Alternatively, this file may be used under the terms of Open CASCADE
12 // commercial license or contractual agreement.
13
14 #ifndef _XCAFDoc_VisMaterialTool_HeaderFile
15 #define _XCAFDoc_VisMaterialTool_HeaderFile
16
17 #include <Standard_Type.hxx>
18 #include <TDF_Attribute.hxx>
19 #include <TDF_LabelSequence.hxx>
20
21 class TopoDS_Shape;
22 class Quantity_ColorRGBA;
23 class XCAFDoc_ShapeTool;
24 class XCAFDoc_VisMaterial;
25
26 //! Provides tools to store and retrieve attributes (visualization materials) of TopoDS_Shape in and from TDocStd_Document.
27 //!
28 //! This attribute defines the list of visualization materials (XCAFDoc_VisMaterial) within the whole document.
29 //! Particular material is assigned to the shape through tree-nodes links.
30 //!
31 //! Visualization materials might co-exists with independent color attributes (XCAFDoc_ColorTool),
32 //! but beware to preserve consistency between them (it is better using one attribute type at once to avoid ambiguity).
33 //! Unlike color attributes, list of materials should be managed explicitly by application,
34 //! so that there is no tool eliminating material duplicates or removing unused materials.
35 //!
36 //! @sa XCAFDoc_VisMaterial
37 class XCAFDoc_VisMaterialTool : public TDF_Attribute
38 {
39   DEFINE_STANDARD_RTTIEXT(XCAFDoc_VisMaterialTool, TDF_Attribute)
40 public:
41
42   //! Creates (if not exist) ColorTool.
43   Standard_EXPORT static Handle(XCAFDoc_VisMaterialTool) Set (const TDF_Label& L);
44
45   Standard_EXPORT static const Standard_GUID& GetID();
46
47 public:
48   //! Empty constructor.
49   Standard_EXPORT XCAFDoc_VisMaterialTool();
50
51   //! returns the label under which colors are stored
52   Standard_EXPORT TDF_Label BaseLabel() const { return Label(); }
53
54   //! Returns internal XCAFDoc_ShapeTool tool
55   Standard_EXPORT const Handle(XCAFDoc_ShapeTool)& ShapeTool();
56
57   //! Returns TRUE if Label belongs to a Material Table.
58   Standard_Boolean IsMaterial (const TDF_Label& theLabel) const { return !GetMaterial (theLabel).IsNull(); }
59
60   //! Returns Material defined by specified Label, or NULL if the label is not in Material Table.
61   Standard_EXPORT Handle(XCAFDoc_VisMaterial) GetMaterial (const TDF_Label& theMatLabel) const;
62
63   //! Adds Material definition to a Material Table and returns its Label.
64   Standard_EXPORT TDF_Label AddMaterial (const Handle(XCAFDoc_VisMaterial)& theMat,
65                                          const TCollection_AsciiString& theName) const;
66
67   //! Adds Material definition to a Material Table and returns its Label.
68   Standard_EXPORT TDF_Label AddMaterial(const TCollection_AsciiString& theName) const;
69
70   //! Removes Material from the Material Table
71   Standard_EXPORT void RemoveMaterial (const TDF_Label& theLabel) const;
72
73   //! Returns a sequence of Materials currently stored in the Material Table.
74   Standard_EXPORT void GetMaterials (TDF_LabelSequence& Labels) const;
75
76   //! Sets new material to the shape.
77   Standard_EXPORT void SetShapeMaterial (const TDF_Label& theShapeLabel,
78                                          const TDF_Label& theMaterialLabel) const;
79
80   //! Removes a link with GUID XCAFDoc::VisMaterialRefGUID() from shape label to material.
81   Standard_EXPORT void UnSetShapeMaterial (const TDF_Label& theShapeLabel) const;
82
83   //! Returns TRUE if label has a material assignment.
84   Standard_EXPORT Standard_Boolean IsSetShapeMaterial (const TDF_Label& theLabel) const;
85
86   //! Returns label with material assigned to shape label.
87   //! @param theShapeLabel [in] shape label
88   //! @param theMaterialLabel [out] material label
89   //! @return FALSE if no material is assigned
90   Standard_EXPORT static Standard_Boolean GetShapeMaterial (const TDF_Label& theShapeLabel, TDF_Label& theMaterialLabel);
91
92   //! Returns material assigned to the shape label.
93   Standard_EXPORT Handle(XCAFDoc_VisMaterial) GetShapeMaterial (const TDF_Label& theShapeLabel);
94
95   //! Sets a link with GUID XCAFDoc::VisMaterialRefGUID() from shape label to material label.
96   //! @param theShape [in] shape
97   //! @param theMaterialLabel [in] material label
98   //! @return FALSE if cannot find a label for shape
99   Standard_EXPORT Standard_Boolean SetShapeMaterial (const TopoDS_Shape& theShape,
100                                                      const TDF_Label& theMaterialLabel);
101
102   //! Removes a link with GUID XCAFDoc::VisMaterialRefGUID() from shape label to material.
103   //! @return TRUE if such link existed
104   Standard_EXPORT Standard_Boolean UnSetShapeMaterial (const TopoDS_Shape& theShape);
105
106   //! Returns TRUE if shape has a material assignment.
107   Standard_EXPORT Standard_Boolean IsSetShapeMaterial (const TopoDS_Shape& theShape);
108
109   //! Returns label with material assigned to shape.
110   //! @param theShape [in] shape
111   //! @param theMaterialLabel [out] material label
112   //! @return FALSE if no material is assigned
113   Standard_EXPORT Standard_Boolean GetShapeMaterial (const TopoDS_Shape& theShape, TDF_Label& theMaterialLabel);
114
115   //! Returns material assigned to shape or NULL if not assigned.
116   Standard_EXPORT Handle(XCAFDoc_VisMaterial) GetShapeMaterial (const TopoDS_Shape& theShape);
117
118 public:
119
120   //! Returns GUID of this attribute type.
121   virtual const Standard_GUID& ID() const Standard_OVERRIDE { return GetID(); }
122
123   //! Does nothing.
124   virtual void Restore (const Handle(TDF_Attribute)& ) Standard_OVERRIDE {}
125
126   //! Creates new instance of this tool.
127   virtual Handle(TDF_Attribute) NewEmpty() const Standard_OVERRIDE { return new XCAFDoc_VisMaterialTool(); }
128
129   //! Does nothing.
130   virtual void Paste (const Handle(TDF_Attribute)& ,
131                       const Handle(TDF_RelocationTable)& ) const Standard_OVERRIDE {}
132
133 private:
134
135   Handle(XCAFDoc_ShapeTool) myShapeTool;
136
137 };
138
139 DEFINE_STANDARD_HANDLE(XCAFDoc_VisMaterialTool, TDF_Attribute)
140
141 #endif // _XCAFDoc_VisMaterialTool_HeaderFile