41ec4afebb01fce7b6a25608764891e5ad17d159
[occt.git] / src / XCAFDoc / XCAFDoc_VisMaterial.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_VisMaterial_HeaderFile
15 #define _XCAFDoc_VisMaterial_HeaderFile
16
17 #include <TDF_Attribute.hxx>
18 #include <XCAFDoc_VisMaterialCommon.hxx>
19 #include <XCAFDoc_VisMaterialPBR.hxx>
20
21 class Graphic3d_Aspects;
22 class Graphic3d_MaterialAspect;
23
24 //! Attribute storing Material definition for visualization purposes.
25 //!
26 //! Visualization material provides extended information about how object should be displayed on the screen
27 //! (albedo, metalness, roughness - not just a single color as in case of XCAFDoc_Color).
28 //! It is expected to correlate with physical material properties (XCAFDoc_Material), but not necessarily (like painted/polished/rusty object).
29 //!
30 //! The document defines the list of visualization materials via global attribute XCAFDoc_VisMaterialTool,
31 //! while particular material assignment to the shape is done through tree-nodes links.
32 //! Therefore, XCAFDoc_VisMaterialTool methods should be used for managing XCAFDoc_VisMaterial attributes.
33 //!
34 //! Visualization material definition consists of two options: Common and PBR (for Physically Based Rendering).
35 //! Common material definition is an obsolete model defined by very first version of OpenGL graphics API
36 //! and having specific hardware-accelerated implementation in past (like T&L).
37 //! PBR metallic-roughness model is closer to physical material properties, and intended to be used within physically-based renderer.
38 //!
39 //! For compatibility reasons, this attribute allows defining both material models,
40 //! so that it is up-to Data Exchange and Application deciding which one to define and use for rendering (depending on viewer capabilities).
41 //! Automatic conversion from one model to another is possible, but lossy (converted material will not look the same).
42 //!
43 //! Within Data Exchange, different file formats have different capabilities for storing visualization material properties
44 //! from simple color (STEP, IGES), to common (OBJ, glTF 1.0) and PBR (glTF 2.0).
45 //! This should be taken into account while defining or converting document into one or another format - material definition might be lost or disturbed.
46 //!
47 //! @sa XCAFDoc_VisMaterialTool
48 class XCAFDoc_VisMaterial : public TDF_Attribute
49 {
50   DEFINE_STANDARD_RTTIEXT(XCAFDoc_VisMaterial, TDF_Attribute)
51 public:
52
53   //! Return attribute GUID.
54   Standard_EXPORT static const Standard_GUID& GetID();
55
56 public:
57
58   //! Empty constructor.
59   Standard_EXPORT XCAFDoc_VisMaterial();
60
61   //! Return TRUE if material definition is empty.
62   bool IsEmpty() const { return !myPbrMat.IsDefined && !myCommonMat.IsDefined; }
63
64   //! Fill in material aspect.
65   Standard_EXPORT void FillMaterialAspect (Graphic3d_MaterialAspect& theAspect) const;
66
67   //! Fill in graphic aspects.
68   Standard_EXPORT void FillAspect (const Handle(Graphic3d_Aspects)& theAspect) const;
69
70   //! Return TRUE if metal-roughness PBR material is defined.
71   Standard_Boolean HasPbrMaterial() const { return myPbrMat.IsDefined; }
72
73   //! Return metal-roughness PBR material.
74   const XCAFDoc_VisMaterialPBR& PbrMaterial() const { return myPbrMat; }
75
76   //! Setup metal-roughness PBR material.
77   Standard_EXPORT void SetPbrMaterial (const XCAFDoc_VisMaterialPBR& theMaterial);
78
79   //! Setup undefined metal-roughness PBR material.
80   void UnsetPbrMaterial() { SetPbrMaterial (XCAFDoc_VisMaterialPBR()); }
81
82   //! Return TRUE if common material is defined.
83   Standard_Boolean HasCommonMaterial() const { return myCommonMat.IsDefined; }
84
85   //! Return common material.
86   const XCAFDoc_VisMaterialCommon& CommonMaterial() const { return myCommonMat; }
87
88   //! Setup common material.
89   Standard_EXPORT void SetCommonMaterial (const XCAFDoc_VisMaterialCommon& theMaterial);
90
91   //! Setup undefined common material.
92   void UnsetCommonMaterial() { SetCommonMaterial (XCAFDoc_VisMaterialCommon()); }
93
94   //! Return base color.
95   Standard_EXPORT Quantity_ColorRGBA BaseColor() const;
96
97   //! Return alpha mode; Graphic3d_AlphaMode_BlendAuto by default.
98   Graphic3d_AlphaMode AlphaMode() const { return myAlphaMode; }
99
100   //! Return alpha cutoff value; 0.5 by default.
101   Standard_ShortReal AlphaCutOff() const { return myAlphaCutOff; }
102
103   //! Set alpha mode.
104   Standard_EXPORT void SetAlphaMode (Graphic3d_AlphaMode theMode,
105                                      Standard_ShortReal  theCutOff = 0.5f);
106
107   //! Specifies whether the material is double sided; TRUE by default.
108   Standard_Boolean IsDoubleSided() const { return myIsDoubleSided; }
109
110   //! Specifies whether the material is double sided.
111   Standard_EXPORT void SetDoubleSided (Standard_Boolean theIsDoubleSided);
112
113   //! Return material name / tag (transient data, not stored in the document).
114   const Handle(TCollection_HAsciiString)& RawName() const { return myRawName; }
115
116   //! Set material name / tag (transient data, not stored in the document).
117   void SetRawName (const Handle(TCollection_HAsciiString)& theName) { myRawName = theName; }
118
119   //! Compare two materials.
120   //! Performs deep comparison by actual values - e.g. can be useful for merging materials.
121   Standard_Boolean IsEqual (const Handle(XCAFDoc_VisMaterial)& theOther) const
122   {
123     if (theOther.get() == this)
124     {
125       return true;
126     }
127     return theOther->myIsDoubleSided == myIsDoubleSided
128         && theOther->myAlphaCutOff == myAlphaCutOff
129         && theOther->myAlphaMode == myAlphaMode
130         && theOther->myCommonMat.IsEqual (myCommonMat)
131         && theOther->myPbrMat.IsEqual (myPbrMat);
132   }
133
134   //! Return Common material or convert PBR into Common material.
135   Standard_EXPORT XCAFDoc_VisMaterialCommon ConvertToCommonMaterial();
136
137   //! Return PBR material or convert Common into PBR material.
138   Standard_EXPORT XCAFDoc_VisMaterialPBR ConvertToPbrMaterial();
139
140 public: //! @name interface implementation
141
142   //! Return GUID of this attribute type.
143   virtual const Standard_GUID& ID() const Standard_OVERRIDE { return GetID(); }
144
145   //! Restore attribute from specified state.
146   //! @param theWith [in] attribute state to restore (copy into this)
147   Standard_EXPORT virtual void Restore (const Handle(TDF_Attribute)& theWith) Standard_OVERRIDE;
148
149   //! Create a new empty attribute.
150   Standard_EXPORT virtual Handle(TDF_Attribute) NewEmpty() const Standard_OVERRIDE;
151
152   //! Paste this attribute into another one.
153   //! @param theInto [in/out] target attribute to copy this into
154   //! @param theRelTable [in] relocation table
155   Standard_EXPORT virtual void Paste (const Handle(TDF_Attribute)& theInto,
156                                       const Handle(TDF_RelocationTable)& theRelTable) const Standard_OVERRIDE;
157
158 private:
159
160   Handle(TCollection_HAsciiString) myRawName;       //!< material name / tag (transient data)
161   XCAFDoc_VisMaterialPBR           myPbrMat;        //!< metal-roughness material definition
162   XCAFDoc_VisMaterialCommon        myCommonMat;     //!< common material definition
163   Graphic3d_AlphaMode              myAlphaMode;     //!< alpha mode; Graphic3d_AlphaMode_BlendAuto by default
164   Standard_ShortReal               myAlphaCutOff;   //!< alpha cutoff value; 0.5 by default
165   Standard_Boolean                 myIsDoubleSided; //!< specifies whether the material is double sided; TRUE by default
166
167 };
168
169 DEFINE_STANDARD_HANDLE(XCAFDoc_VisMaterial, TDF_Attribute)
170
171 #endif // _XCAFDoc_VisMaterial_HeaderFile