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.
  96   Standard_ShortReal Transparency() const { return myTransparencyCoef; }
  97
  98   //! Modifies the transparency coefficient of the surface, where 0 is opaque and 1 is fully transparent.
  99   //! Transparency is applicable to materials that have at least one of reflection modes (ambient, diffuse, specular or emissive) enabled.
 100   //! See also SetReflectionModeOn() and SetReflectionModeOff() methods.
 101   //!
 102   //! Warning: Raises MaterialDefinitionError if given value is a negative value or greater than 1.0.
 103   Standard_EXPORT void SetTransparency (const Standard_ShortReal theValue);
 104
 105   //! Returns the ambient color of the surface.
 106   const Quantity_Color& AmbientColor() const { return myColors[Graphic3d_TOR_AMBIENT]; }
 107
 108   //! Modifies the ambient color of the surface.
 109   Standard_EXPORT void SetAmbientColor (const Quantity_Color& theColor);
 110
 111   //! Returns the diffuse color of the surface.
 112   const Quantity_Color& DiffuseColor() const { return myColors[Graphic3d_TOR_DIFFUSE]; }
 113
 114   //! Modifies the diffuse color of the surface.
 115   Standard_EXPORT void SetDiffuseColor (const Quantity_Color& theColor);
 116
 117   //! Returns the specular color of the surface.
 118   const Quantity_Color& SpecularColor() const { return myColors[Graphic3d_TOR_SPECULAR]; }
 119
 120   //! Modifies the specular color of the surface.
 121   Standard_EXPORT void SetSpecularColor (const Quantity_Color& theColor);
 122
 123   //! Returns the emissive color of the surface.
 124   const Quantity_Color& EmissiveColor() const { return myColors[Graphic3d_TOR_EMISSION]; }
 125
 126   //! Modifies the emissive color of the surface.
 127   Standard_EXPORT void SetEmissiveColor (const Quantity_Color& theColor);
 128
 129   //! Returns the reflection properties of the surface.
 130   Standard_ShortReal Ambient() const { return myColorCoef[Graphic3d_TOR_AMBIENT]; }
 131
 132   //! Modifies the reflection properties of the surface.
 133   //! Warning: Raises MaterialDefinitionError if given value is a negative value or greater than 1.0.
 134   Standard_EXPORT void SetAmbient (const Standard_ShortReal theValue);
 135
 136   //! Returns the reflection properties of the surface.
 137   Standard_ShortReal Diffuse() const { return myColorCoef[Graphic3d_TOR_DIFFUSE]; }
 138
 139   //! Modifies the reflection properties of the surface.
 140   //! Warning: Raises MaterialDefinitionError if given value is a negative value or greater than 1.0.
 141   Standard_EXPORT void SetDiffuse (const Standard_ShortReal theValue);
 142
 143   //! Returns the reflection properties of the surface.
 144   Standard_ShortReal Specular() const { return myColorCoef[Graphic3d_TOR_SPECULAR]; }
 145
 146   //! Modifies the reflection properties of the surface.
 147   //! Warning: Raises MaterialDefinitionError if given value is a negative value or greater than 1.0.
 148   Standard_EXPORT void SetSpecular (const Standard_ShortReal theValue);
 149
 150   //! Returns the emissive coefficient of the surface.
 151   Standard_ShortReal Emissive() const { return myColorCoef[Graphic3d_TOR_EMISSION]; }
 152
 153   //! Modifies the reflection properties of the surface.
 154   //! Warning: Raises MaterialDefinitionError if given value is a negative value or greater than 1.0.
 155   Standard_EXPORT void SetEmissive (const Standard_ShortReal theValue);
 156
 157   //! Returns the luminosity of the surface.
 158   Standard_ShortReal Shininess() const { return myShininess; }
 159
 160   //! Modifies the luminosity of the surface.
 161   //! Warning: Raises MaterialDefinitionError if given value is a negative value or greater than 1.0.
 162   Standard_EXPORT void SetShininess (const Standard_ShortReal theValue);
 163
 164   //! Increases or decreases the luminosity.
 165   //! @param theDelta a signed percentage
 166   Standard_EXPORT void IncreaseShine (const Standard_ShortReal theDelta);
 167
 168   //! Returns the refraction index of the material
 169   Standard_ShortReal RefractionIndex() const { return myRefractionIndex; }
 170
 171   //! Modifies the refraction index of the material.
 172   //! Warning: Raises MaterialDefinitionError if given value is a lesser than 1.0.
 173   Standard_EXPORT void SetRefractionIndex (const Standard_ShortReal theValue);
 174
 175   //! Returns BSDF (bidirectional scattering distribution function).
 176   const Graphic3d_BSDF& BSDF() const { return myBSDF; }
 177
 178   //! Modifies the BSDF (bidirectional scattering distribution function).
 179   void SetBSDF (const Graphic3d_BSDF& theBSDF) { myBSDF = theBSDF; }
 180
 181   //! Returns TRUE if the reflection mode is active, FALSE otherwise.
 182   Standard_Boolean ReflectionMode (const Graphic3d_TypeOfReflection theType) const
 183   {
 184     return myReflActivity[theType];
 185   }
 186
 187   //! Activates or deactivates the reflective properties of the surface with specified reflection type.
 188   //!
 189   //! Disabling diffuse and specular reflectance is useful for efficient visualization
 190   //! of large amounts of data as definition of normals for graphic primitives is not needed
 191   //! when only "all-directional" reflectance is active.
 192   //!
 193   //! NOTE: Disabling all four reflection modes also turns off the following effects:
 194   //! 1. Lighting. Colors of primitives are not affected by the material properties when lighting is off.
 195   //! 2. Transparency.
 196   Standard_EXPORT void SetReflectionMode (const Graphic3d_TypeOfReflection theType,
 197                                           const Standard_Boolean theValue);
 198
 199   //! Activates the reflective properties of the surface with specified reflection type.
 200   void SetReflectionModeOn (const Graphic3d_TypeOfReflection theType) { SetReflectionMode (theType, Standard_True); }
 201
 202   //! Deactivates the reflective properties of the surface with specified reflection type.
 203   void SetReflectionModeOff (const Graphic3d_TypeOfReflection theType) { SetReflectionMode (theType, Standard_False); }
 204
 205   //! Returns TRUE if type of this material is equal to specified type.
 206   Standard_Boolean MaterialType (const Graphic3d_TypeOfMaterial theType) const { return myMaterialType == theType; }
 207
 208   //! Set material type.
 209   Standard_EXPORT void SetMaterialType (const Graphic3d_TypeOfMaterial theType);
 210
 211   Standard_ShortReal EnvReflexion() const { return myEnvReflexion; }
 212
 213   void SetEnvReflexion (const Standard_ShortReal theValue) { myEnvReflexion = theValue; }
 214
 215   //! Returns TRUE if this material differs from specified one.
 216   Standard_Boolean IsDifferent (const Graphic3d_MaterialAspect& theOther) const { return !IsEqual (theOther); }
 217
 218   //! Returns TRUE if this material differs from specified one.
 219   Standard_Boolean operator!= (const Graphic3d_MaterialAspect& theOther) const { return IsDifferent (theOther); }
 220
 221   //! Returns TRUE if this material is identical to specified one.
 222   Standard_Boolean IsEqual (const Graphic3d_MaterialAspect& theOther) const
 223   {
 224     return myColorCoef[Graphic3d_TOR_AMBIENT]  == theOther.myColorCoef[Graphic3d_TOR_AMBIENT]
 225         && myColorCoef[Graphic3d_TOR_DIFFUSE]  == theOther.myColorCoef[Graphic3d_TOR_DIFFUSE]
 226         && myColorCoef[Graphic3d_TOR_SPECULAR] == theOther.myColorCoef[Graphic3d_TOR_SPECULAR]
 227         && myColorCoef[Graphic3d_TOR_EMISSION] == theOther.myColorCoef[Graphic3d_TOR_EMISSION]
 228         && myTransparencyCoef == theOther.myTransparencyCoef
 229         && myRefractionIndex  == theOther.myRefractionIndex
 230         && myBSDF             == theOther.myBSDF
 231         && myShininess        == theOther.myShininess
 232         && myEnvReflexion     == theOther.myEnvReflexion
 233         && myColors[Graphic3d_TOR_AMBIENT]    == theOther.myColors[Graphic3d_TOR_AMBIENT]
 234         && myColors[Graphic3d_TOR_DIFFUSE]    == theOther.myColors[Graphic3d_TOR_DIFFUSE]
 235         && myColors[Graphic3d_TOR_SPECULAR]   == theOther.myColors[Graphic3d_TOR_SPECULAR]
 236         && myColors[Graphic3d_TOR_EMISSION]   == theOther.myColors[Graphic3d_TOR_EMISSION]
 237         && myReflActivity[Graphic3d_TOR_AMBIENT]  == theOther.myReflActivity[Graphic3d_TOR_AMBIENT]
 238         && myReflActivity[Graphic3d_TOR_DIFFUSE]  == theOther.myReflActivity[Graphic3d_TOR_DIFFUSE]
 239         && myReflActivity[Graphic3d_TOR_SPECULAR] == theOther.myReflActivity[Graphic3d_TOR_SPECULAR]
 240         && myReflActivity[Graphic3d_TOR_EMISSION] == theOther.myReflActivity[Graphic3d_TOR_EMISSION];
 241   }
 242
 243   //! Returns TRUE if this material is identical to specified one.
 244   Standard_Boolean operator== (const Graphic3d_MaterialAspect& theOther) const { return IsEqual (theOther); }
 245
 246 private:
 247
 248   //! Initialize the standard material.
 249   Standard_EXPORT void init (const Graphic3d_NameOfMaterial theName);
 250
 251   //! Mark material as user defined.
 252   void setUserMaterial()
 253   {
 254     // if a component of a "standard" material change, the
 255     // result is no more standard (a blue gold is not a gold)
 256     myMaterialName = Graphic3d_NOM_UserDefined;
 257     myStringName   = "UserDefined";
 258   }
 259
 260 private:
 261
 262   Graphic3d_BSDF           myBSDF;
 263   TCollection_AsciiString  myStringName;
 264   Quantity_Color           myColors   [Graphic3d_TypeOfReflection_NB];
 265   Standard_ShortReal       myColorCoef[Graphic3d_TypeOfReflection_NB];
 266   Standard_ShortReal       myTransparencyCoef;
 267   Standard_ShortReal       myRefractionIndex;
 268   Standard_ShortReal       myShininess;
 269   Standard_ShortReal       myEnvReflexion;
 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