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 //! Copy parameters from another light source excluding source type. 37 Standard_EXPORT void CopyFrom (const Handle(Graphic3d_CLight)& theLight); 38 39 //! Returns the Type of the Light, cannot be changed after object construction. Type() const40 Graphic3d_TypeOfLightSource Type() const { return myType; } 41 42 //! Returns light source name; empty string by default. Name() const43 const TCollection_AsciiString& Name() const { return myName; } 44 45 //! Sets light source name. SetName(const TCollection_AsciiString & theName)46 void SetName (const TCollection_AsciiString& theName) { myName = theName; } 47 48 //! Returns the color of the light source; WHITE by default. Color() const49 const Quantity_Color& Color() const { return myColor.GetRGB(); } 50 51 //! Defines the color of a light source by giving the basic color. 52 Standard_EXPORT void SetColor (const Quantity_Color& theColor); 53 54 //! Check that the light source is turned on; TRUE by default. 55 //! This flag affects all occurrences of light sources, where it was registered and activated; 56 //! so that it is possible defining an active light in View which is actually in disabled state. IsEnabled() const57 Standard_Boolean IsEnabled() const { return myIsEnabled; } 58 59 //! Change enabled state of the light state. 60 //! This call does not remove or deactivate light source in Views/Viewers; 61 //! instead it turns it OFF so that it just have no effect. 62 Standard_EXPORT void SetEnabled (Standard_Boolean theIsOn); 63 64 //! Return TRUE if shadow casting is enabled; FALSE by default. 65 //! Has no effect in Ray-Tracing rendering mode. ToCastShadows() const66 Standard_Boolean ToCastShadows() const { return myToCastShadows; } 67 68 //! Enable/disable shadow casting. 69 Standard_EXPORT void SetCastShadows (Standard_Boolean theToCast); 70 71 //! Returns true if the light is a headlight; FALSE by default. 72 //! Headlight flag means that light position/direction are defined not in a World coordinate system, but relative to the camera orientation. IsHeadlight() const73 Standard_Boolean IsHeadlight() const { return myIsHeadlight; } 74 75 //! Alias for IsHeadlight(). Headlight() const76 Standard_Boolean Headlight() const { return myIsHeadlight; } 77 78 //! Setup headlight flag. 79 Standard_EXPORT void SetHeadlight (Standard_Boolean theValue); 80 81 //! @name positional/spot light properties 82 public: 83 84 //! Returns location of positional/spot light; (0, 0, 0) by default. Position() const85 const gp_Pnt& Position() const { return myPosition; } 86 87 //! Setup location of positional/spot light. 88 Standard_EXPORT void SetPosition (const gp_Pnt& thePosition); 89 90 //! Returns location of positional/spot light. Position(Standard_Real & theX,Standard_Real & theY,Standard_Real & theZ) const91 void Position (Standard_Real& theX, 92 Standard_Real& theY, 93 Standard_Real& theZ) const 94 { 95 theX = myPosition.X(); 96 theY = myPosition.Y(); 97 theZ = myPosition.Z(); 98 } 99 100 //! Setup location of positional/spot light. SetPosition(Standard_Real theX,Standard_Real theY,Standard_Real theZ)101 void SetPosition (Standard_Real theX, Standard_Real theY, Standard_Real theZ) { SetPosition (gp_Pnt (theX, theY, theZ)); } 102 103 //! Returns constant attenuation factor of positional/spot light source; 1.0f by default. 104 //! Distance attenuation factors of reducing positional/spot light intensity depending on the distance from its position: 105 //! @code 106 //! float anAttenuation = 1.0 / (ConstAttenuation() + LinearAttenuation() * theDistance + QuadraticAttenuation() * theDistance * theDistance); 107 //! @endcode ConstAttenuation() const108 Standard_ShortReal ConstAttenuation() const { return myParams.x(); } 109 110 //! Returns linear attenuation factor of positional/spot light source; 0.0 by default. 111 //! Distance attenuation factors of reducing positional/spot light intensity depending on the distance from its position: 112 //! @code 113 //! float anAttenuation = 1.0 / (ConstAttenuation() + LinearAttenuation() * theDistance + QuadraticAttenuation() * theDistance * theDistance); 114 //! @endcode LinearAttenuation() const115 Standard_ShortReal LinearAttenuation() const { return myParams.y(); } 116 117 //! Returns the attenuation factors. Attenuation(Standard_Real & theConstAttenuation,Standard_Real & theLinearAttenuation) const118 void Attenuation (Standard_Real& theConstAttenuation, 119 Standard_Real& theLinearAttenuation) const 120 { 121 theConstAttenuation = ConstAttenuation(); 122 theLinearAttenuation = LinearAttenuation(); 123 } 124 125 //! Defines the coefficients of attenuation; values should be >= 0.0 and their summ should not be equal to 0. 126 Standard_EXPORT void SetAttenuation (Standard_ShortReal theConstAttenuation, 127 Standard_ShortReal theLinearAttenuation); 128 129 //! @name directional/spot light additional properties 130 public: 131 132 //! Returns direction of directional/spot light. Direction() const133 gp_Dir Direction() const { return gp_Dir (myDirection.x(), myDirection.y(), myDirection.z()); } 134 135 //! Sets direction of directional/spot light. 136 Standard_EXPORT void SetDirection (const gp_Dir& theDir); 137 138 //! Returns the theVx, theVy, theVz direction of the light source. Direction(Standard_Real & theVx,Standard_Real & theVy,Standard_Real & theVz) const139 void Direction (Standard_Real& theVx, 140 Standard_Real& theVy, 141 Standard_Real& theVz) const 142 { 143 theVx = myDirection.x(); 144 theVy = myDirection.y(); 145 theVz = myDirection.z(); 146 } 147 148 //! Sets direction of directional/spot light. SetDirection(Standard_Real theVx,Standard_Real theVy,Standard_Real theVz)149 void SetDirection (Standard_Real theVx, Standard_Real theVy, Standard_Real theVz) { SetDirection (gp_Dir (theVx, theVy, theVz)); } 150 151 //! Returns location of positional/spot/directional light, which is the same as returned by Position(). DisplayPosition() const152 const gp_Pnt& DisplayPosition() const { return myPosition; } 153 154 //! Setup location of positional/spot/directional light, 155 //! which is the same as SetPosition() but allows directional light source 156 //! (technically having no position, but this point can be used for displaying light source presentation). 157 Standard_EXPORT void SetDisplayPosition (const gp_Pnt& thePosition); 158 159 //! @name spotlight additional definition parameters 160 public: 161 162 //! Returns an angle in radians of the cone created by the spot; 30 degrees by default. Angle() const163 Standard_ShortReal Angle() const { return myParams.z(); } 164 165 //! Angle in radians of the cone created by the spot, should be within range (0.0, M_PI). 166 Standard_EXPORT void SetAngle (Standard_ShortReal theAngle); 167 168 //! Returns intensity distribution of the spot light, within [0.0, 1.0] range; 1.0 by default. 169 //! This coefficient should be converted into spotlight exponent within [0.0, 128.0] range: 170 //! @code 171 //! float aSpotExponent = Concentration() * 128.0; 172 //! anAttenuation *= pow (aCosA, aSpotExponent);" 173 //! @endcode 174 //! The concentration factor determines the dispersion of the light on the surface, the default value (1.0) corresponds to a minimum of dispersion. Concentration() const175 Standard_ShortReal Concentration() const { return myParams.w(); } 176 177 //! Defines the coefficient of concentration; value should be within range [0.0, 1.0]. 178 Standard_EXPORT void SetConcentration (Standard_ShortReal theConcentration); 179 180 //! @name Ray-Tracing / Path-Tracing light properties 181 public: 182 183 //! Returns the intensity of light source; 1.0 by default. Intensity() const184 Standard_ShortReal Intensity() const { return myIntensity; } 185 186 //! Modifies the intensity of light source, which should be > 0.0. 187 Standard_EXPORT void SetIntensity (Standard_ShortReal theValue); 188 189 //! 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() const190 Standard_ShortReal Smoothness() const { return mySmoothness; } 191 192 //! Modifies the smoothing radius of positional/spot light; should be >= 0.0. 193 Standard_EXPORT void SetSmoothRadius (Standard_ShortReal theValue); 194 195 //! Modifies the smoothing angle (in radians) of directional light source; should be within range [0.0, M_PI/2]. 196 Standard_EXPORT void SetSmoothAngle (Standard_ShortReal theValue); 197 198 //! Returns TRUE if maximum distance of point light source is defined. HasRange() const199 bool HasRange() const { return myDirection.w() != 0.0f; } 200 201 //! Returns maximum distance on which point light source affects to objects and is considered during illumination calculations. 202 //! 0.0 means disabling range considering at all without any distance limits. 203 //! Has sense only for point light sources (positional and spot). Range() const204 Standard_ShortReal Range() const { return myDirection.w(); } 205 206 //! Modifies maximum distance on which point light source affects to objects and is considered during illumination calculations. 207 //! Positional and spot lights are only point light sources. 208 //! 0.0 means disabling range considering at all without any distance limits. 209 Standard_EXPORT void SetRange (Standard_ShortReal theValue); 210 211 //! @name low-level access methods 212 public: 213 214 //! @return light resource identifier string GetId() const215 const TCollection_AsciiString& GetId() const { return myId; } 216 217 //! Packed light parameters. PackedParams() const218 const Graphic3d_Vec4& PackedParams() const { return myParams; } 219 220 //! Returns the color of the light source with dummy Alpha component, which should be ignored. PackedColor() const221 const Graphic3d_Vec4& PackedColor() const { return myColor; } 222 223 //! Returns direction of directional/spot light and range for positional/spot light in alpha channel. PackedDirectionRange() const224 const Graphic3d_Vec4& PackedDirectionRange() const { return myDirection; } 225 226 //! Returns direction of directional/spot light. PackedDirection() const227 Graphic3d_Vec3 PackedDirection() const { return myDirection.xyz(); } 228 229 //! @return modification counter Revision() const230 Standard_Size Revision() const { return myRevision; } 231 232 //! Dumps the content of me into the stream 233 Standard_EXPORT void DumpJson (Standard_OStream& theOStream, Standard_Integer theDepth = -1) const; 234 235 private: 236 237 //! Access positional/spot light constant attenuation coefficient from packed vector. changeConstAttenuation()238 Standard_ShortReal& changeConstAttenuation() { return myParams.x(); } 239 240 //! Access positional/spot light linear attenuation coefficient from packed vector. changeLinearAttenuation()241 Standard_ShortReal& changeLinearAttenuation() { return myParams.y(); } 242 243 //! Access spotlight angle parameter from packed vector. changeAngle()244 Standard_ShortReal& changeAngle() { return myParams.z(); } 245 246 //! Access spotlight concentration parameter from packed vector. changeConcentration()247 Standard_ShortReal& changeConcentration() { return myParams.w(); } 248 249 private: 250 251 //! Generate unique object id. 252 void makeId(); 253 254 //! Update modification counter. updateRevisionIf(bool theIsModified)255 void updateRevisionIf (bool theIsModified) 256 { 257 if (theIsModified) 258 { 259 ++myRevision; 260 } 261 } 262 263 private: 264 265 Graphic3d_CLight (const Graphic3d_CLight& ); 266 Graphic3d_CLight& operator= (const Graphic3d_CLight& ); 267 268 protected: 269 270 TCollection_AsciiString myId; //!< resource id 271 TCollection_AsciiString myName; //!< user given name 272 gp_Pnt myPosition; //!< light position 273 Quantity_ColorRGBA myColor; //!< light color 274 Graphic3d_Vec4 myDirection; //!< direction of directional/spot light 275 Graphic3d_Vec4 myParams; //!< packed light parameters 276 Standard_ShortReal mySmoothness; //!< radius for point light or cone angle for directional light 277 Standard_ShortReal myIntensity; //!< intensity multiplier for light 278 const Graphic3d_TypeOfLightSource myType; //!< Graphic3d_TypeOfLightSource enumeration 279 Standard_Size myRevision; //!< modification counter 280 Standard_Boolean myIsHeadlight; //!< flag to mark head light 281 Standard_Boolean myIsEnabled; //!< enabled state 282 Standard_Boolean myToCastShadows;//!< casting shadows is requested 283 284 }; 285 286 DEFINE_STANDARD_HANDLE(Graphic3d_CLight, Standard_Transient) 287 288 #endif // Graphic3d_CLight_HeaderFile 289