source: GTP/trunk/Lib/Geom/OgreStuff/include/OgreControllerManager.h @ 1809

Revision 1809, 13.1 KB checked in by gumbau, 18 years ago (diff)
RevLine 
[1809]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 __ControllerManager_H__
26#define __ControllerManager_H__
27
28#include "OgrePrerequisites.h"
29
30#include "OgreCommon.h"
31#include "OgreSingleton.h"
32#include "OgreController.h"
33#include "OgrePredefinedControllers.h"
34#include "OgreTextureUnitState.h"
35#include "OgreSharedPtr.h"
36
37namespace Ogre {
38
39    typedef SharedPtr< ControllerValue<Real> > ControllerValueRealPtr;
40    typedef SharedPtr< ControllerFunction<Real> > ControllerFunctionRealPtr;
41
42    /** Class for managing Controller instances.
43        @remarks
44            This class is responsible to keeping tabs on all the Controller instances registered
45            and updating them when requested. It also provides a number of convenience methods
46            for creating commonly used controllers (such as texture animators).
47    */
48    class _OgreExport ControllerManager : public Singleton<ControllerManager>
49    {
50    protected:
51        typedef std::set<Controller<Real>*> ControllerList;
52        ControllerList mControllers;
53
54        /// Global predefined controller
55        ControllerValueRealPtr mFrameTimeController;
56       
57                /// Global predefined controller
58                ControllerFunctionRealPtr mPassthroughFunction;
59
60                // Last frame number updated
61        unsigned long mLastFrameNumber;
62
63    public:
64        ControllerManager();
65        ~ControllerManager();
66
67        /** Creates a new controller and registers it with the manager.
68        */
69        Controller<Real>* createController(const ControllerValueRealPtr& src,
70            const ControllerValueRealPtr& dest, const ControllerFunctionRealPtr& func);
71
72        /** Creates a new controller use frame time source and passthrough controller function.
73        */
74        Controller<Real>* createFrameTimePassthroughController(
75            const ControllerValueRealPtr& dest);
76
77        /** Destroys all the controllers in existence.
78        */
79        void clearControllers(void);
80
81        /** Updates all the registered controllers.
82        */
83        void updateAllControllers(void);
84
85
86        /** Returns a ControllerValue which provides the time since the last frame as a control value source.
87            @remarks
88                A common source value to use to feed into a controller is the time since the last frame. This method
89                returns a pointer to a common source value which provides this information.
90            @par
91                Remember the value will only be up to date after the RenderSystem::beginFrame method is called.
92            @see
93                RenderSystem::beginFrame
94        */
95        const ControllerValueRealPtr& getFrameTimeSource(void) const;
96
97                /** Retrieve a simple passthrough controller function. */
98                const ControllerFunctionRealPtr& getPassthroughControllerFunction(void) const;
99
100        /** Creates a texture layer animator controller.
101            @remarks
102                This helper method creates the Controller, ControllerValue and ControllerFunction classes required
103                to animate a texture.
104            @param
105                layer TextureUnitState object to animate
106            @param
107                sequenceTime The amount of time in seconds it will take to loop through all the frames.
108        */
109        Controller<Real>* createTextureAnimator(TextureUnitState* layer, Real sequenceTime);
110
111                /** Creates a basic time-based texture uv coordinate modifier designed for creating scrolling textures.
112            @remarks
113                This simple method allows you to easily create constant-speed uv scrolling textures. If you want to
114                                specify different speed values for horizontal and vertical scroll, use the specific methods
115                                ControllerManager::createTextureUScroller and ControllerManager::createTextureVScroller.
116                                If you want more control, look up the ControllerManager::createTextureWaveTransformer
117                                for more complex wave-based scrollers / stretchers / rotaters.
118            @param
119                layer The texture layer to animate.
120            @param
121                speed Speed of horizontal (u-coord) and vertical (v-coord) scroll, in complete wraps per second
122        */
123        Controller<Real>* createTextureUVScroller(TextureUnitState* layer, Real speed);
124
125        /** Creates a basic time-based texture u coordinate modifier designed for creating scrolling textures.
126            @remarks
127                This simple method allows you to easily create constant-speed u scrolling textures. If you want more
128                control, look up the ControllerManager::createTextureWaveTransformer for more complex wave-based
129                scrollers / stretchers / rotaters.
130            @param
131                layer The texture layer to animate.
132            @param
133                uSpeed Speed of horizontal (u-coord) scroll, in complete wraps per second
134        */
135        Controller<Real>* createTextureUScroller(TextureUnitState* layer, Real uSpeed);
136
137                /** Creates a basic time-based texture v coordinate modifier designed for creating scrolling textures.
138            @remarks
139                This simple method allows you to easily create constant-speed v scrolling textures. If you want more
140                control, look up the ControllerManager::createTextureWaveTransformer for more complex wave-based
141                scrollers / stretchers / rotaters.
142            @param
143                layer The texture layer to animate.           
144            @param
145                vSpeed Speed of vertical (v-coord) scroll, in complete wraps per second
146        */
147        Controller<Real>* createTextureVScroller(TextureUnitState* layer, Real vSpeed);
148
149        /** Creates a basic time-based texture coordinate modifier designed for creating rotating textures.
150            @return
151                This simple method allows you to easily create constant-speed rotating textures. If you want more
152                control, look up the ControllerManager::createTextureWaveTransformer for more complex wave-based
153                scrollers / stretchers / rotaters.
154            @param
155                layer The texture layer to rotate.
156            @param
157                vSpeed Speed of rotation, in complete anticlockwise revolutions per second
158        */
159        Controller<Real>* createTextureRotater(TextureUnitState* layer, Real speed);
160
161        /** Creates a very flexible time-based texture transformation which can alter the scale, position or
162            rotation of a texture based on a wave function.
163            @param
164                layer The texture layer to affect
165            @param
166                ttype The type of transform, either translate (scroll), scale (stretch) or rotate (spin)
167            @param
168                waveType The shape of the wave, see WaveformType enum for details
169            @param
170                base The base value of the output
171            @param
172                frequency The speed of the wave in cycles per second
173            @param
174                phase The offset of the start of the wave, e.g. 0.5 to start half-way through the wave
175            @param
176                amplitude Scales the output so that instead of lying within 0..1 it lies within 0..1*amplitude for exaggerated effects
177        */
178        Controller<Real>* createTextureWaveTransformer(TextureUnitState* layer, TextureUnitState::TextureTransformType ttype,
179            WaveformType waveType, Real base = 0, Real frequency = 1, Real phase = 0, Real amplitude = 1);
180
181        /** Creates a controller for passing a frame time value through to a vertex / fragment program parameter.
182        @remarks
183            The destination parameter is expected to be a float, and the '.x' attribute will be populated
184            with the appropriately scaled time value.
185        @param params The parameters to update
186        @param paramIndex The index of the parameter to update; if you want a named parameter, then
187            retrieve the index beforehand using GpuProgramParameters::getParamIndex
188        @param factor The factor by which to adjust the time elapsed by before passing it to the program
189        */
190        Controller<Real>* createGpuProgramTimerParam(GpuProgramParameters* params, size_t paramIndex,
191            Real timeFactor = 1.0f);
192
193        /** Removes & destroys the controller passed in as a pointer.
194        */
195        void destroyController(Controller<Real>* controller);
196
197                /** Return relative speed of time as perceived by time based controllers.
198        @remarks
199            See setTimeFactor for full information on the meaning of this value.
200                */
201                Real getTimeFactor(void) const;
202
203                /** Set the relative speed to update frame time based controllers.
204        @remarks
205            Normally any controllers which use time as an input (FrameTimeController) are updated
206            automatically in line with the real passage of time. This method allows you to change
207            that, so that controllers are told that the time is passing slower or faster than it
208            actually is. Use this to globally speed up / slow down the effect of time-based controllers.
209        @param tf The virtual speed of time (1.0 is real time).
210                */
211                void setTimeFactor(Real tf);
212
213                /** Gets the constant that is added to time lapsed between each frame.
214                @remarks
215                        See setFrameDelay for full information on the meaning of this value.
216                */
217                Real getFrameDelay(void) const;
218
219                /** Sets a constant frame rate.
220                @remarks
221                        This function is useful when rendering a sequence to
222                        files that should create a film clip with constant frame
223                        rate.
224                        It will ensure that scrolling textures and animations
225                        move at a constant frame rate.
226                @param fd The delay in seconds wanted between each frame
227                        (1.0f / 25.0f means a seconds worth of animation is done
228                        in 25 frames).
229                */
230                void setFrameDelay(Real fd);
231
232                /** Return the elapsed time.
233        @remarks
234            See setElapsedTime for full information on the meaning of this value.
235        */
236        Real getElapsedTime(void) const;
237
238        /** Set the elapsed time.
239        @remarks
240            Normally elapsed time accumulated all frames time (which speed relative to time
241            factor) since the rendering loop started. This method allows your to change that to
242            special time, so some elapsed-time-based globally effect is repeatable.
243        @param elapsedTime The new elapsed time
244        */
245        void setElapsedTime(Real elapsedTime);
246
247        /** Override standard Singleton retrieval.
248        @remarks
249        Why do we do this? Well, it's because the Singleton
250        implementation is in a .h file, which means it gets compiled
251        into anybody who includes it. This is needed for the
252        Singleton template to work, but we actually only want it
253        compiled into the implementation of the class based on the
254        Singleton, not all of them. If we don't change this, we get
255        link errors when trying to use the Singleton-based class from
256        an outside dll.
257        @par
258        This method just delegates to the template version anyway,
259        but the implementation stays in this single compilation unit,
260        preventing link errors.
261        */
262        static ControllerManager& getSingleton(void);
263        /** Override standard Singleton retrieval.
264        @remarks
265        Why do we do this? Well, it's because the Singleton
266        implementation is in a .h file, which means it gets compiled
267        into anybody who includes it. This is needed for the
268        Singleton template to work, but we actually only want it
269        compiled into the implementation of the class based on the
270        Singleton, not all of them. If we don't change this, we get
271        link errors when trying to use the Singleton-based class from
272        an outside dll.
273        @par
274        This method just delegates to the template version anyway,
275        but the implementation stays in this single compilation unit,
276        preventing link errors.
277        */
278        static ControllerManager* getSingletonPtr(void);
279    };
280
281
282}
283#endif
Note: See TracBrowser for help on using the repository browser.