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

#include <OgreRoot.h>

Inheritance diagram for Ogre::Root:

Public Types
typedef ConstMapIterator< MovableObjectFactoryMap >	MovableObjectFactoryIterator

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

typedef std::vector< Plugin * >	PluginInstanceList

typedef std::vector< DynLib * >	PluginLibList

Public Member Functions
	Root (const String &pluginFileName="plugins.cfg", const String &configFileName="ogre.cfg", const String &logFileName="Ogre.log")
	Constructor. More...

	~Root ()

uint32	_allocateNextMovableObjectTypeFlag (void)
	Allocate the next MovableObject type flag. More...

bool	_fireFrameEnded ()
	Method for raising frame ended events. More...

bool	_fireFrameEnded (FrameEvent &evt)
	Method for raising frame ended events. More...

bool	_fireFrameRenderingQueued ()
	Method for raising frame rendering queued events. More...

bool	_fireFrameRenderingQueued (FrameEvent &evt)
	Method for raising frame rendering queued events. More...

bool	_fireFrameStarted ()
	Method for raising frame started events. More...

bool	_fireFrameStarted (FrameEvent &evt)
	Method for raising frame started events. More...

SceneManager *	_getCurrentSceneManager (void) const
	Returns the scene manager currently being used to render a frame. More...

void	_setCurrentSceneManager (SceneManager *sm)
	Sets the scene manager currently being used to render. More...

bool	_updateAllRenderTargets (FrameEvent &evt)
	Internal method used for updating all RenderTarget objects (windows, renderable textures etc) which are set to auto-update, with a custom time passed to the frameRenderingQueued events. More...

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

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

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

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

void	addSceneManagerFactory (SceneManagerFactory *fact)
	Register a new SceneManagerFactory, a factory object for creating instances of specific SceneManagers. More...

void	clearEventTimes (void)
	Clears the history of all event times. More...

RenderWindow *	createRenderWindow (const RenderWindowDescription &desc)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. More...

RenderWindow *	createRenderWindow (const String &name, unsigned int width, unsigned int height, bool fullScreen, const NameValuePairList *miscParams=0)
	Creates a new rendering window. More...

SceneManager *	createSceneManager ()
	create a default scene manager More...

SceneManager *	createSceneManager (const String &typeName, const String &instanceName=BLANKSTRING)
	Create a SceneManager instance of a given type. More...

SceneManager *	createSceneManager (uint16 typeMask, const String &instanceName=BLANKSTRING)

void	destroyRenderTarget (const String &name)
	Destroys the given named RenderTarget. More...

void	destroyRenderTarget (RenderTarget *target)
	Destroys the given RenderTarget. More...

void	destroySceneManager (SceneManager *sm)
	Destroy an instance of a SceneManager. More...

RenderTarget *	detachRenderTarget (const String &name)
	Detaches a named RenderTarget from the active render system and returns a pointer to it. More...

RenderTarget *	detachRenderTarget (RenderTarget *pWin)
	Detaches a RenderTarget from the active render system and returns a pointer to it. More...

bool	endRenderingQueued (void)
	Check for planned end of rendering. More...

RenderWindow *	getAutoCreatedWindow (void)
	Retrieves a pointer to the window that was created automatically. More...

const RenderSystemList &	getAvailableRenderers (void)
	Retrieve a list of the available render systems. More...

Real	getDefaultMinPixelSize ()
	Get the default minimum pixel size for object to be rendered by. More...

unsigned int	getDisplayMonitorCount () const

Real	getFrameSmoothingPeriod (void) const
	Gets the period over which OGRE smooths out fluctuations in frame times. More...

const PluginInstanceList &	getInstalledPlugins () const
	Gets a read-only list of the currently installed plugins. More...

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

const MovableObjectFactoryMap &	getMovableObjectFactories () const
	Return an iterator over all the MovableObjectFactory instances currently registered. More...

MovableObjectFactory *	getMovableObjectFactory (const String &typeName)
	Get a MovableObjectFactory for the given type. More...

MovableObjectFactoryIterator	getMovableObjectFactoryIterator (void) const

unsigned long	getNextFrameNumber (void) const
	Gets the number of the next frame to be rendered. More...

bool	getRemoveRenderQueueStructuresOnClear () const
	Get whether the entire render queue structure should be emptied on clearing, or whether just the objects themselves should be cleared. More...

RenderSystem *	getRenderSystem (void)
	Retrieve a pointer to the currently selected render system. More...

RenderSystem *	getRenderSystemByName (const String &name)
	Retrieve a pointer to the render system by the given name. More...

RenderTarget *	getRenderTarget (const String &name)
	Retrieves a pointer to a named render target. More...

SceneManager *	getSceneManager (const String &instanceName) const
	Get an existing SceneManager instance that has already been created, identified by the instance name. More...

SceneManagerEnumerator::SceneManagerIterator	getSceneManagerIterator (void)
	Get an iterator over all the existing SceneManager instances. More...

const SceneManagerEnumerator::MetaDataList &	getSceneManagerMetaData () const
	get all types of SceneManager available for construction More...

const SceneManagerMetaData *	getSceneManagerMetaData (const String &typeName) const
	Get more information about a given type of SceneManager. More...

SceneManagerEnumerator::MetaDataIterator	getSceneManagerMetaDataIterator (void) const
	Iterate over all types of SceneManager available for construction, providing some information about each one. More...

const SceneManagerEnumerator::Instances &	getSceneManagers (void) const
	Get all the existing SceneManager instances. More...

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

Timer *	getTimer (void)
	Gets a pointer to the central timer used for all OGRE timings. More...

WorkQueue *	getWorkQueue () const
	Get the WorkQueue for processing background tasks. More...

bool	hasMovableObjectFactory (const String &typeName) const
	Checks whether a factory is registered for a given MovableObject type. More...

bool	hasSceneManager (const String &instanceName) const
	Identify if a SceneManager instance already exists. More...

RenderWindow *	initialise (bool autoCreateWindow, const String &windowTitle="OGRE Render Window", const String &customCapabilitiesConfig=BLANKSTRING)
	Initialises the renderer. More...

void	installPlugin (Plugin *plugin)
	Install a new plugin. More...

bool	isBlendIndicesGpuRedundant () const
	Returns whether blend indices information needs to be passed to the GPU see setBlendIndicesGpuRedundant() for more information. More...

bool	isBlendWeightsGpuRedundant () const
	Returns whether blend weights information needs to be passed to the GPU see setBlendWeightsGpuRedundant() for more information. More...

bool	isInitialised (void) const
	Returns whether the system is initialised or not. More...

void	loadPlugin (const String &pluginName)
	Manually load a Plugin contained in a DLL / DSO. More...

void	queueEndRendering (bool state=true)
	Queues the end of rendering. More...

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

void	removeMovableObjectFactory (MovableObjectFactory *fact)
	Removes a previously registered MovableObjectFactory. More...

void	removeSceneManagerFactory (SceneManagerFactory *fact)
	Register a new SceneManagerFactory. More...

bool	renderOneFrame (Real timeSinceLastFrame)
	Updates all the render targets with custom frame time information. More...

bool	renderOneFrame (void)
	Updates all the render targets automatically. More...

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

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

void	setBlendIndicesGpuRedundant (bool redundant)
	Sets whether blend indices information needs to be passed to the GPU. More...

void	setBlendWeightsGpuRedundant (bool redundant)
	Sets whether blend weights information needs to be passed to the GPU. More...

void	setDefaultMinPixelSize (Real pixelSize)
	Set the default minimum pixel size for object to be rendered by. More...

void	setFrameSmoothingPeriod (Real period)
	Sets the period over which OGRE smooths out fluctuations in frame times. More...

void	setRemoveRenderQueueStructuresOnClear (bool r)
	Set whether the entire render queue structure should be emptied on clearing, or whether just the objects themselves should be cleared. More...

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

void	setWorkQueue (WorkQueue *queue)
	Replace the current work queue with an alternative. More...

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

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

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

void	uninstallPlugin (Plugin *plugin)
	Uninstall an existing plugin. More...

void	unloadPlugin (const String &pluginName)
	Manually unloads a Plugin contained in a DLL / DSO. More...

void	useCustomRenderSystemCapabilities (RenderSystemCapabilities *capabilities)
	Requests active RenderSystem to use custom RenderSystemCapabilities. More...

Public Member Functions inherited from Ogre::Singleton< Root >
	Singleton (void)

	~Singleton (void)

Static Public Member Functions
static void	convertColourValue (const ColourValue &colour, uint32 *pDest)

static DataStreamPtr	createFileStream (const String &filename, const String &groupName=ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME, bool overwrite=false, const String &locationPattern=BLANKSTRING)
	Helper method to assist you in creating writeable file streams. More...

static Root &	getSingleton (void)
	Get the singleton instance. More...

static Root *	getSingletonPtr (void)
	Get the singleton instance. More...

static DataStreamPtr	openFileStream (const String &filename, const String &groupName=ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME)
	Helper method to assist you in accessing readable file streams. More...

Static Public Member Functions inherited from Ogre::Singleton< Root >
static Root &	getSingleton (void)
	Get the singleton instance. More...

static Root *	getSingletonPtr (void)
	Get the singleton instance. More...

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

Member Typedef Documentation

◆ MovableObjectFactoryMap

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

◆ PluginLibList

typedef std::vector<DynLib*> Ogre::Root::PluginLibList

◆ PluginInstanceList

typedef std::vector<Plugin*> Ogre::Root::PluginInstanceList

◆ MovableObjectFactoryIterator

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

Constructor & Destructor Documentation

◆ Root()

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. May be left blank to ignore.
configFileName	The file that contains the configuration to be loaded. Defaults to "ogre.cfg", may be left blank to load nothing.
logFileName	The logfile to create, defaults to Ogre.log, may be left blank if you've already set up LogManager & Log yourself

◆ ~Root()

Ogre::Root::~Root ( )

Member Function Documentation

◆ saveConfig()

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.

◆ restoreConfig()

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.

◆ showConfigDialog()

bool Ogre::Root::showConfigDialog ( ConfigDialog * dialog )

Displays a dialog asking the user to choose system settings.

Remarks: This method displays the default dialog allowing the user to choose the rendering 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.

Parameters

dialog ConfigDialog implementation to use. If NULL, the first available render system with the default options will be selected.

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.

◆ addRenderSystem()

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

◆ getAvailableRenderers()

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

◆ getRenderSystemByName()

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.

◆ setRenderSystem()

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

◆ getRenderSystem()

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

Retrieve a pointer to the currently selected render system.

◆ initialise()

RenderWindow* Ogre::Root::initialise	(	bool	autoCreateWindow,
		const String &	windowTitle = `"OGRE Render Window"`,
		const String &	customCapabilitiesConfig = `BLANKSTRING`
	)

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 Root::createRenderWindow). The window will be created based on the options currently set on the render system.
windowTitle
customCapabilitiesConfig	see useCustomRenderSystemCapabilities

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

◆ isInitialised()

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

inline

Returns whether the system is initialised or not.

◆ useCustomRenderSystemCapabilities()

void Ogre::Root::useCustomRenderSystemCapabilities ( RenderSystemCapabilities * capabilities )

Requests active RenderSystem to use custom RenderSystemCapabilities.

Remarks: This is useful for testing how the RenderSystem would behave on a machine with less advanced GPUs. This method MUST be called before creating the first RenderWindow

◆ getRemoveRenderQueueStructuresOnClear()

bool Ogre::Root::getRemoveRenderQueueStructuresOnClear ( ) const

inline

Get whether the entire render queue structure should be emptied on clearing, or whether just the objects themselves should be cleared.

◆ setRemoveRenderQueueStructuresOnClear()

void Ogre::Root::setRemoveRenderQueueStructuresOnClear ( bool r )

inline

Set whether the entire render queue structure should be emptied on clearing, or whether just the objects themselves should be cleared.

◆ addSceneManagerFactory()

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.

◆ removeSceneManagerFactory()

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

Register a new SceneManagerFactory.

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

◆ getSceneManagerMetaData() [1/2]

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.

◆ getSceneManagerMetaData() [2/2]

const SceneManagerEnumerator::MetaDataList& Ogre::Root::getSceneManagerMetaData ( ) const

get all types of SceneManager available for construction

providing some information about each one.

◆ getSceneManagerMetaDataIterator()

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

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

Deprecated:: use getMetaData()

◆ createSceneManager() [1/3]

SceneManager* Ogre::Root::createSceneManager ( )

inline

create a default scene manager

References Ogre::DefaultSceneManagerFactory::FACTORY_TYPE_NAME.

◆ createSceneManager() [2/3]

SceneManager* Ogre::Root::createSceneManager	(	const String &	typeName,
		const String &	instanceName = `BLANKSTRING`
	)

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.

◆ createSceneManager() [3/3]

SceneManager* Ogre::Root::createSceneManager	(	uint16	typeMask,
		const String &	instanceName = `BLANKSTRING`
	)

inline

Deprecated:: typeMask is obsolete

References Ogre::DefaultSceneManagerFactory::FACTORY_TYPE_NAME.

◆ destroySceneManager()

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

Destroy an instance of a SceneManager.

◆ getSceneManager()

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.

◆ hasSceneManager()

bool Ogre::Root::hasSceneManager ( const String & instanceName ) const

Identify if a SceneManager instance already exists.

Parameters

instanceName The name of the instance to retrieve.

◆ getSceneManagerIterator()

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

Get an iterator over all the existing SceneManager instances.

Deprecated:: use getSceneManagers() instead

◆ getSceneManagers()

const SceneManagerEnumerator::Instances& Ogre::Root::getSceneManagers ( void ) const

Get all the existing SceneManager instances.

◆ getTextureManager()

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.

◆ getMeshManager()

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.

◆ addFrameListener()

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

◆ removeFrameListener()

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

Removes a FrameListener from the list of listening classes.

See also: FrameListener, Root::addFrameListener

◆ queueEndRendering()

void Ogre::Root::queueEndRendering ( bool state = true )

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

◆ endRenderingQueued()

bool Ogre::Root::endRenderingQueued ( void )

Check for planned end of rendering.

Remarks: This method return true if queueEndRendering() was called before.

See also: Root, Root::queueEndRendering, Root::startRendering

◆ startRendering()

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, or if you want to run your own render loop you can update all targets on demand using Root::renderOneFrame.; 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.

◆ renderOneFrame() [1/2]

bool Ogre::Root::renderOneFrame ( void )

Updates all the render targets automatically.

Raises frame events before and after.

Overview of the render cycle

◆ renderOneFrame() [2/2]

bool Ogre::Root::renderOneFrame ( Real timeSinceLastFrame )

Updates all the render targets with custom frame time information.

Remarks: Updates all the render targets automatically and then returns, raising frame events before and after - all per-frame times are based on the time value you pass in.

◆ shutdown()

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.

◆ createFileStream()

static DataStreamPtr Ogre::Root::createFileStream	(	const String &	filename,
		const String &	groupName = `ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME`,
		bool	overwrite = `false`,
		const String &	locationPattern = `BLANKSTRING`
	)

static

Helper method to assist you in creating writeable file streams.

Remarks: This is a high-level utility method which you can use to find a place to save a file more easily. If the filename you specify is either an absolute or relative filename (ie it includes path separators), then the file will be created in the normal filesystem using that specification. If it doesn't, then the method will look for a writeable resource location via ResourceGroupManager::createResource using the other params provided.

Parameters

filename	The name of the file to create. If it includes path separators, the filesystem will be accessed direct. If no path separators are present the resource system is used, falling back on the raw filesystem after.
groupName	The name of the group in which to create the file, if the resource system is used
overwrite	If true, an existing file will be overwritten, if false an error will occur if the file already exists
locationPattern	If the resource group contains multiple locations, then usually the file will be created in the first writable location. If you want to be more specific, you can include a location pattern here and only locations which match that pattern (as determined by StringUtil::match) will be considered candidates for creation.

◆ openFileStream()

static DataStreamPtr Ogre::Root::openFileStream	(	const String &	filename,
		const String &	groupName = `ResourceGroupManager::DEFAULT_RESOURCE_GROUP_NAME`
	)

static

Helper method to assist you in accessing readable file streams.

Remarks: This is a high-level utility method which you can use to find a place to open a file more easily. It checks the resource system first, and if that fails falls back on accessing the file system directly.

Parameters

filename	The name of the file to open.
groupName	The name of the group in which to create the file, if the resource system is used

◆ convertColourValue()

static void Ogre::Root::convertColourValue	(	const ColourValue &	colour,
		uint32 *	pDest
	)

inlinestatic

Deprecated:: use ColourValue::getAsBYTE()

References Ogre::ColourValue::getAsBYTE().

◆ getAutoCreatedWindow()

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 retrieves a pointer to that window.

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

◆ createRenderWindow() [1/2]

RenderWindow* Ogre::Root::createRenderWindow	(	const String &	name,
		unsigned int	width,
		unsigned int	height,
		bool	fullScreen,
		const NameValuePairList *	miscParams = `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.

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

Parameters

name	The name of the window. Used in other methods later like setRenderTarget and getRenderTarget.
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 platforms unless indicated otherwise:

Key	Type / Values	Default	Description	Platform
title	String	RenderTarget name	The title of the window that will appear in the title bar
left	Positive integers	Centred	Screen x coordinate from left
top	Positive integers	Centred	Screen y coordinate from left
hidden	true, false	false	hide the created window
FSAA	Positive integer (usually 0, 2, 4, 8, 16)	0	Full screen antialiasing factor
gamma	true, false	false	Enable hardware conversion from linear colour space to gamma colour space on rendering to the window.
vsync	true, false	false	Synchronize buffer swaps to monitor vsync, eliminating tearing at the expense of a fixed frame rate
vsyncInterval	1, 2, 3, 4	1	If vsync is enabled, the minimum number of vertical blanks that should occur between renders. For example if vsync is enabled, the refresh rate is 60 and this is set to 2, then the frame rate will be locked at 30.
Full Screen	true, false	false	Specify whether to create the window in full screen mode
border	none, fixed, resize	resize	The type of window border (in windowed mode)	Windows, OSX
displayFrequency	Refresh rate in Hertz (e.g. 60, 75, 100)	Desktop vsync rate	Display frequency rate, for fullscreen mode
externalWindowHandle	Win32: HWND as int Linux: X11 Window as ulong OSX: OgreGLView address as an integer. You can pass NSView or NSWindow too, but should perform OgreGLView callbacks into the Ogre manually iOS: UIWindow address as an integer Emscripten: canvas selector String ("#canvas")	0 (none)	External window handle, for embedding the OGRE render in an existing window
externalGLControl	true, false	false	Let the external window control OpenGL i.e. don't select a pixel format for the window, do not change v-sync and do not swap buffer. When set to true, the calling application is responsible of OpenGL initialization and buffer swapping. It should also create an OpenGL context for its own rendering, Ogre will create one for its use. Then the calling application must also enable Ogre OpenGL context before calling any Ogre function and restore its OpenGL context after these calls.	OpenGL
currentGLContext	true, false	false	Use an externally created GL context. (Must be current)	OpenGL
minColourBufferSize	Positive integer (usually 16, 32)	16	Min total colour buffer size. See EGL_BUFFER_SIZE	OpenGL
windowProc	WNDPROC	DefWindowProc	function that processes window messages	Win 32
colourDepth	16, 32	Desktop depth	Colour depth of the resulting rendering window; only applies if fullScreen	Win32
FSAAHint	RenderSystem specific. Currently enables EQAA/ CSAA mode on D3D: if you want 4f8x (8x CSAA), set FSAA=4 and this to "f8"	Blank	FSAA mode hint	D3D
outerDimensions	true, false	false	Whether the width/height is expressed as the size of the outer window, rather than the content area	Win32
monitorIndex		-1		Win 32
monitorHandle		0 (none)		Win 32 (OpenGL)
enableDoubleClick	true, false	false	Enable the window to keep track and transmit double click messages.	Win32
useNVPerfHUD	true, false	false	Enable the use of nVidia NVPerfHUD	D3D
depthBuffer	true, false	true	Use depth buffer	D3D
NSOpenGLCPSurfaceOrder	-1 or 1	1	NSOpenGLCPSurfaceOrder	OSX
contentScalingFactor	Positive Float	The default content scaling factor of the screen	On IOS specifies the CAEAGLLayer content scaling factor. This can be useful to limit the resolution of the OpenGL ES backing store. For example, the iPhone 4's native resolution is 960 x 640. Windows are always 320 x 480, if you would like to limit the display to 720 x 480, specify 1.5 as the scaling factor.	OSX, iOS, Android
externalViewHandle	UIView pointer as an integer	0	External view handle, for rendering OGRE render in an existing view	iOS
externalViewControllerHandle	UIViewController pointer as an integer	0	External view controller handle, for embedding OGRE in an existing view controller	iOS
externalSharegroup	EAGLSharegroup pointer as an integer	0	External sharegroup, used to shared GL resources between contexts	iOS
CSAA	Positive integer (usually 0, 2, 4, 8, 16)	0	Coverage sampling factor	Android
maxColourBufferSize	Positive integer (usually 16, 32)	32	Max EGL_BUFFER_SIZE	Android
maxStencilBufferSize	Positive integer (usually 0, 8)	0	EGL_STENCIL_SIZE	Android
maxDepthBufferSize	Positive integer (usually 0, 16, 24)	16	EGL_DEPTH_SIZE	Android

◆ createRenderWindow() [2/2]

RenderWindow* Ogre::Root::createRenderWindow ( const RenderWindowDescription & desc )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

References Ogre::RenderWindowDescription::height, Ogre::RenderWindowDescription::miscParams, Ogre::RenderWindowDescription::name, Ogre::RenderWindowDescription::useFullScreen, and Ogre::RenderWindowDescription::width.

◆ detachRenderTarget() [1/2]

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

Detaches a RenderTarget from the active render system and returns a pointer to it.

Note: If the render target cannot be found, NULL is returned.

◆ detachRenderTarget() [2/2]

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

Detaches a named RenderTarget from the active render system and returns a pointer to it.

Note: If the render target cannot be found, NULL is returned.

◆ destroyRenderTarget() [1/2]

void Ogre::Root::destroyRenderTarget ( RenderTarget * target )

Destroys the given RenderTarget.

◆ destroyRenderTarget() [2/2]

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

Destroys the given named RenderTarget.

◆ getRenderTarget()

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

Retrieves a pointer to a named render target.

◆ loadPlugin()

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

Manually load a Plugin contained in a DLL / DSO.

Remarks: Plugins embedded in DLLs can be loaded at startup using the plugin configuration file specified when you create Root. This method allows you to load plugin DLLs directly in code. The DLL in question is expected to implement a dllStartPlugin method which instantiates a Plugin subclass and calls Root::installPlugin. It should also implement dllStopPlugin (see Root::unloadPlugin)

Parameters

pluginName Name of the plugin library to load

◆ unloadPlugin()

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

Manually unloads a Plugin contained in a DLL / DSO.

Remarks: Plugin DLLs are unloaded at shutdown automatically. This method allows you to unload plugins in code, but make sure their dependencies are decoupled first. This method will call the dllStopPlugin method defined in the DLL, which in turn should call Root::uninstallPlugin.

Parameters

pluginName Name of the plugin library to unload

◆ installPlugin()

void Ogre::Root::installPlugin ( Plugin * plugin )

Install a new plugin.

Remarks: This installs a new extension to OGRE. The plugin itself may be loaded from a DLL / DSO, or it might be statically linked into your own application. Either way, something has to call this method to get it registered and functioning. You should only call this method directly if your plugin is not in a DLL that could otherwise be loaded with loadPlugin, since the DLL function dllStartPlugin should call this method when the DLL is loaded.

◆ uninstallPlugin()

void Ogre::Root::uninstallPlugin ( Plugin * plugin )

Uninstall an existing plugin.

Remarks: This uninstalls an extension to OGRE. Plugins are automatically uninstalled at shutdown but this lets you remove them early. If the plugin was loaded from a DLL / DSO you should call unloadPlugin which should result in this method getting called anyway (if the DLL is well behaved).

◆ getInstalledPlugins()

const PluginInstanceList& Ogre::Root::getInstalledPlugins ( ) const

inline

Gets a read-only list of the currently installed plugins.

◆ getTimer()

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

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

◆ _fireFrameStarted() [1/2]

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.

◆ _fireFrameRenderingQueued() [1/2]

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

Method for raising frame rendering queued 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 too, to ensure that all state is updated correctly. You should call it after the windows have been updated but before the buffers are swapped, or if you are not separating the update and buffer swap, then after the update just before _fireFrameEnded.

◆ _fireFrameEnded() [1/2]

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.

◆ _fireFrameStarted() [2/2]

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.

◆ _fireFrameRenderingQueued() [2/2]

bool Ogre::Root::_fireFrameRenderingQueued ( )

Method for raising frame rendering queued 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 you may want to call this method too, although nothing in OGRE relies on this particular event. Really if you're running your own rendering loop at this level of detail then you can get the same effect as doing your updates in a frameRenderingQueued callback by just calling RenderWindow::update with the 'swapBuffers' option set to false.

◆ _fireFrameEnded() [2/2]

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.

◆ getNextFrameNumber()

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

inline

Gets the number of the next frame to be rendered.

Remarks: Note that this is 'next frame' rather than 'current frame' because it indicates the frame number that current changes made to the scene will take effect. It is incremented after all rendering commands for the current frame have been queued, thus reflecting that if you start performing changes then, you will actually see them in the next frame.

◆ _getCurrentSceneManager()

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

inline

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.

◆ _setCurrentSceneManager()

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

inline

Sets the scene manager currently being used to render.

Remarks: This is only intended for internal use.

◆ _updateAllRenderTargets() [1/2]

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

Returns: false if a FrameListener indicated it wishes to exit the render loop

◆ _updateAllRenderTargets() [2/2]

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

Internal method used for updating all RenderTarget objects (windows, renderable textures etc) which are set to auto-update, with a custom time passed to the frameRenderingQueued events.

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.

Returns: false if a FrameListener indicated it wishes to exit the render loop

◆ getSingleton()

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

static

Get the singleton instance.

◆ getSingletonPtr()

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

static

Get the singleton instance.

◆ clearEventTimes()

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

◆ setFrameSmoothingPeriod()

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

inline

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

◆ getFrameSmoothingPeriod()

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

inline

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

◆ addMovableObjectFactory()

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.

◆ removeMovableObjectFactory()

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.

◆ hasMovableObjectFactory()

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

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

◆ getMovableObjectFactory()

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

Get a MovableObjectFactory for the given type.

◆ _allocateNextMovableObjectTypeFlag()

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.

◆ getMovableObjectFactories()

const MovableObjectFactoryMap& Ogre::Root::getMovableObjectFactories ( ) const

inline

Return an iterator over all the MovableObjectFactory instances currently registered.

◆ getMovableObjectFactoryIterator()

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

Deprecated:: use getMovableObjectFactories

◆ getDisplayMonitorCount()

unsigned int Ogre::Root::getDisplayMonitorCount ( ) const

Deprecated:: do not use

◆ getWorkQueue()

WorkQueue* Ogre::Root::getWorkQueue ( ) const

inline

Get the WorkQueue for processing background tasks.

You are free to add new requests and handlers to this queue to process your custom background tasks using the shared thread pool. However, you must remember to assign yourself a new channel through which to process your tasks.

◆ setWorkQueue()

void Ogre::Root::setWorkQueue ( WorkQueue * queue )

Replace the current work queue with an alternative.

You can use this method to replace the internal implementation of WorkQueue with your own, e.g. to externalise the processing of background events. Doing so will delete the existing queue and replace it with this one.

Parameters

queue The new WorkQueue instance. Root will delete this work queue at shutdown, so do not destroy it yourself.

◆ setBlendIndicesGpuRedundant()

void Ogre::Root::setBlendIndicesGpuRedundant ( bool redundant )

inline

Sets whether blend indices information needs to be passed to the GPU.

When entities use software animation they remove blend information such as indices and weights from the vertex buffers sent to the graphic card. This function can be used to limit which information is removed.

Parameters

redundant Set to true to remove blend indices information.

◆ isBlendIndicesGpuRedundant()

bool Ogre::Root::isBlendIndicesGpuRedundant ( ) const

inline

Returns whether blend indices information needs to be passed to the GPU see setBlendIndicesGpuRedundant() for more information.

◆ setBlendWeightsGpuRedundant()

void Ogre::Root::setBlendWeightsGpuRedundant ( bool redundant )

inline

Sets whether blend weights information needs to be passed to the GPU.

When entities use software animation they remove blend information such as indices and weights from the vertex buffers sent to the graphic card. This function can be used to limit which information is removed.

Parameters

redundant Set to true to remove blend weights information.

◆ isBlendWeightsGpuRedundant()

bool Ogre::Root::isBlendWeightsGpuRedundant ( ) const

inline

Returns whether blend weights information needs to be passed to the GPU see setBlendWeightsGpuRedundant() for more information.

◆ setDefaultMinPixelSize()

void Ogre::Root::setDefaultMinPixelSize ( Real pixelSize )

inline

Set the default minimum pixel size for object to be rendered by.

Note: To use this feature see Camera::setUseMinPixelSize()

◆ getDefaultMinPixelSize()

Real Ogre::Root::getDefaultMinPixelSize ( )

inline

Get the default minimum pixel size for object to be rendered by.

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

OgreRoot.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ MovableObjectFactoryMap

◆ PluginLibList

◆ PluginInstanceList

◆ MovableObjectFactoryIterator

Constructor & Destructor Documentation

◆ Root()

◆ ~Root()

Member Function Documentation

◆ saveConfig()

◆ restoreConfig()

◆ showConfigDialog()

◆ addRenderSystem()

◆ getAvailableRenderers()

◆ getRenderSystemByName()

◆ setRenderSystem()

◆ getRenderSystem()

◆ initialise()

◆ isInitialised()

◆ useCustomRenderSystemCapabilities()

◆ getRemoveRenderQueueStructuresOnClear()

◆ setRemoveRenderQueueStructuresOnClear()

◆ addSceneManagerFactory()

◆ removeSceneManagerFactory()

◆ getSceneManagerMetaData() [1/2]

◆ getSceneManagerMetaData() [2/2]

◆ getSceneManagerMetaDataIterator()

◆ createSceneManager() [1/3]

◆ createSceneManager() [2/3]

◆ createSceneManager() [3/3]

◆ destroySceneManager()

◆ getSceneManager()

◆ hasSceneManager()

◆ getSceneManagerIterator()

◆ getSceneManagers()

◆ getTextureManager()

◆ getMeshManager()

◆ addFrameListener()

◆ removeFrameListener()

◆ queueEndRendering()

◆ endRenderingQueued()

◆ startRendering()

◆ renderOneFrame() [1/2]

◆ renderOneFrame() [2/2]

◆ shutdown()

◆ createFileStream()

◆ openFileStream()

◆ convertColourValue()

◆ getAutoCreatedWindow()

◆ createRenderWindow() [1/2]

◆ createRenderWindow() [2/2]

◆ detachRenderTarget() [1/2]

◆ detachRenderTarget() [2/2]

◆ destroyRenderTarget() [1/2]

◆ destroyRenderTarget() [2/2]

◆ getRenderTarget()

◆ loadPlugin()

◆ unloadPlugin()

◆ installPlugin()

◆ uninstallPlugin()

◆ getInstalledPlugins()

◆ getTimer()

◆ _fireFrameStarted() [1/2]

◆ _fireFrameRenderingQueued() [1/2]

◆ _fireFrameEnded() [1/2]

◆ _fireFrameStarted() [2/2]

◆ _fireFrameRenderingQueued() [2/2]

◆ _fireFrameEnded() [2/2]

◆ getNextFrameNumber()

◆ _getCurrentSceneManager()

◆ _setCurrentSceneManager()

◆ _updateAllRenderTargets() [1/2]

◆ _updateAllRenderTargets() [2/2]

◆ getSingleton()

◆ getSingletonPtr()

◆ clearEventTimes()