src/Graphic3d/Graphic3d_CLight.hxx

   1 // Copyright (c) 1999-2014 OPEN CASCADE SAS
   2 //
   3 // This file is part of Open CASCADE Technology software library.
   4 //
   5 // This library is free software; you can redistribute it and/or modify it under
   6 // the terms of the GNU Lesser General Public License version 2.1 as published
   7 // by the Free Software Foundation, with special exception defined in the file
   8 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
   9 // distribution for complete text of the license and disclaimer of any warranty.
  10 //
  11 // Alternatively, this file may be used under the terms of Open CASCADE
  12 // commercial license or contractual agreement.
  13
  14 #ifndef _Graphic3d_CLight_HeaderFile
  15 #define _Graphic3d_CLight_HeaderFile
  16
  17 #include <gp_Dir.hxx>
  18 #include <Graphic3d_TypeOfLightSource.hxx>
  19 #include <Graphic3d_Vec.hxx>
  20 #include <NCollection_List.hxx>
  21 #include <TCollection_AsciiString.hxx>
  22 #include <Quantity_ColorRGBA.hxx>
  23
  24 //! Generic light source definition.
  25 //! This class defines arbitrary light source - see Graphic3d_TypeOfLightSource enumeration.
  26 //! Some parameters are applicable only to particular light type;
  27 //! calling methods unrelated to current type will throw an exception.
  28 class Graphic3d_CLight : public Standard_Transient
  29 {
  30   DEFINE_STANDARD_RTTIEXT(Graphic3d_CLight, Standard_Transient)
  31 public:
  32
  33   //! Empty constructor, which should be followed by light source properties configuration.
  34   Standard_EXPORT Graphic3d_CLight (Graphic3d_TypeOfLightSource theType);
  35
  36   //! Returns the Type of the Light, cannot be changed after object construction.
  37   Graphic3d_TypeOfLightSource Type() const { return myType; }
  38
  39   //! Returns light source name; empty string by default.
  40   const TCollection_AsciiString& Name() const { return myName; }
  41
  42   //! Sets light source name.
  43   void SetName (const TCollection_AsciiString& theName) { myName = theName; }
  44
  45   //! Returns the color of the light source; WHITE by default.
  46   const Quantity_Color& Color() const { return myColor.GetRGB(); }
  47
  48   //! Defines the color of a light source by giving the basic color.
  49   Standard_EXPORT void SetColor (const Quantity_Color& theColor);
  50
  51   //! Check that the light source is turned on; TRUE by default.
  52   //! This flag affects all occurrences of light sources, where it was registered and activated;
  53   //! so that it is possible defining an active light in View which is actually in disabled state.
  54   Standard_Boolean IsEnabled() const { return myIsEnabled; }
  55
  56   //! Change enabled state of the light state.
  57   //! This call does not remove or deactivate light source in Views/Viewers;
  58   //! instead it turns it OFF so that it just have no effect.
  59   Standard_EXPORT void SetEnabled (Standard_Boolean theIsOn);
  60
  61   //! Returns true if the light is a headlight; FALSE by default.
  62   //! Headlight flag means that light position/direction are defined not in a World coordinate system, but relative to the camera orientation.
  63   Standard_Boolean IsHeadlight() const { return myIsHeadlight; }
  64
  65   //! Alias for IsHeadlight().
  66   Standard_Boolean Headlight() const { return myIsHeadlight; }
  67
  68   //! Setup headlight flag.
  69   Standard_EXPORT void SetHeadlight (Standard_Boolean theValue);
  70
  71 //! @name positional/spot light properties
  72 public:
  73
  74   //! Returns location of positional/spot light; (0, 0, 0) by default.
  75   const gp_Pnt& Position() const { return myPosition; }
  76
  77   //! Setup location of positional/spot light.
  78   Standard_EXPORT void SetPosition (const gp_Pnt& thePosition);
  79
  80   //! Returns location of positional/spot light.
  81   void Position (Standard_Real& theX,
  82                  Standard_Real& theY,
  83                  Standard_Real& theZ) const
  84   {
  85     theX = myPosition.X();
  86     theY = myPosition.Y();
  87     theZ = myPosition.Z();
  88   }
  89
  90   //! Setup location of positional/spot light.
  91   void SetPosition (Standard_Real theX, Standard_Real theY, Standard_Real theZ) { SetPosition (gp_Pnt (theX, theY, theZ)); }
  92
  93   //! Returns constant attenuation factor of positional/spot light source; 1.0f by default.
  94   //! Distance attenuation factors of reducing positional/spot light intensity depending on the distance from its position:
  95   //! @code
  96   //!   float anAttenuation = 1.0 / (ConstAttenuation() + LinearAttenuation() * theDistance + QuadraticAttenuation() * theDistance * theDistance);
  97   //! @endcode
  98   Standard_ShortReal ConstAttenuation()  const { return myParams.x(); }
  99
 100   //! Returns linear attenuation factor of positional/spot light source; 0.0 by default.
 101   //! Distance attenuation factors of reducing positional/spot light intensity depending on the distance from its position:
 102   //! @code
 103   //!   float anAttenuation = 1.0 / (ConstAttenuation() + LinearAttenuation() * theDistance + QuadraticAttenuation() * theDistance * theDistance);
 104   //! @endcode
 105   Standard_ShortReal LinearAttenuation() const { return myParams.y(); }
 106
 107   //! Returns the attenuation factors.
 108   void Attenuation (Standard_Real& theConstAttenuation,
 109                     Standard_Real& theLinearAttenuation) const
 110   {
 111     theConstAttenuation  = ConstAttenuation();
 112     theLinearAttenuation = LinearAttenuation();
 113   }
 114
 115   //! Defines the coefficients of attenuation; values should be >= 0.0 and their summ should not be equal to 0.
 116   Standard_EXPORT void SetAttenuation (Standard_ShortReal theConstAttenuation,
 117                                        Standard_ShortReal theLinearAttenuation);
 118
 119 //! @name directional/spot light additional properties
 120 public:
 121
 122   //! Returns direction of directional/spot light.
 123   gp_Dir Direction() const { return gp_Dir (myDirection.x(), myDirection.y(), myDirection.z()); }
 124
 125   //! Sets direction of directional/spot light.
 126   Standard_EXPORT void SetDirection (const gp_Dir& theDir);
 127
 128   //! Returns the theVx, theVy, theVz direction of the light source.
 129   void Direction (Standard_Real& theVx,
 130                   Standard_Real& theVy,
 131                   Standard_Real& theVz) const
 132   {
 133     theVx = myDirection.x();
 134     theVy = myDirection.y();
 135     theVz = myDirection.z();
 136   }
 137
 138   //! Sets direction of directional/spot light.
 139   void SetDirection (Standard_Real theVx, Standard_Real theVy, Standard_Real theVz) { SetDirection (gp_Dir (theVx, theVy, theVz)); }
 140
 141 //! @name spotlight additional definition parameters
 142 public:
 143
 144   //! Returns an angle in radians of the cone created by the spot; 30 degrees by default.
 145   Standard_ShortReal Angle() const { return myParams.z(); }
 146
 147   //! Angle in radians of the cone created by the spot, should be within range (0.0, M_PI).
 148   Standard_EXPORT void SetAngle (Standard_ShortReal theAngle);
 149
 150   //! Returns intensity distribution of the spot light, within [0.0, 1.0] range; 1.0 by default.
 151   //! This coefficient should be converted into spotlight exponent within [0.0, 128.0] range:
 152   //! @code
 153   //!   float aSpotExponent = Concentration() * 128.0;
 154   //!   anAttenuation *= pow (aCosA, aSpotExponent);"
 155   //! @endcode
 156   //! The concentration factor determines the dispersion of the light on the surface, the default value (1.0) corresponds to a minimum of dispersion.
 157   Standard_ShortReal Concentration() const { return myParams.w(); }
 158
 159   //! Defines the coefficient of concentration; value should be within range [0.0, 1.0].
 160   Standard_EXPORT void SetConcentration (Standard_ShortReal theConcentration);
 161
 162 //! @name Ray-Tracing / Path-Tracing light properties
 163 public:
 164
 165   //! Returns the intensity of light source; 1.0 by default.
 166   Standard_ShortReal Intensity() const { return myIntensity; }
 167
 168   //! Modifies the intensity of light source, which should be > 0.0.
 169   Standard_EXPORT void SetIntensity (Standard_ShortReal theValue);
 170
 171   //! Returns the smoothness of light source (either smoothing angle for directional light or smoothing radius in case of positional light); 0.0 by default.
 172   Standard_ShortReal Smoothness() const { return mySmoothness; }
 173
 174   //! Modifies the smoothing radius of positional/spot light; should be >= 0.0.
 175   Standard_EXPORT void SetSmoothRadius (Standard_ShortReal theValue);
 176
 177   //! Modifies the smoothing angle (in radians) of directional light source; should be within range [0.0, M_PI/2].
 178   Standard_EXPORT void SetSmoothAngle (Standard_ShortReal theValue);
 179
 180   //! Returns maximum distance on which point light source affects to objects and is considered during illumination calculations.
 181   //! 0.0 means disabling range considering at all without any distance limits.
 182   //! Has sense only for point light sources (positional and spot).
 183   Standard_ShortReal Range() const { return myDirection.w(); }
 184
 185   //! Modifies maximum distance on which point light source affects to objects and is considered during illumination calculations.
 186   //! Positional and spot lights are only point light sources.
 187   //! 0.0 means disabling range considering at all without any distance limits.
 188   Standard_EXPORT void SetRange (Standard_ShortReal theValue);
 189
 190 //! @name low-level access methods
 191 public:
 192
 193   //! @return light resource identifier string
 194   const TCollection_AsciiString& GetId() const { return myId; }
 195
 196   //! Packed light parameters.
 197   const Graphic3d_Vec4& PackedParams() const { return myParams; }
 198
 199   //! Returns the color of the light source with dummy Alpha component, which should be ignored.
 200   const Graphic3d_Vec4& PackedColor() const { return myColor; }
 201
 202   //! Returns direction of directional/spot light and range for positional/spot light in alpha channel.
 203   const Graphic3d_Vec4& PackedDirectionRange() const { return myDirection; }
 204
 205   //! @return modification counter
 206   Standard_Size Revision() const { return myRevision; }
 207
 208 private:
 209
 210   //! Access positional/spot light constant attenuation coefficient from packed vector.
 211   Standard_ShortReal& changeConstAttenuation()  { return myParams.x(); }
 212
 213   //! Access positional/spot light linear attenuation coefficient from packed vector.
 214   Standard_ShortReal& changeLinearAttenuation() { return myParams.y(); }
 215
 216   //! Access spotlight angle parameter from packed vector.
 217   Standard_ShortReal& changeAngle()             { return myParams.z(); }
 218
 219   //! Access spotlight concentration parameter from packed vector.
 220   Standard_ShortReal& changeConcentration()     { return myParams.w(); }
 221
 222 private:
 223
 224   //! Generate unique object id.
 225   void makeId();
 226
 227   //! Update modification counter.
 228   void updateRevisionIf (bool theIsModified)
 229   {
 230     if (theIsModified)
 231     {
 232       ++myRevision;
 233     }
 234   }
 235
 236 private:
 237
 238   Graphic3d_CLight (const Graphic3d_CLight& );
 239   Graphic3d_CLight& operator= (const Graphic3d_CLight& );
 240
 241 protected:
 242
 243   TCollection_AsciiString           myId;          //!< resource id
 244   TCollection_AsciiString           myName;        //!< user given name
 245   gp_Pnt                            myPosition;    //!< light position
 246   Quantity_ColorRGBA                myColor;       //!< light color
 247   Graphic3d_Vec4                    myDirection;   //!< direction of directional/spot light
 248   Graphic3d_Vec4                    myParams;      //!< packed light parameters
 249   Standard_ShortReal                mySmoothness;  //!< radius for point light or cone angle for directional light
 250   Standard_ShortReal                myIntensity;   //!< intensity multiplier for light
 251   const Graphic3d_TypeOfLightSource myType;        //!< Graphic3d_TypeOfLightSource enumeration
 252   Standard_Size                     myRevision;    //!< modification counter
 253   Standard_Boolean                  myIsHeadlight; //!< flag to mark head light
 254   Standard_Boolean                  myIsEnabled;   //!< enabled state
 255
 256 };
 257
 258 DEFINE_STANDARD_HANDLE(Graphic3d_CLight, Standard_Transient)
 259
 260 #endif // Graphic3d_CLight_HeaderFile