0028738: Data Exchange, XCAFPrs_Style - add transparency property
[occt.git] / src / Graphic3d / Graphic3d_MaterialAspect.hxx
1 // Created by: NW,JPB,CAL
2 // Copyright (c) 1991-1999 Matra Datavision
3 // Copyright (c) 1999-2014 OPEN CASCADE SAS
4 //
5 // This file is part of Open CASCADE Technology software library.
6 //
7 // This library is free software; you can redistribute it and/or modify it under
8 // the terms of the GNU Lesser General Public License version 2.1 as published
9 // by the Free Software Foundation, with special exception defined in the file
10 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
11 // distribution for complete text of the license and disclaimer of any warranty.
12 //
13 // Alternatively, this file may be used under the terms of Open CASCADE
14 // commercial license or contractual agreement.
15
16 #ifndef _Graphic3d_MaterialAspect_HeaderFile
17 #define _Graphic3d_MaterialAspect_HeaderFile
18
19 #include <Graphic3d_BSDF.hxx>
20 #include <Graphic3d_NameOfMaterial.hxx>
21 #include <Graphic3d_TypeOfMaterial.hxx>
22 #include <Graphic3d_TypeOfReflection.hxx>
23 #include <TCollection_AsciiString.hxx>
24 #include <Quantity_Color.hxx>
25
26 //! This class allows the definition of the type of a surface.
27 //! Aspect attributes of a 3d face.
28 //! Keywords: Material, FillArea, Shininess, Ambient, Color, Diffuse,
29 //! Specular, Transparency, Emissive, ReflectionMode,
30 //! BackFace, FrontFace, Reflection, Absorbtion
31 class Graphic3d_MaterialAspect 
32 {
33 public:
34   DEFINE_STANDARD_ALLOC
35
36   //! Returns the number of predefined textures.
37   static Standard_Integer NumberOfMaterials() { return Graphic3d_NOM_DEFAULT; }
38
39   //! Returns the name of the predefined material of specified rank within range [1, NumberOfMaterials()].
40   Standard_EXPORT static Standard_CString MaterialName (const Standard_Integer theRank);
41
42   //! Returns the type of the predefined material of specified rank within range [1, NumberOfMaterials()].
43   Standard_EXPORT static Graphic3d_TypeOfMaterial MaterialType (const Standard_Integer theRank);
44
45   //! Returns the material for specified name or Graphic3d_NOM_DEFAULT if name is unknown.
46   Standard_EXPORT static Graphic3d_NameOfMaterial MaterialFromName (const Standard_CString theName);
47
48 public:
49
50   //! Creates a material from default values.
51   Standard_EXPORT Graphic3d_MaterialAspect();
52
53   //! Creates a generic material.
54   Standard_EXPORT Graphic3d_MaterialAspect (const Graphic3d_NameOfMaterial theName);
55
56   //! Returns the material name (within predefined enumeration).
57   Graphic3d_NameOfMaterial Name() const { return myMaterialName; }
58
59   //! Returns the material name within predefined enumeration which has been requested (before modifications).
60   Graphic3d_NameOfMaterial RequestedName() const { return myRequestedMaterialName; }
61
62   //! Returns the given name of this material. This might be:
63   //! - given name set by method ::SetMaterialName()
64   //! - standard name for a material within enumeration
65   //! - "UserDefined" for non-standard material without name specified externally.
66   const TCollection_AsciiString& StringName() const { return myStringName; }
67
68   //! Returns the given name of this material. This might be:
69   Standard_CString MaterialName() const { return myStringName.ToCString(); }
70
71   //! The current material become a "UserDefined" material.
72   //! Set the name of the "UserDefined" material.
73   void SetMaterialName (const TCollection_AsciiString& theName)
74   {
75     // if a component of a "standard" material change, the
76     // result is no more standard (a blue gold is not a gold)
77     myMaterialName = Graphic3d_NOM_UserDefined;
78     myStringName   = theName;
79   }
80
81   //! Resets the material with the original values according to
82   //! the material name but leave the current color values untouched
83   //! for the material of type ASPECT.
84   void Reset()
85   {
86     init (myRequestedMaterialName);
87   }
88
89   //! Returns the diffuse color of the surface.
90   const Quantity_Color& Color() const { return myColors[Graphic3d_TOR_DIFFUSE]; }
91
92   //! Modifies the ambient and diffuse color of the surface.
93   Standard_EXPORT void SetColor (const Quantity_Color& theColor);
94
95   //! Returns the transparency coefficient of the surface (1.0 - Alpha); 0.0 means opaque.
96   Standard_ShortReal Transparency() const { return myTransparencyCoef; }
97
98   //! Returns the alpha coefficient of the surface (1.0 - Transparency); 1.0 means opaque.
99   Standard_ShortReal Alpha() const { return 1.0f - myTransparencyCoef; }
100
101   //! Modifies the transparency coefficient of the surface, where 0 is opaque and 1 is fully transparent.
102   //! Transparency is applicable to materials that have at least one of reflection modes (ambient, diffuse, specular or emissive) enabled.
103   //! See also SetReflectionModeOn() and SetReflectionModeOff() methods.
104   //!
105   //! Warning: Raises MaterialDefinitionError if given value is a negative value or greater than 1.0.
106   Standard_EXPORT void SetTransparency (const Standard_ShortReal theValue);
107
108   //! Modifies the alpha coefficient of the surface, where 1.0 is opaque and 0.0 is fully transparent.
109   void SetAlpha (Standard_ShortReal theValue) { SetTransparency (1.0f - theValue); }
110
111   //! Returns the ambient color of the surface.
112   const Quantity_Color& AmbientColor() const { return myColors[Graphic3d_TOR_AMBIENT]; }
113
114   //! Modifies the ambient color of the surface.
115   Standard_EXPORT void SetAmbientColor (const Quantity_Color& theColor);
116
117   //! Returns the diffuse color of the surface.
118   const Quantity_Color& DiffuseColor() const { return myColors[Graphic3d_TOR_DIFFUSE]; }
119
120   //! Modifies the diffuse color of the surface.
121   Standard_EXPORT void SetDiffuseColor (const Quantity_Color& theColor);
122
123   //! Returns the specular color of the surface.
124   const Quantity_Color& SpecularColor() const { return myColors[Graphic3d_TOR_SPECULAR]; }
125
126   //! Modifies the specular color of the surface.
127   Standard_EXPORT void SetSpecularColor (const Quantity_Color& theColor);
128
129   //! Returns the emissive color of the surface.
130   const Quantity_Color& EmissiveColor() const { return myColors[Graphic3d_TOR_EMISSION]; }
131
132   //! Modifies the emissive color of the surface.
133   Standard_EXPORT void SetEmissiveColor (const Quantity_Color& theColor);
134
135   //! Returns the reflection properties of the surface.
136   Standard_ShortReal Ambient() const { return myColorCoef[Graphic3d_TOR_AMBIENT]; }
137
138   //! Modifies the reflection properties of the surface.
139   //! Warning: Raises MaterialDefinitionError if given value is a negative value or greater than 1.0.
140   Standard_EXPORT void SetAmbient (const Standard_ShortReal theValue);
141
142   //! Returns the reflection properties of the surface.
143   Standard_ShortReal Diffuse() const { return myColorCoef[Graphic3d_TOR_DIFFUSE]; }
144
145   //! Modifies the reflection properties of the surface.
146   //! Warning: Raises MaterialDefinitionError if given value is a negative value or greater than 1.0.
147   Standard_EXPORT void SetDiffuse (const Standard_ShortReal theValue);
148
149   //! Returns the reflection properties of the surface.
150   Standard_ShortReal Specular() const { return myColorCoef[Graphic3d_TOR_SPECULAR]; }
151
152   //! Modifies the reflection properties of the surface.
153   //! Warning: Raises MaterialDefinitionError if given value is a negative value or greater than 1.0.
154   Standard_EXPORT void SetSpecular (const Standard_ShortReal theValue);
155
156   //! Returns the emissive coefficient of the surface.
157   Standard_ShortReal Emissive() const { return myColorCoef[Graphic3d_TOR_EMISSION]; }
158
159   //! Modifies the reflection properties of the surface.
160   //! Warning: Raises MaterialDefinitionError if given value is a negative value or greater than 1.0.
161   Standard_EXPORT void SetEmissive (const Standard_ShortReal theValue);
162
163   //! Returns the luminosity of the surface.
164   Standard_ShortReal Shininess() const { return myShininess; }
165
166   //! Modifies the luminosity of the surface.
167   //! Warning: Raises MaterialDefinitionError if given value is a negative value or greater than 1.0.
168   Standard_EXPORT void SetShininess (const Standard_ShortReal theValue);
169
170   //! Increases or decreases the luminosity.
171   //! @param theDelta a signed percentage
172   Standard_EXPORT void IncreaseShine (const Standard_ShortReal theDelta);
173
174   //! Returns the refraction index of the material
175   Standard_ShortReal RefractionIndex() const { return myRefractionIndex; }
176
177   //! Modifies the refraction index of the material.
178   //! Warning: Raises MaterialDefinitionError if given value is a lesser than 1.0.
179   Standard_EXPORT void SetRefractionIndex (const Standard_ShortReal theValue);
180
181   //! Returns BSDF (bidirectional scattering distribution function).
182   const Graphic3d_BSDF& BSDF() const { return myBSDF; }
183
184   //! Modifies the BSDF (bidirectional scattering distribution function).
185   void SetBSDF (const Graphic3d_BSDF& theBSDF) { myBSDF = theBSDF; }
186
187   //! Returns TRUE if the reflection mode is active, FALSE otherwise.
188   Standard_Boolean ReflectionMode (const Graphic3d_TypeOfReflection theType) const
189   {
190     return myReflActivity[theType];
191   }
192
193   //! Activates or deactivates the reflective properties of the surface with specified reflection type.
194   //!
195   //! Disabling diffuse and specular reflectance is useful for efficient visualization
196   //! of large amounts of data as definition of normals for graphic primitives is not needed
197   //! when only "all-directional" reflectance is active.
198   //!
199   //! NOTE: Disabling all four reflection modes also turns off the following effects:
200   //! 1. Lighting. Colors of primitives are not affected by the material properties when lighting is off.
201   //! 2. Transparency.
202   Standard_EXPORT void SetReflectionMode (const Graphic3d_TypeOfReflection theType,
203                                           const Standard_Boolean theValue);
204
205   //! Activates the reflective properties of the surface with specified reflection type.
206   void SetReflectionModeOn (const Graphic3d_TypeOfReflection theType) { SetReflectionMode (theType, Standard_True); }
207   
208   //! Deactivates the reflective properties of the surface with specified reflection type.
209   void SetReflectionModeOff (const Graphic3d_TypeOfReflection theType) { SetReflectionMode (theType, Standard_False); }
210
211   //! Returns TRUE if type of this material is equal to specified type.
212   Standard_Boolean MaterialType (const Graphic3d_TypeOfMaterial theType) const { return myMaterialType == theType; }
213
214   //! Set material type.
215   Standard_EXPORT void SetMaterialType (const Graphic3d_TypeOfMaterial theType);
216
217   //! Returns TRUE if this material differs from specified one.
218   Standard_Boolean IsDifferent (const Graphic3d_MaterialAspect& theOther) const { return !IsEqual (theOther); }
219
220   //! Returns TRUE if this material differs from specified one.
221   Standard_Boolean operator!= (const Graphic3d_MaterialAspect& theOther) const { return IsDifferent (theOther); }
222   
223   //! Returns TRUE if this material is identical to specified one.
224   Standard_Boolean IsEqual (const Graphic3d_MaterialAspect& theOther) const
225   {
226     return myColorCoef[Graphic3d_TOR_AMBIENT]  == theOther.myColorCoef[Graphic3d_TOR_AMBIENT]
227         && myColorCoef[Graphic3d_TOR_DIFFUSE]  == theOther.myColorCoef[Graphic3d_TOR_DIFFUSE]
228         && myColorCoef[Graphic3d_TOR_SPECULAR] == theOther.myColorCoef[Graphic3d_TOR_SPECULAR]
229         && myColorCoef[Graphic3d_TOR_EMISSION] == theOther.myColorCoef[Graphic3d_TOR_EMISSION]
230         && myTransparencyCoef == theOther.myTransparencyCoef
231         && myRefractionIndex  == theOther.myRefractionIndex
232         && myBSDF             == theOther.myBSDF
233         && myShininess        == theOther.myShininess
234         && myColors[Graphic3d_TOR_AMBIENT]    == theOther.myColors[Graphic3d_TOR_AMBIENT]
235         && myColors[Graphic3d_TOR_DIFFUSE]    == theOther.myColors[Graphic3d_TOR_DIFFUSE]
236         && myColors[Graphic3d_TOR_SPECULAR]   == theOther.myColors[Graphic3d_TOR_SPECULAR]
237         && myColors[Graphic3d_TOR_EMISSION]   == theOther.myColors[Graphic3d_TOR_EMISSION]
238         && myReflActivity[Graphic3d_TOR_AMBIENT]  == theOther.myReflActivity[Graphic3d_TOR_AMBIENT]
239         && myReflActivity[Graphic3d_TOR_DIFFUSE]  == theOther.myReflActivity[Graphic3d_TOR_DIFFUSE]
240         && myReflActivity[Graphic3d_TOR_SPECULAR] == theOther.myReflActivity[Graphic3d_TOR_SPECULAR]
241         && myReflActivity[Graphic3d_TOR_EMISSION] == theOther.myReflActivity[Graphic3d_TOR_EMISSION];
242   }
243
244   //! Returns TRUE if this material is identical to specified one.
245   Standard_Boolean operator== (const Graphic3d_MaterialAspect& theOther) const { return IsEqual (theOther); }
246
247 private:
248
249   //! Initialize the standard material.
250   Standard_EXPORT void init (const Graphic3d_NameOfMaterial theName);
251
252   //! Mark material as user defined.
253   void setUserMaterial()
254   {
255     // if a component of a "standard" material change, the
256     // result is no more standard (a blue gold is not a gold)
257     myMaterialName = Graphic3d_NOM_UserDefined;
258     myStringName   = "UserDefined";
259   }
260
261 private:
262
263   Graphic3d_BSDF           myBSDF;
264   TCollection_AsciiString  myStringName;
265   Quantity_Color           myColors   [Graphic3d_TypeOfReflection_NB];
266   Standard_ShortReal       myColorCoef[Graphic3d_TypeOfReflection_NB];
267   Standard_ShortReal       myTransparencyCoef;
268   Standard_ShortReal       myRefractionIndex;
269   Standard_ShortReal       myShininess;
270
271   Graphic3d_TypeOfMaterial myMaterialType;
272   Graphic3d_NameOfMaterial myMaterialName;
273   Graphic3d_NameOfMaterial myRequestedMaterialName;
274
275   Standard_Boolean         myReflActivity[Graphic3d_TypeOfReflection_NB];
276
277 };
278
279 #endif // _Graphic3d_MaterialAspect_HeaderFile