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. Type() const37 Graphic3d_TypeOfLightSource Type() const { return myType; } 38 39 //! Returns light source name; empty string by default. Name() const40 const TCollection_AsciiString& Name() const { return myName; } 41 42 //! Sets light source name. SetName(const TCollection_AsciiString & theName)43 void SetName (const TCollection_AsciiString& theName) { myName = theName; } 44 45 //! Returns the color of the light source; WHITE by default. Color() const46 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. IsEnabled() const54 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. IsHeadlight() const63 Standard_Boolean IsHeadlight() const { return myIsHeadlight; } 64 65 //! Alias for IsHeadlight(). Headlight() const66 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. Position() const75 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. Position(Standard_Real & theX,Standard_Real & theY,Standard_Real & theZ) const81 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. SetPosition(Standard_Real theX,Standard_Real theY,Standard_Real theZ)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 ConstAttenuation() const98 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 LinearAttenuation() const105 Standard_ShortReal LinearAttenuation() const { return myParams.y(); } 106 107 //! Returns the attenuation factors. Attenuation(Standard_Real & theConstAttenuation,Standard_Real & theLinearAttenuation) const108 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. Direction() const123 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. Direction(Standard_Real & theVx,Standard_Real & theVy,Standard_Real & theVz) const129 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. SetDirection(Standard_Real theVx,Standard_Real theVy,Standard_Real theVz)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. Angle() const145 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. Concentration() const157 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. Intensity() const166 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. Smoothness() const172 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 //! @name low-level access methods 181 public: 182 183 //! @return light resource identifier string GetId() const184 const TCollection_AsciiString& GetId() const { return myId; } 185 186 //! Packed light parameters. PackedParams() const187 const Graphic3d_Vec4& PackedParams() const { return myParams; } 188 189 //! Returns the color of the light source with dummy Alpha component, which should be ignored. PackedColor() const190 const Graphic3d_Vec4& PackedColor() const { return myColor; } 191 192 //! Returns direction of directional/spot light. PackedDirection() const193 const Graphic3d_Vec4& PackedDirection() const { return myDirection; } 194 195 //! @return modification counter Revision() const196 Standard_Size Revision() const { return myRevision; } 197 198 private: 199 200 //! Access positional/spot light constant attenuation coefficient from packed vector. changeConstAttenuation()201 Standard_ShortReal& changeConstAttenuation() { return myParams.x(); } 202 203 //! Access positional/spot light linear attenuation coefficient from packed vector. changeLinearAttenuation()204 Standard_ShortReal& changeLinearAttenuation() { return myParams.y(); } 205 206 //! Access spotlight angle parameter from packed vector. changeAngle()207 Standard_ShortReal& changeAngle() { return myParams.z(); } 208 209 //! Access spotlight concentration parameter from packed vector. changeConcentration()210 Standard_ShortReal& changeConcentration() { return myParams.w(); } 211 212 private: 213 214 //! Generate unique object id. 215 void makeId(); 216 217 //! Update modification counter. updateRevisionIf(bool theIsModified)218 void updateRevisionIf (bool theIsModified) 219 { 220 if (theIsModified) 221 { 222 ++myRevision; 223 } 224 } 225 226 private: 227 228 Graphic3d_CLight (const Graphic3d_CLight& ); 229 Graphic3d_CLight& operator= (const Graphic3d_CLight& ); 230 231 protected: 232 233 TCollection_AsciiString myId; //!< resource id 234 TCollection_AsciiString myName; //!< user given name 235 gp_Pnt myPosition; //!< light position 236 Quantity_ColorRGBA myColor; //!< light color 237 Graphic3d_Vec4 myDirection; //!< direction of directional/spot light 238 Graphic3d_Vec4 myParams; //!< packed light parameters 239 Standard_ShortReal mySmoothness; //!< radius for point light or cone angle for directional light 240 Standard_ShortReal myIntensity; //!< intensity multiplier for light 241 const Graphic3d_TypeOfLightSource myType; //!< Graphic3d_TypeOfLightSource enumeration 242 Standard_Size myRevision; //!< modification counter 243 Standard_Boolean myIsHeadlight; //!< flag to mark head light 244 Standard_Boolean myIsEnabled; //!< enabled state 245 246 }; 247 248 DEFINE_STANDARD_HANDLE(Graphic3d_CLight, Standard_Transient) 249 250 #endif // Graphic3d_CLight_HeaderFile 251