source: OGRE/trunk/ogrenew/OgreMain/include/OgreLight.h @ 692

Revision 692, 17.1 KB checked in by mattausch, 19 years ago (diff)

adding ogre 1.2 and dependencies

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