A world section which includes paged terrain. More...

#include <OgreTerrainPagedWorldSection.h>

Inheritance diagram for Ogre::TerrainPagedWorldSection:

Classes
class	TerrainDefiner
Public Types
typedef map< PageID, Page * >::type	PageMap
Public Member Functions
	TerrainPagedWorldSection (const String &name, PagedWorld parent, SceneManager sm)
	Constructor.
virtual	~TerrainPagedWorldSection ()
virtual bool	_loadProceduralPage (Page *page)
	Give a section the opportunity to prepare page content procedurally.
virtual bool	_prepareProceduralPage (Page *page)
	Give a section the opportunity to prepare page content procedurally.
virtual StreamSerialiser *	_readPageStream (PageID pageID)
	Get a serialiser set up to read Page data for the given PageID.
virtual bool	_unloadProceduralPage (Page *page)
	Give a section the opportunity to unload page content procedurally.
virtual bool	_unprepareProceduralPage (Page *page)
	Give a section the opportunity to unprepare page content procedurally.
virtual StreamSerialiser *	_writePageStream (PageID pageID)
	Get a serialiser set up to write Page data for the given PageID.
virtual bool	canHandleRequest (const Request req, const WorkQueue srcQ)
	Return whether this handler can process a given request.
virtual bool	canHandleResponse (const Response res, const WorkQueue srcQ)
	Return whether this handler can process a given response.
virtual void	frameEnd (Real timeElapsed)
	Called when the frame ends.
virtual void	frameStart (Real timeSinceLastFrame)
	Called when the frame starts.
virtual const AxisAlignedBox &	getBoundingBox () const
	Get the bounds of this section.
virtual Grid2DPageStrategy *	getGridStrategy () const
	Convenience method - this section always uses a grid strategy.
virtual Grid2DPageStrategyData *	getGridStrategyData () const
	Convenience method - this section always uses a grid strategy.
virtual Real	getHoldRadius ()
	Get the Holding radius.
virtual uint32	getLoadingIntervalMs () const
	Get the interval between the loading of single pages in milliseconds (ms)
virtual Real	getLoadRadius () const
	Get the loading radius.
PageManager *	getManager () const
virtual const String &	getName () const
	Get the name of this section.
virtual Page *	getPage (PageID pageID)
	Retrieves a Page.
virtual PageID	getPageID (const Vector3 &worldPos)
	Get the page ID for a given world position.
virtual PageProvider *	getPageProvider () const
	Get the PageProvider which can provide streams for Pages in this section.
virtual int32	getPageRangeMaxX () const
	get the index range of all Pages (values outside this will be ignored)
virtual int32	getPageRangeMaxY () const
	get the index range of all Pages (values outside this will be ignored)
virtual int32	getPageRangeMinX () const
	get the index range of all Pages (values outside this will be ignored)
virtual int32	getPageRangeMinY () const
	get the index range of all Pages (values outside this will be ignored)
virtual SceneManager *	getSceneManager () const
	Get the current SceneManager.
virtual PageStrategy *	getStrategy () const
	Get the page strategy which this section is using.
virtual PageStrategyData *	getStrategyData () const
	Get the data required by the PageStrategy which is specific to this world section.
virtual TerrainGroup *	getTerrainGroup ()
	Get the TerrainGroup which this world section is using.
virtual const String &	getType ()
	Get the type name of this section.
virtual PagedWorld *	getWorld () const
	Get the parent world.
WorkQueue::Response *	handleRequest (const WorkQueue::Request req, const WorkQueue srcQ)
	WorkQueue::RequestHandler override.
void	handleResponse (const WorkQueue::Response res, const WorkQueue srcQ)
	WorkQueue::ResponseHandler override.
virtual void	holdPage (PageID pageID)
	Ask for a page to be kept in memory if it's loaded.
virtual void	init (TerrainGroup *grp)
	Initialise this section from an existing TerrainGroup instance.
virtual bool	load (StreamSerialiser &stream)
	Load this section from a stream (returns true if successful)
virtual Page *	loadOrCreatePage (const Vector3 &worldPos)
	Load or create a page against this section covering the given world space position.
void	loadPage (PageID pageID, bool forceSynchronous=false)
	Overridden from PagedWorldSection.
virtual void	notifyCamera (Camera *cam)
	Notify a section of the current camera.
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 *)
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)
virtual void	removeAllPages ()
	Remove all pages immediately.
virtual void	save (StreamSerialiser &stream)
	Save this section to a stream.
virtual void	setBoundingBox (const AxisAlignedBox &box)
	Set the bounds of this section.
void	setDefiner (TerrainDefiner *terrainDefiner)
virtual void	setHoldRadius (Real sz)
	Set the Holding radius.
virtual void	setLoadingIntervalMs (uint32 loadingIntervalMs)
	Set the interval between the loading of single pages in milliseconds (ms)
virtual void	setLoadRadius (Real sz)
	Set the loading radius.
virtual void	setPageProvider (PageProvider *provider)
	Set the PageProvider which can provide streams Pages in this section.
virtual void	setPageRange (int32 minX, int32 minY, int32 maxX, int32 maxY)
	Set the index range of all Pages (values outside this will be ignored)
virtual void	setPageRangeMaxX (int32 maxX)
	Set the index range of all Pages (values outside this will be ignored)
virtual void	setPageRangeMaxY (int32 maxY)
	Set the index range of all Pages (values outside this will be ignored)
virtual void	setPageRangeMinX (int32 minX)
	Set the index range of all Pages (values outside this will be ignored)
virtual void	setPageRangeMinY (int32 minY)
	Set the index range of all Pages (values outside this will be ignored)
virtual void	setSceneManager (SceneManager *sm)
	Change the SceneManager.
virtual void	setSceneManager (const String &smName)
	Change the SceneManager.
virtual void	setStrategy (PageStrategy *strat)
	Change the page strategy.
virtual void	setStrategy (const String &stratName)
	Change the page strategy.
void	unloadPage (PageID pageID, bool forceSynchronous=false)
	Overridden from PagedWorldSection.
virtual void	unloadPage (Page *p, bool forceSynchronous=false)
	Ask for a page to be unloaded with the given (section-relative) PageID.
Static Public Attributes
static const uint32	CHUNK_ID
static const uint16	CHUNK_VERSION
static const uint16	WORKQUEUE_LOAD_TERRAIN_PAGE_REQUEST
Protected Member Functions
void	loadSubtypeData (StreamSerialiser &ser)
	Overridden from PagedWorldSection.
void	saveSubtypeData (StreamSerialiser &ser)
virtual void	syncSettings ()
Protected Attributes
AxisAlignedBox	mAABB
bool	mHasRunningTasks
uint32	mLoadingIntervalMs
String	mName
unsigned long	mNextLoadingTime
PageProvider *	mPageProvider
PageMap	mPages
std::list< PageID >	mPagesInLoading
PagedWorld *	mParent
SceneManager *	mSceneMgr
PageStrategy *	mStrategy
PageStrategyData *	mStrategyData
TerrainDefiner *	mTerrainDefiner
TerrainGroup *	mTerrainGroup
uint16	mWorkQueueChannel
Friends
_OgrePagingExport friend std::ostream &	operator<< (std::ostream &o, const PagedWorldSection &p)
	Function for writing to a stream.

Detailed Description

A world section which includes paged terrain.

Remarks:: Rather than implement terrain paging as a PageContent subclass, because terrain benefits from direct knowledge of neighbour arrangements and the tight coupling between that and the paging strategy, instead we use a PagedWorldSection subclass. This automatically provides a PageStrategy subclass of the correct type (Grid2DPageStrategy) and derives the correct settings for it compared to the terrain being used. This frees the user from having to try to match all these up through the generic interfaces.

: When creating this in code, the user should make use of the helper functions on the TerrainPaging class. The basic sequence is that you define your terrain settings in a TerrainGroup, and then create an instance of TerrainPagedWorldSection via TerrainPaging::createWorldSection. That's basically all there is to it - the normal rules of TerrainGroup apply, it's just that instead of having to choose when to try to load / unload pages from the TerrainGroup, that is automatically done by the paging system. You can also create other types of content in this PagedWorldSection other than terrain, it's just that this comes with terrain handling built-in.

: When this world data is saved, you basically get 3 sets of data - firstly the top-level 'world data' which is where the definition of the world sections are stored (and hence, the definition of this class, although none of the terrain instance content is included). Secondly, you get a number of .page files which include any other content that you might have inserted into the pages. Lastly, you get the standard terrain data files which are saved as per TerrainGroup.

Definition at line 81 of file OgreTerrainPagedWorldSection.h.

Member Typedef Documentation

typedef map<PageID, Page*>::type Ogre::PagedWorldSection::PageMap [inherited]

Definition at line 72 of file OgrePagedWorldSection.h.

Constructor & Destructor Documentation

Ogre::TerrainPagedWorldSection::TerrainPagedWorldSection	(	const String &	name,
		PagedWorld *	parent,
		SceneManager *	sm
	)

Constructor.

Parameters:

name	The name of the section
parent	The parent world
sm	The SceneManager to use (can be left as null if to be loaded)

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

Member Function Documentation

virtual bool Ogre::PagedWorldSection::_loadProceduralPage ( Page * page ) [virtual, inherited]

Give a section 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::PagedWorldSection::_prepareProceduralPage ( Page * page ) [virtual, inherited]

Give a section 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

virtual StreamSerialiser* Ogre::PagedWorldSection::_readPageStream ( PageID pageID ) [virtual, inherited]

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

Parameters:

pageID The ID of the page being requested

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

virtual bool Ogre::PagedWorldSection::_unloadProceduralPage ( Page * page ) [virtual, inherited]

Give a section 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::PagedWorldSection::_unprepareProceduralPage ( Page * page ) [virtual, inherited]

Give a section 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

virtual StreamSerialiser* Ogre::PagedWorldSection::_writePageStream ( PageID pageID ) [virtual, inherited]

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

Parameters:

pageID The ID of the page being requested

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

virtual bool Ogre::WorkQueue::RequestHandler::canHandleRequest	(	const Request *	req,
		const WorkQueue *	srcQ
	)		`[virtual, inherited]`

Return whether this handler can process a given request.

Remarks:: Defaults to true, but if you wish to add several handlers each of which deal with different types of request, you can override this method.

Reimplemented in Ogre::Terrain, Ogre::TerrainGroup, Ogre::ResourceBackgroundQueue, Ogre::Page, and Ogre::TerrainLodManager.

Definition at line 173 of file OgreWorkQueue.h.

References Ogre::WorkQueue::Request::getAborted().

virtual bool Ogre::WorkQueue::ResponseHandler::canHandleResponse	(	const Response *	res,
		const WorkQueue *	srcQ
	)		`[virtual, inherited]`

Return whether this handler can process a given response.

Remarks:: Defaults to true, but if you wish to add several handlers each of which deal with different types of response, you can override this method.

Reimplemented in Ogre::Terrain, Ogre::TerrainGroup, Ogre::ResourceBackgroundQueue, Ogre::Page, and Ogre::TerrainLodManager.

Definition at line 208 of file OgreWorkQueue.h.

References Ogre::WorkQueue::Request::getAborted(), and Ogre::WorkQueue::Response::getRequest().

virtual void Ogre::PagedWorldSection::frameEnd ( Real timeElapsed ) [virtual, inherited]

Called when the frame ends.

virtual void Ogre::PagedWorldSection::frameStart ( Real timeSinceLastFrame ) [virtual, inherited]

Called when the frame starts.

virtual const AxisAlignedBox& Ogre::PagedWorldSection::getBoundingBox ( ) const [virtual, inherited]

Get the bounds of this section.

virtual Grid2DPageStrategy* Ogre::TerrainPagedWorldSection::getGridStrategy ( ) const [virtual]

Convenience method - this section always uses a grid strategy.

virtual Grid2DPageStrategyData* Ogre::TerrainPagedWorldSection::getGridStrategyData ( ) const [virtual]

Convenience method - this section always uses a grid strategy.

virtual Real Ogre::TerrainPagedWorldSection::getHoldRadius ( ) [virtual]

Get the Holding radius.

virtual uint32 Ogre::TerrainPagedWorldSection::getLoadingIntervalMs ( ) const [virtual]

Get the interval between the loading of single pages in milliseconds (ms)

virtual Real Ogre::TerrainPagedWorldSection::getLoadRadius ( ) const [virtual]

Get the loading radius.

PageManager* Ogre::PagedWorldSection::getManager ( ) const [inherited]

virtual const String& Ogre::PagedWorldSection::getName ( void ) const [virtual, inherited]

Get the name of this section.

Definition at line 99 of file OgrePagedWorldSection.h.

virtual Page* Ogre::PagedWorldSection::getPage ( PageID pageID ) [virtual, inherited]

Retrieves a Page.

Remarks:: This method will only return Page instances that are already loaded. It will return null if a page is not loaded.

virtual PageID Ogre::PagedWorldSection::getPageID ( const Vector3 & worldPos ) [virtual, inherited]

Get the page ID for a given world position.

virtual PageProvider* Ogre::PagedWorldSection::getPageProvider ( ) const [virtual, inherited]

Get the PageProvider which can provide streams for Pages in this section.

Definition at line 271 of file OgrePagedWorldSection.h.

virtual int32 Ogre::TerrainPagedWorldSection::getPageRangeMaxX ( ) const [virtual]

get the index range of all Pages (values outside this will be ignored)

virtual int32 Ogre::TerrainPagedWorldSection::getPageRangeMaxY ( ) const [virtual]

get the index range of all Pages (values outside this will be ignored)

virtual int32 Ogre::TerrainPagedWorldSection::getPageRangeMinX ( ) const [virtual]

get the index range of all Pages (values outside this will be ignored)

virtual int32 Ogre::TerrainPagedWorldSection::getPageRangeMinY ( ) const [virtual]

get the index range of all Pages (values outside this will be ignored)

virtual SceneManager* Ogre::PagedWorldSection::getSceneManager ( ) const [virtual, inherited]

Get the current SceneManager.

Definition at line 130 of file OgrePagedWorldSection.h.

virtual PageStrategy* Ogre::PagedWorldSection::getStrategy ( ) const [virtual, inherited]

Get the page strategy which this section is using.

Definition at line 101 of file OgrePagedWorldSection.h.

virtual PageStrategyData* Ogre::PagedWorldSection::getStrategyData ( ) const [virtual, inherited]

Get the data required by the PageStrategy which is specific to this world section.

Definition at line 135 of file OgrePagedWorldSection.h.

virtual TerrainGroup* Ogre::TerrainPagedWorldSection::getTerrainGroup ( ) [virtual]

Get the TerrainGroup which this world section is using.

Remarks:: For information, you can use the returned TerrainGroup to convert to/from x/y locations and the pageID, since the grid strategy is the same.

Definition at line 109 of file OgreTerrainPagedWorldSection.h.

virtual const String& Ogre::PagedWorldSection::getType ( ) [virtual, inherited]

Get the type name of this section.

virtual PagedWorld* Ogre::PagedWorldSection::getWorld ( ) const [virtual, inherited]

Get the parent world.

Definition at line 133 of file OgrePagedWorldSection.h.

WorkQueue::Response* Ogre::TerrainPagedWorldSection::handleRequest	(	const WorkQueue::Request *	req,
		const WorkQueue *	srcQ
	)		`[virtual]`

WorkQueue::RequestHandler override.

Implements Ogre::WorkQueue::RequestHandler.

void Ogre::TerrainPagedWorldSection::handleResponse	(	const WorkQueue::Response *	res,
		const WorkQueue *	srcQ
	)		`[virtual]`

WorkQueue::ResponseHandler override.

Implements Ogre::WorkQueue::ResponseHandler.

virtual void Ogre::PagedWorldSection::holdPage ( PageID pageID ) [virtual, inherited]

Ask for a page to be kept in memory if it's loaded.

Remarks:: This method indicates that a page should be retained if it's already in memory, but if it's not then it won't trigger a load. This is useful for retaining pages that have just gone out of range, but which you don't want to unload just yet because it's quite possible they may come back into the active set again very quickly / easily. But at the same time, if they've already been purged you don't want to force them to load. This is the 'maybe' region of pages.

: Any Page that is neither requested nor held in a frame will be deemed a candidate for unloading.

virtual void Ogre::TerrainPagedWorldSection::init ( TerrainGroup * grp ) [virtual]

Initialise this section from an existing TerrainGroup instance.

Remarks:: This is the route you will take if you're defining this world section from scratch in code. The other alternative is that you'll be loading this section from a file, in which case all the settings will be derived from that.

Parameters:

grp	The TerrainGroup which will form the basis of this world section. The instance will be owned by this class from now on and will be destroyed by it.

virtual bool Ogre::PagedWorldSection::load ( StreamSerialiser & stream ) [virtual, inherited]

Load this section from a stream (returns true if successful)

virtual Page* Ogre::PagedWorldSection::loadOrCreatePage ( const Vector3 & worldPos ) [virtual, inherited]

Load or create a page against this section covering the given world space position.

Remarks:: This method is designed mainly for editors - it will try to load an existing page if there is one, otherwise it will create a new one synchronously.

void Ogre::TerrainPagedWorldSection::loadPage	(	PageID	pageID,
		bool	forceSynchronous = `false`
	)		`[virtual]`

Overridden from PagedWorldSection.

Reimplemented from Ogre::PagedWorldSection.

void Ogre::TerrainPagedWorldSection::loadSubtypeData ( StreamSerialiser & ser ) [protected, virtual]

Overridden from PagedWorldSection.

Reimplemented from Ogre::PagedWorldSection.

virtual void Ogre::PagedWorldSection::notifyCamera ( Camera * cam ) [virtual, inherited]

Notify a section of the current camera.

template<class Alloc >

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

Definition at line 96 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 102 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 108 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 113 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 119 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 68 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 73 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 79 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 86 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

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

Definition at line 91 of file OgreMemoryAllocatedObject.h.

virtual void Ogre::PagedWorldSection::removeAllPages ( ) [virtual, inherited]

Remove all pages immediately.

Remarks:: Effectively 'resets' this section by deleting all pages.

virtual void Ogre::PagedWorldSection::save ( StreamSerialiser & stream ) [virtual, inherited]

Save this section to a stream.

void Ogre::TerrainPagedWorldSection::saveSubtypeData ( StreamSerialiser & ser ) [protected, virtual]

Reimplemented from Ogre::PagedWorldSection.

virtual void Ogre::PagedWorldSection::setBoundingBox ( const AxisAlignedBox & box ) [virtual, inherited]

Set the bounds of this section.

void Ogre::TerrainPagedWorldSection::setDefiner ( TerrainDefiner * terrainDefiner )

Definition at line 170 of file OgreTerrainPagedWorldSection.h.

References OGRE_DELETE.

virtual void Ogre::TerrainPagedWorldSection::setHoldRadius ( Real sz ) [virtual]

Set the Holding radius.

virtual void Ogre::TerrainPagedWorldSection::setLoadingIntervalMs ( uint32 loadingIntervalMs ) [virtual]

Set the interval between the loading of single pages in milliseconds (ms)

virtual void Ogre::TerrainPagedWorldSection::setLoadRadius ( Real sz ) [virtual]

Set the loading radius.

virtual void Ogre::PagedWorldSection::setPageProvider ( PageProvider * provider ) [virtual, inherited]

Set the PageProvider which can provide streams Pages in this section.

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.

Note:: The caller remains responsible for the destruction of the provider.

Definition at line 268 of file OgrePagedWorldSection.h.

virtual void Ogre::TerrainPagedWorldSection::setPageRange	(	int32	minX,
		int32	minY,
		int32	maxX,
		int32	maxY
	)		`[virtual]`