source: GTP/trunk/App/Demos/Geom/OgreStuff/include/OgreRoot.h @ 1092

Revision 1092, 30.8 KB checked in by gumbau, 18 years ago (diff)

LodStrips? and LODTrees demos

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 __ROOT__
26#define __ROOT__
27
28// Precompiler options
29#include "OgrePrerequisites.h"
30
31#include "OgreSingleton.h"
32#include "OgreString.h"
33#include "OgreSceneManagerEnumerator.h"
34#include "OgreResourceGroupManager.h"
35
36#include <exception>
37
38#if OGRE_COMPILER == OGRE_COMPILER_MSVC || OGRE_COMPILER == OGRE_COMPILER_BORL
39#   define SET_TERM_HANDLER { set_terminate( &Ogre::Root::termHandler ); }
40#else
41#   define SET_TERM_HANDLER { std::set_terminate( &Ogre::Root::termHandler ); }
42#endif
43
44namespace Ogre
45{
46    typedef std::vector<RenderSystem*> RenderSystemList;
47
48    /** The root class of the Ogre system.
49        @remarks
50            The Ogre::Root class represents a starting point for the client
51            application. From here, the application can gain access to the
52            fundamentals of the system, namely the rendering systems
53            available, management of saved configurations, logging, and
54            access to other classes in the system. Acts as a hub from which
55            all other objects may be reached. An instance of Root must be
56            created before any other Ogre operations are called. Once an
57            instance has been created, the same instance is accessible
58            throughout the life of that object by using Root::getSingleton
59            (as a reference) or Root::getSingletonPtr (as a pointer).
60    */
61    class _OgreExport Root : public Singleton<Root>
62    {
63        // To allow update of active renderer if
64        // RenderSystem::initialise is used directly
65        friend class RenderSystem;
66    private:
67        RenderSystemList mRenderers;
68        RenderSystem* mActiveRenderer;
69        String mVersion;
70                String mConfigFileName;
71            bool mQueuedEnd;
72        // In case multiple render windows are created, only once are the resources loaded.
73        bool mFirstTimePostWindowInit;
74
75        // Singletons
76        LogManager* mLogManager;
77        ControllerManager* mControllerManager;
78        SceneManagerEnumerator* mSceneManagerEnum;
79        SceneManager* mCurrentSceneManager;
80        DynLibManager* mDynLibManager;
81        PlatformManager* mPlatformManager;
82        ArchiveManager* mArchiveManager;
83        MaterialManager* mMaterialManager;
84        MeshManager* mMeshManager;
85        ParticleSystemManager* mParticleManager;
86        SkeletonManager* mSkeletonManager;
87        OverlayElementFactory* mPanelFactory;
88        OverlayElementFactory* mBorderPanelFactory;
89        OverlayElementFactory* mTextAreaFactory;
90        OverlayManager* mOverlayManager;
91        FontManager* mFontManager;
92        ArchiveFactory *mZipArchiveFactory;
93        ArchiveFactory *mFileSystemArchiveFactory;
94                ResourceGroupManager* mResourceGroupManager;
95                ResourceBackgroundQueue* mResourceBackgroundQueue;
96
97        Timer* mTimer;
98        RenderWindow* mAutoWindow;
99        Profiler* mProfiler;
100        HighLevelGpuProgramManager* mHighLevelGpuProgramManager;
101                ExternalTextureSourceManager* mExternalTextureSourceManager;
102        unsigned long mCurrentFrame;
103
104        std::vector<DynLib*> mPluginLibs;
105        /** Method reads a plugins configuration file and instantiates all
106            plugins.
107            @param
108                pluginsfile The file that contains plugins information.
109                Defaults to "plugins.cfg".
110        */
111        void loadPlugins( const String& pluginsfile = "plugins.cfg" );
112                /** Shuts down all loaded plugins - allows things to be tidied up whilst
113                        all plugins are still loaded.
114                */
115                void shutdownPlugins();
116
117                /** Unloads all loaded plugins.
118        */
119        void unloadPlugins();
120
121        // Internal method for one-time tasks after first window creation
122        void oneTimePostWindowInit(void);
123
124        /** Set of registered frame listeners */
125        std::set<FrameListener*> mFrameListeners;
126
127        /** Set of frame listeners marked for removal*/
128        std::set<FrameListener*> mRemovedFrameListeners;
129
130        /** Indicates the type of event to be considered by calculateEventTime(). */
131        enum FrameEventTimeType {
132            FETT_ANY, FETT_STARTED, FETT_ENDED
133        };
134
135        /// Contains the times of recently fired events
136        std::deque<unsigned long> mEventTimes[3];
137
138        /** Internal method for calculating the average time between recently fired events.
139        @param now The current time in ms.
140        @param type The type of event to be considered.
141        */
142        Real calculateEventTime(unsigned long now, FrameEventTimeType type);
143    public:
144
145        static void termHandler();
146
147        /** Constructor
148            @param
149                pluginFileName The file that contains plugins information.
150                Defaults to "plugins.cfg".
151                */
152        Root(const String& pluginFileName = "plugins.cfg", const String& configFileName = "ogre.cfg", const String& logFileName = "Ogre.log");
153        ~Root();
154
155        /** Saves the details of the current configuration
156            @remarks
157                Stores details of the current configuration so it may be
158                restored later on.
159        */
160        void saveConfig(void);
161
162        /** Checks for saved video/sound/etc settings
163            @remarks
164                This method checks to see if there is a valid saved configuration
165                from a previous run. If there is, the state of the system will
166                be restored to that configuration.
167
168            @returns
169                If a valid configuration was found, <b>true</b> is returned.
170            @par
171                If there is no saved configuration, or if the system failed
172                with the last config settings, <b>false</b> is returned.
173        */
174        bool restoreConfig(void);
175
176        /** Displays a dialog asking the user to choose system settings.
177            @remarks
178                This method displays the default dialog allowing the user to
179                choose the renderering system, video mode etc. If there is are
180                any settings saved already, they will be restored automatically
181                before displaying the dialogue. When the user accepts a group of
182                settings, this will automatically call Root::setRenderSystem,
183                RenderSystem::setConfigOption and Root::saveConfig with the
184                user's choices. This is the easiest way to get the system
185                configured.
186            @returns
187                If the user clicked 'Ok', <b>true</b> is returned.
188            @par
189                If they clicked 'Cancel' (in which case the app should
190                strongly consider terminating), <b>false</b> is returned.
191         */
192        bool showConfigDialog(void);
193
194        /** Adds a new rendering subsystem to the list of available renderers.
195            @remarks
196                Intended for use by advanced users and plugin writers only!
197                Calling this method with a pointer to a valid RenderSystem
198                (sublcass) adds a rendering API implementation to the list of
199                available ones. Typical examples would be an OpenGL
200                implementation and a Direct3D implementation.
201            @note
202                <br>This should usually be called from the dllStartPlugin()
203                function of an extension plug-in.
204        */
205        void addRenderSystem(RenderSystem* newRend);
206
207        /** Sets the passed in SceneManager to be the one responsible for
208            the indicated type of scene.
209            @remarks
210                This method is provided for application writers and plugin
211                authors to use to attach their SceneManager subclasses to the
212                engine. See the SceneManager class for more information.
213        */
214        void setSceneManager(SceneType sType, SceneManager* sm);
215
216        /** Retrieve a list of the available render systems.
217            @remarks
218                Retrieves a pointer to the list of available renderers as a
219                list of RenderSystem subclasses. Can be used to build a
220                custom settings dialog.
221        */
222        RenderSystemList* getAvailableRenderers(void);
223
224        /** Sets the rendering subsystem to be used.
225            @remarks
226                This method indicates to OGRE which rendering system is to be
227                used (e.g. Direct3D, OpenGL etc). This is called
228                automatically by the default config dialog, and when settings
229                are restored from a previous configuraion. If used manually
230                it could be used to set the renderer from a custom settings
231                dialog. Once this has been done, the renderer can be
232                initialised using Root::initialise.
233            @par
234                This method is also called by render systems if they are
235                initialised directly.
236            @param
237                system Pointer to the render system to use.
238            @see
239                RenderSystem
240        */
241        void setRenderSystem(RenderSystem* system);
242
243        /** Retrieve a pointer to the currently selected render system.
244        */
245        RenderSystem* getRenderSystem(void);
246
247        /** Initialises the renderer.
248            @remarks
249                This method can only be called after a renderer has been
250                selected with Root::setRenderSystem, and it will initialise
251                the selected rendering system ready for use.
252            @param
253                autoCreateWindow If true, a rendering window will
254                automatically be created (saving a call to
255                RenderSystem::createRenderWindow). The window will be
256                created based on the options currently set on the render
257                system.
258            @returns
259                A pointer to the automatically created window, if
260                requested, otherwise <b>NULL</b>.
261        */
262            RenderWindow* initialise(bool autoCreateWindow, const String& windowTitle = "OGRE Render Window");
263
264        /** Gets a reference to a SceneManager object.
265            @remarks
266                The SceneManager class (and any subclasses) is a key class
267                which controls the contents of the scene, and is responsible
268                for issuing rendering commands to the RenderSystem to draw
269                it. The SceneManager is the class which an application using
270                Ogre will interact with most, since controlling the contents
271                of the scene is the most frequent action of an application.
272            @par
273                As described in the SceneManager documentation, different
274                subclasses can be specialised for rendering particular types
275                of scene e.g. landscapes or indoor enviroments.
276            @note
277                <br>This function delegates it's implementation to the
278                SceneManagerEnumerator class. This class can be customised to
279                include new SceneType entries and to create new subclasses of
280                SceneManager if they are introduced. This is done because the
281                customisation of the Root class is strongly discouraged and
282                in the future it may be locked down.
283            @param
284                sceneType A value from the SceneType enumeration. The method
285                will return a SceneManager which is most appropriate for this
286                type of scene.
287            @see
288                SceneManager, SceneManagerEnumerator
289        */
290        SceneManager* getSceneManager(SceneType sceneType);
291
292        /** Retrieves a reference to the current TextureManager.
293            @remarks
294                This performs the same function as
295                TextureManager::getSingleton, but is provided for convenience
296                particularly to scripting engines.
297            @par
298                Note that a TextureManager will NOT be available until the
299                Ogre system has been initialised by selecting a RenderSystem,
300                calling Root::initialise and a window having been created
301                (this may have been done by initialise if required). This is
302                because the exact runtime subclass which will be implementing
303                the calls will differ depending on the rendering engine
304                selected, and these typically require a window upon which to
305                base texture format decisions.
306        */
307        TextureManager* getTextureManager(void);
308
309        /** Retrieves a reference to the current MeshManager.
310            @remarks
311                This performs the same function as MeshManager::getSingleton
312                and is provided for convenience to scripting engines.
313        */
314        MeshManager* getMeshManager(void);
315
316        /** Utility function for getting a better description of an error
317            code.
318        */
319        String getErrorDescription(long errorNumber);
320
321        /** Registers a FrameListener which will be called back every frame.
322            @remarks
323                A FrameListener is a class which implements methods which
324                will be called every frame.
325            @par
326                See the FrameListener class for more details on the specifics
327                It is imperitive that the instance passed to this method is
328                not destroyed before either the rendering loop ends, or the
329                class is removed from the listening list using
330                removeFrameListener.
331            @note
332                <br>This method can only be called after Root::initialise has
333                been called.
334            @see
335                FrameListener, Root::removeFrameListener
336        */
337        void addFrameListener(FrameListener* newListener);
338
339        /** Removes a FrameListener from the list of listening classes.
340            @see
341                FrameListener, Root::addFrameListener
342        */
343        void removeFrameListener(FrameListener* oldListener);
344
345        /** Queues the end of rendering.
346            @remarks
347                This method will do nothing unless startRendering() has
348                been called, in which case before the next frame is rendered
349                the rendering loop will bail out.
350            @see
351                Root, Root::startRendering
352        */
353        void queueEndRendering(void);
354
355        /** Starts / restarts the automatic rendering cycle.
356            @remarks
357                This method begins the automatic rendering of the scene. It
358                will <b>NOT</b> return until the rendering cycle is halted.
359            @par
360                During rendering, any FrameListener classes registered using
361                addFrameListener will be called back for each frame that is
362                to be rendered, These classes can tell OGRE to halt the
363                rendering if required, which will cause this method to
364                return.
365            @note
366                <br>Users of the OGRE library do not have to use this
367                automatic rendering loop. It is there as a convenience and is
368                most useful for high frame rate applications e.g. games. For
369                applications that don't need to constantly refresh the
370                rendering targets (e.g. an editor utility), it is better to
371                manually refresh each render target only when required by
372                calling RenderTarget::update.
373            @note
374                This frees up the CPU to do other things in between
375                refreshes, since in this case frame rate is less important.
376            @note
377                This method can only be called after Root::initialise has
378                been called.
379        */
380        void startRendering(void);
381
382        /** Render one frame.
383        @remarks
384            Updates all the render targets automatically and then returns,
385            raising frame events before and after.
386        */
387        bool renderOneFrame(void);
388        /** Shuts down the system manually.
389            @remarks
390                This is normally done by Ogre automatically so don't think
391                you have to call this yourself. However this is here for
392                convenience, especially for dealing with unexpected errors or
393                for systems which need to shut down Ogre on demand.
394        */
395        void shutdown(void);
396
397        /** Adds a location to the list of searchable locations for a
398            Resource type.
399            @remarks
400                Resource files (textures, models etc) need to be loaded from
401                specific locations. By calling this method, you add another
402                                search location to the list. Locations added first are preferred
403                                over locations added later.
404            @par
405                Locations can be folders, compressed archives, even perhaps
406                remote locations. Facilities for loading from different
407                locations are provided by plugins which provide
408                implementations of the Archive class.
409                All the application user has to do is specify a 'loctype'
410                string in order to indicate the type of location, which
411                should map onto one of the provided plugins. Ogre comes
412                configured with the 'FileSystem' (folders) and 'Zip' (archive
413                compressed with the pkzip / WinZip etc utilities) types.
414            @par
415                                You can also supply the name of a resource group which should
416                                have this location applied to it. The
417                                ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME group is the
418                                default, and one resource group which will always exist. You
419                                should consider defining resource groups for your more specific
420                                resources (e.g. per level) so that you can control loading /
421                                unloading better.
422            @param
423                name The name of the location, e.g. './data' or
424                '/compressed/gamedata.zip'
425            @param
426                locType A string identifying the location type, e.g.
427                'FileSystem' (for folders), 'Zip' etc. Must map to a
428                registered plugin which deals with this type (FileSystem and
429                Zip should always be available)
430            @param
431                groupName Type of name of the resource group which this location
432                                should apply to; defaults to the General group which applies to
433                                all non-specific resources.
434                        @param
435                                recursive If the resource location has a concept of recursive
436                                directory traversal, enabling this option will mean you can load
437                                resources in subdirectories using only their unqualified name.
438                                The default is to disable this so that resources in subdirectories
439                                with the same name are still unique.
440            @see
441                Archive
442        */
443        void addResourceLocation(const String& name, const String& locType,
444                        const String& groupName = ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME,
445                        bool recursive = false);
446
447                /** Removes a resource location from the list.
448                @see addResourceLocation
449                @param name The name of the resource location as specified in addResourceLocation
450                @param groupName The name of the resource group to which this location
451                        was assigned.
452                */
453                void removeResourceLocation(const String& name,
454                        const String& groupName = ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME);
455
456        /** Generates a packed data version of the passed in ColourValue suitable for
457            use with the current RenderSystem.
458        @remarks
459            Since different render systems have different colour data formats (eg
460            RGBA for GL, ARGB for D3D) this method allows you to use 1 method for all.
461        @param colour The colour to convert
462        @param pDest Pointer to location to put the result.
463        */
464        void convertColourValue(const ColourValue& colour, uint32* pDest);
465
466        /** Retrieves a pointer to the window that was created automatically
467            @remarks
468                When Root is initialised an optional window is created. This
469                method retreives a pointer to that window.
470            @note
471                returns a null pointer when Root has not been initialised with
472                the option of creating a window.
473        */
474        RenderWindow* getAutoCreatedWindow(void);
475
476        /** @copydoc RenderSystem::createRenderWindow
477        */
478                RenderWindow* createRenderWindow(const String &name, unsigned int width, unsigned int height,
479                        bool fullScreen, const NameValuePairList *miscParams = 0) ;
480
481        /** Destroys a rendering window.
482        */
483        void detachRenderTarget( RenderTarget* pWin );
484
485        /** Destroys a named rendering window.
486        */
487        void detachRenderTarget( const String & name );
488
489        /** Retrieves a pointer to the a named render window.
490        */
491        RenderTarget * getRenderTarget(const String &name);
492
493        /** Sets whether or not the debug overlay is shown.
494        @remarks
495            The debug overlay displays frame rate stats and various other debug
496            information. You can enable it or disable it using this method.
497            Alternatively you could access the overlay directly using mSceneManager::getOverlay
498            but this is simpler.
499        void showDebugOverlay(bool show);
500        */
501
502                /** Manually load a plugin.
503                 @remarks
504                        Plugins are loaded at startup using the plugin configuration
505                        file specified when you create Root (default: plugins.cfg).
506                        This method allows you to load plugins in code.
507                @param pluginName Name of the plugin library to load
508                */
509                void loadPlugin(const String& pluginName);
510
511                /** Manually unloads a plugin.
512                 @remarks
513                        Plugins are unloaded at shutdown automatically.
514                        This method allows you to unload plugins in code, but
515                        make sure their dependencies are decoupled frist.
516                @param pluginName Name of the plugin library to unload
517                */
518                void unloadPlugin(const String& pluginName);
519
520        /** Gets a pointer to the central timer used for all OGRE timings */
521        Timer* getTimer(void);
522
523        /** Method for raising frame started events.
524        @remarks
525            This method is only for internal use when you use OGRE's inbuilt rendering
526            loop (Root::startRendering). However, if you run your own rendering loop then
527            you should call this method to ensure that FrameListener objects are notified
528            of frame events; processes like texture animation and particle systems rely on
529            this.
530        @par
531            Calling this method also increments the frame number, which is
532            important for keeping some elements of the engine up to date.
533        @note
534            This method takes an event object as a parameter, so you can specify the times
535            yourself. If you are happy for OGRE to automatically calculate the frame time
536            for you, then call the other version of this method with no parameters.
537        @param evt Event object which includes all the timing information which you have
538            calculated for yourself
539        @returns False if one or more frame listeners elected that the rendering loop should
540            be terminated, true otherwise.
541        */
542        bool _fireFrameStarted(FrameEvent& evt);
543        /** Method for raising frame ended events.
544        @remarks
545            This method is only for internal use when you use OGRE's inbuilt rendering
546            loop (Root::startRendering). However, if you run your own rendering loop then
547            you should call this method to ensure that FrameListener objects are notified
548            of frame events; processes like texture animation and particle systems rely on
549            this.
550        @note
551            This method takes an event object as a parameter, so you can specify the times
552            yourself. If you are happy for OGRE to automatically calculate the frame time
553            for you, then call the other version of this method with no parameters.
554        @param evt Event object which includes all the timing information which you have
555            calculated for yourself
556        @returns False if one or more frame listeners elected that the rendering loop should
557            be terminated, true otherwise.
558        */
559        bool _fireFrameEnded(FrameEvent& evt);
560        /** Method for raising frame started events.
561        @remarks
562            This method is only for internal use when you use OGRE's inbuilt rendering
563            loop (Root::startRendering). However, if you run your own rendering loop then
564            you should call this method to ensure that FrameListener objects are notified
565            of frame events; processes like texture animation and particle systems rely on
566            this.
567        @par
568            Calling this method also increments the frame number, which is
569            important for keeping some elements of the engine up to date.
570        @note
571            This method calculates the frame timing information for you based on the elapsed
572            time. If you want to specify elapsed times yourself you should call the other
573            version of this method which takes event details as a parameter.
574        @returns False if one or more frame listeners elected that the rendering loop should
575            be terminated, true otherwise.
576        */
577        bool _fireFrameStarted();
578        /** Method for raising frame ended events.
579        @remarks
580            This method is only for internal use when you use OGRE's inbuilt rendering
581            loop (Root::startRendering). However, if you run your own rendering loop then
582            you should call this method to ensure that FrameListener objects are notified
583            of frame events; processes like texture animation and particle systems rely on
584            this.
585        @note
586            This method calculates the frame timing information for you based on the elapsed
587            time. If you want to specify elapsed times yourself you should call the other
588            version of this method which takes event details as a parameter.
589        @returns False if one or more frame listeners elected that the rendering loop should
590            be terminated, true otherwise.
591        */
592        bool _fireFrameEnded();
593
594        /** Gets the number of the current frame. */
595        unsigned long getCurrentFrameNumber(void) const { return mCurrentFrame; }
596
597        /** Returns the scene manager currently being used to render a frame.
598        @remarks
599            This is only intended for internal use; it is only valid during the
600            rendering of a frame.
601        */
602        SceneManager* _getCurrentSceneManager(void) const { return mCurrentSceneManager; }
603        /** Sets the scene manager currently being used to render a frame.
604        @remarks
605            This is only intended for internal use.
606        */
607        void _setCurrentSceneManager(SceneManager* sm) { mCurrentSceneManager = sm; }
608
609        /** Internal method used for updating all RenderTarget objects (windows,
610            renderable textures etc) which are set to auto-update.
611        @remarks
612            You don't need to use this method if you're using Ogre's own internal
613            rendering loop (Root::startRendering). If you're running your own loop
614            you may wish to call it to update all the render targets which are
615            set to auto update (RenderTarget::setAutoUpdated). You can also update
616            individual RenderTarget instances using their own update() method.
617        */
618        void _updateAllRenderTargets(void);
619
620        /** Override standard Singleton retrieval.
621            @remarks
622                Why do we do this? Well, it's because the Singleton
623                implementation is in a .h file, which means it gets compiled
624                into anybody who includes it. This is needed for the
625                Singleton template to work, but we actually only want it
626                compiled into the implementation of the class based on the
627                Singleton, not all of them. If we don't change this, we get
628                link errors when trying to use the Singleton-based class from
629                an outside dll.
630            @par
631                This method just delegates to the template version anyway,
632                but the implementation stays in this single compilation unit,
633                preventing link errors.
634        */
635        static Root& getSingleton(void);
636        /** Override standard Singleton retrieval.
637            @remarks
638                Why do we do this? Well, it's because the Singleton
639                implementation is in a .h file, which means it gets compiled
640                into anybody who includes it. This is needed for the
641                Singleton template to work, but we actually only want it
642                compiled into the implementation of the class based on the
643                Singleton, not all of them. If we don't change this, we get
644                link errors when trying to use the Singleton-based class from
645                an outside dll.
646            @par
647                This method just delegates to the template version anyway,
648                but the implementation stays in this single compilation unit,
649                preventing link errors.
650        */
651        static Root* getSingletonPtr(void);
652
653                /** Clears the history of all event times.
654                @remarks
655                        OGRE stores a history of the last few event times in order to smooth
656                        out any inaccuracies and temporary fluctuations. However, if you
657                        pause or don't render for a little while this can cause a lurch, so
658                        if you're resuming rendering after a break, call this method to reset
659                        the stored times
660                */
661                void clearEventTimes(void);
662
663    };
664} // Namespace Ogre
665#endif
Note: See TracBrowser for help on using the repository browser.