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

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

adding ogre 1.2 and dependencies

Line 
1/*
2-----------------------------------------------------------------------------
3This source file is part of OGRE
4    (Object-oriented Graphics Rendering Engine)
5For the latest info, see http://www.ogre3d.org/
6
7Copyright (c) 2000-2005 The OGRE Team
8Also see acknowledgements in Readme.html
9
10This program is free software; you can redistribute it and/or modify it under
11the terms of the GNU Lesser General Public License as published by the Free Software
12Foundation; either version 2 of the License, or (at your option) any later
13version.
14
15This program is distributed in the hope that it will be useful, but WITHOUT
16ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
18
19You should have received a copy of the GNU Lesser General Public License along with
20this program; if not, write to the Free Software Foundation, Inc., 59 Temple
21Place - Suite 330, Boston, MA 02111-1307, USA, or go to
22http://www.gnu.org/copyleft/lesser.txt.
23-----------------------------------------------------------------------------
24*/
25#ifndef __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.
439            @note
440                This frees up the CPU to do other things in between
441                refreshes, since in this case frame rate is less important.
442            @note
443                This method can only be called after Root::initialise has
444                been called.
445        */
446        void startRendering(void);
447
448        /** Render one frame.
449        @remarks
450            Updates all the render targets automatically and then returns,
451            raising frame events before and after.
452        */
453        bool renderOneFrame(void);
454        /** Shuts down the system manually.
455            @remarks
456                This is normally done by Ogre automatically so don't think
457                you have to call this yourself. However this is here for
458                convenience, especially for dealing with unexpected errors or
459                for systems which need to shut down Ogre on demand.
460        */
461        void shutdown(void);
462
463        /** Adds a location to the list of searchable locations for a
464            Resource type.
465            @remarks
466                Resource files (textures, models etc) need to be loaded from
467                specific locations. By calling this method, you add another
468                                search location to the list. Locations added first are preferred
469                                over locations added later.
470            @par
471                Locations can be folders, compressed archives, even perhaps
472                remote locations. Facilities for loading from different
473                locations are provided by plugins which provide
474                implementations of the Archive class.
475                All the application user has to do is specify a 'loctype'
476                string in order to indicate the type of location, which
477                should map onto one of the provided plugins. Ogre comes
478                configured with the 'FileSystem' (folders) and 'Zip' (archive
479                compressed with the pkzip / WinZip etc utilities) types.
480            @par
481                                You can also supply the name of a resource group which should
482                                have this location applied to it. The
483                                ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME group is the
484                                default, and one resource group which will always exist. You
485                                should consider defining resource groups for your more specific
486                                resources (e.g. per level) so that you can control loading /
487                                unloading better.
488            @param
489                name The name of the location, e.g. './data' or
490                '/compressed/gamedata.zip'
491            @param
492                locType A string identifying the location type, e.g.
493                'FileSystem' (for folders), 'Zip' etc. Must map to a
494                registered plugin which deals with this type (FileSystem and
495                Zip should always be available)
496            @param
497                groupName Type of name of the resource group which this location
498                                should apply to; defaults to the General group which applies to
499                                all non-specific resources.
500                        @param
501                                recursive If the resource location has a concept of recursive
502                                directory traversal, enabling this option will mean you can load
503                                resources in subdirectories using only their unqualified name.
504                                The default is to disable this so that resources in subdirectories
505                                with the same name are still unique.
506            @see
507                Archive
508        */
509        void addResourceLocation(const String& name, const String& locType,
510                        const String& groupName = ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME,
511                        bool recursive = false);
512
513                /** Removes a resource location from the list.
514                @see addResourceLocation
515                @param name The name of the resource location as specified in addResourceLocation
516                @param groupName The name of the resource group to which this location
517                        was assigned.
518                */
519                void removeResourceLocation(const String& name,
520                        const String& groupName = ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME);
521
522        /** Generates a packed data version of the passed in ColourValue suitable for
523            use with the current RenderSystem.
524        @remarks
525            Since different render systems have different colour data formats (eg
526            RGBA for GL, ARGB for D3D) this method allows you to use 1 method for all.
527        @param colour The colour to convert
528        @param pDest Pointer to location to put the result.
529        */
530        void convertColourValue(const ColourValue& colour, uint32* pDest);
531
532        /** Retrieves a pointer to the window that was created automatically
533            @remarks
534                When Root is initialised an optional window is created. This
535                method retreives a pointer to that window.
536            @note
537                returns a null pointer when Root has not been initialised with
538                the option of creating a window.
539        */
540        RenderWindow* getAutoCreatedWindow(void);
541
542        /** @copydoc RenderSystem::createRenderWindow
543        */
544                RenderWindow* createRenderWindow(const String &name, unsigned int width, unsigned int height,
545                        bool fullScreen, const NameValuePairList *miscParams = 0) ;
546
547        /** Destroys a rendering window.
548        */
549        void detachRenderTarget( RenderTarget* pWin );
550
551        /** Destroys a named rendering window.
552        */
553        void detachRenderTarget( const String & name );
554
555        /** Retrieves a pointer to the a named render window.
556        */
557        RenderTarget * getRenderTarget(const String &name);
558
559        /** Sets whether or not the debug overlay is shown.
560        @remarks
561            The debug overlay displays frame rate stats and various other debug
562            information. You can enable it or disable it using this method.
563            Alternatively you could access the overlay directly using mSceneManager::getOverlay
564            but this is simpler.
565        void showDebugOverlay(bool show);
566        */
567
568                /** Manually load a plugin.
569                 @remarks
570                        Plugins are loaded at startup using the plugin configuration
571                        file specified when you create Root (default: plugins.cfg).
572                        This method allows you to load plugins in code.
573                @param pluginName Name of the plugin library to load
574                */
575                void loadPlugin(const String& pluginName);
576
577                /** Manually unloads a plugin.
578                 @remarks
579                        Plugins are unloaded at shutdown automatically.
580                        This method allows you to unload plugins in code, but
581                        make sure their dependencies are decoupled frist.
582                @param pluginName Name of the plugin library to unload
583                */
584                void unloadPlugin(const String& pluginName);
585
586        /** Gets a pointer to the central timer used for all OGRE timings */
587        Timer* getTimer(void);
588
589        /** Method for raising frame started events.
590        @remarks
591            This method is only for internal use when you use OGRE's inbuilt rendering
592            loop (Root::startRendering). However, if you run your own rendering loop then
593            you should call this method to ensure that FrameListener objects are notified
594            of frame events; processes like texture animation and particle systems rely on
595            this.
596        @par
597            Calling this method also increments the frame number, which is
598            important for keeping some elements of the engine up to date.
599        @note
600            This method takes an event object as a parameter, so you can specify the times
601            yourself. If you are happy for OGRE to automatically calculate the frame time
602            for you, then call the other version of this method with no parameters.
603        @param evt Event object which includes all the timing information which you have
604            calculated for yourself
605        @returns False if one or more frame listeners elected that the rendering loop should
606            be terminated, true otherwise.
607        */
608        bool _fireFrameStarted(FrameEvent& evt);
609        /** Method for raising frame ended events.
610        @remarks
611            This method is only for internal use when you use OGRE's inbuilt rendering
612            loop (Root::startRendering). However, if you run your own rendering loop then
613            you should call this method to ensure that FrameListener objects are notified
614            of frame events; processes like texture animation and particle systems rely on
615            this.
616        @note
617            This method takes an event object as a parameter, so you can specify the times
618            yourself. If you are happy for OGRE to automatically calculate the frame time
619            for you, then call the other version of this method with no parameters.
620        @param evt Event object which includes all the timing information which you have
621            calculated for yourself
622        @returns False if one or more frame listeners elected that the rendering loop should
623            be terminated, true otherwise.
624        */
625        bool _fireFrameEnded(FrameEvent& evt);
626        /** Method for raising frame started events.
627        @remarks
628            This method is only for internal use when you use OGRE's inbuilt rendering
629            loop (Root::startRendering). However, if you run your own rendering loop then
630            you should call this method to ensure that FrameListener objects are notified
631            of frame events; processes like texture animation and particle systems rely on
632            this.
633        @par
634            Calling this method also increments the frame number, which is
635            important for keeping some elements of the engine up to date.
636        @note
637            This method calculates the frame timing information for you based on the elapsed
638            time. If you want to specify elapsed times yourself you should call the other
639            version of this method which takes event details as a parameter.
640        @returns False if one or more frame listeners elected that the rendering loop should
641            be terminated, true otherwise.
642        */
643        bool _fireFrameStarted();
644        /** Method for raising frame ended events.
645        @remarks
646            This method is only for internal use when you use OGRE's inbuilt rendering
647            loop (Root::startRendering). However, if you run your own rendering loop then
648            you should call this method to ensure that FrameListener objects are notified
649            of frame events; processes like texture animation and particle systems rely on
650            this.
651        @note
652            This method calculates the frame timing information for you based on the elapsed
653            time. If you want to specify elapsed times yourself you should call the other
654            version of this method which takes event details as a parameter.
655        @returns False if one or more frame listeners elected that the rendering loop should
656            be terminated, true otherwise.
657        */
658        bool _fireFrameEnded();
659
660        /** Gets the number of the current frame. */
661        unsigned long getCurrentFrameNumber(void) const { return mCurrentFrame; }
662
663        /** Returns the scene manager currently being used to render a frame.
664        @remarks
665            This is only intended for internal use; it is only valid during the
666            rendering of a frame.
667        */
668        SceneManager* _getCurrentSceneManager(void) const { return mCurrentSceneManager; }
669        /** Sets the scene manager currently being used to render a frame.
670        @remarks
671            This is only intended for internal use.
672        */
673        void _setCurrentSceneManager(SceneManager* sm);
674
675        /** Internal method used for updating all RenderTarget objects (windows,
676            renderable textures etc) which are set to auto-update.
677        @remarks
678            You don't need to use this method if you're using Ogre's own internal
679            rendering loop (Root::startRendering). If you're running your own loop
680            you may wish to call it to update all the render targets which are
681            set to auto update (RenderTarget::setAutoUpdated). You can also update
682            individual RenderTarget instances using their own update() method.
683        */
684        void _updateAllRenderTargets(void);
685
686                /** Create a new RenderQueueInvocationSequence, useful for linking to
687                        Viewport instances to perform custom rendering.
688                @param name The name to give the new sequence
689                */
690                RenderQueueInvocationSequence* createRenderQueueInvocationSequence(
691                        const String& name);
692
693                /** Get a RenderQueueInvocationSequence.
694                @param name The name to identify the sequence
695                */
696                RenderQueueInvocationSequence* getRenderQueueInvocationSequence(
697                        const String& name);
698
699                /** Destroy a RenderQueueInvocationSequence.
700                @remarks
701                        You must ensure that no Viewports are using this sequence.
702                @param name The name to identify the sequence
703                */
704                void destroyRenderQueueInvocationSequence(
705                        const String& name);
706
707                /** Destroy all RenderQueueInvocationSequences.
708                @remarks
709                        You must ensure that no Viewports are using custom sequences.
710                @param name The name to identify the sequence
711                */
712                void destroyAllRenderQueueInvocationSequences(void);
713
714        /** Override standard Singleton retrieval.
715            @remarks
716                Why do we do this? Well, it's because the Singleton
717                implementation is in a .h file, which means it gets compiled
718                into anybody who includes it. This is needed for the
719                Singleton template to work, but we actually only want it
720                compiled into the implementation of the class based on the
721                Singleton, not all of them. If we don't change this, we get
722                link errors when trying to use the Singleton-based class from
723                an outside dll.
724            @par
725                This method just delegates to the template version anyway,
726                but the implementation stays in this single compilation unit,
727                preventing link errors.
728        */
729        static Root& getSingleton(void);
730        /** Override standard Singleton retrieval.
731            @remarks
732                Why do we do this? Well, it's because the Singleton
733                implementation is in a .h file, which means it gets compiled
734                into anybody who includes it. This is needed for the
735                Singleton template to work, but we actually only want it
736                compiled into the implementation of the class based on the
737                Singleton, not all of them. If we don't change this, we get
738                link errors when trying to use the Singleton-based class from
739                an outside dll.
740            @par
741                This method just delegates to the template version anyway,
742                but the implementation stays in this single compilation unit,
743                preventing link errors.
744        */
745        static Root* getSingletonPtr(void);
746
747                /** Clears the history of all event times.
748                @remarks
749                        OGRE stores a history of the last few event times in order to smooth
750                        out any inaccuracies and temporary fluctuations. However, if you
751                        pause or don't render for a little while this can cause a lurch, so
752                        if you're resuming rendering after a break, call this method to reset
753                        the stored times
754                */
755                void clearEventTimes(void);
756
757                /** Sets the period over which OGRE smooths out fluctuations in frame times.
758                @remarks
759                        OGRE by default gives you the raw frame time, but can optionally
760                        smooths it out over several frames, in order to reduce the
761                        noticeable effect of occasional hiccups in framerate.
762                        These smoothed values are passed back as parameters to FrameListener
763                        calls.
764                @par
765                        This method allow you to tweak the smoothing period, and is expressed
766                        in seconds. Setting it to 0 will result in completely unsmoothed
767                        frame times (the default).
768                */
769                void setFrameSmoothingPeriod(Real period) { mFrameSmoothingTime = period; }
770                /** Gets the period over which OGRE smooths out fluctuations in frame times. */
771                Real getFrameSmoothingPeriod(void) const { return mFrameSmoothingTime; }
772
773                /** Register a new MovableObjectFactory which will create new MovableObject
774                        instances of a particular type, as identified by the getType() method.
775                @remarks
776                        Plugin creators can create subclasses of MovableObjectFactory which
777                        construct custom subclasses of MovableObject for insertion in the
778                        scene. This is the primary way that plugins can make custom objects
779                        available.
780                @param fact Pointer to the factory instance
781                @param overrideExisting Set this to true to override any existing
782                        factories which are registered for the same type. You should only
783                        change this if you are very sure you know what you're doing.
784                */
785                void addMovableObjectFactory(MovableObjectFactory* fact,
786                        bool overrideExisting = false);
787                /** Removes a previously registered MovableObjectFactory.
788                @remarks
789                        All instances of objects created by this factory will be destroyed
790                        before removing the factory (by calling back the factories
791                        'destroyInstance' method). The plugin writer is responsible for actually
792                        destroying the factory.
793                */
794                void removeMovableObjectFactory(MovableObjectFactory* fact);
795                /// Checks whether a factory is registered for a given MovableObject type
796                bool hasMovableObjectFactory(const String& typeName) const;
797                /// Get a MovableObjectFactory for the given type
798                MovableObjectFactory* getMovableObjectFactory(const String& typeName);
799                /** Allocate the next MovableObject type flag.
800                @remarks
801                        This is done automatically if MovableObjectFactory::requestTypeFlags
802                        returns true; don't call this manually unless you're sure you need to.
803                */
804                uint32 _allocateNextMovableObjectTypeFlag(void);
805
806                typedef ConstMapIterator<MovableObjectFactoryMap> MovableObjectFactoryIterator;
807                /** Return an iterator over all the MovableObjectFactory instances currently
808                        registered.
809                */
810                MovableObjectFactoryIterator getMovableObjectFactoryIterator(void) const;
811    };
812} // Namespace Ogre
813#endif
Note: See TracBrowser for help on using the repository browser.