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

Revision 1809, 36.9 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 __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        CompositorManager* mCompositorManager;     
103        unsigned long mCurrentFrame;
104                Real mFrameSmoothingTime;
105
106        std::vector<DynLib*> mPluginLibs;
107
108                typedef std::map<String, MovableObjectFactory*> MovableObjectFactoryMap;
109                MovableObjectFactoryMap mMovableObjectFactoryMap;
110                uint32 mNextMovableObjectTypeFlag;
111                // stock movable factories
112                MovableObjectFactory* mEntityFactory;
113                MovableObjectFactory* mLightFactory;
114                MovableObjectFactory* mBillboardSetFactory;
115                MovableObjectFactory* mManualObjectFactory;
116                MovableObjectFactory* mBillboardChainFactory;
117                MovableObjectFactory* mRibbonTrailFactory;
118
119                typedef std::map<String, RenderQueueInvocationSequence*> RenderQueueInvocationSequenceMap;
120                RenderQueueInvocationSequenceMap mRQSequenceMap;
121
122                /// Are we initialised yet?
123                bool mIsInitialised;
124
125        /** Method reads a plugins configuration file and instantiates all
126            plugins.
127            @param
128                pluginsfile The file that contains plugins information.
129                Defaults to "plugins.cfg".
130        */
131        void loadPlugins( const String& pluginsfile = "plugins.cfg" );
132                /** Initialise all loaded plugins - allows plugins to perform actions
133                        once the renderer is initialised.
134                */
135                void initialisePlugins();
136                /** Shuts down all loaded plugins - allows things to be tidied up whilst
137                        all plugins are still loaded.
138                */
139                void shutdownPlugins();
140
141                /** Unloads all loaded plugins.
142        */
143        void unloadPlugins();
144
145        // Internal method for one-time tasks after first window creation
146        void oneTimePostWindowInit(void);
147
148        /** Set of registered frame listeners */
149        std::set<FrameListener*> mFrameListeners;
150
151        /** Set of frame listeners marked for removal*/
152        std::set<FrameListener*> mRemovedFrameListeners;
153
154        /** Indicates the type of event to be considered by calculateEventTime(). */
155        enum FrameEventTimeType {
156            FETT_ANY, FETT_STARTED, FETT_ENDED
157        };
158
159        /// Contains the times of recently fired events
160        std::deque<unsigned long> mEventTimes[3];
161
162        /** Internal method for calculating the average time between recently fired events.
163        @param now The current time in ms.
164        @param type The type of event to be considered.
165        */
166        Real calculateEventTime(unsigned long now, FrameEventTimeType type);
167    public:
168
169        static void termHandler();
170
171        /** Constructor
172            @param
173                pluginFileName The file that contains plugins information.
174                Defaults to "plugins.cfg".
175                */
176        Root(const String& pluginFileName = "plugins.cfg", const String& configFileName = "ogre.cfg", const String& logFileName = "Ogre.log");
177        ~Root();
178
179        /** Saves the details of the current configuration
180            @remarks
181                Stores details of the current configuration so it may be
182                restored later on.
183        */
184        void saveConfig(void);
185
186        /** Checks for saved video/sound/etc settings
187            @remarks
188                This method checks to see if there is a valid saved configuration
189                from a previous run. If there is, the state of the system will
190                be restored to that configuration.
191
192            @returns
193                If a valid configuration was found, <b>true</b> is returned.
194            @par
195                If there is no saved configuration, or if the system failed
196                with the last config settings, <b>false</b> is returned.
197        */
198        bool restoreConfig(void);
199
200        /** Displays a dialog asking the user to choose system settings.
201            @remarks
202                This method displays the default dialog allowing the user to
203                choose the renderering system, video mode etc. If there is are
204                any settings saved already, they will be restored automatically
205                before displaying the dialogue. When the user accepts a group of
206                settings, this will automatically call Root::setRenderSystem,
207                RenderSystem::setConfigOption and Root::saveConfig with the
208                user's choices. This is the easiest way to get the system
209                configured.
210            @returns
211                If the user clicked 'Ok', <b>true</b> is returned.
212            @par
213                If they clicked 'Cancel' (in which case the app should
214                strongly consider terminating), <b>false</b> is returned.
215         */
216        bool showConfigDialog(void);
217
218        /** Adds a new rendering subsystem to the list of available renderers.
219            @remarks
220                Intended for use by advanced users and plugin writers only!
221                Calling this method with a pointer to a valid RenderSystem
222                (sublcass) adds a rendering API implementation to the list of
223                available ones. Typical examples would be an OpenGL
224                implementation and a Direct3D implementation.
225            @note
226                <br>This should usually be called from the dllStartPlugin()
227                function of an extension plug-in.
228        */
229        void addRenderSystem(RenderSystem* newRend);
230
231        /** Retrieve a list of the available render systems.
232            @remarks
233                Retrieves a pointer to the list of available renderers as a
234                list of RenderSystem subclasses. Can be used to build a
235                custom settings dialog.
236        */
237        RenderSystemList* getAvailableRenderers(void);
238
239        /** Retrieve a pointer to the render system by the given name
240            @param
241                name Name of the render system intend to retrieve.
242            @returns
243                A pointer to the render system, <b>NULL</b> if no found.
244        */
245        RenderSystem* getRenderSystemByName(const String& name);
246
247        /** Sets the rendering subsystem to be used.
248            @remarks
249                This method indicates to OGRE which rendering system is to be
250                used (e.g. Direct3D, OpenGL etc). This is called
251                automatically by the default config dialog, and when settings
252                are restored from a previous configuraion. If used manually
253                it could be used to set the renderer from a custom settings
254                dialog. Once this has been done, the renderer can be
255                initialised using Root::initialise.
256            @par
257                This method is also called by render systems if they are
258                initialised directly.
259            @param
260                system Pointer to the render system to use.
261            @see
262                RenderSystem
263        */
264        void setRenderSystem(RenderSystem* system);
265
266        /** Retrieve a pointer to the currently selected render system.
267        */
268        RenderSystem* getRenderSystem(void);
269
270        /** Initialises the renderer.
271            @remarks
272                This method can only be called after a renderer has been
273                selected with Root::setRenderSystem, and it will initialise
274                the selected rendering system ready for use.
275            @param
276                autoCreateWindow If true, a rendering window will
277                automatically be created (saving a call to
278                RenderSystem::createRenderWindow). The window will be
279                created based on the options currently set on the render
280                system.
281            @returns
282                A pointer to the automatically created window, if
283                requested, otherwise <b>NULL</b>.
284        */
285            RenderWindow* initialise(bool autoCreateWindow, const String& windowTitle = "OGRE Render Window");
286
287                /** Returns whether the system is initialised or not. */
288                bool isInitialised(void) const { return mIsInitialised; }
289
290                /** Register a new SceneManagerFactory, a factory object for creating instances
291                        of specific SceneManagers.
292                @remarks
293                        Plugins should call this to register as new SceneManager providers.
294                */
295                void addSceneManagerFactory(SceneManagerFactory* fact);
296
297                /** Unregister a SceneManagerFactory.
298                */
299                void removeSceneManagerFactory(SceneManagerFactory* fact);
300
301                /** Get more information about a given type of SceneManager.
302                @remarks
303                        The metadata returned tells you a few things about a given type
304                        of SceneManager, which can be created using a factory that has been
305                        registered already.
306                @param typeName The type name of the SceneManager you want to enquire on.
307                        If you don't know the typeName already, you can iterate over the
308                        metadata for all types using getMetaDataIterator.
309                */
310                const SceneManagerMetaData* getSceneManagerMetaData(const String& typeName) const;
311
312                /** Iterate over all types of SceneManager available for construction,
313                        providing some information about each one.
314                */
315                SceneManagerEnumerator::MetaDataIterator getSceneManagerMetaDataIterator(void) const;
316
317                /** Create a SceneManager instance of a given type.
318                @remarks
319                        You can use this method to create a SceneManager instance of a
320                        given specific type. You may know this type already, or you may
321                        have discovered it by looking at the results from getMetaDataIterator.
322                @note
323                        This method throws an exception if the named type is not found.
324                @param typeName String identifying a unique SceneManager type
325                @param instanceName Optional name to given the new instance that is
326                        created. If you leave this blank, an auto name will be assigned.
327                */
328                SceneManager* createSceneManager(const String& typeName,
329                        const String& instanceName = StringUtil::BLANK);
330
331                /** Create a SceneManager instance based on scene type support.
332                @remarks
333                        Creates an instance of a SceneManager which supports the scene types
334                        identified in the parameter. If more than one type of SceneManager
335                        has been registered as handling that combination of scene types,
336                        in instance of the last one registered is returned.
337                @note This method always succeeds, if a specific scene manager is not
338                        found, the default implementation is always returned.
339                @param typeMask A mask containing one or more SceneType flags
340                @param instanceName Optional name to given the new instance that is
341                        created. If you leave this blank, an auto name will be assigned.
342                */
343                SceneManager* createSceneManager(SceneTypeMask typeMask,
344                        const String& instanceName = StringUtil::BLANK);
345
346                /** Destroy an instance of a SceneManager. */
347                void destroySceneManager(SceneManager* sm);
348
349                /** Get an existing SceneManager instance that has already been created,
350                        identified by the instance name.
351                @param instanceName The name of the instance to retrieve.
352                */
353                SceneManager* getSceneManager(const String& instanceName) const;
354
355                /** Get an iterator over all the existing SceneManager instances. */
356                SceneManagerEnumerator::SceneManagerIterator getSceneManagerIterator(void);
357
358        /** Retrieves a reference to the current TextureManager.
359            @remarks
360                This performs the same function as
361                TextureManager::getSingleton, but is provided for convenience
362                particularly to scripting engines.
363            @par
364                Note that a TextureManager will NOT be available until the
365                Ogre system has been initialised by selecting a RenderSystem,
366                calling Root::initialise and a window having been created
367                (this may have been done by initialise if required). This is
368                because the exact runtime subclass which will be implementing
369                the calls will differ depending on the rendering engine
370                selected, and these typically require a window upon which to
371                base texture format decisions.
372        */
373        TextureManager* getTextureManager(void);
374
375        /** Retrieves a reference to the current MeshManager.
376            @remarks
377                This performs the same function as MeshManager::getSingleton
378                and is provided for convenience to scripting engines.
379        */
380        MeshManager* getMeshManager(void);
381
382        /** Utility function for getting a better description of an error
383            code.
384        */
385        String getErrorDescription(long errorNumber);
386
387        /** Registers a FrameListener which will be called back every frame.
388            @remarks
389                A FrameListener is a class which implements methods which
390                will be called every frame.
391            @par
392                See the FrameListener class for more details on the specifics
393                It is imperitive that the instance passed to this method is
394                not destroyed before either the rendering loop ends, or the
395                class is removed from the listening list using
396                removeFrameListener.
397            @note
398                <br>This method can only be called after Root::initialise has
399                been called.
400            @see
401                FrameListener, Root::removeFrameListener
402        */
403        void addFrameListener(FrameListener* newListener);
404
405        /** Removes a FrameListener from the list of listening classes.
406            @see
407                FrameListener, Root::addFrameListener
408        */
409        void removeFrameListener(FrameListener* oldListener);
410
411        /** Queues the end of rendering.
412            @remarks
413                This method will do nothing unless startRendering() has
414                been called, in which case before the next frame is rendered
415                the rendering loop will bail out.
416            @see
417                Root, Root::startRendering
418        */
419        void queueEndRendering(void);
420
421        /** Starts / restarts the automatic rendering cycle.
422            @remarks
423                This method begins the automatic rendering of the scene. It
424                will <b>NOT</b> return until the rendering cycle is halted.
425            @par
426                During rendering, any FrameListener classes registered using
427                addFrameListener will be called back for each frame that is
428                to be rendered, These classes can tell OGRE to halt the
429                rendering if required, which will cause this method to
430                return.
431            @note
432                <br>Users of the OGRE library do not have to use this
433                automatic rendering loop. It is there as a convenience and is
434                most useful for high frame rate applications e.g. games. For
435                applications that don't need to constantly refresh the
436                rendering targets (e.g. an editor utility), it is better to
437                manually refresh each render target only when required by
438                calling RenderTarget::update, or if you want to run your own
439                                render loop you can update all targets on demand using
440                                Root::renderOneFrame.
441            @note
442                This frees up the CPU to do other things in between
443                refreshes, since in this case frame rate is less important.
444            @note
445                This method can only be called after Root::initialise has
446                been called.
447        */
448        void startRendering(void);
449
450        /** Render one frame.
451        @remarks
452            Updates all the render targets automatically and then returns,
453            raising frame events before and after.
454        */
455        bool renderOneFrame(void);
456        /** Shuts down the system manually.
457            @remarks
458                This is normally done by Ogre automatically so don't think
459                you have to call this yourself. However this is here for
460                convenience, especially for dealing with unexpected errors or
461                for systems which need to shut down Ogre on demand.
462        */
463        void shutdown(void);
464
465        /** Adds a location to the list of searchable locations for a
466            Resource type.
467            @remarks
468                Resource files (textures, models etc) need to be loaded from
469                specific locations. By calling this method, you add another
470                                search location to the list. Locations added first are preferred
471                                over locations added later.
472            @par
473                Locations can be folders, compressed archives, even perhaps
474                remote locations. Facilities for loading from different
475                locations are provided by plugins which provide
476                implementations of the Archive class.
477                All the application user has to do is specify a 'loctype'
478                string in order to indicate the type of location, which
479                should map onto one of the provided plugins. Ogre comes
480                configured with the 'FileSystem' (folders) and 'Zip' (archive
481                compressed with the pkzip / WinZip etc utilities) types.
482            @par
483                                You can also supply the name of a resource group which should
484                                have this location applied to it. The
485                                ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME group is the
486                                default, and one resource group which will always exist. You
487                                should consider defining resource groups for your more specific
488                                resources (e.g. per level) so that you can control loading /
489                                unloading better.
490            @param
491                name The name of the location, e.g. './data' or
492                '/compressed/gamedata.zip'
493            @param
494                locType A string identifying the location type, e.g.
495                'FileSystem' (for folders), 'Zip' etc. Must map to a
496                registered plugin which deals with this type (FileSystem and
497                Zip should always be available)
498            @param
499                groupName Type of name of the resource group which this location
500                                should apply to; defaults to the General group which applies to
501                                all non-specific resources.
502                        @param
503                                recursive If the resource location has a concept of recursive
504                                directory traversal, enabling this option will mean you can load
505                                resources in subdirectories using only their unqualified name.
506                                The default is to disable this so that resources in subdirectories
507                                with the same name are still unique.
508            @see
509                Archive
510        */
511        void addResourceLocation(const String& name, const String& locType,
512                        const String& groupName = ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME,
513                        bool recursive = false);
514
515                /** Removes a resource location from the list.
516                @see addResourceLocation
517                @param name The name of the resource location as specified in addResourceLocation
518                @param groupName The name of the resource group to which this location
519                        was assigned.
520                */
521                void removeResourceLocation(const String& name,
522                        const String& groupName = ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME);
523
524        /** Generates a packed data version of the passed in ColourValue suitable for
525            use with the current RenderSystem.
526        @remarks
527            Since different render systems have different colour data formats (eg
528            RGBA for GL, ARGB for D3D) this method allows you to use 1 method for all.
529        @param colour The colour to convert
530        @param pDest Pointer to location to put the result.
531        */
532        void convertColourValue(const ColourValue& colour, uint32* pDest);
533
534        /** Retrieves a pointer to the window that was created automatically
535            @remarks
536                When Root is initialised an optional window is created. This
537                method retreives a pointer to that window.
538            @note
539                returns a null pointer when Root has not been initialised with
540                the option of creating a window.
541        */
542        RenderWindow* getAutoCreatedWindow(void);
543
544        /** @copydoc RenderSystem::createRenderWindow
545        */
546                RenderWindow* createRenderWindow(const String &name, unsigned int width, unsigned int height,
547                        bool fullScreen, const NameValuePairList *miscParams = 0) ;
548
549        /** Destroys a rendering window.
550        */
551        void detachRenderTarget( RenderTarget* pWin );
552
553        /** Destroys a named rendering window.
554        */
555        void detachRenderTarget( const String & name );
556
557        /** Retrieves a pointer to the a named render window.
558        */
559        RenderTarget * getRenderTarget(const String &name);
560
561        /** Sets whether or not the debug overlay is shown.
562        @remarks
563            The debug overlay displays frame rate stats and various other debug
564            information. You can enable it or disable it using this method.
565            Alternatively you could access the overlay directly using mSceneManager::getOverlay
566            but this is simpler.
567        void showDebugOverlay(bool show);
568        */
569
570                /** Manually load a plugin.
571                 @remarks
572                        Plugins are loaded at startup using the plugin configuration
573                        file specified when you create Root (default: plugins.cfg).
574                        This method allows you to load plugins in code.
575                @param pluginName Name of the plugin library to load
576                */
577                void loadPlugin(const String& pluginName);
578
579                /** Manually unloads a plugin.
580                 @remarks
581                        Plugins are unloaded at shutdown automatically.
582                        This method allows you to unload plugins in code, but
583                        make sure their dependencies are decoupled frist.
584                @param pluginName Name of the plugin library to unload
585                */
586                void unloadPlugin(const String& pluginName);
587
588        /** Gets a pointer to the central timer used for all OGRE timings */
589        Timer* getTimer(void);
590
591        /** Method for raising frame started events.
592        @remarks
593            This method is only for internal use when you use OGRE's inbuilt rendering
594            loop (Root::startRendering). However, if you run your own rendering loop then
595            you should call this method to ensure that FrameListener objects are notified
596            of frame events; processes like texture animation and particle systems rely on
597            this.
598        @par
599            Calling this method also increments the frame number, which is
600            important for keeping some elements of the engine up to date.
601        @note
602            This method takes an event object as a parameter, so you can specify the times
603            yourself. If you are happy for OGRE to automatically calculate the frame time
604            for you, then call the other version of this method with no parameters.
605        @param evt Event object which includes all the timing information which you have
606            calculated for yourself
607        @returns False if one or more frame listeners elected that the rendering loop should
608            be terminated, true otherwise.
609        */
610        bool _fireFrameStarted(FrameEvent& evt);
611        /** Method for raising frame ended events.
612        @remarks
613            This method is only for internal use when you use OGRE's inbuilt rendering
614            loop (Root::startRendering). However, if you run your own rendering loop then
615            you should call this method to ensure that FrameListener objects are notified
616            of frame events; processes like texture animation and particle systems rely on
617            this.
618        @note
619            This method takes an event object as a parameter, so you can specify the times
620            yourself. If you are happy for OGRE to automatically calculate the frame time
621            for you, then call the other version of this method with no parameters.
622        @param evt Event object which includes all the timing information which you have
623            calculated for yourself
624        @returns False if one or more frame listeners elected that the rendering loop should
625            be terminated, true otherwise.
626        */
627        bool _fireFrameEnded(FrameEvent& evt);
628        /** Method for raising frame started events.
629        @remarks
630            This method is only for internal use when you use OGRE's inbuilt rendering
631            loop (Root::startRendering). However, if you run your own rendering loop then
632            you should call this method to ensure that FrameListener objects are notified
633            of frame events; processes like texture animation and particle systems rely on
634            this.
635        @par
636            Calling this method also increments the frame number, which is
637            important for keeping some elements of the engine up to date.
638        @note
639            This method calculates the frame timing information for you based on the elapsed
640            time. If you want to specify elapsed times yourself you should call the other
641            version of this method which takes event details as a parameter.
642        @returns False if one or more frame listeners elected that the rendering loop should
643            be terminated, true otherwise.
644        */
645        bool _fireFrameStarted();
646        /** Method for raising frame ended events.
647        @remarks
648            This method is only for internal use when you use OGRE's inbuilt rendering
649            loop (Root::startRendering). However, if you run your own rendering loop then
650            you should call this method to ensure that FrameListener objects are notified
651            of frame events; processes like texture animation and particle systems rely on
652            this.
653        @note
654            This method calculates the frame timing information for you based on the elapsed
655            time. If you want to specify elapsed times yourself you should call the other
656            version of this method which takes event details as a parameter.
657        @returns False if one or more frame listeners elected that the rendering loop should
658            be terminated, true otherwise.
659        */
660        bool _fireFrameEnded();
661
662        /** Gets the number of the current frame. */
663        unsigned long getCurrentFrameNumber(void) const { return mCurrentFrame; }
664
665        /** Returns the scene manager currently being used to render a frame.
666        @remarks
667            This is only intended for internal use; it is only valid during the
668            rendering of a frame.
669        */
670        SceneManager* _getCurrentSceneManager(void) const { return mCurrentSceneManager; }
671        /** Sets the scene manager currently being used to render a frame.
672        @remarks
673            This is only intended for internal use.
674        */
675        void _setCurrentSceneManager(SceneManager* sm);
676
677        /** Internal method used for updating all RenderTarget objects (windows,
678            renderable textures etc) which are set to auto-update.
679        @remarks
680            You don't need to use this method if you're using Ogre's own internal
681            rendering loop (Root::startRendering). If you're running your own loop
682            you may wish to call it to update all the render targets which are
683            set to auto update (RenderTarget::setAutoUpdated). You can also update
684            individual RenderTarget instances using their own update() method.
685        */
686        void _updateAllRenderTargets(void);
687
688                /** Create a new RenderQueueInvocationSequence, useful for linking to
689                        Viewport instances to perform custom rendering.
690                @param name The name to give the new sequence
691                */
692                RenderQueueInvocationSequence* createRenderQueueInvocationSequence(
693                        const String& name);
694
695                /** Get a RenderQueueInvocationSequence.
696                @param name The name to identify the sequence
697                */
698                RenderQueueInvocationSequence* getRenderQueueInvocationSequence(
699                        const String& name);
700
701                /** Destroy a RenderQueueInvocationSequence.
702                @remarks
703                        You must ensure that no Viewports are using this sequence.
704                @param name The name to identify the sequence
705                */
706                void destroyRenderQueueInvocationSequence(
707                        const String& name);
708
709                /** Destroy all RenderQueueInvocationSequences.
710                @remarks
711                        You must ensure that no Viewports are using custom sequences.
712                @param name The name to identify the sequence
713                */
714                void destroyAllRenderQueueInvocationSequences(void);
715
716        /** Override standard Singleton retrieval.
717            @remarks
718                Why do we do this? Well, it's because the Singleton
719                implementation is in a .h file, which means it gets compiled
720                into anybody who includes it. This is needed for the
721                Singleton template to work, but we actually only want it
722                compiled into the implementation of the class based on the
723                Singleton, not all of them. If we don't change this, we get
724                link errors when trying to use the Singleton-based class from
725                an outside dll.
726            @par
727                This method just delegates to the template version anyway,
728                but the implementation stays in this single compilation unit,
729                preventing link errors.
730        */
731        static Root& getSingleton(void);
732        /** Override standard Singleton retrieval.
733            @remarks
734                Why do we do this? Well, it's because the Singleton
735                implementation is in a .h file, which means it gets compiled
736                into anybody who includes it. This is needed for the
737                Singleton template to work, but we actually only want it
738                compiled into the implementation of the class based on the
739                Singleton, not all of them. If we don't change this, we get
740                link errors when trying to use the Singleton-based class from
741                an outside dll.
742            @par
743                This method just delegates to the template version anyway,
744                but the implementation stays in this single compilation unit,
745                preventing link errors.
746        */
747        static Root* getSingletonPtr(void);
748
749                /** Clears the history of all event times.
750                @remarks
751                        OGRE stores a history of the last few event times in order to smooth
752                        out any inaccuracies and temporary fluctuations. However, if you
753                        pause or don't render for a little while this can cause a lurch, so
754                        if you're resuming rendering after a break, call this method to reset
755                        the stored times
756                */
757                void clearEventTimes(void);
758
759                /** Sets the period over which OGRE smooths out fluctuations in frame times.
760                @remarks
761                        OGRE by default gives you the raw frame time, but can optionally
762                        smooths it out over several frames, in order to reduce the
763                        noticeable effect of occasional hiccups in framerate.
764                        These smoothed values are passed back as parameters to FrameListener
765                        calls.
766                @par
767                        This method allow you to tweak the smoothing period, and is expressed
768                        in seconds. Setting it to 0 will result in completely unsmoothed
769                        frame times (the default).
770                */
771                void setFrameSmoothingPeriod(Real period) { mFrameSmoothingTime = period; }
772                /** Gets the period over which OGRE smooths out fluctuations in frame times. */
773                Real getFrameSmoothingPeriod(void) const { return mFrameSmoothingTime; }
774
775                /** Register a new MovableObjectFactory which will create new MovableObject
776                        instances of a particular type, as identified by the getType() method.
777                @remarks
778                        Plugin creators can create subclasses of MovableObjectFactory which
779                        construct custom subclasses of MovableObject for insertion in the
780                        scene. This is the primary way that plugins can make custom objects
781                        available.
782                @param fact Pointer to the factory instance
783                @param overrideExisting Set this to true to override any existing
784                        factories which are registered for the same type. You should only
785                        change this if you are very sure you know what you're doing.
786                */
787                void addMovableObjectFactory(MovableObjectFactory* fact,
788                        bool overrideExisting = false);
789                /** Removes a previously registered MovableObjectFactory.
790                @remarks
791                        All instances of objects created by this factory will be destroyed
792                        before removing the factory (by calling back the factories
793                        'destroyInstance' method). The plugin writer is responsible for actually
794                        destroying the factory.
795                */
796                void removeMovableObjectFactory(MovableObjectFactory* fact);
797                /// Checks whether a factory is registered for a given MovableObject type
798                bool hasMovableObjectFactory(const String& typeName) const;
799                /// Get a MovableObjectFactory for the given type
800                MovableObjectFactory* getMovableObjectFactory(const String& typeName);
801                /** Allocate the next MovableObject type flag.
802                @remarks
803                        This is done automatically if MovableObjectFactory::requestTypeFlags
804                        returns true; don't call this manually unless you're sure you need to.
805                */
806                uint32 _allocateNextMovableObjectTypeFlag(void);
807
808                typedef ConstMapIterator<MovableObjectFactoryMap> MovableObjectFactoryIterator;
809                /** Return an iterator over all the MovableObjectFactory instances currently
810                        registered.
811                */
812                MovableObjectFactoryIterator getMovableObjectFactoryIterator(void) const;
813    };
814} // Namespace Ogre
815#endif
Note: See TracBrowser for help on using the repository browser.