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_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>
  26
  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
  33 {
  34 public:
  35   DEFINE_STANDARD_ALLOC
  36
  37   //! Returns the number of predefined textures.
  38   static Standard_Integer NumberOfMaterials() { return Graphic3d_NOM_DEFAULT; }
  39
  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);
  42
  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);
  45
  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);
  52
  53   //! Returns the material for specified name or Graphic3d_NOM_DEFAULT if name is unknown.
  54   static Graphic3d_NameOfMaterial MaterialFromName (const Standard_CString theName)
  55   {
  56     Graphic3d_NameOfMaterial aMat = Graphic3d_NOM_DEFAULT;
  57     MaterialFromName (theName, aMat);
  58     return aMat;
  59   }
  60
  61 public:
  62
  63   //! Creates a material from default values.
  64   Standard_EXPORT Graphic3d_MaterialAspect();
  65
  66   //! Creates a generic material.
  67   Standard_EXPORT Graphic3d_MaterialAspect (const Graphic3d_NameOfMaterial theName);
  68
  69   //! Returns the material name (within predefined enumeration).
  70   Graphic3d_NameOfMaterial Name() const { return myMaterialName; }
  71
  72   //! Returns the material name within predefined enumeration which has been requested (before modifications).
  73   Graphic3d_NameOfMaterial RequestedName() const { return myRequestedMaterialName; }
  74
  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; }
  80
  81   //! Returns the given name of this material. This might be:
  82   Standard_CString MaterialName() const { return myStringName.ToCString(); }
  83
  84   //! The current material become a "UserDefined" material.
  85   //! Set the name of the "UserDefined" material.
  86   void SetMaterialName (const TCollection_AsciiString& theName)
  87   {
  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;
  92   }
  93
  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.
  97   void Reset()
  98   {
  99     init (myRequestedMaterialName);
 100   }
 101
 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]; }
 105
 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);
 109
 110   //! Returns the transparency coefficient of the surface (1.0 - Alpha); 0.0 means opaque.
 111   Standard_ShortReal Transparency() const { return myTransparencyCoef; }
 112
 113   //! Returns the alpha coefficient of the surface (1.0 - Transparency); 1.0 means opaque.
 114   Standard_ShortReal Alpha() const { return 1.0f - myTransparencyCoef; }
 115
 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.
 119   //!
 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);
 122
 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); }
 125
 126   //! Returns the ambient color of the surface.
 127   const Quantity_Color& AmbientColor() const { return myColors[Graphic3d_TOR_AMBIENT]; }
 128
 129   //! Modifies the ambient color of the surface.
 130   Standard_EXPORT void SetAmbientColor (const Quantity_Color& theColor);
 131
 132   //! Returns the diffuse color of the surface.
 133   const Quantity_Color& DiffuseColor() const { return myColors[Graphic3d_TOR_DIFFUSE]; }
 134
 135   //! Modifies the diffuse color of the surface.
 136   Standard_EXPORT void SetDiffuseColor (const Quantity_Color& theColor);
 137
 138   //! Returns the specular color of the surface.
 139   const Quantity_Color& SpecularColor() const { return myColors[Graphic3d_TOR_SPECULAR]; }
 140
 141   //! Modifies the specular color of the surface.
 142   Standard_EXPORT void SetSpecularColor (const Quantity_Color& theColor);
 143
 144   //! Returns the emissive color of the surface.
 145   const Quantity_Color& EmissiveColor() const { return myColors[Graphic3d_TOR_EMISSION]; }
 146
 147   //! Modifies the emissive color of the surface.
 148   Standard_EXPORT void SetEmissiveColor (const Quantity_Color& theColor);
 149
 150   //! Returns the luminosity of the surface.
 151   Standard_ShortReal Shininess() const { return myShininess; }
 152
 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);
 156
 157   //! Increases or decreases the luminosity.
 158   //! @param theDelta a signed percentage
 159   Standard_EXPORT void IncreaseShine (const Standard_ShortReal theDelta);
 160
 161   //! Returns the refraction index of the material
 162   Standard_ShortReal RefractionIndex() const { return myRefractionIndex; }
 163
 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);
 167
 168   //! Returns BSDF (bidirectional scattering distribution function).
 169   const Graphic3d_BSDF& BSDF() const { return myBSDF; }
 170
 171   //! Modifies the BSDF (bidirectional scattering distribution function).
 172   void SetBSDF (const Graphic3d_BSDF& theBSDF) { myBSDF = theBSDF; }
 173
 174   //! Returns physically based representation of material
 175   const Graphic3d_PBRMaterial& PBRMaterial () const { return myPBRMaterial; }
 176
 177   //! Modifies the physically based representation of material
 178   void SetPBRMaterial (const Graphic3d_PBRMaterial& thePBRMaterial) { myPBRMaterial = thePBRMaterial; }
 179
 180   //! Returns TRUE if the reflection mode is active, FALSE otherwise.
 181   Standard_Boolean ReflectionMode (const Graphic3d_TypeOfReflection theType) const
 182   {
 183     return !myColors[theType].IsEqual (Quantity_NOC_BLACK);
 184   }
 185
 186   //! Returns material type.
 187   Graphic3d_TypeOfMaterial MaterialType() const { return myMaterialType; }
 188
 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; }
 191
 192   //! Set material type.
 193   Standard_EXPORT void SetMaterialType (const Graphic3d_TypeOfMaterial theType);
 194
 195   //! Returns TRUE if this material differs from specified one.
 196   Standard_Boolean IsDifferent (const Graphic3d_MaterialAspect& theOther) const { return !IsEqual (theOther); }
 197
 198   //! Returns TRUE if this material differs from specified one.
 199   Standard_Boolean operator!= (const Graphic3d_MaterialAspect& theOther) const { return IsDifferent (theOther); }
 200
 201   //! Returns TRUE if this material is identical to specified one.
 202   Standard_Boolean IsEqual (const Graphic3d_MaterialAspect& theOther) const
 203   {
 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];
 213   }
 214
 215   //! Returns TRUE if this material is identical to specified one.
 216   Standard_Boolean operator== (const Graphic3d_MaterialAspect& theOther) const { return IsEqual (theOther); }
 217
 218   //! Dumps the content of me into the stream
 219   Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const;
 220
 221 public:
 222
 223   //! Deactivates the reflective properties of the surface with specified reflection type.
 224   Standard_DEPRECATED("Deprecated method, specific material component should be zerroed instead")
 225   void SetReflectionModeOff (const Graphic3d_TypeOfReflection theType)
 226   {
 227     if (!ReflectionMode (theType))
 228     {
 229       return;
 230     }
 231
 232     switch (theType)
 233     {
 234       case Graphic3d_TOR_AMBIENT:  SetAmbientColor (Quantity_NOC_BLACK); break;
 235       case Graphic3d_TOR_DIFFUSE:  SetDiffuseColor (Quantity_NOC_BLACK); break;
 236       case Graphic3d_TOR_SPECULAR: SetSpecularColor(Quantity_NOC_BLACK); break;
 237       case Graphic3d_TOR_EMISSION: SetEmissiveColor(Quantity_NOC_BLACK); break;
 238     }
 239   }
 240
 241 private:
 242
 243   //! Initialize the standard material.
 244   Standard_EXPORT void init (const Graphic3d_NameOfMaterial theName);
 245
 246   //! Mark material as user defined.
 247   void setUserMaterial()
 248   {
 249     // if a component of a "standard" material change, the
 250     // result is no more standard (a blue gold is not a gold)
 251     if (myMaterialName != Graphic3d_NOM_UserDefined)
 252     {
 253       myMaterialName = Graphic3d_NOM_UserDefined;
 254       myStringName   = "UserDefined";
 255     }
 256   }
 257
 258 private:
 259
 260   Graphic3d_BSDF           myBSDF;
 261   Graphic3d_PBRMaterial    myPBRMaterial;
 262   TCollection_AsciiString  myStringName;
 263   Quantity_Color           myColors[Graphic3d_TypeOfReflection_NB];
 264   Standard_ShortReal       myTransparencyCoef;
 265   Standard_ShortReal       myRefractionIndex;
 266   Standard_ShortReal       myShininess;
 267
 268   Graphic3d_TypeOfMaterial myMaterialType;
 269   Graphic3d_NameOfMaterial myMaterialName;
 270   Graphic3d_NameOfMaterial myRequestedMaterialName;
 271
 272 };
 273
 274 #endif // _Graphic3d_MaterialAspect_HeaderFile