Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/ogre_src_v1-9-0/OgreMain/include/OgreLight.h @ 148

Last change on this file since 148 was 148, checked in by patricwi, 6 years ago

Added new dependencies for ogre1.9 and cegui0.8

File size: 27.4 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-2013 Torus Knot Software Ltd
8
9Permission is hereby granted, free of charge, to any person obtaining a copy
10of this software and associated documentation files (the "Software"), to deal
11in the Software without restriction, including without limitation the rights
12to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13copies of the Software, and to permit persons to whom the Software is
14furnished to do so, subject to the following conditions:
15
16The above copyright notice and this permission notice shall be included in
17all copies or substantial portions of the Software.
18
19THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
25THE SOFTWARE.
26-----------------------------------------------------------------------------
27*/
28#ifndef _LIGHT_H__
29#define _LIGHT_H__
30
31#include "OgrePrerequisites.h"
32
33#include "OgreColourValue.h"
34#include "OgreVector3.h"
35#include "OgreVector4.h"
36#include "OgreString.h"
37#include "OgreMovableObject.h"
38#include "OgrePlaneBoundedVolume.h"
39#include "OgreShadowCameraSetup.h"
40#include "OgreHeaderPrefix.h"
41
42namespace Ogre {
43
44
45    /** \addtogroup Core
46    *  @{
47    */
48    /** \addtogroup Scene
49    *  @{
50    */
51    /** Representation of a dynamic light source in the scene.
52    @remarks
53        Lights are added to the scene like any other object. They contain various
54        parameters like type, position, attenuation (how light intensity fades with
55        distance), colour etc.
56    @par
57        The defaults when a light is created is pure white diffuse light, with no
58        attenuation (does not decrease with distance) and a range of 1000 world units.
59    @par
60        Lights are created by using the SceneManager::createLight method. They can subsequently be
61        added to a SceneNode if required to allow them to move relative to a node in the scene. A light attached
62        to a SceneNode is assumed to have a base position of (0,0,0) and a direction of (0,0,1) before modification
63        by the SceneNode's own orientation. If not attached to a SceneNode,
64        the light's position and direction is as set using setPosition and setDirection.
65    @par
66        Remember also that dynamic lights rely on modifying the colour of vertices based on the position of
67        the light compared to an object's vertex normals. Dynamic lighting will only look good if the
68        object being lit has a fair level of tessellation and the normals are properly set. This is particularly
69        true for the spotlight which will only look right on highly tessellated models. In the future OGRE may be
70        extended for certain scene types so an alternative to the standard dynamic lighting may be used, such
71            as dynamic lightmaps.
72    */
73    class _OgreExport Light : public MovableObject
74    {
75    public:
76        /// Temp tag used for sorting
77        Real tempSquareDist;
78        /// internal method for calculating current squared distance from some world position
79        void _calcTempSquareDist(const Vector3& worldPos);
80
81        /// Defines the type of light
82        enum LightTypes
83        {
84            /// Point light sources give off light equally in all directions, so require only position not direction
85            LT_POINT = 0,
86            /// Directional lights simulate parallel light beams from a distant source, hence have direction but no position
87            LT_DIRECTIONAL = 1,
88            /// Spotlights simulate a cone of light from a source so require position and direction, plus extra values for falloff
89            LT_SPOTLIGHT = 2
90        };
91
92        /** Default constructor (for Python mainly).
93        */
94        Light();
95
96        /** Normal constructor. Should not be called directly, but rather the SceneManager::createLight method should be used.
97        */
98        Light(const String& name);
99
100        /** Standard destructor.
101        */
102        ~Light();
103
104        /** Sets the type of light - see LightTypes for more info.
105        */
106        void setType(LightTypes type);
107
108        /** Returns the light type.
109        */
110        LightTypes getType(void) const;
111
112        /** Sets the colour of the diffuse light given off by this source.
113        @remarks
114            Material objects have ambient, diffuse and specular values which indicate how much of each type of
115            light an object reflects. This value denotes the amount and colour of this type of light the light
116            exudes into the scene. The actual appearance of objects is a combination of the two.
117        @par
118            Diffuse light simulates the typical light emanating from light sources and affects the base colour
119            of objects together with ambient light.
120        */
121        void setDiffuseColour(Real red, Real green, Real blue);
122
123        /** Sets the colour of the diffuse light given off by this source.
124        @remarks
125            Material objects have ambient, diffuse and specular values which indicate how much of each type of
126            light an object reflects. This value denotes the amount and colour of this type of light the light
127            exudes into the scene. The actual appearance of objects is a combination of the two.
128        @par
129            Diffuse light simulates the typical light emanating from light sources and affects the base colour
130            of objects together with ambient light.
131        */
132        void setDiffuseColour(const ColourValue& colour);
133
134        /** Returns the colour of the diffuse light given off by this light source (see setDiffuseColour for more info).
135        */
136        const ColourValue& getDiffuseColour(void) const;
137
138        /** Sets the colour of the specular light given off by this source.
139        @remarks
140            Material objects have ambient, diffuse and specular values which indicate how much of each type of
141            light an object reflects. This value denotes the amount and colour of this type of light the light
142            exudes into the scene. The actual appearance of objects is a combination of the two.
143        @par
144            Specular light affects the appearance of shiny highlights on objects, and is also dependent on the
145            'shininess' Material value.
146        */
147        void setSpecularColour(Real red, Real green, Real blue);
148
149        /** Sets the colour of the specular light given off by this source.
150        @remarks
151            Material objects have ambient, diffuse and specular values which indicate how much of each type of
152            light an object reflects. This value denotes the amount and colour of this type of light the light
153            exudes into the scene. The actual appearance of objects is a combination of the two.
154        @par
155            Specular light affects the appearance of shiny highlights on objects, and is also dependent on the
156            'shininess' Material value.
157        */
158        void setSpecularColour(const ColourValue& colour);
159
160        /** Returns the colour of specular light given off by this light source.
161        */
162        const ColourValue& getSpecularColour(void) const;
163
164        /** Sets the attenuation parameters of the light source i.e. how it diminishes with distance.
165        @remarks
166            Lights normally get fainter the further they are away. Also, each light is given a maximum range
167            beyond which it cannot affect any objects.
168        @par
169            Light attenuation is not applicable to directional lights since they have an infinite range and
170            constant intensity.
171        @par
172            This follows a standard attenuation approach - see any good 3D text for the details of what they mean
173            since i don't have room here!
174        @param range
175            The absolute upper range of the light in world units.
176        @param constant
177            The constant factor in the attenuation formula: 1.0 means never attenuate, 0.0 is complete attenuation.
178        @param linear
179            The linear factor in the attenuation formula: 1 means attenuate evenly over the distance.
180        @param quadratic
181            The quadratic factor in the attenuation formula: adds a curvature to the attenuation formula.
182        */
183        void setAttenuation(Real range, Real constant, Real linear, Real quadratic);
184
185        /** Returns the absolute upper range of the light.
186        */
187        Real getAttenuationRange(void) const;
188
189        /** Returns the constant factor in the attenuation formula.
190        */
191        Real getAttenuationConstant(void) const;
192
193        /** Returns the linear factor in the attenuation formula.
194        */
195        Real getAttenuationLinear(void) const;
196
197        /** Returns the quadric factor in the attenuation formula.
198        */
199        Real getAttenuationQuadric(void) const;
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(Real x, Real y, Real z);
208
209        /** Sets the position of the light.
210        @remarks
211            Applicable to point lights and spotlights only.
212        @note
213            This will be overridden if the light is attached to a SceneNode.
214        */
215        void setPosition(const Vector3& vec);
216
217        /** Returns the position of the light.
218        @note
219            Applicable to point lights and spotlights only.
220        */
221        const Vector3& getPosition(void) const;
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(Real x, Real y, Real z);
230
231        /** Sets the direction in which a light points.
232        @remarks
233            Applicable only to the spotlight and directional light types.
234        @note
235            This will be overridden if the light is attached to a SceneNode.
236        */
237        void setDirection(const Vector3& vec);
238
239        /** Returns the light's direction.
240        @remarks
241            Applicable only to the spotlight and directional light types.
242        */
243        const Vector3& getDirection(void) const;
244
245        /** Sets the range of a spotlight, i.e. the angle of the inner and outer cones
246            and the rate of falloff between them.
247        @param innerAngle
248            Angle covered by the bright inner cone
249            @note
250                The inner cone applicable only to Direct3D, it'll always treat as zero in OpenGL.
251        @param outerAngle
252            Angle covered by the outer cone
253        @param falloff
254            The rate of falloff between the inner and outer cones. 1.0 means a linear falloff,
255            less means slower falloff, higher means faster falloff.
256        */
257        void setSpotlightRange(const Radian& innerAngle, const Radian& outerAngle, Real falloff = 1.0);
258
259        /** Returns the angle covered by the spotlights inner cone.
260        */
261        const Radian& getSpotlightInnerAngle(void) const;
262
263        /** Returns the angle covered by the spotlights outer cone.
264        */
265        const Radian& getSpotlightOuterAngle(void) const;
266
267        /** Returns the falloff between the inner and outer cones of the spotlight.
268        */
269        Real getSpotlightFalloff(void) const;
270
271        /** Sets the angle covered by the spotlights inner cone.
272        */
273        void setSpotlightInnerAngle(const Radian& val);
274
275        /** Sets the angle covered by the spotlights outer cone.
276        */
277        void setSpotlightOuterAngle(const Radian& val);
278
279        /** Sets the falloff between the inner and outer cones of the spotlight.
280        */
281        void setSpotlightFalloff(Real val);
282
283        /** Set the near clip plane distance to be used by spotlights that use light
284            clipping, allowing you to render spots as if they start from further
285            down their frustum.
286        @param nearClip
287            The near distance.
288        */
289        void setSpotlightNearClipDistance(Real nearClip) { mSpotNearClip = nearClip; }
290       
291        /** Get the near clip plane distance to be used by spotlights that use light
292            clipping.
293        */
294        Real getSpotlightNearClipDistance() const { return mSpotNearClip; }
295       
296        /** Set a scaling factor to indicate the relative power of a light.
297        @remarks
298            This factor is only useful in High Dynamic Range (HDR) rendering.
299            You can bind it to a shader variable to take it into account,
300            @see GpuProgramParameters
301        @param power
302            The power rating of this light, default is 1.0.
303        */
304        void setPowerScale(Real power);
305
306        /** Set the scaling factor which indicates the relative power of a
307            light.
308        */
309        Real getPowerScale(void) const;
310
311        /** @copydoc MovableObject::_notifyAttached */
312        void _notifyAttached(Node* parent, bool isTagPoint = false);
313
314        /** @copydoc MovableObject::_notifyMoved */
315        void _notifyMoved(void);
316
317        /** @copydoc MovableObject::getBoundingBox */
318        const AxisAlignedBox& getBoundingBox(void) const;
319
320        /** @copydoc MovableObject::_updateRenderQueue */
321        void _updateRenderQueue(RenderQueue* queue);
322
323        /** @copydoc MovableObject::getMovableType */
324        const String& getMovableType(void) const;
325
326        /** Retrieves the position of the light including any transform from nodes it is attached to.
327        @param cameraRelativeIfSet If set to true, returns data in camera-relative units if that's been set up (render use)
328        */
329        const Vector3& getDerivedPosition(bool cameraRelativeIfSet = false) const;
330
331        /** Retrieves the direction of the light including any transform from nodes it is attached to. */
332        const Vector3& getDerivedDirection(void) const;
333
334        /** @copydoc MovableObject::setVisible.
335        @remarks
336            Although lights themselves are not 'visible', setting a light to invisible
337            means it no longer affects the scene.
338        */
339        void setVisible(bool visible);
340
341        /** @copydoc MovableObject::getBoundingRadius */
342        Real getBoundingRadius(void) const { return 0; /* not visible */ }
343
344        /** Gets the details of this light as a 4D vector.
345        @remarks
346            Getting details of a light as a 4D vector can be useful for
347            doing general calculations between different light types; for
348            example the vector can represent both position lights (w=1.0f)
349            and directional lights (w=0.0f) and be used in the same
350            calculations.
351        @param cameraRelativeIfSet
352            If set to @c true, returns data in camera-relative units if that's been set up (render use).
353        */
354        Vector4 getAs4DVector(bool cameraRelativeIfSet = false) const;
355
356        /** Internal method for calculating the 'near clip volume', which is
357            the volume formed between the near clip rectangle of the
358            camera and the light.
359        @remarks
360            This volume is a pyramid for a point/spot light and
361            a cuboid for a directional light. It can used to detect whether
362            an object could be casting a shadow on the viewport. Note that
363            the reference returned is to a shared volume which will be
364            reused across calls to this method.
365        */
366        virtual const PlaneBoundedVolume& _getNearClipVolume(const Camera* const cam) const;
367
368        /** Internal method for calculating the clip volumes outside of the
369            frustum which can be used to determine which objects are casting
370            shadow on the frustum as a whole.
371        @remarks
372            Each of the volumes is a pyramid for a point/spot light and
373            a cuboid for a directional light.
374        */
375        virtual const PlaneBoundedVolumeList& _getFrustumClipVolumes(const Camera* const cam) const;
376
377        /// Override to return specific type flag
378        uint32 getTypeFlags(void) const;
379
380        /// @copydoc AnimableObject::createAnimableValue
381        AnimableValuePtr createAnimableValue(const String& valueName);
382
383        /** Set this light to use a custom shadow camera when rendering texture shadows.
384        @remarks
385            This changes the shadow camera setup for just this light,  you can set
386            the shadow camera setup globally using SceneManager::setShadowCameraSetup
387        @see ShadowCameraSetup
388        */
389        void setCustomShadowCameraSetup(const ShadowCameraSetupPtr& customShadowSetup);
390
391        /** Reset the shadow camera setup to the default.
392        @see ShadowCameraSetup
393        */
394        void resetCustomShadowCameraSetup(void);
395
396        /** Return a pointer to the custom shadow camera setup (null means use SceneManager global version). */
397        const ShadowCameraSetupPtr& getCustomShadowCameraSetup(void) const;
398
399        /// @copydoc MovableObject::visitRenderables
400        void visitRenderables(Renderable::Visitor* visitor, 
401            bool debugRenderables = false);
402
403        /** Gets the index at which this light is in the current render.
404        @remarks
405            Lights will be present in the in a list for every renderable,
406            detected and sorted appropriately, and sometimes it's useful to know
407            what position in that list a given light occupies. This can vary
408            from frame to frame (and object to object) so you should not use this
409            value unless you're sure the context is correct.
410        */
411        size_t _getIndexInFrame() const { return mIndexInFrame; }
412        void _notifyIndexInFrame(size_t i) { mIndexInFrame = i; }
413       
414        /** Sets the maximum distance away from the camera that shadows
415            by this light will be visible.
416        @remarks
417            Shadow techniques can be expensive, therefore it is a good idea
418            to limit them to being rendered close to the camera if possible,
419            and to skip the expense of rendering shadows for distance objects.
420            This method allows you to set the distance at which shadows will no
421            longer be rendered.
422        @note
423            Each shadow technique can interpret this subtely differently.
424            For example, one technique may use this to eliminate casters,
425            another might use it to attenuate the shadows themselves.
426            You should tweak this value to suit your chosen shadow technique
427            and scene setup.
428        */
429        void setShadowFarDistance(Real distance);
430        /** Tells the light to use the shadow far distance of the SceneManager
431        */
432        void resetShadowFarDistance(void);
433        /** Gets the maximum distance away from the camera that shadows
434            by this light will be visible.
435        */
436        Real getShadowFarDistance(void) const;
437        Real getShadowFarDistanceSquared(void) const;
438
439        /** Set the near clip plane distance to be used by the shadow camera, if
440            this light casts texture shadows.
441        @param nearClip
442            The distance, or -1 to use the main camera setting.
443        */
444        void setShadowNearClipDistance(Real nearClip) { mShadowNearClipDist = nearClip; }
445
446        /** Get the near clip plane distance to be used by the shadow camera, if
447            this light casts texture shadows.
448        @remarks
449            May be zero if the light doesn't have it's own near distance set;
450            use _deriveShadowNearDistance for a version guaranteed to give a result.
451        */
452        Real getShadowNearClipDistance() const { return mShadowNearClipDist; }
453
454        /** Derive a shadow camera near distance from either the light, or
455            from the main camera if the light doesn't have its own setting.
456        */
457        Real _deriveShadowNearClipDistance(const Camera* maincam) const;
458
459        /** Set the far clip plane distance to be used by the shadow camera, if
460            this light casts texture shadows.
461        @remarks
462            This is different from the 'shadow far distance', which is
463            always measured from the main camera. This distance is the far clip plane
464            of the light camera.
465        @param farClip
466            The distance, or -1 to use the main camera setting.
467        */
468        void setShadowFarClipDistance(Real farClip) { mShadowFarClipDist = farClip; }
469
470        /** Get the far clip plane distance to be used by the shadow camera, if
471            this light casts texture shadows.
472        @remarks
473            May be zero if the light doesn't have it's own far distance set;
474            use _deriveShadowfarDistance for a version guaranteed to give a result.
475        */
476        Real getShadowFarClipDistance() const { return mShadowFarClipDist; }
477
478        /** Derive a shadow camera far distance from either the light, or
479            from the main camera if the light doesn't have its own setting.
480        */
481        Real _deriveShadowFarClipDistance(const Camera* maincam) const;
482
483        /// Set the camera which this light should be relative to, for camera-relative rendering
484        void _setCameraRelative(Camera* cam);
485
486        /** Sets a custom parameter for this Light, which may be used to
487            drive calculations for this specific Renderable, like GPU program parameters.
488        @remarks
489            Calling this method simply associates a numeric index with a 4-dimensional
490            value for this specific Light. This is most useful if the material
491            which this Renderable uses a vertex or fragment program, and has an
492            ACT_LIGHT_CUSTOM parameter entry. This parameter entry can refer to the
493            index you specify as part of this call, thereby mapping a custom
494            parameter for this renderable to a program parameter.
495        @param index
496            The index with which to associate the value. Note that this
497            does not have to start at 0, and can include gaps. It also has no direct
498            correlation with a GPU program parameter index - the mapping between the
499            two is performed by the ACT_LIGHT_CUSTOM entry, if that is used.
500        @param value
501            The value to associate.
502        */
503        void setCustomParameter(uint16 index, const Vector4& value);
504
505        /** Gets the custom value associated with this Light at the given index.
506        @param index Index of the parameter to retrieve
507        @see setCustomParameter for full details.
508        */
509        const Vector4& getCustomParameter(uint16 index) const;
510
511        /** Update a custom GpuProgramParameters constant which is derived from
512            information only this Light knows.
513        @remarks
514            This method allows a Light to map in a custom GPU program parameter
515            based on it's own data. This is represented by a GPU auto parameter
516            of ACT_LIGHT_CUSTOM, and to allow there to be more than one of these per
517            Light, the 'data' field on the auto parameter will identify
518            which parameter is being updated and on which light. The implementation
519            of this method must identify the parameter being updated, and call a 'setConstant'
520            method on the passed in GpuProgramParameters object.
521        @par
522            You do not need to override this method if you're using the standard
523            sets of data associated with the Renderable as provided by setCustomParameter
524            and getCustomParameter. By default, the implementation will map from the
525            value indexed by the 'constantEntry.data' parameter to a value previously
526            set by setCustomParameter. But custom Renderables are free to override
527            this if they want, in any case.
528        @param paramIndex
529            The index of the constant being updated
530        @param constantEntry
531            The auto constant entry from the program parameters
532        @param params
533            The parameters object which this method should call to
534            set the updated parameters.
535        */
536        virtual void _updateCustomGpuParameter(uint16 paramIndex, 
537            const GpuProgramParameters::AutoConstantEntry& constantEntry, 
538            GpuProgramParameters* params) const;
539               
540        /** Check whether a sphere is included in the lighted area of the light
541        @note
542            The function trades accuracy for efficiency. As a result you may get
543            false-positives (The function should not return any false-negatives).
544        */
545        bool isInLightRange(const Ogre::Sphere& sphere) const;
546       
547        /** Check whether a bounding box is included in the lighted     area of the light
548        @note
549            The function trades accuracy for efficiency. As a result you may get
550            false-positives (The function should not return any false-negatives).
551        */
552        bool isInLightRange(const Ogre::AxisAlignedBox& container) const;
553   
554    protected:
555        /// Internal method for synchronising with parent node (if any)
556        virtual void update(void) const;
557
558        /// @copydoc AnimableObject::getAnimableDictionaryName
559        const String& getAnimableDictionaryName(void) const;
560        /// @copydoc AnimableObject::initialiseAnimableDictionary
561        void initialiseAnimableDictionary(StringVector& vec) const;
562
563        LightTypes mLightType;
564        Vector3 mPosition;
565        ColourValue mDiffuse;
566        ColourValue mSpecular;
567
568        Vector3 mDirection;
569
570        Radian mSpotOuter;
571        Radian mSpotInner;
572        Real mSpotFalloff;
573        Real mSpotNearClip;
574        Real mRange;
575        Real mAttenuationConst;
576        Real mAttenuationLinear;
577        Real mAttenuationQuad;
578        Real mPowerScale;
579        size_t mIndexInFrame;
580        bool mOwnShadowFarDist;
581        Real mShadowFarDist;
582        Real mShadowFarDistSquared;
583       
584        Real mShadowNearClipDist;
585        Real mShadowFarClipDist;
586
587
588        mutable Vector3 mDerivedPosition;
589        mutable Vector3 mDerivedDirection;
590        // Slightly hacky but unless we separate observed light render state from main Light...
591        mutable Vector3 mDerivedCamRelativePosition;
592        mutable bool mDerivedCamRelativeDirty;
593        Camera* mCameraToBeRelativeTo;
594
595        /// Shared class-level name for Movable type.
596        static String msMovableType;
597
598        mutable PlaneBoundedVolume mNearClipVolume;
599        mutable PlaneBoundedVolumeList mFrustumClipVolumes;
600        /// Is the derived transform dirty?
601        mutable bool mDerivedTransformDirty;
602
603        /// Pointer to a custom shadow camera setup.
604        mutable ShadowCameraSetupPtr mCustomShadowCameraSetup;
605
606        typedef map<uint16, Vector4>::type CustomParameterMap;
607        /// Stores the custom parameters for the light.
608        CustomParameterMap mCustomParameters;
609    };
610
611    /** Factory object for creating Light instances. */
612    class _OgreExport LightFactory : public MovableObjectFactory
613    {
614    protected:
615        MovableObject* createInstanceImpl( const String& name, const NameValuePairList* params);
616    public:
617        LightFactory() {}
618        ~LightFactory() {}
619
620        static String FACTORY_TYPE_NAME;
621
622        const String& getType(void) const;
623        void destroyInstance(MovableObject* obj); 
624
625    };
626    /** @} */
627    /** @} */
628
629#include "OgreHeaderPrefix.h"
630
631} // namespace Ogre
632#endif // _LIGHT_H__
Note: See TracBrowser for help on using the repository browser.