0030930: Draw Harness, ViewerTest - add commands vlistcolors and vlistmaterials listi...
[occt.git] / src / Graphic3d / Graphic3d_MaterialAspect.hxx
CommitLineData
42cf5bc1 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
42cf5bc1 19#include <Graphic3d_BSDF.hxx>
42cf5bc1 20#include <Graphic3d_NameOfMaterial.hxx>
4e1bc39a 21#include <Graphic3d_TypeOfMaterial.hxx>
42cf5bc1 22#include <Graphic3d_TypeOfReflection.hxx>
4e1bc39a 23#include <TCollection_AsciiString.hxx>
24#include <Quantity_Color.hxx>
42cf5bc1 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
31class Graphic3d_MaterialAspect
32{
33public:
42cf5bc1 34 DEFINE_STANDARD_ALLOC
35
4e1bc39a 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
48public:
49
42cf5bc1 50 //! Creates a material from default values.
51 Standard_EXPORT Graphic3d_MaterialAspect();
4e1bc39a 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.
42cf5bc1 72 //! Set the name of the "UserDefined" material.
4e1bc39a 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
42cf5bc1 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.
4e1bc39a 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
a71a71de 95 //! Returns the transparency coefficient of the surface (1.0 - Alpha); 0.0 means opaque.
4e1bc39a 96 Standard_ShortReal Transparency() const { return myTransparencyCoef; }
97
a71a71de 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
4e1bc39a 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
a71a71de 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
4e1bc39a 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
42cf5bc1 135 //! Returns the reflection properties of the surface.
4e1bc39a 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
42cf5bc1 142 //! Returns the reflection properties of the surface.
4e1bc39a 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
42cf5bc1 149 //! Returns the reflection properties of the surface.
4e1bc39a 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
42cf5bc1 156 //! Returns the emissive coefficient of the surface.
4e1bc39a 157 Standard_ShortReal Emissive() const { return myColorCoef[Graphic3d_TOR_EMISSION]; }
42cf5bc1 158
4e1bc39a 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);
42cf5bc1 162
4e1bc39a 163 //! Returns the luminosity of the surface.
164 Standard_ShortReal Shininess() const { return myShininess; }
42cf5bc1 165
4e1bc39a 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);
42cf5bc1 169
4e1bc39a 170 //! Increases or decreases the luminosity.
171 //! @param theDelta a signed percentage
172 Standard_EXPORT void IncreaseShine (const Standard_ShortReal theDelta);
42cf5bc1 173
4e1bc39a 174 //! Returns the refraction index of the material
175 Standard_ShortReal RefractionIndex() const { return myRefractionIndex; }
42cf5bc1 176
4e1bc39a 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);
42cf5bc1 180
4e1bc39a 181 //! Returns BSDF (bidirectional scattering distribution function).
182 const Graphic3d_BSDF& BSDF() const { return myBSDF; }
42cf5bc1 183
4e1bc39a 184 //! Modifies the BSDF (bidirectional scattering distribution function).
185 void SetBSDF (const Graphic3d_BSDF& theBSDF) { myBSDF = theBSDF; }
42cf5bc1 186
4e1bc39a 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 }
42cf5bc1 192
4e1bc39a 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
59ee34ef 211 //! Returns material type.
212 Graphic3d_TypeOfMaterial MaterialType() const { return myMaterialType; }
213
4e1bc39a 214 //! Returns TRUE if type of this material is equal to specified type.
215 Standard_Boolean MaterialType (const Graphic3d_TypeOfMaterial theType) const { return myMaterialType == theType; }
216
217 //! Set material type.
218 Standard_EXPORT void SetMaterialType (const Graphic3d_TypeOfMaterial theType);
219
4e1bc39a 220 //! Returns TRUE if this material differs from specified one.
221 Standard_Boolean IsDifferent (const Graphic3d_MaterialAspect& theOther) const { return !IsEqual (theOther); }
222
223 //! Returns TRUE if this material differs from specified one.
224 Standard_Boolean operator!= (const Graphic3d_MaterialAspect& theOther) const { return IsDifferent (theOther); }
225
226 //! Returns TRUE if this material is identical to specified one.
227 Standard_Boolean IsEqual (const Graphic3d_MaterialAspect& theOther) const
228 {
229 return myColorCoef[Graphic3d_TOR_AMBIENT] == theOther.myColorCoef[Graphic3d_TOR_AMBIENT]
230 && myColorCoef[Graphic3d_TOR_DIFFUSE] == theOther.myColorCoef[Graphic3d_TOR_DIFFUSE]
231 && myColorCoef[Graphic3d_TOR_SPECULAR] == theOther.myColorCoef[Graphic3d_TOR_SPECULAR]
232 && myColorCoef[Graphic3d_TOR_EMISSION] == theOther.myColorCoef[Graphic3d_TOR_EMISSION]
233 && myTransparencyCoef == theOther.myTransparencyCoef
234 && myRefractionIndex == theOther.myRefractionIndex
235 && myBSDF == theOther.myBSDF
236 && myShininess == theOther.myShininess
4e1bc39a 237 && myColors[Graphic3d_TOR_AMBIENT] == theOther.myColors[Graphic3d_TOR_AMBIENT]
238 && myColors[Graphic3d_TOR_DIFFUSE] == theOther.myColors[Graphic3d_TOR_DIFFUSE]
239 && myColors[Graphic3d_TOR_SPECULAR] == theOther.myColors[Graphic3d_TOR_SPECULAR]
240 && myColors[Graphic3d_TOR_EMISSION] == theOther.myColors[Graphic3d_TOR_EMISSION]
241 && myReflActivity[Graphic3d_TOR_AMBIENT] == theOther.myReflActivity[Graphic3d_TOR_AMBIENT]
242 && myReflActivity[Graphic3d_TOR_DIFFUSE] == theOther.myReflActivity[Graphic3d_TOR_DIFFUSE]
243 && myReflActivity[Graphic3d_TOR_SPECULAR] == theOther.myReflActivity[Graphic3d_TOR_SPECULAR]
244 && myReflActivity[Graphic3d_TOR_EMISSION] == theOther.myReflActivity[Graphic3d_TOR_EMISSION];
245 }
246
247 //! Returns TRUE if this material is identical to specified one.
248 Standard_Boolean operator== (const Graphic3d_MaterialAspect& theOther) const { return IsEqual (theOther); }
42cf5bc1 249
4e1bc39a 250private:
42cf5bc1 251
4e1bc39a 252 //! Initialize the standard material.
253 Standard_EXPORT void init (const Graphic3d_NameOfMaterial theName);
42cf5bc1 254
4e1bc39a 255 //! Mark material as user defined.
256 void setUserMaterial()
257 {
258 // if a component of a "standard" material change, the
259 // result is no more standard (a blue gold is not a gold)
260 myMaterialName = Graphic3d_NOM_UserDefined;
261 myStringName = "UserDefined";
262 }
42cf5bc1 263
264private:
265
4e1bc39a 266 Graphic3d_BSDF myBSDF;
267 TCollection_AsciiString myStringName;
268 Quantity_Color myColors [Graphic3d_TypeOfReflection_NB];
269 Standard_ShortReal myColorCoef[Graphic3d_TypeOfReflection_NB];
270 Standard_ShortReal myTransparencyCoef;
271 Standard_ShortReal myRefractionIndex;
272 Standard_ShortReal myShininess;
4e1bc39a 273
42cf5bc1 274 Graphic3d_TypeOfMaterial myMaterialType;
275 Graphic3d_NameOfMaterial myMaterialName;
276 Graphic3d_NameOfMaterial myRequestedMaterialName;
42cf5bc1 277
4e1bc39a 278 Standard_Boolean myReflActivity[Graphic3d_TypeOfReflection_NB];
42cf5bc1 279
280};
281
42cf5bc1 282#endif // _Graphic3d_MaterialAspect_HeaderFile