0027860: Visualization - clean up Transformation Persistence API
[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 <Standard.hxx>
20 #include <Standard_DefineAlloc.hxx>
21 #include <Standard_Handle.hxx>
22
23 #include <Standard_ShortReal.hxx>
24 #include <Quantity_Color.hxx>
25 #include <Standard_Boolean.hxx>
26 #include <Graphic3d_BSDF.hxx>
27 #include <Graphic3d_TypeOfMaterial.hxx>
28 #include <Graphic3d_NameOfMaterial.hxx>
29 #include <TCollection_AsciiString.hxx>
30 #include <Standard_Real.hxx>
31 #include <Graphic3d_TypeOfReflection.hxx>
32 #include <Standard_CString.hxx>
33 #include <Standard_Integer.hxx>
34 class Graphic3d_MaterialDefinitionError;
35 class Standard_OutOfRange;
36 class Quantity_Color;
37
38
39 //! This class allows the definition of the type of a surface.
40 //! Aspect attributes of a 3d face.
41 //! Keywords: Material, FillArea, Shininess, Ambient, Color, Diffuse,
42 //! Specular, Transparency, Emissive, ReflectionMode,
43 //! BackFace, FrontFace, Reflection, Absorbtion
44 class Graphic3d_MaterialAspect 
45 {
46 public:
47
48   DEFINE_STANDARD_ALLOC
49
50   
51   //! Creates a material from default values.
52   Standard_EXPORT Graphic3d_MaterialAspect();
53   
54   //! Creates a generic material calls <AName>
55   Standard_EXPORT Graphic3d_MaterialAspect(const Graphic3d_NameOfMaterial AName);
56   
57   //! Increases or decreases the luminosity of <me>.
58   //! <ADelta> is a signed percentage.
59   Standard_EXPORT void IncreaseShine (const Standard_Real ADelta);
60   
61   //! Modifies the reflection properties of the surface.
62   //! Category: Methods to modify the class definition
63   //! Warning: Raises MaterialDefinitionError if <AValue> is
64   //! a negative value or greater than 1.0.
65   Standard_EXPORT void SetAmbient (const Standard_Real AValue);
66   
67   //! Modifies the reflection properties of the surface.
68   //! Category: Methods to modify the class definition
69   //! Warning: Raises MaterialDefinitionError if <AValue> is a
70   //! negative value or greater than 1.0.
71   Standard_EXPORT void SetDiffuse (const Standard_Real AValue);
72   
73   //! Modifies the reflection properties of the surface.
74   //! Category: Methods to modify the class definition
75   //! Warning: Raises MaterialDefinitionError if <AValue> is a
76   //! negative value or greater than 1.0.
77   Standard_EXPORT void SetEmissive (const Standard_Real AValue);
78   
79   //! Modifies the luminosity of the surface.
80   //! Category: Methods to modify the class definition
81   //! Warning: Raises MaterialDefinitionError if <AValue> is a
82   //! negative value or greater than 1.0.
83   Standard_EXPORT void SetShininess (const Standard_Real AValue);
84   
85   //! Modifies the reflection properties of the surface.
86   //! Category: Methods to modify the class definition
87   //! Warning: Raises MaterialDefinitionError if <AValue> is a
88   //! negative value or greater than 1.0.
89   Standard_EXPORT void SetSpecular (const Standard_Real AValue);
90   
91   //! Modifies the transparency coefficient of the surface.
92   //! <AValue> = 0. opaque. (default)
93   //! <AValue> = 1. transparent.
94   //! Transparency is applicable to materials that have at least
95   //! one of reflection modes (ambient, diffuse, specular or emissive)
96   //! enabled. See also SetReflectionModeOn() and SetReflectionModeOff() methods.
97   //!
98   //! Category: Methods to modify the class definition
99   //! Warning: Raises MaterialDefinitionError if <AValue> is a
100   //! negative value or greater than 1.0.
101   Standard_EXPORT void SetTransparency (const Standard_Real AValue);
102   
103   //! Modifies the refraction index of the material.
104   //! Category: Methods to modify the class definition
105   //! Warning: Raises MaterialDefinitionError if <theValue> is a
106   //! lesser than 1.0.
107   Standard_EXPORT void SetRefractionIndex (const Standard_Real theValue);
108   
109   //! Modifies the BSDF (bidirectional scattering distribution function).
110   //! Category: Methods to modify the class definition
111   Standard_EXPORT void SetBSDF (const Graphic3d_BSDF& theBSDF);
112   
113   //! Modifies the ambient and diffuse colour of the surface.
114   //! Category: Methods to modify the class definition
115   Standard_EXPORT void SetColor (const Quantity_Color& AColor);
116   
117   //! Modifies the ambient colour of the surface.
118   Standard_EXPORT void SetAmbientColor (const Quantity_Color& AColor);
119   
120   //! Modifies the difuse colour of the surface.
121   Standard_EXPORT void SetDiffuseColor (const Quantity_Color& AColor);
122   
123   //! Modifies the specular colour of the surface.
124   Standard_EXPORT void SetSpecularColor (const Quantity_Color& AColor);
125   
126   //! Modifies the emissive colour of the surface.
127   Standard_EXPORT void SetEmissiveColor (const Quantity_Color& AColor);
128   
129   //! Activates the reflective properties of the surface <AType>.
130   //!
131   //! TypeOfReflection : TOR_AMBIENT
132   //! TOR_DIFFUSE
133   //! TOR_SPECULAR
134   //! TOR_EMISSION
135   //! 1, 2, 3 or 4 types of reflection can be set for a given surface.
136   Standard_EXPORT void SetReflectionModeOn (const Graphic3d_TypeOfReflection AType);
137   
138   //! Deactivates the reflective properties of
139   //! the surface <AType>.
140   //!
141   //! TypeOfReflection : TOR_AMBIENT
142   //! TOR_DIFFUSE
143   //! TOR_SPECULAR
144   //! TOR_EMISSION
145   //! 1, 2, 3 or 4 types of reflection can be set off for a given surface.
146   //! Disabling diffuse and specular reflectance is useful for efficient visualization
147   //! of large amounts of data as definition of normals for graphic primitives is not needed
148   //! when only "all-directional" reflectance is active.
149   //!
150   //! NOTE: Disabling all four reflection modes also turns off the following effects:
151   //! 1. Lighting. Colors of primitives are not affected by the material properties when lighting is off.
152   //! 2. Transparency.
153   Standard_EXPORT void SetReflectionModeOff (const Graphic3d_TypeOfReflection AType);
154   
155   //! Set MyMaterialType to the value of parameter <AType>
156   //!
157   //! TypeOfMaterial :   MATERIAL_ASPECT
158   //! MATERIAL_PHYSIC
159   Standard_EXPORT void SetMaterialType (const Graphic3d_TypeOfMaterial AType);
160   
161   //! The current matarial become a "UserDefined" material.
162   //! Set the name of the "UserDefined" material.
163   Standard_EXPORT void SetMaterialName (const Standard_CString AName);
164   
165   Standard_EXPORT void SetEnvReflexion (const Standard_ShortReal AValue);
166   
167   //! Resets the material with the original values according to
168   //! the material name but leave the current color values untouched
169   //! for the material of type ASPECT.
170   Standard_EXPORT void Reset();
171   
172   //! Returns the diffuse colour of the surface.
173   Standard_EXPORT const Quantity_Color& Color() const;
174   
175   //! Returns the ambient colour of the surface.
176   Standard_EXPORT const Quantity_Color& AmbientColor() const;
177   
178   //! Returns the diffuse colour of the surface.
179   Standard_EXPORT const Quantity_Color& DiffuseColor() const;
180   
181   //! Returns the specular colour of the surface.
182   Standard_EXPORT const Quantity_Color& SpecularColor() const;
183   
184   //! Returns the emissive colour of the surface.
185   Standard_EXPORT const Quantity_Color& EmissiveColor() const;
186   
187   //! Returns the reflection properties of the surface.
188   Standard_EXPORT Standard_Real Ambient() const;
189   
190   //! Returns the reflection properties of the surface.
191   Standard_EXPORT Standard_Real Diffuse() const;
192   
193   //! Returns the reflection properties of the surface.
194   Standard_EXPORT Standard_Real Specular() const;
195   
196   //! Returns the transparency coefficient of the surface.
197   Standard_EXPORT Standard_Real Transparency() const;
198   
199   //! Returns the refraction index of the material
200   Standard_EXPORT Standard_Real RefractionIndex() const;
201   
202   //! Returns BSDF (bidirectional scattering distribution function).
203   Standard_EXPORT const Graphic3d_BSDF& BSDF() const;
204   
205   //! Returns the emissive coefficient of the surface.
206   Standard_EXPORT Standard_Real Emissive() const;
207   
208   //! Returns the luminosity of the surface.
209   Standard_EXPORT Standard_Real Shininess() const;
210   
211   //! Returns Standard_True if the reflection mode is active,
212   //! Standard_False otherwise.
213   Standard_EXPORT Standard_Boolean ReflectionMode (const Graphic3d_TypeOfReflection AType) const;
214   
215   //! Returns Standard_True if MyMaterialType equal the parameter AType,
216   //! Standard_False otherwise.
217   Standard_EXPORT Standard_Boolean MaterialType (const Graphic3d_TypeOfMaterial AType) const;
218   
219   Standard_EXPORT Standard_ShortReal EnvReflexion() const;
220   
221   //! Returns the material name.
222   Standard_EXPORT Graphic3d_NameOfMaterial Name() const;
223   
224   //! Returns Standard_True if the materials <me> and
225   //! <Other> are different.
226   Standard_EXPORT Standard_Boolean IsDifferent (const Graphic3d_MaterialAspect& Other) const;
227 Standard_Boolean operator != (const Graphic3d_MaterialAspect& Other) const
228 {
229   return IsDifferent(Other);
230 }
231   
232   //! Returns Standard_True if the materials <me> and
233   //! <Other> are identical.
234   Standard_EXPORT Standard_Boolean IsEqual (const Graphic3d_MaterialAspect& Other) const;
235 Standard_Boolean operator == (const Graphic3d_MaterialAspect& Other) const
236 {
237   return IsEqual(Other);
238 }
239   
240
241   //! Returns the number of predefined textures.
242   Standard_EXPORT static Standard_Integer NumberOfMaterials();
243   
244
245   //! Returns the name of the predefined material of rank <aRank>
246   //! Trigger: when <aRank> is < 1 or > NumberOfMaterials.
247   Standard_EXPORT static Standard_CString MaterialName (const Standard_Integer aRank);
248   
249
250   //! Returns the name of this material
251   Standard_EXPORT Standard_CString MaterialName() const;
252   
253
254   //! Returns the type of the predefined material of rank <aRank>
255   //! Trigger: when <aRank> is < 1 or > NumberOfMaterials.
256   Standard_EXPORT static Graphic3d_TypeOfMaterial MaterialType (const Standard_Integer aRank);
257   
258
259   //! Returns the material for specified name or Graphic3d_NOM_DEFAULT if name is unknown.
260   Standard_EXPORT static Graphic3d_NameOfMaterial MaterialFromName (const Standard_CString theName);
261
262
263
264
265 protected:
266
267
268
269
270
271 private:
272
273   
274   Standard_EXPORT void Init (const Graphic3d_NameOfMaterial AName);
275
276
277   Standard_ShortReal myDiffuseCoef;
278   Quantity_Color myDiffuseColor;
279   Standard_Boolean myDiffuseActivity;
280   Standard_ShortReal myAmbientCoef;
281   Quantity_Color myAmbientColor;
282   Standard_Boolean myAmbientActivity;
283   Standard_ShortReal mySpecularCoef;
284   Quantity_Color mySpecularColor;
285   Standard_Boolean mySpecularActivity;
286   Standard_ShortReal myEmissiveCoef;
287   Quantity_Color myEmissiveColor;
288   Standard_Boolean myEmissiveActivity;
289   Standard_ShortReal myTransparencyCoef;
290   Standard_ShortReal myRefractionIndex;
291   Graphic3d_BSDF myBSDF;
292   Standard_ShortReal myShininess;
293   Standard_ShortReal myEnvReflexion;
294   Graphic3d_TypeOfMaterial myMaterialType;
295   Graphic3d_NameOfMaterial myMaterialName;
296   Graphic3d_NameOfMaterial myRequestedMaterialName;
297   TCollection_AsciiString myStringName;
298
299
300 };
301
302
303
304
305
306
307
308 #endif // _Graphic3d_MaterialAspect_HeaderFile