Ogre::PageManager Class Reference
[Paging]

The PageManager is the entry point through which you load all PagedWorld instances, and the place where PageStrategy instances and factory classes are registered to customise the paging behaviour. More...

#include <OgrePageManager.h>

Inheritance diagram for Ogre::PageManager:

[legend]

List of all members.

Classes
class	EventRouter
Public Types
typedef map< String, PagedWorld * >::type	WorldMap
typedef map< String, PageStrategy * >::type	StrategyMap
typedef map< String, PageContentCollectionFactory * > ::type	ContentCollectionFactoryMap
typedef map< String, PageContentFactory * >::type	ContentFactoryMap
typedef map< String, PagedWorldSectionFactory * > ::type	WorldSectionFactoryMap
typedef vector< Camera * >::type	CameraList
Public Member Functions
	PageManager ()
virtual	~PageManager ()
PagedWorld *	createWorld (const String &name=StringUtil::BLANK)
	Create a new PagedWorld instance.
void	destroyWorld (const String &name)
	Destroy a world.
void	destroyWorld (PagedWorld *world)
	Destroy a world.
PagedWorld *	loadWorld (const String &filename, const String &name=StringUtil::BLANK)
	Load a new PagedWorld from a file.
PagedWorld *	loadWorld (const DataStreamPtr &stream, const String &name=StringUtil::BLANK)
	Load a new PagedWorld from a stream.
void	saveWorld (PagedWorld *world, const String &filename)
	Save a PagedWorld instance to a file.
void	saveWorld (PagedWorld *world, const DataStreamPtr &stream)
	Save a PagedWorld instance to a file.
PagedWorld *	getWorld (const String &name)
	Get a named world.
const WorldMap &	getWorlds () const
	Get a reference to the worlds that are currently loaded.
void	addStrategy (PageStrategy *strategy)
	Add a new PageStrategy implementation.
void	removeStrategy (PageStrategy *strategy)
	Remove a PageStrategy implementation.
PageStrategy *	getStrategy (const String &name)
	Get a PageStrategy.
const StrategyMap &	getStrategies () const
	Get a reference to the registered strategies.
void	addContentCollectionFactory (PageContentCollectionFactory *f)
	Add a new PageContentCollectionFactory implementation.
void	removeContentCollectionFactory (PageContentCollectionFactory *f)
	Remove a PageContentCollectionFactory implementation.
PageContentCollectionFactory *	getContentCollectionFactory (const String &name)
	Get a PageContentCollectionFactory.
PageContentCollection *	createContentCollection (const String &typeName)
	Create a new instance of PageContentCollection using the registered factories.
void	destroyContentCollection (PageContentCollection *coll)
	Destroy an instance of PageContentCollection.
const ContentCollectionFactoryMap &	getContentCollectionFactories () const
	Get a reference to the registered strategies.
void	addContentFactory (PageContentFactory *f)
	Add a new PageContentFactory implementation.
void	removeContentFactory (PageContentFactory *f)
	Remove a PageContentFactory implementation.
PageContentFactory *	getContentFactory (const String &name)
	Get a PageContentFactory.
const ContentFactoryMap &	getContentFactories () const
	Get a reference to the registered strategies.
PageContent *	createContent (const String &typeName)
	Create a new instance of PageContent using the registered factories.
void	destroyContent (PageContent *c)
	Destroy an instance of PageContent.
void	addWorldSectionFactory (PagedWorldSectionFactory *f)
	Add a new PagedWorldSectionFactory implementation.
void	removeWorldSectionFactory (PagedWorldSectionFactory *f)
	Remove a PagedWorldSectionFactory implementation.
PagedWorldSectionFactory *	getWorldSectionFactory (const String &name)
	Get a PagedWorldSectionFactory.
PagedWorldSection *	createWorldSection (const String &typeName, const String &name, PagedWorld parent, SceneManager sm)
	Create a new instance of PagedWorldSection using the registered factories.
void	destroyWorldSection (PagedWorldSection *s)
	Destroy an instance of PagedWorldSection.
const WorldSectionFactoryMap &	getWorldSectionFactories () const
	Get a reference to the registered strategies.
void	setPageProvider (PageProvider *provider)
	Set the PageProvider which can provide streams for any Page.
PageProvider *	getPageProvider () const
	Get the PageProvider which can provide streams for any Page.
virtual bool	_prepareProceduralPage (Page page, PagedWorldSection section)
	Give a provider the opportunity to prepare page content procedurally.
virtual bool	_loadProceduralPage (Page page, PagedWorldSection section)
	Give a provider the opportunity to prepare page content procedurally.
virtual bool	_unloadProceduralPage (Page page, PagedWorldSection section)
	Give a manager the opportunity to unload page content procedurally.
virtual bool	_unprepareProceduralPage (Page page, PagedWorldSection section)
	Give a manager the opportunity to unprepare page content procedurally.
StreamSerialiser *	_readPageStream (PageID pageID, PagedWorldSection *section)
	Get a serialiser set up to read Page data for the given PageID.
StreamSerialiser *	_writePageStream (PageID pageID, PagedWorldSection *section)
	Get a serialiser set up to write Page data for the given PageID.
StreamSerialiser *	_readWorldStream (const String &filename)
	Get a serialiser set up to read PagedWorld data for the given world name.
StreamSerialiser *	_writeWorldStream (const String &filename)
	Get a serialiser set up to write PagedWorld data.
const String &	getPageResourceGroup () const
	Get the resource group that will be used to read/write files when the default load routines are used.
void	setPageResourceGroup (const String &g)
	Set the resource group that will be used to read/write files when the default load routines are used.
void	addCamera (Camera *c)
	Tells the paging system to start tracking a given camera.
void	removeCamera (Camera *c)
	Tells the paging system to stop tracking a given camera.
bool	hasCamera (Camera *c) const
	Returns whether or not a given camera is being watched by the paging system.
const CameraList &	getCameraList () const
	Returns a list of cameras being tracked.
void	setDebugDisplayLevel (uint8 lvl)
	Set the debug display level.
uint8	getDebugDisplayLevel () const
	Get the debug display level.
void	setPagingOperationsEnabled (bool enabled)
	Pause or unpause all paging operations.
bool	getPagingOperationsEnabled () const
	Get whether paging operations are currently allowed to happen.
void *	operator new (size_t sz, const char file, int line, const char func)
	operator new, with debug line info
void *	operator new (size_t sz)
void *	operator new (size_t sz, void *ptr)
	placement operator new
void *	operator new[] (size_t sz, const char file, int line, const char func)
	array operator new, with debug line info
void *	operator new[] (size_t sz)
void	operator delete (void *ptr)
void	operator delete (void ptr, void )
void	operator delete (void ptr, const char , int, const char *)
void	operator delete[] (void *ptr)
void	operator delete[] (void ptr, const char , int, const char *)
Protected Member Functions
void	createStandardStrategies ()
void	createStandardContentFactories ()
Protected Attributes
WorldMap	mWorlds
StrategyMap	mStrategies
ContentCollectionFactoryMap	mContentCollectionFactories
ContentFactoryMap	mContentFactories
WorldSectionFactoryMap	mWorldSectionFactories
NameGenerator	mWorldNameGenerator
PageProvider *	mPageProvider
String	mPageResourceGroup
CameraList	mCameraList
EventRouter	mEventRouter
uint8	mDebugDisplayLvl
bool	mPagingEnabled
Grid2DPageStrategy *	mGrid2DPageStrategy
Grid3DPageStrategy *	mGrid3DPageStrategy
SimplePageContentCollectionFactory *	mSimpleCollectionFactory

Detailed Description

The PageManager is the entry point through which you load all PagedWorld instances, and the place where PageStrategy instances and factory classes are registered to customise the paging behaviour.

Remarks:: To get started, the minimum you need is a PagedWorld with at least one PagedWorldSection within it, and at least one Camera being tracked (see addCamera).

Definition at line 135 of file OgrePageManager.h.

Member Typedef Documentation

typedef vector<Camera*>::type Ogre::PageManager::CameraList

Definition at line 409 of file OgrePageManager.h.

typedef map<String, PageContentCollectionFactory*>::type Ogre::PageManager::ContentCollectionFactoryMap

Definition at line 208 of file OgrePageManager.h.

typedef map<String, PageContentFactory*>::type Ogre::PageManager::ContentFactoryMap

Definition at line 238 of file OgrePageManager.h.

typedef map<String, PageStrategy*>::type Ogre::PageManager::StrategyMap

Definition at line 186 of file OgrePageManager.h.

typedef map<String, PagedWorld*>::type Ogre::PageManager::WorldMap

Definition at line 181 of file OgrePageManager.h.

typedef map<String, PagedWorldSectionFactory*>::type Ogre::PageManager::WorldSectionFactoryMap

Definition at line 269 of file OgrePageManager.h.

Constructor & Destructor Documentation

Ogre::PageManager::PageManager ( )

virtual Ogre::PageManager::~PageManager ( ) [virtual]

Member Function Documentation

virtual bool Ogre::PageManager::_loadProceduralPage	(	Page *	page,
		PagedWorldSection *	section
	)			`[virtual]`

Give a provider the opportunity to prepare page content procedurally.

Remarks:: You should not call this method directly. This call will happen in the main render thread so it can access GPU resources. Use _prepareProceduralPage for background preparation.

Returns:: true if the page was populated, false otherwise

virtual bool Ogre::PageManager::_prepareProceduralPage	(	Page *	page,
		PagedWorldSection *	section
	)			`[virtual]`

Give a provider the opportunity to prepare page content procedurally.

Remarks:: You should not call this method directly. This call may well happen in a separate thread so it should not access GPU resources, use _loadProceduralPage for that

Returns:: true if the page was populated, false otherwise

StreamSerialiser* Ogre::PageManager::_readPageStream	(	PageID	pageID,
		PagedWorldSection *	section
	)

Get a serialiser set up to read Page data for the given PageID.

Parameters:

	pageID	The ID of the page being requested
	section	The parent section to which this page will belong

Remarks:: The StreamSerialiser returned is the responsibility of the caller to delete.

StreamSerialiser* Ogre::PageManager::_readWorldStream ( const String & filename )

Get a serialiser set up to read PagedWorld data for the given world name.

Remarks:: The StreamSerialiser returned is the responsibility of the caller to delete.

virtual bool Ogre::PageManager::_unloadProceduralPage	(	Page *	page,
		PagedWorldSection *	section
	)			`[virtual]`

Give a manager the opportunity to unload page content procedurally.

Remarks:: You should not call this method directly. This call will happen in the main render thread so it can access GPU resources. Use _unprepareProceduralPage for background preparation.

Returns:: true if the page was populated, false otherwise

virtual bool Ogre::PageManager::_unprepareProceduralPage	(	Page *	page,
		PagedWorldSection *	section
	)			`[virtual]`

Give a manager the opportunity to unprepare page content procedurally.

Remarks:: You should not call this method directly. This call may well happen in a separate thread so it should not access GPU resources, use _unloadProceduralPage for that

Returns:: true if the page was unpopulated, false otherwise

StreamSerialiser* Ogre::PageManager::_writePageStream	(	PageID	pageID,
		PagedWorldSection *	section
	)

Get a serialiser set up to write Page data for the given PageID.

Parameters:

	pageID	The ID of the page being requested
	section	The parent section to which this page will belong

Remarks:: The StreamSerialiser returned is the responsibility of the caller to delete.

StreamSerialiser* Ogre::PageManager::_writeWorldStream ( const String & filename )

Get a serialiser set up to write PagedWorld data.

Remarks:: The StreamSerialiser returned is the responsibility of the caller to delete.

void Ogre::PageManager::addCamera ( Camera * c )

Tells the paging system to start tracking a given camera.

Remarks:: In order for the paging system to funciton it needs to know which Cameras to track. You may not want to have all your cameras affect the paging system, so just add the cameras you want it to keep track of here.

void Ogre::PageManager::addContentCollectionFactory ( PageContentCollectionFactory * f )

Add a new PageContentCollectionFactory implementation.

Remarks:: The caller remains resonsible for destruction of this instance.

void Ogre::PageManager::addContentFactory ( PageContentFactory * f )

Add a new PageContentFactory implementation.

Remarks:: The caller remains resonsible for destruction of this instance.

void Ogre::PageManager::addStrategy ( PageStrategy * strategy )

Add a new PageStrategy implementation.

Remarks:: The caller remains resonsible for destruction of this instance.

void Ogre::PageManager::addWorldSectionFactory ( PagedWorldSectionFactory * f )

Add a new PagedWorldSectionFactory implementation.

Remarks:: The caller remains resonsible for destruction of this instance.

PageContent* Ogre::PageManager::createContent ( const String & typeName )

Create a new instance of PageContent using the registered factories.

Parameters:

typeName

The name of the type of content to create

PageContentCollection* Ogre::PageManager::createContentCollection ( const String & typeName )

Create a new instance of PageContentCollection using the registered factories.

Parameters:

typeName

The name of the type of collection to create

void Ogre::PageManager::createStandardContentFactories ( ) [protected]

void Ogre::PageManager::createStandardStrategies ( ) [protected]

PagedWorld* Ogre::PageManager::createWorld ( const String & name = StringUtil::BLANK )

Create a new PagedWorld instance.

Parameters:

name

Optionally give a name to the world (if no name is given, one will be generated).

PagedWorldSection* Ogre::PageManager::createWorldSection	(	const String &	typeName,
		const String &	name,
		PagedWorld *	parent,
		SceneManager *	sm
	)

Create a new instance of PagedWorldSection using the registered factories.

Parameters:

	typeName	The name of the type of collection to create
	name	The instance name
	parent	The parent world
	sm	The SceneManager to use (can be null if this is to be loaded)

void Ogre::PageManager::destroyContent ( PageContent * c )

Destroy an instance of PageContent.

void Ogre::PageManager::destroyContentCollection ( PageContentCollection * coll )

Destroy an instance of PageContentCollection.

void Ogre::PageManager::destroyWorld ( PagedWorld * world )

Destroy a world.

void Ogre::PageManager::destroyWorld ( const String & name )

Destroy a world.

void Ogre::PageManager::destroyWorldSection ( PagedWorldSection * s )

Destroy an instance of PagedWorldSection.

const CameraList& Ogre::PageManager::getCameraList ( ) const

Returns a list of cameras being tracked.

const ContentCollectionFactoryMap& Ogre::PageManager::getContentCollectionFactories ( ) const

Get a reference to the registered strategies.

PageContentCollectionFactory* Ogre::PageManager::getContentCollectionFactory ( const String & name )

Get a PageContentCollectionFactory.

Parameters:

name

The name of the factory to retrieve

Returns:: Pointer to a PageContentCollectionFactory, or null if the ContentCollection was not found.

const ContentFactoryMap& Ogre::PageManager::getContentFactories ( ) const

Get a reference to the registered strategies.

PageContentFactory* Ogre::PageManager::getContentFactory ( const String & name )

Get a PageContentFactory.

Parameters:

name

The name of the factory to retrieve

Returns:: Pointer to a PageContentFactory, or null if the Content was not found.

uint8 Ogre::PageManager::getDebugDisplayLevel ( ) const

Get the debug display level.

Definition at line 424 of file OgrePageManager.h.

PageProvider* Ogre::PageManager::getPageProvider ( ) const

Get the PageProvider which can provide streams for any Page.

Definition at line 318 of file OgrePageManager.h.

const String& Ogre::PageManager::getPageResourceGroup ( ) const

Get the resource group that will be used to read/write files when the default load routines are used.

Definition at line 386 of file OgrePageManager.h.

bool Ogre::PageManager::getPagingOperationsEnabled ( ) const

Get whether paging operations are currently allowed to happen.

Definition at line 435 of file OgrePageManager.h.

const StrategyMap& Ogre::PageManager::getStrategies ( ) const

Get a reference to the registered strategies.

PageStrategy* Ogre::PageManager::getStrategy ( const String & name )

Get a PageStrategy.

Parameters:

name

The name of the strategy to retrieve

Returns:: Pointer to a PageStrategy, or null if the strategy was not found.

PagedWorld* Ogre::PageManager::getWorld ( const String & name )

Get a named world.

name The name of the world (not a filename, the identifying name)

Returns:: The world, or null if the world doesn't exist.

const WorldMap& Ogre::PageManager::getWorlds ( ) const

Get a reference to the worlds that are currently loaded.

Definition at line 183 of file OgrePageManager.h.

const WorldSectionFactoryMap& Ogre::PageManager::getWorldSectionFactories ( ) const

Get a reference to the registered strategies.

PagedWorldSectionFactory* Ogre::PageManager::getWorldSectionFactory ( const String & name )

Get a PagedWorldSectionFactory.

Parameters:

name

The name of the factory to retrieve

Returns:: Pointer to a PagedWorldSectionFactory, or null if the WorldSection was not found.

bool Ogre::PageManager::hasCamera ( Camera * c ) const

Returns whether or not a given camera is being watched by the paging system.

PagedWorld* Ogre::PageManager::loadWorld	(	const DataStreamPtr &	stream,
		const String &	name = `StringUtil::BLANK`
	)

Load a new PagedWorld from a stream.

Parameters:

	stream	A stream from which to load the world data
	name	Optionally give a name to the world (if no name is given, one will be generated).

PagedWorld* Ogre::PageManager::loadWorld	(	const String &	filename,
		const String &	name = `StringUtil::BLANK`
	)

Load a new PagedWorld from a file.

Parameters:

	filename	The name of the file to load (standard is .world)
	name	Optionally give a name to the world (if no name is given, one will be generated).

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete	(	void *	ptr,
		const char *	,
		int	,
		const char *
	)			`[inherited]`

Definition at line 107 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete	(	void *	ptr,
		void *
	)			`[inherited]`

Definition at line 101 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete ( void * ptr ) [inherited]

Definition at line 95 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[]	(	void *	ptr,
		const char *	,
		int	,
		const char *
	)			`[inherited]`

Definition at line 118 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[] ( void * ptr ) [inherited]

Definition at line 112 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new	(	size_t	sz,
		void *	ptr
	)			`[inherited]`

placement operator new

Definition at line 78 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new ( size_t sz ) [inherited]

Definition at line 72 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new	(	size_t	sz,
		const char *	file,
		int	line,
		const char *	func
	)			`[inherited]`

operator new, with debug line info

Definition at line 67 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[] ( size_t sz ) [inherited]

Definition at line 90 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[]	(	size_t	sz,
		const char *	file,
		int	line,
		const char *	func
	)			`[inherited]`

array operator new, with debug line info

Definition at line 85 of file OgreMemoryAllocatedObject.h.

void Ogre::PageManager::removeCamera ( Camera * c )

Tells the paging system to stop tracking a given camera.

void Ogre::PageManager::removeContentCollectionFactory ( PageContentCollectionFactory * f )

Remove a PageContentCollectionFactory implementation.

void Ogre::PageManager::removeContentFactory ( PageContentFactory * f )

Remove a PageContentFactory implementation.

void Ogre::PageManager::removeStrategy ( PageStrategy * strategy )

Remove a PageStrategy implementation.

void Ogre::PageManager::removeWorldSectionFactory ( PagedWorldSectionFactory * f )

Remove a PagedWorldSectionFactory implementation.

void Ogre::PageManager::saveWorld	(	PagedWorld *	world,
		const DataStreamPtr &	stream
	)

Save a PagedWorld instance to a file.

Parameters:

	world	The world to be saved
	stream	The stream to save the data to

void Ogre::PageManager::saveWorld	(	PagedWorld *	world,
		const String &	filename
	)

Save a PagedWorld instance to a file.

Parameters:

	world	The world to be saved
	filename	The filename to save the data to
	arch	The Archive that filename is relative to (optional)

void Ogre::PageManager::setDebugDisplayLevel ( uint8 lvl )

Set the debug display level.

Remarks:: This setting controls how much debug information is displayed in the scene. The exact interpretation of this value depends on the PageStrategy you're using, and whether the PageContent decides to also display debug information. Generally speaking, 0 means no debug display, 1 means simple debug display (usually the PageStrategy) and anything more than that is up to the classes involved.

Definition at line 422 of file OgrePageManager.h.

void Ogre::PageManager::setPageProvider ( PageProvider * provider )

Set the PageProvider which can provide streams for any Page.

Remarks:: This is the top-level way that you can direct how Page data is loaded. When data for a Page is requested for a PagedWorldSection, the following sequence of classes will be checked to see if they have a provider willing to supply the stream: PagedWorldSection, PagedWorld, PageManager. If none of these do, then the default behaviour is to look for a file called worldname_sectionname_pageID.page.