Main Page Namespace List Class Hierarchy Alphabetical List Compound List File List Namespace Members Compound Members File Members Related Pages

# Ogre::Root Class Reference

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

`#include <OgreRoot.h>`

Inheritance diagram for Ogre::Root:

[legend]
List of all members.

## Public Methods

| 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.
void | setSceneManager (SceneType sType, SceneManager *sm)
| Sets the passed in SceneManager to be the one responsible for the indicated type of scene.
RenderSystemList * | getAvailableRenderers (void)
| Retrieve a list of the available render systems.
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.
SceneManager * | getSceneManager (SceneType sceneType)
| Gets a reference to a SceneManager object.
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, ResourceType resType=RESTYPE_ALL)
| Adds a location to the list of searchable locations for a Resource type.
void | convertColourValue (const ColourValue &colour, unsigned long *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, unsigned int colourDepth, bool fullScreen, int left=0, int top=0, bool depthBuffer=true, RenderWindow *parentWindowHandle=0)
| Creates a new rendering window.
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)
| Gets the number of the current frame.
SceneManager * | _getCurrentSceneManager (void)
| 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.

## Static Public Methods

void | termHandler ()
Root & | getSingleton (void)
| Override standard Singleton retrieval.
Root * | getSingletonPtr (void)
| Override standard Singleton retrieval.

## Static Protected Attributes

Root * | ms_Singleton = 0

## Private Types

enum | FrameEventTimeType { FETT_ANY, FETT_STARTED, FETT_ENDED }
| Indicates the type of event to be considered by calculateEventTime(). More...

## Private Methods

void | loadPlugins (const String &pluginsfile="plugins.cfg")
| Method reads a plugins configuration file and instantiates all plugins.
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
GuiManager * | mGuiManager
OverlayManager * | mOverlayManager
FontManager * | mFontManager
ArchiveFactory * | mZipArchiveFactory
Timer * | mTimer
RenderWindow * | mAutoWindow
Profiler * | mProfiler
HighLevelGpuProgramManager * | mHighLevelGpuProgramManager
ExternalTextureSourceManager * | mExternalTextureSourceManager
unsigned long | mCurrentFrame
std::vector< DynLib * > | mPluginLibs
std::set< FrameListener * > | mFrameListeners
| Set of registered frame listeners.
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 65 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 123 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".

Definition at line 116 of file OgreRoot.cpp.

References Ogre::LogManager::createLog(), Ogre::PlatformManager::createTimer(), loadPlugins(), Ogre::LogManager::logMessage(), mActiveRenderer, mArchiveManager, mAutoWindow, mConfigFileName, mControllerManager, mCurrentSceneManager, mDynLibManager, mExternalTextureSourceManager, mFirstTimePostWindowInit, mFontManager, mGuiManager, mHighLevelGpuProgramManager, mLogManager, mMaterialManager, mMeshManager, mOverlayManager, mParticleManager, mPlatformManager, mProfiler, mSceneManagerEnum, mSkeletonManager, mTimer, mVersion, mZipArchiveFactory, OGRE_VERSION_MAJOR, OGRE_VERSION_MINOR, OGRE_VERSION_NAME, OGRE_VERSION_PATCH, SET_TERM_HANDLER, and Ogre::String.

Ogre::Root::~Root | ( |  | ) |

Definition at line 209 of file OgreRoot.cpp.

References Ogre::PlatformManager::destroyTimer(), mArchiveManager, mControllerManager, mDynLibManager, mExternalTextureSourceManager, mFontManager, mGuiManager, mHighLevelGpuProgramManager, mLogManager, mMaterialManager, mMeshManager, mOverlayManager, mParticleManager, mPlatformManager, mProfiler, mSceneManagerEnum, mSkeletonManager, mTimer, mZipArchiveFactory, shutdown(), and unloadPlugins().

## Member Function Documentation

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.

Definition at line 526 of file OgreRoot.cpp.

References calculateEventTime(), FETT_ANY, FETT_ENDED, Ogre::Timer::getMilliseconds(), mTimer, Ogre::FrameEvent::timeSinceLastEvent, and Ogre::FrameEvent::timeSinceLastFrame.

Referenced by renderOneFrame().

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.

Definition at line 499 of file OgreRoot.cpp.

References mFrameListeners.

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.

Definition at line 516 of file OgreRoot.cpp.

References calculateEventTime(), FETT_ANY, FETT_STARTED, Ogre::Timer::getMilliseconds(), mTimer, Ogre::FrameEvent::timeSinceLastEvent, and Ogre::FrameEvent::timeSinceLastFrame.

Referenced by renderOneFrame().

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.

Definition at line 482 of file OgreRoot.cpp.

References mCurrentFrame, and mFrameListeners.

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

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 613 of file OgreRoot.h.

Referenced by Ogre::Entity::updateAnimation().

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.

Definition at line 618 of file OgreRoot.h.

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.

Definition at line 840 of file OgreRoot.cpp.

References Ogre::RenderSystem::_updateAllRenderTargets(), and mActiveRenderer.

Referenced by renderOneFrame().

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

Definition at line 468 of file OgreRoot.cpp.

References mFrameListeners.

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.

Definition at line 400 of file OgreRoot.cpp.

References mRenderers.

void Ogre::Root::addResourceLocation | ( | const String & | name,
|  | const String & | locType,
|  | ResourceType | resType = RESTYPE_ALL
| ) |

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

Remarks:
  Resource files (textures, models etc) can be loaded from locations other than the current application folder. By calling this method, you add another search location to the list. Locations added first are preferred over locations added later, with the current application folder always being the most preferred (and already set up for you).

  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 ArchiveEx 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.

Note:
  Because of dependencies on certain initialisation tasks, you should not call this method for any Resource type other than 'RESTYPE_ALL' unless you have already called the 'Root::initialise' method.

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)
  resType | Type of resource which will be searched for in this location. Defaults to all resources, but you can specify that textures are loaded from one location, models from another etc. if you like.

See also:
  ArchiveEx

Definition at line 676 of file OgreRoot.cpp.

References Ogre::ResourceType, Ogre::RESTYPE_ALL, Ogre::RESTYPE_MODELS, Ogre::RESTYPE_TEXTURES, and Ogre::String.

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.

Definition at line 536 of file OgreRoot.cpp.

References mEventTimes, and Ogre::Real.

Referenced by _fireFrameEnded(), and _fireFrameStarted().

void Ogre::Root::convertColourValue | ( | const ColourValue & | colour,
|  | unsigned long * | 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.

Definition at line 693 of file OgreRoot.cpp.

References Ogre::RenderSystem::convertColourValue(), and mActiveRenderer.

RenderWindow * Ogre::Root::createRenderWindow | ( | const String & | name,
|  | unsigned int | width,
|  | unsigned int | height,
|  | unsigned int | colourDepth,
|  | bool | fullScreen,
|  | int | left = 0,
|  | int | top = 0,
|  | bool | depthBuffer = true,
|  | RenderWindow * | parentWindowHandle = 0
| ) |

Creates a new rendering window.

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.

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.
  colourDepth | The colour depth in bits per pixel. Only applicable if fullScreen = true
  fullScreen | Specify true to make the window full screen without borders, title bar or menu bar.
  left | The x position of the new window. Only applicable if fullScreen is false. Units are relative to the parent window if applicable, otherwise they are in screen coordinates.
  top | The y position of the new window.
  depthBuffer | If true, a depth buffer will be assigned to this window.
  parentWindowHandle | Should be null if this window is to be stand-alone. Otherwise, specify a pointer to a RenderWindow which represents the parent window.

Definition at line 704 of file OgreRoot.cpp.

References Ogre::RenderSystem::createRenderWindow(), Except, mActiveRenderer, oneTimePostWindowInit(), and Ogre::String.

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

| Destroys a named rendering window. Definition at line 736 of file OgreRoot.cpp. References Ogre::RenderSystem::detachRenderTarget(), Except, mActiveRenderer, and Ogre::String.

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

| Destroys a rendering window. Definition at line 724 of file OgreRoot.cpp. References Ogre::RenderSystem::detachRenderTarget(), Except, Ogre::RenderTarget::getName(), and mActiveRenderer.

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.

Definition at line 699 of file OgreRoot.cpp.

References mAutoWindow.

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.

Definition at line 372 of file OgreRoot.cpp.

References mRenderers, and Ogre::RenderSystemList.

Referenced by restoreConfig().

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

| Gets the number of the current frame. Definition at line 606 of file OgreRoot.h. Referenced by Ogre::Entity::cacheBoneMatrices(), and Ogre::Entity::updateAnimation().

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

| Utility function for getting a better description of an error code. Definition at line 441 of file OgreRoot.cpp. References Ogre::RenderSystem::getErrorDescription(), mActiveRenderer, and Ogre::String.

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.

Definition at line 463 of file OgreRoot.cpp.

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

| Retrieve a pointer to the currently selected render system. Definition at line 411 of file OgreRoot.cpp. References mActiveRenderer.

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

| Retrieves a pointer to the a named render window. Definition at line 748 of file OgreRoot.cpp. References Except, Ogre::RenderSystem::getRenderTarget(), mActiveRenderer, and Ogre::String.

SceneManager * Ogre::Root::getSceneManager | ( | SceneType | sceneType | ) |

Gets a reference to a SceneManager object.

Remarks:
  The SceneManager class (and any subclasses) is a key class which controls the contents of the scene, and is responsible for issuing rendering commands to the RenderSystem to draw it. The SceneManager is the class which an application using Ogre will interact with most, since controlling the contents of the scene is the most frequent action of an application.

  As described in the SceneManager documentation, different subclasses can be specialised for rendering particular types of scene e.g. landscapes or indoor enviroments.

Note:
  This function delegates it's implementation to the SceneManagerEnumerator class. This class can be customised to include new SceneType entries and to create new subclasses of SceneManager if they are introduced. This is done because the customisation of the Root class is strongly discouraged and in the future it may be locked down.

Parameters:

  sceneType | A value from the SceneType enumeration. The method will return a SceneManager which is most appropriate for this type of scene.

See also:
  SceneManager, SceneManagerEnumerator

Definition at line 452 of file OgreRoot.cpp.

References Ogre::SceneManagerEnumerator::getSceneManager(), mSceneManagerEnum, and Ogre::SceneType.

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 >.

Definition at line 78 of file OgreRoot.cpp.

References Ogre::Singleton< Root >::ms_Singleton.

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 >.

Definition at line 74 of file OgreRoot.cpp.

References Ogre::Singleton< Root >::ms_Singleton.

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.

Definition at line 458 of file OgreRoot.cpp.

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

| Gets a pointer to the central timer used for all OGRE timings. Definition at line 816 of file OgreRoot.cpp. References mTimer.

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.

Definition at line 419 of file OgreRoot.cpp.

References Except, Ogre::RenderSystem::initialise(), mActiveRenderer, mAutoWindow, mControllerManager, mTimer, oneTimePostWindowInit(), Ogre::Timer::reset(), and Ogre::String.

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

Definition at line 779 of file OgreRoot.cpp.

References Ogre::DLL_START_PLUGIN, Except, Ogre::DynLib::getSymbol(), mPluginLibs, and Ogre::String.

Referenced by loadPlugins().

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".

Definition at line 621 of file OgreRoot.cpp.

References Ogre::ConfigFile::getMultiSetting(), Ogre::ConfigFile::getSetting(), Ogre::ConfigFile::load(), loadPlugin(), Ogre::String, and Ogre::StringVector.

Referenced by Root().

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

| Definition at line 821 of file OgreRoot.cpp. References Ogre::ParticleSystemManager::_initialise(), Ogre::MaterialManager::initialise(), mFirstTimePostWindowInit, mFontManager, mMaterialManager, mOverlayManager, mParticleManager, Ogre::OverlayManager::parseAllSources(), and Ogre::FontManager::parseAllSources(). Referenced by createRenderWindow(), and initialise().

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

Definition at line 567 of file OgreRoot.cpp.

References mQueuedEnd.

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

Removes a FrameListener from the list of listening classes.

See also:
  FrameListener, Root::addFrameListener

Definition at line 476 of file OgreRoot.cpp.

References mFrameListeners.

bool Ogre::Root::renderOneFrame | ( | void |  | ) |

Render one frame.

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

Definition at line 604 of file OgreRoot.cpp.

References _fireFrameEnded(), _fireFrameStarted(), and _updateAllRenderTargets().

Referenced by startRendering().

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.

Definition at line 285 of file OgreRoot.cpp.

References getAvailableRenderers(), Ogre::ConfigFile::getSetting(), Ogre::ConfigFile::getSettingsIterator(), Ogre::ConfigFile::load(), mActiveRenderer, mConfigFileName, Ogre::RenderSystem::setConfigOption(), setRenderSystem(), and Ogre::String.

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.

Definition at line 252 of file OgreRoot.cpp.

References Ogre::ConfigOptionMap, Except, Ogre::RenderSystem::getConfigOptions(), Ogre::RenderSystem::getName(), mActiveRenderer, and mConfigFileName.

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

Definition at line 381 of file OgreRoot.cpp.

References mActiveRenderer, and Ogre::RenderSystem::shutdown().

Referenced by restoreConfig().

void Ogre::Root::setSceneManager | ( | SceneType | sType,
|  | SceneManager * | sm
| ) |

Sets the passed in SceneManager to be the one responsible for the indicated type of scene.

Remarks:
  This method is provided for application writers and plugin authors to use to attach their SceneManager subclasses to the engine. See the SceneManager class for more information.

Definition at line 405 of file OgreRoot.cpp.

References Ogre::SceneType.

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.

Definition at line 354 of file OgreRoot.cpp.

References Ogre::PlatformManager::createConfigDialog(), Ogre::PlatformManager::destroyConfigDialog(), Ogre::ConfigDialog::display(), Ogre::dlg, and mPlatformManager.

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.

Definition at line 614 of file OgreRoot.cpp.

References Ogre::LogManager::logMessage(), and mLogManager.

Referenced by Ogre::handleTerminate(), and ~Root().

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.

Definition at line 572 of file OgreRoot.cpp.

References Ogre::RenderSystem::_initRenderTargets(), mActiveRenderer, mEventTimes, mQueuedEnd, and renderOneFrame().

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

| Definition at line 109 of file OgreRoot.cpp. References Ogre::handleTerminate().

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

Definition at line 795 of file OgreRoot.cpp.

References Ogre::DLL_STOP_PLUGIN, mPluginLibs, and Ogre::String.

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

| Unloads all loaded plugins. Definition at line 656 of file OgreRoot.cpp. References Ogre::DLL_STOP_PLUGIN, and mPluginLibs. Referenced by ~Root().

## Friends And Related Function Documentation

friend class RenderSystem`[friend]`

| Definition at line 69 of file OgreRoot.h.

## Member Data Documentation

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

| Definition at line 72 of file OgreRoot.h. Referenced by _updateAllRenderTargets(), convertColourValue(), createRenderWindow(), detachRenderTarget(), getErrorDescription(), getRenderSystem(), getRenderTarget(), initialise(), restoreConfig(), Root(), saveConfig(), setRenderSystem(), and startRendering().

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

| Definition at line 86 of file OgreRoot.h. Referenced by Root(), and ~Root().

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

| Definition at line 97 of file OgreRoot.h. Referenced by getAutoCreatedWindow(), initialise(), and Root().

String Ogre::Root::mConfigFileName`[private]`

| Definition at line 74 of file OgreRoot.h. Referenced by restoreConfig(), Root(), and saveConfig().

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

| Definition at line 81 of file OgreRoot.h. Referenced by initialise(), Root(), and ~Root().

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

| Definition at line 101 of file OgreRoot.h. Referenced by _fireFrameStarted().

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

| Definition at line 83 of file OgreRoot.h. Referenced by Root().

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

| Definition at line 84 of file OgreRoot.h. Referenced by Root(), and ~Root().

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

| Contains the times of recently fired events. Definition at line 128 of file OgreRoot.h. Referenced by calculateEventTime(), and startRendering().

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

| Definition at line 100 of file OgreRoot.h. Referenced by Root(), and ~Root().

bool Ogre::Root::mFirstTimePostWindowInit`[private]`

| Definition at line 77 of file OgreRoot.h. Referenced by oneTimePostWindowInit(), and Root().

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

| Definition at line 93 of file OgreRoot.h. Referenced by oneTimePostWindowInit(), Root(), and ~Root().

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

| Set of registered frame listeners. Definition at line 119 of file OgreRoot.h. Referenced by _fireFrameEnded(), _fireFrameStarted(), addFrameListener(), and removeFrameListener().

GuiManager* Ogre::Root::mGuiManager`[private]`

| Definition at line 91 of file OgreRoot.h. Referenced by Root(), and ~Root().

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

| Definition at line 99 of file OgreRoot.h. Referenced by Root(), and ~Root().

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

| Definition at line 80 of file OgreRoot.h. Referenced by Root(), shutdown(), and ~Root().

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

| Definition at line 87 of file OgreRoot.h. Referenced by oneTimePostWindowInit(), Root(), and ~Root().

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

| Definition at line 88 of file OgreRoot.h. Referenced by Root(), and ~Root().

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

| Definition at line 92 of file OgreRoot.h. Referenced by oneTimePostWindowInit(), Root(), and ~Root().

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

| Definition at line 89 of file OgreRoot.h. Referenced by oneTimePostWindowInit(), Root(), and ~Root().

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

| Definition at line 85 of file OgreRoot.h. Referenced by Root(), showConfigDialog(), and ~Root().

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

| Definition at line 103 of file OgreRoot.h. Referenced by loadPlugin(), unloadPlugin(), and unloadPlugins().

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

| Definition at line 98 of file OgreRoot.h. Referenced by Root(), and ~Root().

bool Ogre::Root::mQueuedEnd`[private]`

| Definition at line 75 of file OgreRoot.h. Referenced by queueEndRendering(), and startRendering().

RenderSystemList Ogre::Root::mRenderers`[private]`

| Definition at line 71 of file OgreRoot.h. Referenced by addRenderSystem(), and getAvailableRenderers().

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

| Definition at line 73 of file OgreRoot.cpp. Referenced by getSingleton(), and getSingletonPtr().

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

| Definition at line 82 of file OgreRoot.h. Referenced by getSceneManager(), Root(), and ~Root().

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

| Definition at line 90 of file OgreRoot.h. Referenced by Root(), and ~Root().

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

| Definition at line 96 of file OgreRoot.h. Referenced by _fireFrameEnded(), _fireFrameStarted(), getTimer(), initialise(), Root(), and ~Root().

String Ogre::Root::mVersion`[private]`

| Definition at line 73 of file OgreRoot.h. Referenced by Root().

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

| Definition at line 94 of file OgreRoot.h. Referenced by Root(), and ~Root().

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

- OgreRoot.h
- OgreRoot.cpp

Copyright © 2002-2003 by The OGRE Team
Last modified Sun Nov 28 19:51:33 2004