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   //! Finds the material for specified name.
  46   //! @param theName [in]  name to find
  47   //! @param theMat  [out] found material
  48   //! @return FALSE if name was unrecognized
  49   Standard_EXPORT static Standard_Boolean MaterialFromName (const Standard_CString theName,
  50                                                             Graphic3d_NameOfMaterial& theMat);
  51
  52   //! Returns the material for specified name or Graphic3d_NOM_DEFAULT if name is unknown.
  53   static Graphic3d_NameOfMaterial MaterialFromName (const Standard_CString theName)
  54   {
  55     Graphic3d_NameOfMaterial aMat = Graphic3d_NOM_DEFAULT;
  56     MaterialFromName (theName, aMat);
  57     return aMat;
  58   }
  59
  60 public:
  61
  62   //! Creates a material from default values.
  63   Standard_EXPORT Graphic3d_MaterialAspect();
  64
  65   //! Creates a generic material.
  66   Standard_EXPORT Graphic3d_MaterialAspect (const Graphic3d_NameOfMaterial theName);
  67
  68   //! Returns the material name (within predefined enumeration).
  69   Graphic3d_NameOfMaterial Name() const { return myMaterialName; }
  70
  71   //! Returns the material name within predefined enumeration which has been requested (before modifications).
  72   Graphic3d_NameOfMaterial RequestedName() const { return myRequestedMaterialName; }
  73
  74   //! Returns the given name of this material. This might be:
  75   //! - given name set by method ::SetMaterialName()
  76   //! - standard name for a material within enumeration
  77   //! - "UserDefined" for non-standard material without name specified externally.
  78   const TCollection_AsciiString& StringName() const { return myStringName; }
  79
  80   //! Returns the given name of this material. This might be:
  81   Standard_CString MaterialName() const { return myStringName.ToCString(); }
  82
  83   //! The current material become a "UserDefined" material.
  84   //! Set the name of the "UserDefined" material.
  85   void SetMaterialName (const TCollection_AsciiString& theName)
  86   {
  87     // if a component of a "standard" material change, the
  88     // result is no more standard (a blue gold is not a gold)
  89     myMaterialName = Graphic3d_NOM_UserDefined;
  90     myStringName   = theName;
  91   }
  92
  93   //! Resets the material with the original values according to
  94   //! the material name but leave the current color values untouched
  95   //! for the material of type ASPECT.
  96   void Reset()
  97   {
  98     init (myRequestedMaterialName);
  99   }
 100
 101   //! Returns the diffuse color of the surface.
 102   //! WARNING! This method does NOT return color for Graphic3d_MATERIAL_ASPECT material (color is defined by Graphic3d_Aspects::InteriorColor()).
 103   const Quantity_Color& Color() const { return myColors[Graphic3d_TOR_DIFFUSE]; }
 104
 105   //! Modifies the ambient and diffuse color of the surface.
 106   //! WARNING! Has no effect for Graphic3d_MATERIAL_ASPECT material (color should be set to Graphic3d_Aspects::SetInteriorColor()).
 107   Standard_EXPORT void SetColor (const Quantity_Color& theColor);
 108
 109   //! Returns the transparency coefficient of the surface (1.0 - Alpha); 0.0 means opaque.
 110   Standard_ShortReal Transparency() const { return myTransparencyCoef; }
 111
 112   //! Returns the alpha coefficient of the surface (1.0 - Transparency); 1.0 means opaque.
 113   Standard_ShortReal Alpha() const { return 1.0f - myTransparencyCoef; }
 114
 115   //! Modifies the transparency coefficient of the surface, where 0 is opaque and 1 is fully transparent.
 116   //! Transparency is applicable to materials that have at least one of reflection modes (ambient, diffuse, specular or emissive) enabled.
 117   //! See also SetReflectionModeOn() and SetReflectionModeOff() methods.
 118   //!
 119   //! Warning: Raises MaterialDefinitionError if given value is a negative value or greater than 1.0.
 120   Standard_EXPORT void SetTransparency (const Standard_ShortReal theValue);
 121
 122   //! Modifies the alpha coefficient of the surface, where 1.0 is opaque and 0.0 is fully transparent.
 123   void SetAlpha (Standard_ShortReal theValue) { SetTransparency (1.0f - theValue); }
 124
 125   //! Returns the ambient color of the surface.
 126   const Quantity_Color& AmbientColor() const { return myColors[Graphic3d_TOR_AMBIENT]; }
 127
 128   //! Modifies the ambient color of the surface.
 129   Standard_EXPORT void SetAmbientColor (const Quantity_Color& theColor);
 130
 131   //! Returns the diffuse color of the surface.
 132   const Quantity_Color& DiffuseColor() const { return myColors[Graphic3d_TOR_DIFFUSE]; }
 133
 134   //! Modifies the diffuse color of the surface.
 135   Standard_EXPORT void SetDiffuseColor (const Quantity_Color& theColor);
 136
 137   //! Returns the specular color of the surface.
 138   const Quantity_Color& SpecularColor() const { return myColors[Graphic3d_TOR_SPECULAR]; }
 139
 140   //! Modifies the specular color of the surface.
 141   Standard_EXPORT void SetSpecularColor (const Quantity_Color& theColor);
 142
 143   //! Returns the emissive color of the surface.
 144   const Quantity_Color& EmissiveColor() const { return myColors[Graphic3d_TOR_EMISSION]; }
 145
 146   //! Modifies the emissive color of the surface.
 147   Standard_EXPORT void SetEmissiveColor (const Quantity_Color& theColor);
 148
 149   //! Returns the luminosity of the surface.
 150   Standard_ShortReal Shininess() const { return myShininess; }
 151
 152   //! Modifies the luminosity of the surface.
 153   //! Warning: Raises MaterialDefinitionError if given value is a negative value or greater than 1.0.
 154   Standard_EXPORT void SetShininess (const Standard_ShortReal theValue);
 155
 156   //! Increases or decreases the luminosity.
 157   //! @param theDelta a signed percentage
 158   Standard_EXPORT void IncreaseShine (const Standard_ShortReal theDelta);
 159
 160   //! Returns the refraction index of the material
 161   Standard_ShortReal RefractionIndex() const { return myRefractionIndex; }
 162
 163   //! Modifies the refraction index of the material.
 164   //! Warning: Raises MaterialDefinitionError if given value is a lesser than 1.0.
 165   Standard_EXPORT void SetRefractionIndex (const Standard_ShortReal theValue);
 166
 167   //! Returns BSDF (bidirectional scattering distribution function).
 168   const Graphic3d_BSDF& BSDF() const { return myBSDF; }
 169
 170   //! Modifies the BSDF (bidirectional scattering distribution function).
 171   void SetBSDF (const Graphic3d_BSDF& theBSDF) { myBSDF = theBSDF; }
 172
 173   //! Returns TRUE if the reflection mode is active, FALSE otherwise.
 174   Standard_Boolean ReflectionMode (const Graphic3d_TypeOfReflection theType) const
 175   {
 176     return !myColors[theType].IsEqual (Quantity_NOC_BLACK);
 177   }
 178
 179   //! Returns material type.
 180   Graphic3d_TypeOfMaterial MaterialType() const { return myMaterialType; }
 181
 182   //! Returns TRUE if type of this material is equal to specified type.
 183   Standard_Boolean MaterialType (const Graphic3d_TypeOfMaterial theType) const { return myMaterialType == theType; }
 184
 185   //! Set material type.
 186   Standard_EXPORT void SetMaterialType (const Graphic3d_TypeOfMaterial theType);
 187
 188   //! Returns TRUE if this material differs from specified one.
 189   Standard_Boolean IsDifferent (const Graphic3d_MaterialAspect& theOther) const { return !IsEqual (theOther); }
 190
 191   //! Returns TRUE if this material differs from specified one.
 192   Standard_Boolean operator!= (const Graphic3d_MaterialAspect& theOther) const { return IsDifferent (theOther); }
 193
 194   //! Returns TRUE if this material is identical to specified one.
 195   Standard_Boolean IsEqual (const Graphic3d_MaterialAspect& theOther) const
 196   {
 197     return myTransparencyCoef == theOther.myTransparencyCoef
 198         && myRefractionIndex  == theOther.myRefractionIndex
 199         && myBSDF             == theOther.myBSDF
 200         && myShininess        == theOther.myShininess
 201         && myColors[Graphic3d_TOR_AMBIENT]  == theOther.myColors[Graphic3d_TOR_AMBIENT]
 202         && myColors[Graphic3d_TOR_DIFFUSE]  == theOther.myColors[Graphic3d_TOR_DIFFUSE]
 203         && myColors[Graphic3d_TOR_SPECULAR] == theOther.myColors[Graphic3d_TOR_SPECULAR]
 204         && myColors[Graphic3d_TOR_EMISSION] == theOther.myColors[Graphic3d_TOR_EMISSION];
 205   }
 206
 207   //! Returns TRUE if this material is identical to specified one.
 208   Standard_Boolean operator== (const Graphic3d_MaterialAspect& theOther) const { return IsEqual (theOther); }
 209
 210 public:
 211
 212   //! Deactivates the reflective properties of the surface with specified reflection type.
 213   Standard_DEPRECATED("Deprecated method, specific material component should be zerroed instead")
 214   void SetReflectionModeOff (const Graphic3d_TypeOfReflection theType)
 215   {
 216     if (!ReflectionMode (theType))
 217     {
 218       return;
 219     }
 220
 221     switch (theType)
 222     {
 223       case Graphic3d_TOR_AMBIENT:  SetAmbientColor (Quantity_NOC_BLACK); break;
 224       case Graphic3d_TOR_DIFFUSE:  SetDiffuseColor (Quantity_NOC_BLACK); break;
 225       case Graphic3d_TOR_SPECULAR: SetSpecularColor(Quantity_NOC_BLACK); break;
 226       case Graphic3d_TOR_EMISSION: SetEmissiveColor(Quantity_NOC_BLACK); break;
 227     }
 228   }
 229
 230 private:
 231
 232   //! Initialize the standard material.
 233   Standard_EXPORT void init (const Graphic3d_NameOfMaterial theName);
 234
 235   //! Mark material as user defined.
 236   void setUserMaterial()
 237   {
 238     // if a component of a "standard" material change, the
 239     // result is no more standard (a blue gold is not a gold)
 240     if (myMaterialName != Graphic3d_NOM_UserDefined)
 241     {
 242       myMaterialName = Graphic3d_NOM_UserDefined;
 243       myStringName   = "UserDefined";
 244     }
 245   }
 246
 247 private:
 248
 249   Graphic3d_BSDF           myBSDF;
 250   TCollection_AsciiString  myStringName;
 251   Quantity_Color           myColors[Graphic3d_TypeOfReflection_NB];
 252   Standard_ShortReal       myTransparencyCoef;
 253   Standard_ShortReal       myRefractionIndex;
 254   Standard_ShortReal       myShininess;
 255
 256   Graphic3d_TypeOfMaterial myMaterialType;
 257   Graphic3d_NameOfMaterial myMaterialName;
 258   Graphic3d_NameOfMaterial myRequestedMaterialName;
 259
 260 };
 261
 262 #endif // _Graphic3d_MaterialAspect_HeaderFile