1 // Created by: NW,JPB,CAL
2 // Copyright (c) 1991-1999 Matra Datavision
3 // Copyright (c) 1999-2014 OPEN CASCADE SAS
5 // This file is part of Open CASCADE Technology software library.
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.
13 // Alternatively, this file may be used under the terms of Open CASCADE
14 // commercial license or contractual agreement.
16 #ifndef _Graphic3d_MaterialAspect_HeaderFile
17 #define _Graphic3d_MaterialAspect_HeaderFile
19 #include <Graphic3d_BSDF.hxx>
20 #include <Graphic3d_PBRMaterial.hxx>
21 #include <Graphic3d_NameOfMaterial.hxx>
22 #include <Graphic3d_TypeOfMaterial.hxx>
23 #include <Graphic3d_TypeOfReflection.hxx>
24 #include <TCollection_AsciiString.hxx>
25 #include <Quantity_Color.hxx>
27 //! This class allows the definition of the type of a surface.
28 //! Aspect attributes of a 3d face.
29 //! Keywords: Material, FillArea, Shininess, Ambient, Color, Diffuse,
30 //! Specular, Transparency, Emissive, ReflectionMode,
31 //! BackFace, FrontFace, Reflection, Absorbtion
32 class Graphic3d_MaterialAspect
37 //! Returns the number of predefined textures.
38 static Standard_Integer NumberOfMaterials() { return Graphic3d_NOM_DEFAULT; }
40 //! Returns the name of the predefined material of specified rank within range [1, NumberOfMaterials()].
41 Standard_EXPORT static Standard_CString MaterialName (const Standard_Integer theRank);
43 //! Returns the type of the predefined material of specified rank within range [1, NumberOfMaterials()].
44 Standard_EXPORT static Graphic3d_TypeOfMaterial MaterialType (const Standard_Integer theRank);
46 //! Finds the material for specified name.
47 //! @param theName [in] name to find
48 //! @param theMat [out] found material
49 //! @return FALSE if name was unrecognized
50 Standard_EXPORT static Standard_Boolean MaterialFromName (const Standard_CString theName,
51 Graphic3d_NameOfMaterial& theMat);
53 //! Returns the material for specified name or Graphic3d_NOM_DEFAULT if name is unknown.
54 static Graphic3d_NameOfMaterial MaterialFromName (const Standard_CString theName)
56 Graphic3d_NameOfMaterial aMat = Graphic3d_NOM_DEFAULT;
57 MaterialFromName (theName, aMat);
63 //! Creates a material from default values.
64 Standard_EXPORT Graphic3d_MaterialAspect();
66 //! Creates a generic material.
67 Standard_EXPORT Graphic3d_MaterialAspect (const Graphic3d_NameOfMaterial theName);
69 //! Returns the material name (within predefined enumeration).
70 Graphic3d_NameOfMaterial Name() const { return myMaterialName; }
72 //! Returns the material name within predefined enumeration which has been requested (before modifications).
73 Graphic3d_NameOfMaterial RequestedName() const { return myRequestedMaterialName; }
75 //! Returns the given name of this material. This might be:
76 //! - given name set by method ::SetMaterialName()
77 //! - standard name for a material within enumeration
78 //! - "UserDefined" for non-standard material without name specified externally.
79 const TCollection_AsciiString& StringName() const { return myStringName; }
81 //! Returns the given name of this material. This might be:
82 Standard_CString MaterialName() const { return myStringName.ToCString(); }
84 //! The current material become a "UserDefined" material.
85 //! Set the name of the "UserDefined" material.
86 void SetMaterialName (const TCollection_AsciiString& theName)
88 // if a component of a "standard" material change, the
89 // result is no more standard (a blue gold is not a gold)
90 myMaterialName = Graphic3d_NOM_UserDefined;
91 myStringName = theName;
94 //! Resets the material with the original values according to
95 //! the material name but leave the current color values untouched
96 //! for the material of type ASPECT.
99 init (myRequestedMaterialName);
102 //! Returns the diffuse color of the surface.
103 //! WARNING! This method does NOT return color for Graphic3d_MATERIAL_ASPECT material (color is defined by Graphic3d_Aspects::InteriorColor()).
104 const Quantity_Color& Color() const { return myColors[Graphic3d_TOR_DIFFUSE]; }
106 //! Modifies the ambient and diffuse color of the surface.
107 //! WARNING! Has no effect for Graphic3d_MATERIAL_ASPECT material (color should be set to Graphic3d_Aspects::SetInteriorColor()).
108 Standard_EXPORT void SetColor (const Quantity_Color& theColor);
110 //! Returns the transparency coefficient of the surface (1.0 - Alpha); 0.0 means opaque.
111 Standard_ShortReal Transparency() const { return myTransparencyCoef; }
113 //! Returns the alpha coefficient of the surface (1.0 - Transparency); 1.0 means opaque.
114 Standard_ShortReal Alpha() const { return 1.0f - myTransparencyCoef; }
116 //! Modifies the transparency coefficient of the surface, where 0 is opaque and 1 is fully transparent.
117 //! Transparency is applicable to materials that have at least one of reflection modes (ambient, diffuse, specular or emissive) enabled.
118 //! See also SetReflectionModeOn() and SetReflectionModeOff() methods.
120 //! Warning: Raises MaterialDefinitionError if given value is a negative value or greater than 1.0.
121 Standard_EXPORT void SetTransparency (const Standard_ShortReal theValue);
123 //! Modifies the alpha coefficient of the surface, where 1.0 is opaque and 0.0 is fully transparent.
124 void SetAlpha (Standard_ShortReal theValue) { SetTransparency (1.0f - theValue); }
126 //! Returns the ambient color of the surface.
127 const Quantity_Color& AmbientColor() const { return myColors[Graphic3d_TOR_AMBIENT]; }
129 //! Modifies the ambient color of the surface.
130 Standard_EXPORT void SetAmbientColor (const Quantity_Color& theColor);
132 //! Returns the diffuse color of the surface.
133 const Quantity_Color& DiffuseColor() const { return myColors[Graphic3d_TOR_DIFFUSE]; }
135 //! Modifies the diffuse color of the surface.
136 Standard_EXPORT void SetDiffuseColor (const Quantity_Color& theColor);
138 //! Returns the specular color of the surface.
139 const Quantity_Color& SpecularColor() const { return myColors[Graphic3d_TOR_SPECULAR]; }
141 //! Modifies the specular color of the surface.
142 Standard_EXPORT void SetSpecularColor (const Quantity_Color& theColor);
144 //! Returns the emissive color of the surface.
145 const Quantity_Color& EmissiveColor() const { return myColors[Graphic3d_TOR_EMISSION]; }
147 //! Modifies the emissive color of the surface.
148 Standard_EXPORT void SetEmissiveColor (const Quantity_Color& theColor);
150 //! Returns the luminosity of the surface.
151 Standard_ShortReal Shininess() const { return myShininess; }
153 //! Modifies the luminosity of the surface.
154 //! Warning: Raises MaterialDefinitionError if given value is a negative value or greater than 1.0.
155 Standard_EXPORT void SetShininess (const Standard_ShortReal theValue);
157 //! Increases or decreases the luminosity.
158 //! @param theDelta a signed percentage
159 Standard_EXPORT void IncreaseShine (const Standard_ShortReal theDelta);
161 //! Returns the refraction index of the material
162 Standard_ShortReal RefractionIndex() const { return myRefractionIndex; }
164 //! Modifies the refraction index of the material.
165 //! Warning: Raises MaterialDefinitionError if given value is a lesser than 1.0.
166 Standard_EXPORT void SetRefractionIndex (const Standard_ShortReal theValue);
168 //! Returns BSDF (bidirectional scattering distribution function).
169 const Graphic3d_BSDF& BSDF() const { return myBSDF; }
171 //! Modifies the BSDF (bidirectional scattering distribution function).
172 void SetBSDF (const Graphic3d_BSDF& theBSDF) { myBSDF = theBSDF; }
174 //! Returns physically based representation of material
175 const Graphic3d_PBRMaterial& PBRMaterial () const { return myPBRMaterial; }
177 //! Modifies the physically based representation of material
178 void SetPBRMaterial (const Graphic3d_PBRMaterial& thePBRMaterial) { myPBRMaterial = thePBRMaterial; }
180 //! Returns TRUE if the reflection mode is active, FALSE otherwise.
181 Standard_Boolean ReflectionMode (const Graphic3d_TypeOfReflection theType) const
183 return !myColors[theType].IsEqual (Quantity_NOC_BLACK);
186 //! Returns material type.
187 Graphic3d_TypeOfMaterial MaterialType() const { return myMaterialType; }
189 //! Returns TRUE if type of this material is equal to specified type.
190 Standard_Boolean MaterialType (const Graphic3d_TypeOfMaterial theType) const { return myMaterialType == theType; }
192 //! Set material type.
193 Standard_EXPORT void SetMaterialType (const Graphic3d_TypeOfMaterial theType);
195 //! Returns TRUE if this material differs from specified one.
196 Standard_Boolean IsDifferent (const Graphic3d_MaterialAspect& theOther) const { return !IsEqual (theOther); }
198 //! Returns TRUE if this material differs from specified one.
199 Standard_Boolean operator!= (const Graphic3d_MaterialAspect& theOther) const { return IsDifferent (theOther); }
201 //! Returns TRUE if this material is identical to specified one.
202 Standard_Boolean IsEqual (const Graphic3d_MaterialAspect& theOther) const
204 return myTransparencyCoef == theOther.myTransparencyCoef
205 && myRefractionIndex == theOther.myRefractionIndex
206 && myBSDF == theOther.myBSDF
207 && myPBRMaterial == theOther.myPBRMaterial
208 && myShininess == theOther.myShininess
209 && myColors[Graphic3d_TOR_AMBIENT] == theOther.myColors[Graphic3d_TOR_AMBIENT]
210 && myColors[Graphic3d_TOR_DIFFUSE] == theOther.myColors[Graphic3d_TOR_DIFFUSE]
211 && myColors[Graphic3d_TOR_SPECULAR] == theOther.myColors[Graphic3d_TOR_SPECULAR]
212 && myColors[Graphic3d_TOR_EMISSION] == theOther.myColors[Graphic3d_TOR_EMISSION];
215 //! Returns TRUE if this material is identical to specified one.
216 Standard_Boolean operator== (const Graphic3d_MaterialAspect& theOther) const { return IsEqual (theOther); }
220 //! Deactivates the reflective properties of the surface with specified reflection type.
221 Standard_DEPRECATED("Deprecated method, specific material component should be zerroed instead")
222 void SetReflectionModeOff (const Graphic3d_TypeOfReflection theType)
224 if (!ReflectionMode (theType))
231 case Graphic3d_TOR_AMBIENT: SetAmbientColor (Quantity_NOC_BLACK); break;
232 case Graphic3d_TOR_DIFFUSE: SetDiffuseColor (Quantity_NOC_BLACK); break;
233 case Graphic3d_TOR_SPECULAR: SetSpecularColor(Quantity_NOC_BLACK); break;
234 case Graphic3d_TOR_EMISSION: SetEmissiveColor(Quantity_NOC_BLACK); break;
240 //! Initialize the standard material.
241 Standard_EXPORT void init (const Graphic3d_NameOfMaterial theName);
243 //! Mark material as user defined.
244 void setUserMaterial()
246 // if a component of a "standard" material change, the
247 // result is no more standard (a blue gold is not a gold)
248 if (myMaterialName != Graphic3d_NOM_UserDefined)
250 myMaterialName = Graphic3d_NOM_UserDefined;
251 myStringName = "UserDefined";
257 Graphic3d_BSDF myBSDF;
258 Graphic3d_PBRMaterial myPBRMaterial;
259 TCollection_AsciiString myStringName;
260 Quantity_Color myColors[Graphic3d_TypeOfReflection_NB];
261 Standard_ShortReal myTransparencyCoef;
262 Standard_ShortReal myRefractionIndex;
263 Standard_ShortReal myShininess;
265 Graphic3d_TypeOfMaterial myMaterialType;
266 Graphic3d_NameOfMaterial myMaterialName;
267 Graphic3d_NameOfMaterial myRequestedMaterialName;
271 #endif // _Graphic3d_MaterialAspect_HeaderFile