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:

Ogre::Singleton< Root > List of all members.

Public Methods

 Root (const String &pluginFileName="plugins.cfg")
 Constructor. More...

 ~Root ()
void saveConfig (void)
 Saves the details of the current configuration. More...

bool restoreConfig (void)
 Checks for saved video/sound/etc settings. More...

bool showConfigDialog (void)
 Displays a dialog asking the user to choose system settings. More...

void addRenderSystem (RenderSystem *newRend)
 Adds a new rendering subsystem to the list of available renderers. More...

void setSceneManager (SceneType sType, SceneManager *sm)
 Sets the passed in SceneManager to be the one responsible for the indicated type of scene. More...

RenderSystemListgetAvailableRenderers (void)
 Retrieve a list of the available render systems. More...

void setRenderSystem (RenderSystem *system)
 Sets the rendering subsystem to be used. More...

RenderSystemgetRenderSystem (void)
 Retrieve a pointer to the currently selected render system. More...

RenderWindowinitialise (bool autoCreateWindow)
 Initialises the renderer. More...

SceneManagergetSceneManager (SceneType sceneType)
 Gets a reference to a SceneManager object. More...

TextureManagergetTextureManager (void)
 Retrieves a reference to the current TextureManager. More...

MeshManagergetMeshManager (void)
 Retrieves a reference to the current MeshManager. More...

String getErrorDescription (long errorNumber)
 Utility function for getting a better description of an error code. More...

void addFrameListener (FrameListener *newListener)
 Registers a FrameListener which will be called back every frame. More...

void removeFrameListener (FrameListener *oldListener)
 Removes a FrameListener from the list of listening classes. More...

void startRendering (void)
 Starts / restarts the automatic rendering cycle. More...

void shutdown (void)
 Shuts down the system manually. More...

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

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

RenderWindowcreateRenderWindow (const String &name, int width, int height, int colourDepth, bool fullScreen, int left=0, int top=0, bool depthBuffer=true, RenderWindow *parentWindowHandle=0)
 Creates a new rendering window. More...

void detachRenderTarget (RenderTarget *pWin)
 Destroys a rendering window. More...

void detachRenderTarget (const String &name)
 Destroys a named rendering window. More...

RenderTargetgetRenderTarget (const String &name)
 Retrieves a pointer to the a named render window. More...

void showDebugOverlay (bool show)
 Sets whether or not the debug overlay is shown. More...


Static Public Methods

void termHandler ()
Root & getSingleton (void)
 Override standard Singleton retrieval. More...

Root * getSingletonPtr (void)

Static Protected Attributes

Root * ms_Singleton = 0

Private Methods

void loadPlugins (const String &pluginsfile="plugins.cfg")
 Method reads a plugins configuration file and instantiates all plugins. More...

void unloadPlugins ()
 Unloads all loaded plugins. More...


Private Attributes

RenderSystemList mRenderers
RenderSystemmActiveRenderer
String mVersion
MathmMath
LogManagermLogManager
ControllerManagermControllerManager
SceneManagerEnumeratormSceneManagerEnum
DynLibManagermDynLibManager
PlatformManagermPlatformManager
ArchiveManagermArchiveManager
MaterialManagermMaterialManager
MeshManagermMeshManager
ParticleSystemManagermParticleManager
SkeletonManagermSkeletonManager
GuiManagermGuiManager
OverlayManagermOverlayManager
FontManagermFontManager
ArchiveFactorymZipArchiveFactory
CodecmPNGCodec
CodecmJPGCodec
CodecmJPEGCodec
CodecmTGACodec
std::vector< DynLib * > mPluginLibs

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


Constructor & Destructor Documentation

Ogre::Root::Root const String   pluginFileName = "plugins.cfg"
 

Constructor.

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

Ogre::Root::~Root  
 


Member Function Documentation

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 during Ogre's automatic rendering loop (started with RenderSystem::startRendering).

See the FrameListener class for more details on the specifics It is imperitive that the instance passed to this method is not destroyed before iether 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::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,
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

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.

RenderWindow * Ogre::Root::createRenderWindow const String   name,
int    width,
int    height,
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.

void Ogre::Root::detachRenderTarget const String   name
 

Destroys a named rendering window.

void Ogre::Root::detachRenderTarget RenderTarget   pWin
 

Destroys a rendering 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.

String Ogre::Root::getErrorDescription long    errorNumber
 

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

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.

RenderSystem * Ogre::Root::getRenderSystem void   
 

Retrieve a pointer to the currently selected render system.

RenderTarget * Ogre::Root::getRenderTarget const String   name
 

Retrieves a pointer to the a named render window.

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

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::Singleton< Root >::getSingletonPtr void    [inline, static, inherited]
 

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.

RenderWindow * Ogre::Root::initialise bool    autoCreateWindow
 

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::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::removeFrameListener FrameListener   oldListener
 

Removes a FrameListener from the list of listening classes.

See also:
FrameListener, Root::addFrameListener

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

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.

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::showDebugOverlay bool    show
 

Sets whether or not the debug overlay is shown.

Remarks:
The debug overlay displays frame rate stats and various other debug information. You can enable it or disable it using this method. Alternatively you could access the overlay directly using mSceneManager::getOverlay but this is simpler.

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::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::unloadPlugins   [private]
 

Unloads all loaded plugins.


Friends And Related Function Documentation

friend class RenderSystem [friend]
 


Member Data Documentation

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

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

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

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

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

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

Codec * Ogre::Root::mJPEGCodec [private]
 

Codec * Ogre::Root::mJPGCodec [private]
 

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

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

Math* Ogre::Root::mMath [private]
 

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

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

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

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

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

Codec* Ogre::Root::mPNGCodec [private]
 

RenderSystemList Ogre::Root::mRenderers [private]
 

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

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

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

Codec * Ogre::Root::mTGACodec [private]
 

String Ogre::Root::mVersion [private]
 

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

Copyright © 2002 by The OGRE Team