Ogre::Root Class Reference

The root class of the Ogre system. More...

#include <OgreRoot.h>

Inheritance diagram for Ogre::Root:

List of all members.

Public Types

typedef ConstMapIterator<
MovableObjectFactoryMap > MovableObjectFactoryIterator

Public Member Functions

Root (const String &pluginFileName="plugins.cfg", const String &configFileName="ogre.cfg", const String &logFileName="Ogre.log")

Constructor.

~Root ()

void saveConfig (void)

Saves the details of the current configuration.

bool restoreConfig (void)

Checks for saved video/sound/etc settings.

bool showConfigDialog (void)

Displays a dialog asking the user to choose system settings.

void addRenderSystem (RenderSystem *newRend)

Adds a new rendering subsystem to the list of available renderers.

RenderSystemList * getAvailableRenderers (void)

Retrieve a list of the available render systems.

RenderSystem * getRenderSystemByName (const String &name)

Retrieve a pointer to the render system by the given name.

void setRenderSystem (RenderSystem *system)

Sets the rendering subsystem to be used.

RenderSystem * getRenderSystem (void)

Retrieve a pointer to the currently selected render system.

RenderWindow * initialise (bool autoCreateWindow, const String &windowTitle="OGRE Render Window")

Initialises the renderer.

bool isInitialised (void) const

Returns whether the system is initialised or not.

void addSceneManagerFactory (SceneManagerFactory *fact)

void removeSceneManagerFactory (SceneManagerFactory *fact)

Unregister a SceneManagerFactory.

const SceneManagerMetaData * getSceneManagerMetaData (const String &typeName) const

Get more information about a given type of SceneManager.

SceneManagerEnumerator::MetaDataIterator getSceneManagerMetaDataIterator (void) const

Iterate over all types of SceneManager available for construction, providing some information about each one.

SceneManager * createSceneManager (const String &typeName, const String &instanceName=StringUtil::BLANK)

Create a SceneManager instance of a given type.

SceneManager * createSceneManager (SceneTypeMask typeMask, const String &instanceName=StringUtil::BLANK)

Create a SceneManager instance based on scene type support.

void destroySceneManager (SceneManager *sm)

Destroy an instance of a SceneManager.

SceneManager * getSceneManager (const String &instanceName) const

Get an existing SceneManager instance that has already been created, identified by the instance name.

SceneManagerEnumerator::SceneManagerIterator getSceneManagerIterator (void)

Get an iterator over all the existing SceneManager instances.

TextureManager * getTextureManager (void)

Retrieves a reference to the current TextureManager.

MeshManager * getMeshManager (void)

Retrieves a reference to the current MeshManager.

String getErrorDescription (long errorNumber)

Utility function for getting a better description of an error code.

void addFrameListener (FrameListener *newListener)

Registers a FrameListener which will be called back every frame.

void removeFrameListener (FrameListener *oldListener)

Removes a FrameListener from the list of listening classes.

void queueEndRendering (void)

Queues the end of rendering.

void startRendering (void)

Starts / restarts the automatic rendering cycle.

bool renderOneFrame (void)

Render one frame.

void shutdown (void)

Shuts down the system manually.

void addResourceLocation (const String &name, const String &locType, const String &groupName=ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME, bool recursive=false)

Adds a location to the list of searchable locations for a Resource type.

void removeResourceLocation (const String &name, const String &groupName=ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME)

Removes a resource location from the list.

void convertColourValue (const ColourValue &colour, uint32 *pDest)

Generates a packed data version of the passed in ColourValue suitable for use with the current RenderSystem.

RenderWindow * getAutoCreatedWindow (void)

Retrieves a pointer to the window that was created automatically.

RenderWindow * createRenderWindow (const String &name, unsigned int width, unsigned int height, bool fullScreen, const NameValuePairList *miscParams=0)

Remarks:: This method creates a new rendering window as specified by the paramteters. The rendering system could be responible for only a single window (e.g. in the case of a game), or could be in charge of multiple ones (in the case of a level editor). The option to create the window as a child of another is therefore given. This method will create an appropriate subclass of RenderWindow depending on the API and platform implementation.

: After creation, this window can be retrieved using getRenderTarget().

Parameters:

name	The name of the window. Used in other methods later like setRenderTarget and getRenderWindow.
width	The width of the new window.
height	The height of the new window.
fullScreen	Specify true to make the window full screen without borders, title bar or menu bar.
miscParams	A NameValuePairList describing the other parameters for the new rendering window. Options are case sensitive. Unrecognised parameters will be ignored silently. These values might be platform dependent, but these are present for all platorms unless indicated otherwise:

Key: "title" Description: The title of the window that will appear in the title bar Values: string Default: RenderTarget name

Key: "colourDepth" Description: Colour depth of the resulting rendering window; only applies if fullScreen is set. Values: 16 or 32 Default: desktop depth Notes: [W32 specific]

Key: "left" Description: screen x coordinate from left Values: positive integers Default: 'center window on screen' Notes: Ignored in case of full screen

Key: "top" Description: screen y coordinate from top Values: positive integers Default: 'center window on screen' Notes: Ignored in case of full screen

Key: "depthBuffer" [DX9 specific] Description: Use depth buffer Values: false or true Default: true

Key: "externalWindowHandle" [API specific] Description: External window handle, for embedding the OGRE context Values: positive integer for W32 (HWND handle) poslong:posint:poslong (display*:screen:windowHandle) or poslong:posint:poslong:poslong (display*:screen:windowHandle:XVisualInfo*) for GLX Default: 0 (None)

Key: "parentWindowHandle" [API specific] Description: Parent window handle, for embedding the OGRE context Values: positive integer for W32 (HWND handle) poslong:posint:poslong for GLX (display*:screen:windowHandle) Default: 0 (None)

Key: "FSAA" Description: Full screen antialiasing factor Values: 0,2,4,6,... Default: 0

Key: "displayFrequency" Description: Display frequency rate, for fullscreen mode Values: 60...? Default: Desktop vsync rate

Key: "vsync" Description: Synchronize buffer swaps to vsync Values: true, false Default: 0

Key: "border" Description: The type of window border (in windowed mode) Values: none, fixed, resize Default: resize

Key: "outerDimensions" Description: Whether the width/height is expressed as the size of the outer window, rather than the content area Values: true, false Default: false

Key: "useNVPerfHUD" [DX9 specific] Description: Enable the use of nVidia NVPerfHUD Values: true, false Default: false

void detachRenderTarget (RenderTarget *pWin)

Destroys a rendering window.

void detachRenderTarget (const String &name)

Destroys a named rendering window.

RenderTarget * getRenderTarget (const String &name)

Retrieves a pointer to the a named render window.

void loadPlugin (const String &pluginName)

Manually load a plugin.

void unloadPlugin (const String &pluginName)

Manually unloads a plugin.

Timer * getTimer (void)

Gets a pointer to the central timer used for all OGRE timings.

bool _fireFrameStarted (FrameEvent &evt)

Method for raising frame started events.

bool _fireFrameEnded (FrameEvent &evt)

Method for raising frame ended events.

bool _fireFrameStarted ()

Method for raising frame started events.

bool _fireFrameEnded ()

Method for raising frame ended events.

unsigned long getCurrentFrameNumber (void) const

Gets the number of the current frame.

SceneManager * _getCurrentSceneManager (void) const

Returns the scene manager currently being used to render a frame.

void _setCurrentSceneManager (SceneManager *sm)

Sets the scene manager currently being used to render a frame.

void _updateAllRenderTargets (void)

Internal method used for updating all RenderTarget objects (windows, renderable textures etc) which are set to auto-update.

RenderQueueInvocationSequence * createRenderQueueInvocationSequence (const String &name)

Create a new RenderQueueInvocationSequence, useful for linking to Viewport instances to perform custom rendering.

RenderQueueInvocationSequence * getRenderQueueInvocationSequence (const String &name)

Get a RenderQueueInvocationSequence.

void destroyRenderQueueInvocationSequence (const String &name)

Destroy a RenderQueueInvocationSequence.

void destroyAllRenderQueueInvocationSequences (void)

Destroy all RenderQueueInvocationSequences.

void clearEventTimes (void)

Clears the history of all event times.

void setFrameSmoothingPeriod (Real period)

Sets the period over which OGRE smooths out fluctuations in frame times.

Real getFrameSmoothingPeriod (void) const

Gets the period over which OGRE smooths out fluctuations in frame times.

void addMovableObjectFactory (MovableObjectFactory *fact, bool overrideExisting=false)

Register a new MovableObjectFactory which will create new MovableObject instances of a particular type, as identified by the getType() method.

void removeMovableObjectFactory (MovableObjectFactory *fact)

Removes a previously registered MovableObjectFactory.

bool hasMovableObjectFactory (const String &typeName) const

Checks whether a factory is registered for a given MovableObject type.

MovableObjectFactory * getMovableObjectFactory (const String &typeName)

Get a MovableObjectFactory for the given type.

uint32 _allocateNextMovableObjectTypeFlag (void)

Allocate the next MovableObject type flag.

MovableObjectFactoryIterator getMovableObjectFactoryIterator (void) const

Return an iterator over all the MovableObjectFactory instances currently registered.

Static Public Member Functions

void termHandler ()

Root & getSingleton (void)

Override standard Singleton retrieval.

Root * getSingletonPtr (void)

Override standard Singleton retrieval.

Static Protected Attributes

Root * ms_Singleton

Private Types

typedef std::map< String,
MovableObjectFactory * > MovableObjectFactoryMap

typedef std::map< String,
RenderQueueInvocationSequence * > RenderQueueInvocationSequenceMap

enum FrameEventTimeType { FETT_ANY, FETT_STARTED, FETT_ENDED }

Indicates the type of event to be considered by calculateEventTime(). More...

Private Member Functions

void loadPlugins (const String &pluginsfile="plugins.cfg")

Method reads a plugins configuration file and instantiates all plugins.

void initialisePlugins ()

Initialise all loaded plugins - allows plugins to perform actions once the renderer is initialised.

void shutdownPlugins ()

Shuts down all loaded plugins - allows things to be tidied up whilst all plugins are still loaded.

void unloadPlugins ()

Unloads all loaded plugins.

void oneTimePostWindowInit (void)

Real calculateEventTime (unsigned long now, FrameEventTimeType type)

Internal method for calculating the average time between recently fired events.

Private Attributes

RenderSystemList

mRenderers

RenderSystem * mActiveRenderer

String

mVersion

String

mConfigFileName

bool mQueuedEnd

bool mFirstTimePostWindowInit

LogManager * mLogManager

ControllerManager * mControllerManager

SceneManagerEnumerator * mSceneManagerEnum

SceneManager * mCurrentSceneManager

DynLibManager * mDynLibManager

PlatformManager * mPlatformManager

ArchiveManager * mArchiveManager

MaterialManager * mMaterialManager

MeshManager * mMeshManager

ParticleSystemManager * mParticleManager

SkeletonManager * mSkeletonManager

OverlayElementFactory * mPanelFactory

OverlayElementFactory * mBorderPanelFactory

OverlayElementFactory * mTextAreaFactory

OverlayManager * mOverlayManager

FontManager * mFontManager

ArchiveFactory * mZipArchiveFactory

ArchiveFactory * mFileSystemArchiveFactory

ResourceGroupManager * mResourceGroupManager

ResourceBackgroundQueue * mResourceBackgroundQueue

Timer * mTimer

RenderWindow * mAutoWindow

Profiler * mProfiler

HighLevelGpuProgramManager * mHighLevelGpuProgramManager

ExternalTextureSourceManager * mExternalTextureSourceManager

CompositorManager * mCompositorManager

unsigned long mCurrentFrame

Real

mFrameSmoothingTime

std::vector< DynLib * > mPluginLibs

MovableObjectFactoryMap

mMovableObjectFactoryMap

uint32

mNextMovableObjectTypeFlag

MovableObjectFactory * mEntityFactory

MovableObjectFactory * mLightFactory

MovableObjectFactory * mBillboardSetFactory

MovableObjectFactory * mManualObjectFactory

MovableObjectFactory * mBillboardChainFactory

MovableObjectFactory * mRibbonTrailFactory

RenderQueueInvocationSequenceMap

mRQSequenceMap

bool mIsInitialised

Are we initialised yet?

std::set< FrameListener * > mFrameListeners

Set of registered frame listeners.

std::set< FrameListener * > mRemovedFrameListeners

Set of frame listeners marked for removal.

std::deque< unsigned long > mEventTimes [3]

Contains the times of recently fired events.

Friends

class RenderSystem

Detailed Description

The root class of the Ogre system.

Remarks:: The Ogre::Root class represents a starting point for the client application. From here, the application can gain access to the fundamentals of the system, namely the rendering systems available, management of saved configurations, logging, and access to other classes in the system. Acts as a hub from which all other objects may be reached. An instance of Root must be created before any other Ogre operations are called. Once an instance has been created, the same instance is accessible throughout the life of that object by using Root::getSingleton (as a reference) or Root::getSingletonPtr (as a pointer).

Definition at line 61 of file OgreRoot.h.

Member Typedef Documentation

typedef ConstMapIterator<MovableObjectFactoryMap> Ogre::Root::MovableObjectFactoryIterator

Definition at line 806 of file OgreRoot.h.

typedef std::map<String, MovableObjectFactory*> Ogre::Root::MovableObjectFactoryMap [private]

Definition at line 108 of file OgreRoot.h.

typedef std::map<String, RenderQueueInvocationSequence*> Ogre::Root::RenderQueueInvocationSequenceMap [private]

Definition at line 119 of file OgreRoot.h.

Member Enumeration Documentation

enum Ogre::Root::FrameEventTimeType [private]

Indicates the type of event to be considered by calculateEventTime().

Enumeration values:

FETT_ANY

FETT_STARTED

FETT_ENDED

Definition at line 155 of file OgreRoot.h.

Constructor & Destructor Documentation

Ogre::Root::Root ( const String & pluginFileName = "plugins.cfg",

const String & configFileName = "ogre.cfg",

const String & logFileName = "Ogre.log"

)

Constructor.

Parameters:

pluginFileName The file that contains plugins information. Defaults to "plugins.cfg".

Ogre::Root::~Root ( )

Member Function Documentation

uint32 Ogre::Root::_allocateNextMovableObjectTypeFlag ( void )

Allocate the next MovableObject type flag.

Remarks:
This is done automatically if MovableObjectFactory::requestTypeFlags returns true; don't call this manually unless you're sure you need to.

bool Ogre::Root::_fireFrameEnded ( )

Method for raising frame ended events.

Remarks:
This method is only for internal use when you use OGRE's inbuilt rendering loop (Root::startRendering). However, if you run your own rendering loop then you should call this method to ensure that FrameListener objects are notified of frame events; processes like texture animation and particle systems rely on this.

Note:
This method calculates the frame timing information for you based on the elapsed time. If you want to specify elapsed times yourself you should call the other version of this method which takes event details as a parameter.

Returns:
False if one or more frame listeners elected that the rendering loop should be terminated, true otherwise.

bool Ogre::Root::_fireFrameEnded ( FrameEvent & evt )

Method for raising frame ended events.

Remarks:
This method is only for internal use when you use OGRE's inbuilt rendering loop (Root::startRendering). However, if you run your own rendering loop then you should call this method to ensure that FrameListener objects are notified of frame events; processes like texture animation and particle systems rely on this.

Note:
This method takes an event object as a parameter, so you can specify the times yourself. If you are happy for OGRE to automatically calculate the frame time for you, then call the other version of this method with no parameters.

Parameters:

evt Event object which includes all the timing information which you have calculated for yourself

Returns:
False if one or more frame listeners elected that the rendering loop should be terminated, true otherwise.

bool Ogre::Root::_fireFrameStarted ( )

Method for raising frame started events.

Remarks:
This method is only for internal use when you use OGRE's inbuilt rendering loop (Root::startRendering). However, if you run your own rendering loop then you should call this method to ensure that FrameListener objects are notified of frame events; processes like texture animation and particle systems rely on this.

Calling this method also increments the frame number, which is important for keeping some elements of the engine up to date.

Note:
This method calculates the frame timing information for you based on the elapsed time. If you want to specify elapsed times yourself you should call the other version of this method which takes event details as a parameter.

Returns:
False if one or more frame listeners elected that the rendering loop should be terminated, true otherwise.

bool Ogre::Root::_fireFrameStarted ( FrameEvent & evt )

Method for raising frame started events.

Remarks:
This method is only for internal use when you use OGRE's inbuilt rendering loop (Root::startRendering). However, if you run your own rendering loop then you should call this method to ensure that FrameListener objects are notified of frame events; processes like texture animation and particle systems rely on this.

Calling this method also increments the frame number, which is important for keeping some elements of the engine up to date.

Note:
This method takes an event object as a parameter, so you can specify the times yourself. If you are happy for OGRE to automatically calculate the frame time for you, then call the other version of this method with no parameters.

Parameters:

evt Event object which includes all the timing information which you have calculated for yourself

Returns:
False if one or more frame listeners elected that the rendering loop should be terminated, true otherwise.

SceneManager* Ogre::Root::_getCurrentSceneManager ( void ) const

Returns the scene manager currently being used to render a frame.

Remarks:
This is only intended for internal use; it is only valid during the rendering of a frame.

Definition at line 668 of file OgreRoot.h.

void Ogre::Root::_setCurrentSceneManager ( SceneManager * sm )

Sets the scene manager currently being used to render a frame.

Remarks:
This is only intended for internal use.

void Ogre::Root::_updateAllRenderTargets ( void )

Internal method used for updating all RenderTarget objects (windows, renderable textures etc) which are set to auto-update.

Remarks:
You don't need to use this method if you're using Ogre's own internal rendering loop (Root::startRendering). If you're running your own loop you may wish to call it to update all the render targets which are set to auto update (RenderTarget::setAutoUpdated). You can also update individual RenderTarget instances using their own update() method.

void Ogre::Root::addFrameListener ( FrameListener * newListener )

Registers a FrameListener which will be called back every frame.

Remarks:
A FrameListener is a class which implements methods which will be called every frame.

See the FrameListener class for more details on the specifics It is imperitive that the instance passed to this method is not destroyed before either the rendering loop ends, or the class is removed from the listening list using removeFrameListener.

Note:

This method can only be called after Root::initialise has been called.

See also:
FrameListener, Root::removeFrameListener

void Ogre::Root::addMovableObjectFactory ( MovableObjectFactory * fact,

bool overrideExisting = false

)

Register a new MovableObjectFactory which will create new MovableObject instances of a particular type, as identified by the getType() method.

Remarks:
Plugin creators can create subclasses of MovableObjectFactory which construct custom subclasses of MovableObject for insertion in the scene. This is the primary way that plugins can make custom objects available.

Parameters:

fact Pointer to the factory instance

overrideExisting Set this to true to override any existing factories which are registered for the same type. You should only change this if you are very sure you know what you're doing.

void Ogre::Root::addRenderSystem ( RenderSystem * newRend )

Adds a new rendering subsystem to the list of available renderers.

Remarks:
Intended for use by advanced users and plugin writers only! Calling this method with a pointer to a valid RenderSystem (sublcass) adds a rendering API implementation to the list of available ones. Typical examples would be an OpenGL implementation and a Direct3D implementation.

Note:

This should usually be called from the dllStartPlugin() function of an extension plug-in.

void Ogre::Root::addResourceLocation ( const String & name,

const String & locType,

const String & groupName = ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME,

bool recursive = false

)

Adds a location to the list of searchable locations for a Resource type.

Remarks:
Resource files (textures, models etc) need to be loaded from specific locations. By calling this method, you add another search location to the list. Locations added first are preferred over locations added later.

Locations can be folders, compressed archives, even perhaps remote locations. Facilities for loading from different locations are provided by plugins which provide implementations of the Archive class. All the application user has to do is specify a 'loctype' string in order to indicate the type of location, which should map onto one of the provided plugins. Ogre comes configured with the 'FileSystem' (folders) and 'Zip' (archive compressed with the pkzip / WinZip etc utilities) types.

You can also supply the name of a resource group which should have this location applied to it. The ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME group is the default, and one resource group which will always exist. You should consider defining resource groups for your more specific resources (e.g. per level) so that you can control loading / unloading better.

Parameters:

name The name of the location, e.g. './data' or '/compressed/gamedata.zip'

locType A string identifying the location type, e.g. 'FileSystem' (for folders), 'Zip' etc. Must map to a registered plugin which deals with this type (FileSystem and Zip should always be available)

groupName Type of name of the resource group which this location should apply to; defaults to the General group which applies to all non-specific resources.

recursive If the resource location has a concept of recursive directory traversal, enabling this option will mean you can load resources in subdirectories using only their unqualified name. The default is to disable this so that resources in subdirectories with the same name are still unique.

See also:
Archive

void Ogre::Root::addSceneManagerFactory ( SceneManagerFactory * fact )

Register a new SceneManagerFactory, a factory object for creating instances of specific SceneManagers.

Remarks:
Plugins should call this to register as new SceneManager providers.

Real Ogre::Root::calculateEventTime ( unsigned long now,

FrameEventTimeType type

) [private]

Internal method for calculating the average time between recently fired events.

Parameters:

now The current time in ms.

type The type of event to be considered.

void Ogre::Root::clearEventTimes ( void )

Clears the history of all event times.

Remarks:
OGRE stores a history of the last few event times in order to smooth out any inaccuracies and temporary fluctuations. However, if you pause or don't render for a little while this can cause a lurch, so if you're resuming rendering after a break, call this method to reset the stored times

void Ogre::Root::convertColourValue ( const ColourValue & colour,

uint32 * pDest

)

Generates a packed data version of the passed in ColourValue suitable for use with the current RenderSystem.

Remarks:
Since different render systems have different colour data formats (eg RGBA for GL, ARGB for D3D) this method allows you to use 1 method for all.

Parameters:

colour The colour to convert

pDest Pointer to location to put the result.

RenderQueueInvocationSequence* Ogre::Root::createRenderQueueInvocationSequence ( const String & name )

Create a new RenderQueueInvocationSequence, useful for linking to Viewport instances to perform custom rendering.

Parameters:

name The name to give the new sequence

RenderWindow* Ogre::Root::createRenderWindow ( const String & name,

unsigned int width,

unsigned int height,

bool fullScreen,

const NameValuePairList * miscParams = 0

)

Remarks:
This method creates a new rendering window as specified by the paramteters. The rendering system could be responible for only a single window (e.g. in the case of a game), or could be in charge of multiple ones (in the case of a level editor). The option to create the window as a child of another is therefore given. This method will create an appropriate subclass of RenderWindow depending on the API and platform implementation.

After creation, this window can be retrieved using getRenderTarget().

Parameters:

name The name of the window. Used in other methods later like setRenderTarget and getRenderWindow.

width The width of the new window.

height The height of the new window.

fullScreen Specify true to make the window full screen without borders, title bar or menu bar.

miscParams A NameValuePairList describing the other parameters for the new rendering window. Options are case sensitive. Unrecognised parameters will be ignored silently. These values might be platform dependent, but these are present for all platorms unless indicated otherwise:

Key: "title" Description: The title of the window that will appear in the title bar Values: string Default: RenderTarget name
Key: "colourDepth" Description: Colour depth of the resulting rendering window; only applies if fullScreen is set. Values: 16 or 32 Default: desktop depth Notes: [W32 specific]
Key: "left" Description: screen x coordinate from left Values: positive integers Default: 'center window on screen' Notes: Ignored in case of full screen
Key: "top" Description: screen y coordinate from top Values: positive integers Default: 'center window on screen' Notes: Ignored in case of full screen
Key: "depthBuffer" [DX9 specific] Description: Use depth buffer Values: false or true Default: true
Key: "externalWindowHandle" [API specific] Description: External window handle, for embedding the OGRE context Values: positive integer for W32 (HWND handle) poslong:posint:poslong (display*:screen:windowHandle) or poslong:posint:poslong:poslong (display*:screen:windowHandle:XVisualInfo*) for GLX Default: 0 (None)
Key: "parentWindowHandle" [API specific] Description: Parent window handle, for embedding the OGRE context Values: positive integer for W32 (HWND handle) poslong:posint:poslong for GLX (display*:screen:windowHandle) Default: 0 (None)
Key: "FSAA" Description: Full screen antialiasing factor Values: 0,2,4,6,... Default: 0
Key: "displayFrequency" Description: Display frequency rate, for fullscreen mode Values: 60...? Default: Desktop vsync rate
Key: "vsync" Description: Synchronize buffer swaps to vsync Values: true, false Default: 0
Key: "border" Description: The type of window border (in windowed mode) Values: none, fixed, resize Default: resize
Key: "outerDimensions" Description: Whether the width/height is expressed as the size of the outer window, rather than the content area Values: true, false Default: false
Key: "useNVPerfHUD" [DX9 specific] Description: Enable the use of nVidia NVPerfHUD Values: true, false Default: false

SceneManager* Ogre::Root::createSceneManager ( SceneTypeMask typeMask,

const String & instanceName = StringUtil::BLANK

)

Create a SceneManager instance based on scene type support.

Remarks:
Creates an instance of a SceneManager which supports the scene types identified in the parameter. If more than one type of SceneManager has been registered as handling that combination of scene types, in instance of the last one registered is returned.

Note:
This method always succeeds, if a specific scene manager is not found, the default implementation is always returned.

Parameters:

typeMask A mask containing one or more SceneType flags

instanceName Optional name to given the new instance that is created. If you leave this blank, an auto name will be assigned.

SceneManager* Ogre::Root::createSceneManager ( const String & typeName,

const String & instanceName = StringUtil::BLANK

)

Create a SceneManager instance of a given type.

Remarks:
You can use this method to create a SceneManager instance of a given specific type. You may know this type already, or you may have discovered it by looking at the results from getMetaDataIterator.

Note:
This method throws an exception if the named type is not found.

Parameters:

typeName String identifying a unique SceneManager type

instanceName Optional name to given the new instance that is created. If you leave this blank, an auto name will be assigned.

void Ogre::Root::destroyAllRenderQueueInvocationSequences ( void )

Destroy all RenderQueueInvocationSequences.

Remarks:
You must ensure that no Viewports are using custom sequences.

Parameters:

name The name to identify the sequence

void Ogre::Root::destroyRenderQueueInvocationSequence ( const String & name )

Destroy a RenderQueueInvocationSequence.

Remarks:
You must ensure that no Viewports are using this sequence.

Parameters:

name The name to identify the sequence

void Ogre::Root::destroySceneManager ( SceneManager * sm )

Destroy an instance of a SceneManager.

void Ogre::Root::detachRenderTarget ( const String & name )

Destroys a named rendering window.

void Ogre::Root::detachRenderTarget ( RenderTarget * pWin )

Destroys a rendering window.

RenderWindow* Ogre::Root::getAutoCreatedWindow ( void )

Retrieves a pointer to the window that was created automatically.

Remarks:
When Root is initialised an optional window is created. This method retreives a pointer to that window.

Note:
returns a null pointer when Root has not been initialised with the option of creating a window.

RenderSystemList* Ogre::Root::getAvailableRenderers ( void )

Retrieve a list of the available render systems.

Remarks:
Retrieves a pointer to the list of available renderers as a list of RenderSystem subclasses. Can be used to build a custom settings dialog.

unsigned long Ogre::Root::getCurrentFrameNumber ( void ) const

Gets the number of the current frame.

Definition at line 661 of file OgreRoot.h.

String Ogre::Root::getErrorDescription ( long errorNumber )

Utility function for getting a better description of an error code.

Real Ogre::Root::getFrameSmoothingPeriod ( void ) const

Gets the period over which OGRE smooths out fluctuations in frame times.

Definition at line 771 of file OgreRoot.h.
References Ogre::Real.

MeshManager* Ogre::Root::getMeshManager ( void )

Retrieves a reference to the current MeshManager.

Remarks:
This performs the same function as MeshManager::getSingleton and is provided for convenience to scripting engines.

MovableObjectFactory* Ogre::Root::getMovableObjectFactory ( const String & typeName )

Get a MovableObjectFactory for the given type.

MovableObjectFactoryIterator Ogre::Root::getMovableObjectFactoryIterator ( void ) const

Return an iterator over all the MovableObjectFactory instances currently registered.

RenderQueueInvocationSequence* Ogre::Root::getRenderQueueInvocationSequence ( const String & name )

Get a RenderQueueInvocationSequence.

Parameters:

name The name to identify the sequence

RenderSystem* Ogre::Root::getRenderSystem ( void )

Retrieve a pointer to the currently selected render system.

RenderSystem* Ogre::Root::getRenderSystemByName ( const String & name )

Retrieve a pointer to the render system by the given name.

Parameters:

name Name of the render system intend to retrieve.

Returns:
A pointer to the render system, NULL if no found.

RenderTarget* Ogre::Root::getRenderTarget ( const String & name )

Retrieves a pointer to the a named render window.

SceneManager* Ogre::Root::getSceneManager ( const String & instanceName ) const

Get an existing SceneManager instance that has already been created, identified by the instance name.

Parameters:

instanceName The name of the instance to retrieve.

SceneManagerEnumerator::SceneManagerIterator Ogre::Root::getSceneManagerIterator ( void )

Get an iterator over all the existing SceneManager instances.

const SceneManagerMetaData* Ogre::Root::getSceneManagerMetaData ( const String & typeName ) const

Get more information about a given type of SceneManager.

Remarks:
The metadata returned tells you a few things about a given type of SceneManager, which can be created using a factory that has been registered already.

Parameters:

typeName The type name of the SceneManager you want to enquire on. If you don't know the typeName already, you can iterate over the metadata for all types using getMetaDataIterator.

SceneManagerEnumerator::MetaDataIterator Ogre::Root::getSceneManagerMetaDataIterator ( void ) const

Iterate over all types of SceneManager available for construction, providing some information about each one.

Root& Ogre::Root::getSingleton ( void ) [static]

Override standard Singleton retrieval.

Remarks:
Why do we do this? Well, it's because the Singleton implementation is in a .h file, which means it gets compiled into anybody who includes it. This is needed for the Singleton template to work, but we actually only want it compiled into the implementation of the class based on the Singleton, not all of them. If we don't change this, we get link errors when trying to use the Singleton-based class from an outside dll.

This method just delegates to the template version anyway, but the implementation stays in this single compilation unit, preventing link errors.

Reimplemented from Ogre::Singleton< Root >.

Root* Ogre::Root::getSingletonPtr ( void ) [static]

Override standard Singleton retrieval.

Remarks:
Why do we do this? Well, it's because the Singleton implementation is in a .h file, which means it gets compiled into anybody who includes it. This is needed for the Singleton template to work, but we actually only want it compiled into the implementation of the class based on the Singleton, not all of them. If we don't change this, we get link errors when trying to use the Singleton-based class from an outside dll.

This method just delegates to the template version anyway, but the implementation stays in this single compilation unit, preventing link errors.

Reimplemented from Ogre::Singleton< Root >.

TextureManager* Ogre::Root::getTextureManager ( void )

Retrieves a reference to the current TextureManager.

Remarks:
This performs the same function as TextureManager::getSingleton, but is provided for convenience particularly to scripting engines.

Note that a TextureManager will NOT be available until the Ogre system has been initialised by selecting a RenderSystem, calling Root::initialise and a window having been created (this may have been done by initialise if required). This is because the exact runtime subclass which will be implementing the calls will differ depending on the rendering engine selected, and these typically require a window upon which to base texture format decisions.

Timer* Ogre::Root::getTimer ( void )

Gets a pointer to the central timer used for all OGRE timings.

bool Ogre::Root::hasMovableObjectFactory ( const String & typeName ) const

Checks whether a factory is registered for a given MovableObject type.

RenderWindow* Ogre::Root::initialise ( bool autoCreateWindow,

const String & windowTitle = "OGRE Render Window"

)

Initialises the renderer.

Remarks:
This method can only be called after a renderer has been selected with Root::setRenderSystem, and it will initialise the selected rendering system ready for use.

Parameters:

autoCreateWindow If true, a rendering window will automatically be created (saving a call to RenderSystem::createRenderWindow). The window will be created based on the options currently set on the render system.

Returns:
A pointer to the automatically created window, if requested, otherwise NULL.

void Ogre::Root::initialisePlugins ( ) [private]

Initialise all loaded plugins - allows plugins to perform actions once the renderer is initialised.

bool Ogre::Root::isInitialised ( void ) const

Returns whether the system is initialised or not.

Definition at line 288 of file OgreRoot.h.

void Ogre::Root::loadPlugin ( const String & pluginName )

Manually load a plugin.

Remarks:
Plugins are loaded at startup using the plugin configuration file specified when you create Root (default: plugins.cfg). This method allows you to load plugins in code.

Parameters:

pluginName Name of the plugin library to load

void Ogre::Root::loadPlugins ( const String & pluginsfile = "plugins.cfg" ) [private]

Method reads a plugins configuration file and instantiates all plugins.

Parameters:

pluginsfile The file that contains plugins information. Defaults to "plugins.cfg".

void Ogre::Root::oneTimePostWindowInit ( void ) [private]

void Ogre::Root::queueEndRendering ( void )

Queues the end of rendering.

Remarks:
This method will do nothing unless startRendering() has been called, in which case before the next frame is rendered the rendering loop will bail out.

See also:
Root, Root::startRendering

void Ogre::Root::removeFrameListener ( FrameListener * oldListener )

Removes a FrameListener from the list of listening classes.

See also:
FrameListener, Root::addFrameListener

void Ogre::Root::removeMovableObjectFactory ( MovableObjectFactory * fact )

Removes a previously registered MovableObjectFactory.

Remarks:
All instances of objects created by this factory will be destroyed before removing the factory (by calling back the factories 'destroyInstance' method). The plugin writer is responsible for actually destroying the factory.

void Ogre::Root::removeResourceLocation ( const String & name,

const String & groupName = ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME

)

Removes a resource location from the list.

See also:
addResourceLocation

Parameters:

name The name of the resource location as specified in addResourceLocation

groupName The name of the resource group to which this location was assigned.

void Ogre::Root::removeSceneManagerFactory ( SceneManagerFactory * fact )

Unregister a SceneManagerFactory.

bool Ogre::Root::renderOneFrame ( void )

Render one frame.

Remarks:
Updates all the render targets automatically and then returns, raising frame events before and after.

bool Ogre::Root::restoreConfig ( void )

Checks for saved video/sound/etc settings.

Remarks:
This method checks to see if there is a valid saved configuration from a previous run. If there is, the state of the system will be restored to that configuration.

Returns:
If a valid configuration was found, true is returned.

If there is no saved configuration, or if the system failed with the last config settings, false is returned.

void Ogre::Root::saveConfig ( void )

Saves the details of the current configuration.

Remarks:
Stores details of the current configuration so it may be restored later on.

void Ogre::Root::setFrameSmoothingPeriod ( Real period )

Sets the period over which OGRE smooths out fluctuations in frame times.

Remarks:
OGRE by default gives you the raw frame time, but can optionally smooths it out over several frames, in order to reduce the noticeable effect of occasional hiccups in framerate. These smoothed values are passed back as parameters to FrameListener calls.

This method allow you to tweak the smoothing period, and is expressed in seconds. Setting it to 0 will result in completely unsmoothed frame times (the default).

Definition at line 769 of file OgreRoot.h.
References Ogre::Real.

void Ogre::Root::setRenderSystem ( RenderSystem * system )

Sets the rendering subsystem to be used.

Remarks:
This method indicates to OGRE which rendering system is to be used (e.g. Direct3D, OpenGL etc). This is called automatically by the default config dialog, and when settings are restored from a previous configuraion. If used manually it could be used to set the renderer from a custom settings dialog. Once this has been done, the renderer can be initialised using Root::initialise.

This method is also called by render systems if they are initialised directly.

Parameters:

system Pointer to the render system to use.

See also:
RenderSystem

bool Ogre::Root::showConfigDialog ( void )

Displays a dialog asking the user to choose system settings.

Remarks:
This method displays the default dialog allowing the user to choose the renderering system, video mode etc. If there is are any settings saved already, they will be restored automatically before displaying the dialogue. When the user accepts a group of settings, this will automatically call Root::setRenderSystem, RenderSystem::setConfigOption and Root::saveConfig with the user's choices. This is the easiest way to get the system configured.

Returns:
If the user clicked 'Ok', true is returned.

If they clicked 'Cancel' (in which case the app should strongly consider terminating), false is returned.

void Ogre::Root::shutdown ( void )

Shuts down the system manually.

Remarks:
This is normally done by Ogre automatically so don't think you have to call this yourself. However this is here for convenience, especially for dealing with unexpected errors or for systems which need to shut down Ogre on demand.

void Ogre::Root::shutdownPlugins ( ) [private]

Shuts down all loaded plugins - allows things to be tidied up whilst all plugins are still loaded.

void Ogre::Root::startRendering ( void )

Starts / restarts the automatic rendering cycle.

Remarks:
This method begins the automatic rendering of the scene. It will NOT return until the rendering cycle is halted.

During rendering, any FrameListener classes registered using addFrameListener will be called back for each frame that is to be rendered, These classes can tell OGRE to halt the rendering if required, which will cause this method to return.

Note:

Users of the OGRE library do not have to use this automatic rendering loop. It is there as a convenience and is most useful for high frame rate applications e.g. games. For applications that don't need to constantly refresh the rendering targets (e.g. an editor utility), it is better to manually refresh each render target only when required by calling RenderTarget::update.
This frees up the CPU to do other things in between refreshes, since in this case frame rate is less important.
This method can only be called after Root::initialise has been called.

void Ogre::Root::termHandler ( ) [static]

void Ogre::Root::unloadPlugin ( const String & pluginName )

Manually unloads a plugin.

Remarks:
Plugins are unloaded at shutdown automatically. This method allows you to unload plugins in code, but make sure their dependencies are decoupled frist.

Parameters:

pluginName Name of the plugin library to unload

void Ogre::Root::unloadPlugins ( ) [private]

Unloads all loaded plugins.

Friends And Related Function Documentation

friend class RenderSystem [friend]

Definition at line 65 of file OgreRoot.h.

Member Data Documentation

RenderSystem* Ogre::Root::mActiveRenderer [private]

Definition at line 68 of file OgreRoot.h.

ArchiveManager* Ogre::Root::mArchiveManager [private]

Definition at line 82 of file OgreRoot.h.

RenderWindow* Ogre::Root::mAutoWindow [private]

Definition at line 98 of file OgreRoot.h.

MovableObjectFactory* Ogre::Root::mBillboardChainFactory [private]

Definition at line 116 of file OgreRoot.h.

MovableObjectFactory* Ogre::Root::mBillboardSetFactory [private]

Definition at line 114 of file OgreRoot.h.

OverlayElementFactory* Ogre::Root::mBorderPanelFactory [private]

Definition at line 88 of file OgreRoot.h.

CompositorManager* Ogre::Root::mCompositorManager [private]

Definition at line 102 of file OgreRoot.h.

String Ogre::Root::mConfigFileName [private]

Definition at line 70 of file OgreRoot.h.

ControllerManager* Ogre::Root::mControllerManager [private]

Definition at line 77 of file OgreRoot.h.

unsigned long Ogre::Root::mCurrentFrame [private]

Definition at line 103 of file OgreRoot.h.

SceneManager* Ogre::Root::mCurrentSceneManager [private]

Definition at line 79 of file OgreRoot.h.

DynLibManager* Ogre::Root::mDynLibManager [private]

Definition at line 80 of file OgreRoot.h.

MovableObjectFactory* Ogre::Root::mEntityFactory [private]

Definition at line 112 of file OgreRoot.h.

std::deque<unsigned long> Ogre::Root::mEventTimes[3] [private]

Contains the times of recently fired events.

Definition at line 160 of file OgreRoot.h.

ExternalTextureSourceManager* Ogre::Root::mExternalTextureSourceManager [private]

Definition at line 101 of file OgreRoot.h.

ArchiveFactory* Ogre::Root::mFileSystemArchiveFactory [private]

Definition at line 93 of file OgreRoot.h.

bool Ogre::Root::mFirstTimePostWindowInit [private]

Definition at line 73 of file OgreRoot.h.

FontManager* Ogre::Root::mFontManager [private]

Definition at line 91 of file OgreRoot.h.

std::set<FrameListener*> Ogre::Root::mFrameListeners [private]

Set of registered frame listeners.

Definition at line 149 of file OgreRoot.h.

Real Ogre::Root::mFrameSmoothingTime [private]

Definition at line 104 of file OgreRoot.h.

HighLevelGpuProgramManager* Ogre::Root::mHighLevelGpuProgramManager [private]

Definition at line 100 of file OgreRoot.h.

bool Ogre::Root::mIsInitialised [private]

Are we initialised yet?

Definition at line 123 of file OgreRoot.h.

MovableObjectFactory* Ogre::Root::mLightFactory [private]

Definition at line 113 of file OgreRoot.h.

LogManager* Ogre::Root::mLogManager [private]

Definition at line 76 of file OgreRoot.h.

MovableObjectFactory* Ogre::Root::mManualObjectFactory [private]

Definition at line 115 of file OgreRoot.h.

MaterialManager* Ogre::Root::mMaterialManager [private]

Definition at line 83 of file OgreRoot.h.

MeshManager* Ogre::Root::mMeshManager [private]

Definition at line 84 of file OgreRoot.h.

MovableObjectFactoryMap Ogre::Root::mMovableObjectFactoryMap [private]

Definition at line 109 of file OgreRoot.h.

uint32 Ogre::Root::mNextMovableObjectTypeFlag [private]

Definition at line 110 of file OgreRoot.h.

OverlayManager* Ogre::Root::mOverlayManager [private]

Definition at line 90 of file OgreRoot.h.

OverlayElementFactory* Ogre::Root::mPanelFactory [private]

Definition at line 87 of file OgreRoot.h.

ParticleSystemManager* Ogre::Root::mParticleManager [private]

Definition at line 85 of file OgreRoot.h.

PlatformManager* Ogre::Root::mPlatformManager [private]

Definition at line 81 of file OgreRoot.h.

std::vector<DynLib*> Ogre::Root::mPluginLibs [private]

Definition at line 106 of file OgreRoot.h.

Profiler* Ogre::Root::mProfiler [private]

Definition at line 99 of file OgreRoot.h.

bool Ogre::Root::mQueuedEnd [private]

Definition at line 71 of file OgreRoot.h.

std::set<FrameListener*> Ogre::Root::mRemovedFrameListeners [private]

Set of frame listeners marked for removal.

Definition at line 152 of file OgreRoot.h.

RenderSystemList Ogre::Root::mRenderers [private]

Definition at line 67 of file OgreRoot.h.

ResourceBackgroundQueue* Ogre::Root::mResourceBackgroundQueue [private]

Definition at line 95 of file OgreRoot.h.

ResourceGroupManager* Ogre::Root::mResourceGroupManager [private]

Definition at line 94 of file OgreRoot.h.

MovableObjectFactory* Ogre::Root::mRibbonTrailFactory [private]

Definition at line 117 of file OgreRoot.h.

RenderQueueInvocationSequenceMap Ogre::Root::mRQSequenceMap [private]

Definition at line 120 of file OgreRoot.h.

Root * Ogre::Singleton< Root >::ms_Singleton [static, protected, inherited]

Definition at line 54 of file OgreSingleton.h.

SceneManagerEnumerator* Ogre::Root::mSceneManagerEnum [private]

Definition at line 78 of file OgreRoot.h.

SkeletonManager* Ogre::Root::mSkeletonManager [private]

Definition at line 86 of file OgreRoot.h.

OverlayElementFactory* Ogre::Root::mTextAreaFactory [private]

Definition at line 89 of file OgreRoot.h.

Timer* Ogre::Root::mTimer [private]

Definition at line 97 of file OgreRoot.h.

String Ogre::Root::mVersion [private]

Definition at line 69 of file OgreRoot.h.

ArchiveFactory* Ogre::Root::mZipArchiveFactory [private]

Definition at line 92 of file OgreRoot.h.

The documentation for this class was generated from the following file:

OgreRoot.h