OGRE-Next  4.0.0unstable
Object-Oriented Graphics Rendering Engine
Ogre::PagedWorldSection Class Reference

Represents a section of the PagedWorld which uses a given PageStrategy, and which is made up of a generally localised set of Page instances. More...

#include <OgrePagedWorldSection.h>

+ Inheritance diagram for Ogre::PagedWorldSection:

Public Types

typedef map< PageID, Page * >::type PageMap
 

Public Member Functions

 PagedWorldSection (const String &name, PagedWorld *parent, SceneManager *sm)
 Construct a new instance, specifying the parent and scene manager. More...
 
virtual ~PagedWorldSection ()
 
virtual bool _loadProceduralPage (Page *page)
 Give a section the opportunity to prepare page content procedurally. More...
 
virtual bool _prepareProceduralPage (Page *page)
 Give a section the opportunity to prepare page content procedurally. More...
 
virtual StreamSerialiser_readPageStream (PageID pageID)
 Get a serialiser set up to read Page data for the given PageID. More...
 
virtual bool _unloadProceduralPage (Page *page)
 Give a section the opportunity to unload page content procedurally. More...
 
virtual bool _unprepareProceduralPage (Page *page)
 Give a section the opportunity to unprepare page content procedurally. More...
 
virtual StreamSerialiser_writePageStream (PageID pageID)
 Get a serialiser set up to write Page data for the given PageID. More...
 
virtual void frameEnd (Real timeElapsed)
 Called when the frame ends. More...
 
virtual void frameStart (Real timeSinceLastFrame)
 Called when the frame starts. More...
 
virtual const AxisAlignedBoxgetBoundingBox () const
 Get the bounds of this section. More...
 
PageManagergetManager () const
 
virtual const StringgetName () const
 Get the name of this section. More...
 
virtual PagegetPage (PageID pageID)
 Retrieves a Page. More...
 
virtual PageID getPageID (const Vector3 &worldPos)
 Get the page ID for a given world position. More...
 
virtual PageProvidergetPageProvider () const
 Get the PageProvider which can provide streams for Pages in this section. More...
 
virtual SceneManagergetSceneManager () const
 Get the current SceneManager. More...
 
virtual PageStrategygetStrategy () const
 Get the page strategy which this section is using. More...
 
virtual PageStrategyDatagetStrategyData () const
 Get the data required by the PageStrategy which is specific to this world section. More...
 
virtual const StringgetType ()
 Get the type name of this section. More...
 
virtual PagedWorldgetWorld () const
 Get the parent world. More...
 
virtual void holdPage (PageID pageID)
 Ask for a page to be kept in memory if it's loaded. More...
 
virtual bool load (StreamSerialiser &stream)
 Load this section from a stream (returns true if successful) More...
 
virtual PageloadOrCreatePage (const Vector3 &worldPos)
 Load or create a page against this section covering the given world space position. More...
 
virtual void loadPage (PageID pageID, bool forceSynchronous=false)
 Ask for a page to be loaded with the given (section-relative) PageID. More...
 
virtual void notifyCamera (Camera *cam)
 Notify a section of the current camera. More...
 
virtual void removeAllPages ()
 Remove all pages immediately. More...
 
virtual void save (StreamSerialiser &stream)
 Save this section to a stream. More...
 
virtual void setBoundingBox (const AxisAlignedBox &box)
 Set the bounds of this section. More...
 
virtual void setPageProvider (PageProvider *provider)
 Set the PageProvider which can provide streams Pages in this section. More...
 
virtual void setSceneManager (const String &smName)
 Change the SceneManager. More...
 
virtual void setSceneManager (SceneManager *sm)
 Change the SceneManager. More...
 
virtual void setStrategy (const String &stratName)
 Change the page strategy. More...
 
virtual void setStrategy (PageStrategy *strat)
 Change the page strategy. More...
 
virtual void unloadPage (Page *p, bool forceSynchronous=false)
 Ask for a page to be unloaded with the given (section-relative) PageID. More...
 
virtual void unloadPage (PageID pageID, bool forceSynchronous=false)
 Ask for a page to be unloaded with the given (section-relative) PageID. More...
 

Static Public Attributes

static const uint32 CHUNK_ID
 
static const uint16 CHUNK_VERSION
 

Detailed Description

Represents a section of the PagedWorld which uses a given PageStrategy, and which is made up of a generally localised set of Page instances.

Remarks
The reason for PagedWorldSection is that you may wish to cater for multiple sections of your world which use a different approach to paging (ie a different PageStrategy), or which are significantly far apart or separate that the parameters you want to pass to the PageStrategy are different.
PagedWorldSection instances are fully contained within the PagedWorld and their definitions are loaded in their entirety when the PagedWorld is loaded. However, no Page instances are initially loaded - those are the responsibility of the PageStrategy.
PagedWorldSection can be subclassed and derived types provided by a PagedWorldSectionFactory. These subclasses might come preconfigured with a strategy for example, or with additional metadata used only for that particular type of section.
A PagedWorldSection targets a specific SceneManager. When you create one in code via PagedWorld::createSection, you pass that SceneManager in manually. When loading from a saved world file however, the SceneManager type and instance name are saved and that SceneManager is looked up on loading, or created if it didn't exist.

Member Typedef Documentation

◆ PageMap

Constructor & Destructor Documentation

◆ PagedWorldSection()

Ogre::PagedWorldSection::PagedWorldSection ( const String name,
PagedWorld parent,
SceneManager sm 
)

Construct a new instance, specifying the parent and scene manager.

◆ ~PagedWorldSection()

virtual Ogre::PagedWorldSection::~PagedWorldSection ( )
virtual

Member Function Documentation

◆ _loadProceduralPage()

virtual bool Ogre::PagedWorldSection::_loadProceduralPage ( Page page)
virtual

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

◆ _prepareProceduralPage()

virtual bool Ogre::PagedWorldSection::_prepareProceduralPage ( Page page)
virtual

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

◆ _readPageStream()

virtual StreamSerialiser* Ogre::PagedWorldSection::_readPageStream ( PageID  pageID)
virtual

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

Parameters
pageIDThe ID of the page being requested
Remarks
The StreamSerialiser returned is the responsibility of the caller to delete.

◆ _unloadProceduralPage()

virtual bool Ogre::PagedWorldSection::_unloadProceduralPage ( Page page)
virtual

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

◆ _unprepareProceduralPage()

virtual bool Ogre::PagedWorldSection::_unprepareProceduralPage ( Page page)
virtual

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

◆ _writePageStream()

virtual StreamSerialiser* Ogre::PagedWorldSection::_writePageStream ( PageID  pageID)
virtual

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

Parameters
pageIDThe ID of the page being requested
Remarks
The StreamSerialiser returned is the responsibility of the caller to delete.

◆ frameEnd()

virtual void Ogre::PagedWorldSection::frameEnd ( Real  timeElapsed)
virtual

Called when the frame ends.

◆ frameStart()

virtual void Ogre::PagedWorldSection::frameStart ( Real  timeSinceLastFrame)
virtual

Called when the frame starts.

◆ getBoundingBox()

virtual const AxisAlignedBox& Ogre::PagedWorldSection::getBoundingBox ( ) const
virtual

Get the bounds of this section.

◆ getManager()

PageManager* Ogre::PagedWorldSection::getManager ( ) const

◆ getName()

virtual const String& Ogre::PagedWorldSection::getName ( ) const
inlinevirtual

Get the name of this section.

◆ getPage()

virtual Page* Ogre::PagedWorldSection::getPage ( PageID  pageID)
virtual

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.

◆ getPageID()

virtual PageID Ogre::PagedWorldSection::getPageID ( const Vector3 worldPos)
virtual

Get the page ID for a given world position.

◆ getPageProvider()

virtual PageProvider* Ogre::PagedWorldSection::getPageProvider ( ) const
inlinevirtual

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

◆ getSceneManager()

virtual SceneManager* Ogre::PagedWorldSection::getSceneManager ( ) const
inlinevirtual

Get the current SceneManager.

◆ getStrategy()

virtual PageStrategy* Ogre::PagedWorldSection::getStrategy ( ) const
inlinevirtual

Get the page strategy which this section is using.

◆ getStrategyData()

virtual PageStrategyData* Ogre::PagedWorldSection::getStrategyData ( ) const
inlinevirtual

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

◆ getType()

virtual const String& Ogre::PagedWorldSection::getType ( )
virtual

Get the type name of this section.

◆ getWorld()

virtual PagedWorld* Ogre::PagedWorldSection::getWorld ( ) const
inlinevirtual

Get the parent world.

◆ holdPage()

virtual void Ogre::PagedWorldSection::holdPage ( PageID  pageID)
virtual

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.

◆ load()

virtual bool Ogre::PagedWorldSection::load ( StreamSerialiser stream)
virtual

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

◆ loadOrCreatePage()

virtual Page* Ogre::PagedWorldSection::loadOrCreatePage ( const Vector3 worldPos)
virtual

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.

◆ loadPage()

virtual void Ogre::PagedWorldSection::loadPage ( PageID  pageID,
bool  forceSynchronous = false 
)
virtual

Ask for a page to be loaded with the given (section-relative) PageID.

Remarks
You would not normally call this manually, the PageStrategy is in charge of it usually. If this page is already loaded, this request will not load it again. If the page needs loading, then it may be an asynchronous process depending on whether threading is enabled.
Parameters
pageIDThe page ID to load
forceSynchronousIf true, the page will always be loaded synchronously

◆ notifyCamera()

virtual void Ogre::PagedWorldSection::notifyCamera ( Camera cam)
virtual

Notify a section of the current camera.

◆ removeAllPages()

virtual void Ogre::PagedWorldSection::removeAllPages ( )
virtual

Remove all pages immediately.

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

◆ save()

virtual void Ogre::PagedWorldSection::save ( StreamSerialiser stream)
virtual

Save this section to a stream.

◆ setBoundingBox()

virtual void Ogre::PagedWorldSection::setBoundingBox ( const AxisAlignedBox box)
virtual

Set the bounds of this section.

◆ setPageProvider()

virtual void Ogre::PagedWorldSection::setPageProvider ( PageProvider provider)
inlinevirtual

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.

◆ setSceneManager() [1/2]

virtual void Ogre::PagedWorldSection::setSceneManager ( const String smName)
virtual

Change the SceneManager.

Remarks
Doing this will invalidate any pages attached to this world section, and require the pages to be reloaded.
Parameters
smNameThe instance name of the SceneManager

◆ setSceneManager() [2/2]

virtual void Ogre::PagedWorldSection::setSceneManager ( SceneManager sm)
virtual

Change the SceneManager.

Remarks
Doing this will invalidate any pages attached to this world section, and require the pages to be reloaded.

◆ setStrategy() [1/2]

virtual void Ogre::PagedWorldSection::setStrategy ( const String stratName)
virtual

Change the page strategy.

Remarks
Doing this will invalidate any pages attached to this world section, and require the PageStrategyData to be repopulated.

◆ setStrategy() [2/2]

virtual void Ogre::PagedWorldSection::setStrategy ( PageStrategy strat)
virtual

Change the page strategy.

Remarks
Doing this will invalidate any pages attached to this world section, and require the PageStrategyData to be repopulated.

◆ unloadPage() [1/2]

virtual void Ogre::PagedWorldSection::unloadPage ( Page p,
bool  forceSynchronous = false 
)
virtual

Ask for a page to be unloaded with the given (section-relative) PageID.

Remarks
You would not normally call this manually, the PageStrategy is in charge of it usually.
Parameters
pThe Page to unload
forceSynchronousIf true, the page will always be unloaded synchronously

◆ unloadPage() [2/2]

virtual void Ogre::PagedWorldSection::unloadPage ( PageID  pageID,
bool  forceSynchronous = false 
)
virtual

Ask for a page to be unloaded with the given (section-relative) PageID.

Remarks
You would not normally call this manually, the PageStrategy is in charge of it usually.
Parameters
pageIDThe page ID to unload
forceSynchronousIf true, the page will always be unloaded synchronously

Member Data Documentation

◆ CHUNK_ID

const uint32 Ogre::PagedWorldSection::CHUNK_ID
static

◆ CHUNK_VERSION

const uint16 Ogre::PagedWorldSection::CHUNK_VERSION
static

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