Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/OgreMain/include/OgreLight.h @ 1

Last change on this file since 1 was 1, checked in by landauf, 17 years ago
File size: 18.2 KB
Line 
1/*
2-----------------------------------------------------------------------------
3This source file is part of OGRE
4    (Object-oriented Graphics Rendering Engine)
5For the latest info, see http://www.ogre3d.org/
6
7Copyright (c) 2000-2006 Torus Knot Software Ltd
8Also see acknowledgements in Readme.html
9
10This program is free software; you can redistribute it and/or modify it under
11the terms of the GNU Lesser General Public License as published by the Free Software
12Foundation; either version 2 of the License, or (at your option) any later
13version.
14
15This program is distributed in the hope that it will be useful, but WITHOUT
16ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
18
19You should have received a copy of the GNU Lesser General Public License along with
20this program; if not, write to the Free Software Foundation, Inc., 59 Temple
21Place - Suite 330, Boston, MA 02111-1307, USA, or go to
22http://www.gnu.org/copyleft/lesser.txt.
23
24You may alternatively use this source under the terms of a specific version of
25the OGRE Unrestricted License provided you have obtained such a license from
26Torus Knot Software Ltd.
27-----------------------------------------------------------------------------
28*/
29#ifndef _LIGHT_H__
30#define _LIGHT_H__
31
32#include "OgrePrerequisites.h"
33
34#include "OgreColourValue.h"
35#include "OgreVector3.h"
36#include "OgreVector4.h"
37#include "OgreString.h"
38#include "OgreMovableObject.h"
39#include "OgrePlaneBoundedVolume.h"
40#include "OgreShadowCameraSetup.h"
41
42namespace Ogre {
43
44
45    /** Representation of a dynamic light source in the scene.
46        @remarks
47            Lights are added to the scene like any other object. They contain various
48            parameters like type, position, attenuation (how light intensity fades with
49            distance), colour etc.
50        @par
51            The defaults when a light is created is pure white diffues light, with no
52            attenuation (does not decrease with distance) and a range of 1000 world units.
53        @par
54            Lights are created by using the SceneManager::createLight method. They can subsequently be
55            added to a SceneNode if required to allow them to move relative to a node in the scene. A light attached
56            to a SceneNode is assumed to havea base position of (0,0,0) and a direction of (0,0,1) before modification
57            by the SceneNode's own orientation. If not attached to a SceneNode,
58            the light's position and direction is as set using setPosition and setDirection.
59        @par
60            Remember also that dynamic lights rely on modifying the colour of vertices based on the position of
61            the light compared to an object's vertex normals. Dynamic lighting will only look good if the
62            object being lit has a fair level of tesselation and the normals are properly set. This is particularly
63            true for the spotlight which will only look right on highly tesselated models. In the future OGRE may be
64            extended for certain scene types so an alternative to the standard dynamic lighting may be used, such
65            as dynamic lightmaps.
66    */
67    class _OgreExport Light : public MovableObject
68    {
69    public:
70        /// Temp tag used for sorting
71        Real tempSquareDist;
72
73        /// Defines the type of light
74        enum LightTypes
75        {
76            /// Point light sources give off light equally in all directions, so require only position not direction
77            LT_POINT,
78            /// Directional lights simulate parallel light beams from a distant source, hence have direction but no position
79            LT_DIRECTIONAL,
80            /// Spotlights simulate a cone of light from a source so require position and direction, plus extra values for falloff
81            LT_SPOTLIGHT
82        };
83
84        /** Default constructor (for Python mainly).
85        */
86        Light();
87
88        /** Normal constructor. Should not be called directly, but rather the SceneManager::createLight method should be used.
89        */
90        Light(const String& name);
91
92        /** Standard destructor.
93        */
94        ~Light();
95
96        /** Sets the type of light - see LightTypes for more info.
97        */
98        void setType(LightTypes type);
99
100        /** Returns the light type.
101        */
102        LightTypes getType(void) const;
103
104        /** Sets the colour of the diffuse light given off by this source.
105            @remarks
106                Material objects have ambient, diffuse and specular values which indicate how much of each type of
107                light an object reflects. This value denotes the amount and colour of this type of light the light
108                exudes into the scene. The actual appearance of objects is a combination of the two.
109            @par
110                Diffuse light simulates the typical light emenating from light sources and affects the base colour
111                of objects together with ambient light.
112        */
113        void setDiffuseColour(Real red, Real green, Real blue);
114
115        /** Sets the colour of the diffuse light given off by this source.
116            @remarks
117                Material objects have ambient, diffuse and specular values which indicate how much of each type of
118                light an object reflects. This value denotes the amount and colour of this type of light the light
119                exudes into the scene. The actual appearance of objects is a combination of the two.
120            @par
121                Diffuse light simulates the typical light emenating from light sources and affects the base colour
122                of objects together with ambient light.
123        */
124        void setDiffuseColour(const ColourValue& colour);
125
126        /** Returns the colour of the diffuse light given off by this light source (see setDiffuseColour for more info).
127        */
128        const ColourValue& getDiffuseColour(void) const;
129
130        /** Sets the colour of the specular light given off by this source.
131            @remarks
132                Material objects have ambient, diffuse and specular values which indicate how much of each type of
133                light an object reflects. This value denotes the amount and colour of this type of light the light
134                exudes into the scene. The actual appearance of objects is a combination of the two.
135            @par
136                Specular light affects the appearance of shiny highlights on objects, and is also dependent on the
137                'shininess' Material value.
138        */
139        void setSpecularColour(Real red, Real green, Real blue);
140
141        /** Sets the colour of the specular light given off by this source.
142            @remarks
143                Material objects have ambient, diffuse and specular values which indicate how much of each type of
144                light an object reflects. This value denotes the amount and colour of this type of light the light
145                exudes into the scene. The actual appearance of objects is a combination of the two.
146            @par
147                Specular light affects the appearance of shiny highlights on objects, and is also dependent on the
148                'shininess' Material value.
149        */
150        void setSpecularColour(const ColourValue& colour);
151
152        /** Returns the colour of specular light given off by this light source.
153        */
154        const ColourValue& getSpecularColour(void) const;
155
156        /** Sets the attenuation parameters of the light source ie how it diminishes with distance.
157            @remarks
158                Lights normally get fainter the further they are away. Also, each light is given a maximum range
159                beyond which it cannot affect any objects.
160            @par
161                Light attentuation is not applicable to directional lights since they have an infinite range and
162                constant intensity.
163            @par
164                This follows a standard attenuation approach - see any good 3D text for the details of what they mean
165                since i don't have room here!
166            @param
167                range The absolute upper range of the light in world units
168            @param
169                constant The constant factor in the attenuation formula: 1.0 means never attenuate, 0.0 is complete attenuation
170            @param
171                linear The linear factor in the attenuation formula: 1 means attenuate evenly over the distance
172            @param
173                quadratic The quadratic factor in the attenuation formula: adds a curvature to the attenuation formula.
174        */
175        void setAttenuation(Real range, Real constant, Real linear, Real quadratic);
176
177        /** Returns the absolute upper range of the light.
178        */
179        Real getAttenuationRange(void) const;
180
181        /** Returns the constant factor in the attenuation formula.
182        */
183        Real getAttenuationConstant(void) const;
184
185        /** Returns the linear factor in the attenuation formula.
186        */
187        Real getAttenuationLinear(void) const;
188
189        /** Returns the quadric factor in the attenuation formula.
190        */
191        Real getAttenuationQuadric(void) const;
192
193        /** Sets the position of the light.
194            @remarks
195                Applicable to point lights and spotlights only.
196            @note
197                This will be overridden if the light is attached to a SceneNode.
198        */
199        void setPosition(Real x, Real y, Real z);
200
201        /** Sets the position of the light.
202            @remarks
203                Applicable to point lights and spotlights only.
204            @note
205                This will be overridden if the light is attached to a SceneNode.
206        */
207        void setPosition(const Vector3& vec);
208
209        /** Returns the position of the light.
210            @note
211                Applicable to point lights and spotlights only.
212        */
213        const Vector3& getPosition(void) const;
214
215        /** Sets the direction in which a light points.
216            @remarks
217                Applicable only to the spotlight and directional light types.
218            @note
219                This will be overridden if the light is attached to a SceneNode.
220        */
221        void setDirection(Real x, Real y, Real z);
222
223        /** Sets the direction in which a light points.
224            @remarks
225                Applicable only to the spotlight and directional light types.
226            @note
227                This will be overridden if the light is attached to a SceneNode.
228        */
229        void setDirection(const Vector3& vec);
230
231        /** Returns the light's direction.
232            @remarks
233                Applicable only to the spotlight and directional light types.
234        */
235        const Vector3& getDirection(void) const;
236
237        /** Sets the range of a spotlight, i.e. the angle of the inner and outer cones and the rate of falloff between them.
238            @param
239                innerAngle Angle covered by the bright inner cone
240                @node
241                    The inner cone applicable only to Direct3D, it'll always treat as zero in OpenGL.
242            @param
243                outerAngle Angle covered by the outer cone
244            @param
245                falloff The rate of falloff between the inner and outer cones. 1.0 means a linear falloff, less means slower falloff, higher means faster falloff.
246        */
247        void setSpotlightRange(const Radian& innerAngle, const Radian& outerAngle, Real falloff = 1.0);
248#ifndef OGRE_FORCE_ANGLE_TYPES
249        inline void setSpotlightRange(Real innerAngle, Real outerAngle, Real falloff = 1.0) {
250            setSpotlightRange ( Angle(innerAngle), Angle(outerAngle), falloff );
251        }
252#endif//OGRE_FORCE_ANGLE_TYPES
253
254        /** Returns the angle covered by the spotlights inner cone.
255        */
256        const Radian& getSpotlightInnerAngle(void) const;
257
258        /** Returns the angle covered by the spotlights outer cone.
259        */
260        const Radian& getSpotlightOuterAngle(void) const;
261
262        /** Returns the falloff between the inner and outer cones of the spotlight.
263        */
264        Real getSpotlightFalloff(void) const;
265
266                /** Sets the angle covered by the spotlights inner cone.
267                */
268                void setSpotlightInnerAngle(const Radian& val);
269
270                /** Sets the angle covered by the spotlights outer cone.
271                */
272                void setSpotlightOuterAngle(const Radian& val);
273
274                /** Sets the falloff between the inner and outer cones of the spotlight.
275                */
276                void setSpotlightFalloff(Real val);
277
278                /** Set a scaling factor to indicate the relative power of a light.
279                @remarks
280                        This factor is only useful in High Dynamic Range (HDR) rendering.
281                        You can bind it to a shader variable to take it into account,
282                        @see GpuProgramParameters
283                @param power The power rating of this light, default is 1.0.
284                */
285                void setPowerScale(Real power);
286
287                /** Set the scaling factor which indicates the relative power of a
288                        light.
289                */
290                Real getPowerScale(void) const;
291
292        /** Overridden from MovableObject */
293        void _notifyAttached(Node* parent, bool isTagPoint = false);
294
295        /** Overridden from MovableObject */
296        void _notifyMoved(void);
297
298        /** Overridden from MovableObject */
299        const AxisAlignedBox& getBoundingBox(void) const;
300
301        /** Overridden from MovableObject */
302        void _updateRenderQueue(RenderQueue* queue);
303
304        /** Overridden from MovableObject */
305        const String& getMovableType(void) const;
306
307        /** Retrieves the position of the light including any transform from nodes it is attached to. */
308        const Vector3& getDerivedPosition(void) const;
309
310        /** Retrieves the direction of the light including any transform from nodes it is attached to. */
311        const Vector3& getDerivedDirection(void) const;
312
313        /** Overridden from MovableObject.
314        @remarks
315            Although lights themselves are not 'visible', setting a light to invisible
316            means it no longer affects the scene.
317        */
318        void setVisible(bool visible);
319
320        /** Overridden from MovableObject */
321        Real getBoundingRadius(void) const { return 0; /* not visible */ }
322
323                /** Gets the details of this light as a 4D vector.
324                @remarks
325                        Getting details of a light as a 4D vector can be useful for
326                        doing general calculations between different light types; for
327                        example the vector can represent both position lights (w=1.0f)
328                        and directional lights (w=0.0f) and be used in the same
329                        calculations.
330                */
331                Vector4 getAs4DVector(void) const;
332
333        /** Internal method for calculating the 'near clip volume', which is
334            the volume formed between the near clip rectangle of the
335            camera and the light.
336        @remarks This volume is a pyramid for a point/spot light and
337            a cuboid for a directional light. It can used to detect whether
338            an object could be casting a shadow on the viewport. Note that
339            the reference returned is to a shared volume which will be
340            reused across calls to this method.
341        */
342        virtual const PlaneBoundedVolume& _getNearClipVolume(const Camera* const cam) const;
343
344        /** Internal method for calculating the clip volumes outside of the
345            frustum which can be used to determine which objects are casting
346            shadow on the frustum as a whole.
347        @remarks Each of the volumes is a pyramid for a point/spot light and
348            a cuboid for a directional light.
349        */
350        virtual const PlaneBoundedVolumeList& _getFrustumClipVolumes(const Camera* const cam) const;
351
352                /// Override to return specific type flag
353                uint32 getTypeFlags(void) const;
354
355                /// @copydoc AnimableObject::createAnimableValue
356                AnimableValuePtr createAnimableValue(const String& valueName);
357
358                /** Set this light to use a custom shadow camera when rendering texture shadows.
359                @remarks
360                        This changes the shadow camera setup for just this light,  you can set
361                        the shadow camera setup globally using SceneManager::setShadowCameraSetup
362                @see ShadowCameraSetup
363                */
364                void setCustomShadowCameraSetup(const ShadowCameraSetupPtr& customShadowSetup);
365
366                /** Reset the shadow camera setup to the default.
367                @see ShadowCameraSetup
368                */
369                void resetCustomShadowCameraSetup(void);
370
371                /** return a pointer to the custom shadow camera setup (null means use SceneManager global version). */
372                const ShadowCameraSetupPtr& getCustomShadowCameraSetup(void) const;
373
374    protected:
375        /// internal method for synchronising with parent node (if any)
376        virtual void update(void) const;
377
378                /// @copydoc AnimableObject::getAnimableDictionaryName
379                const String& getAnimableDictionaryName(void) const;
380                /// @copydoc AnimableObject::initialiseAnimableDictionary
381                void initialiseAnimableDictionary(StringVector& vec) const;
382
383                LightTypes mLightType;
384        Vector3 mPosition;
385        ColourValue mDiffuse;
386        ColourValue mSpecular;
387
388        Vector3 mDirection;
389
390        Radian mSpotOuter;
391        Radian mSpotInner;
392        Real mSpotFalloff;
393        Real mRange;
394        Real mAttenuationConst;
395        Real mAttenuationLinear;
396        Real mAttenuationQuad;
397                Real mPowerScale;
398
399
400        mutable Vector3 mDerivedPosition;
401        mutable Vector3 mDerivedDirection;
402
403        /// Shared class-level name for Movable type
404        static String msMovableType;
405
406        mutable PlaneBoundedVolume mNearClipVolume;
407        mutable PlaneBoundedVolumeList mFrustumClipVolumes;
408        /// Is the derived transform dirty?
409        mutable bool mDerivedTransformDirty;
410
411                /// Pointer to a custom shadow camera setup
412                mutable ShadowCameraSetupPtr mCustomShadowCameraSetup;
413
414    };
415
416        /** Factory object for creating Light instances */
417        class _OgreExport LightFactory : public MovableObjectFactory
418        {
419        protected:
420                MovableObject* createInstanceImpl( const String& name, const NameValuePairList* params);
421        public:
422                LightFactory() {}
423                ~LightFactory() {}
424
425                static String FACTORY_TYPE_NAME;
426
427                const String& getType(void) const;
428                void destroyInstance( MovableObject* obj); 
429
430        };
431
432} // Namespace
433#endif
Note: See TracBrowser for help on using the repository browser.