0032121: Draw Harness, ViewerTest - implement -reset option for vlight command
[occt.git] / 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   //! 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.
40   Graphic3d_TypeOfLightSource Type() const { return myType; }
41
42   //! Returns light source name; empty string by default.
43   const TCollection_AsciiString& Name() const { return myName; }
44
45   //! Sets light source name.
46   void SetName (const TCollection_AsciiString& theName) { myName = theName; }
47
48   //! Returns the color of the light source; WHITE by default.
49   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.
57   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.
66   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.
73   Standard_Boolean IsHeadlight() const { return myIsHeadlight; }
74
75   //! Alias for IsHeadlight().
76   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.
85   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.
91   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.
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
108   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
115   Standard_ShortReal LinearAttenuation() const { return myParams.y(); }
116
117   //! Returns the attenuation factors.
118   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.
133   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.
139   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.
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().
152   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.
163   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.
175   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.
184   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.
190   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.
199   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).  
204   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
215   const TCollection_AsciiString& GetId() const { return myId; }
216
217   //! Packed light parameters.
218   const Graphic3d_Vec4& PackedParams() const { return myParams; }
219
220   //! Returns the color of the light source with dummy Alpha component, which should be ignored.
221   const Graphic3d_Vec4& PackedColor() const { return myColor; }
222
223   //! Returns direction of directional/spot light and range for positional/spot light in alpha channel.
224   const Graphic3d_Vec4& PackedDirectionRange() const { return myDirection; }
225
226   //! Returns direction of directional/spot light.
227   Graphic3d_Vec3 PackedDirection() const { return myDirection.xyz(); }
228
229   //! @return modification counter
230   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.
238   Standard_ShortReal& changeConstAttenuation()  { return myParams.x(); }
239
240   //! Access positional/spot light linear attenuation coefficient from packed vector.
241   Standard_ShortReal& changeLinearAttenuation() { return myParams.y(); }
242
243   //! Access spotlight angle parameter from packed vector.
244   Standard_ShortReal& changeAngle()             { return myParams.z(); }
245
246   //! Access spotlight concentration parameter from packed vector.
247   Standard_ShortReal& changeConcentration()     { return myParams.w(); }
248
249 private:
250
251   //! Generate unique object id.
252   void makeId();
253
254   //! Update modification counter.
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