OGRE-Next  3.0.0
Object-Oriented Graphics Rendering Engine
Ogre::PagedWorld Class Reference

This class represents a collection of pages which make up a world. More...

#include <OgrePagedWorld.h>

+ Inheritance diagram for Ogre::PagedWorld:

Public Types

typedef map< String, PagedWorldSection * >::type SectionMap
 

Public Member Functions

 PagedWorld (const String &name, PageManager *manager)
 Constructor. More...
 
virtual ~PagedWorld ()
 
virtual bool _loadProceduralPage (Page *page, PagedWorldSection *section)
 Give a world the opportunity to prepare page content procedurally. More...
 
virtual bool _prepareProceduralPage (Page *page, PagedWorldSection *section)
 Give a world the opportunity to prepare page content procedurally. More...
 
StreamSerialiser_readPageStream (PageID pageID, PagedWorldSection *section)
 Get a serialiser set up to read Page data for the given PageID. More...
 
virtual bool _unloadProceduralPage (Page *page, PagedWorldSection *section)
 Give a world the opportunity to unload page content procedurally. More...
 
virtual bool _unprepareProceduralPage (Page *page, PagedWorldSection *section)
 Give a world the opportunity to unprepare page content procedurally. More...
 
StreamSerialiser_writePageStream (PageID pageID, PagedWorldSection *section)
 Get a serialiser set up to read Page data for the given PageID. More...
 
PagedWorldSectioncreateSection (const String &strategyName, SceneManager *sceneMgr, const String &sectionName=BLANKSTRING)
 Create a new manually defined section of the world. More...
 
PagedWorldSectioncreateSection (PageStrategy *strategy, SceneManager *sceneMgr, const String &sectionName=BLANKSTRING)
 Create a manually defined new section of the world. More...
 
PagedWorldSectioncreateSection (SceneManager *sceneMgr, const String &typeName, const String &sectionName=BLANKSTRING)
 Create a new section of the world based on a specialised type. More...
 
void destroyAllSections ()
 Destroy all world sections. More...
 
void destroySection (const String &name)
 Destroy a section of world. More...
 
void destroySection (PagedWorldSection *sec)
 Destroy a section of world. More...
 
virtual void frameEnd (Real timeElapsed)
 Called when the frame ends. More...
 
virtual void frameStart (Real timeSinceLastFrame)
 Called when the frame starts. More...
 
PageManagergetManager () const
 Get the manager of this world. More...
 
const StringgetName () const
 
PageProvidergetPageProvider () const
 Get the PageProvider which can provide streams for Pages in this world. More...
 
PagedWorldSectiongetSection (const String &name)
 Retrieve a section of the world. More...
 
size_t getSectionCount () const
 Get the number of sections this world has. More...
 
const SectionMapgetSections () const
 Retrieve a const reference to all the sections in this world. More...
 
void load (const DataStreamPtr &stream)
 Load world data from a stream. More...
 
void load (const String &filename)
 Load world data from a file. More...
 
bool load (StreamSerialiser &stream)
 Load world data from a serialiser (returns true if successful) More...
 
virtual void notifyCamera (Camera *cam)
 Notify a world of the current camera. More...
 
void save (const DataStreamPtr &stream)
 Save world data to a stream. More...
 
void save (const String &filename)
 Save world data to a file. More...
 
void save (StreamSerialiser &stream)
 Save world data to a serialiser. More...
 
void setPageProvider (PageProvider *provider)
 Set the PageProvider which can provide streams for Pages in this world. More...
 

Static Public Attributes

static const uint32 CHUNK_ID
 
static const uint32 CHUNK_SECTIONDECLARATION_ID
 
static const uint16 CHUNK_VERSION
 

Detailed Description

This class represents a collection of pages which make up a world.

Remarks
It's important to bear in mind that the PagedWorld only delineates the world and knows how to find out about the contents of it. It does not, by design, contain all elements of the world, in memory, at once.

Member Typedef Documentation

◆ SectionMap

Constructor & Destructor Documentation

◆ PagedWorld()

Ogre::PagedWorld::PagedWorld ( const String name,
PageManager manager 
)

Constructor.

Parameters
nameThe name of the world, which must be enough to identify the place where data for it can be loaded from (doesn't have to be a filename necessarily).
managerThe PageManager that is in charge of providing this world with services such as related object factories.

◆ ~PagedWorld()

virtual Ogre::PagedWorld::~PagedWorld ( )
virtual

Member Function Documentation

◆ _loadProceduralPage()

virtual bool Ogre::PagedWorld::_loadProceduralPage ( Page page,
PagedWorldSection section 
)
virtual

Give a world 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::PagedWorld::_prepareProceduralPage ( Page page,
PagedWorldSection section 
)
virtual

Give a world 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()

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

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

Parameters
pageIDThe ID of the page being requested
sectionThe parent section to which this page will belong
Remarks
The StreamSerialiser returned is the responsibility of the caller to delete.

◆ _unloadProceduralPage()

virtual bool Ogre::PagedWorld::_unloadProceduralPage ( Page page,
PagedWorldSection section 
)
virtual

Give a world 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::PagedWorld::_unprepareProceduralPage ( Page page,
PagedWorldSection section 
)
virtual

Give a world 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()

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

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

Parameters
pageIDThe ID of the page being requested
sectionThe parent section to which this page will belong
Remarks
The StreamSerialiser returned is the responsibility of the caller to delete.

◆ createSection() [1/3]

PagedWorldSection* Ogre::PagedWorld::createSection ( const String strategyName,
SceneManager sceneMgr,
const String sectionName = BLANKSTRING 
)

Create a new manually defined section of the world.

Remarks
World sections are areas of the world that use a particular PageStrategy, with a certain set of parameters specific to that strategy. So you would have more than one section in a world only if you needed different simultaneous paging strategies, or you wanted the same strategy but parameterised differently.
Parameters
strategyNameThe name of the strategy to use (must be registered with PageManager)
sceneMgrThe SceneManager to use for this section
sectionNameAn optional name to give the section (if none is provided, one will be generated)

◆ createSection() [2/3]

PagedWorldSection* Ogre::PagedWorld::createSection ( PageStrategy strategy,
SceneManager sceneMgr,
const String sectionName = BLANKSTRING 
)

Create a manually defined new section of the world.

Remarks
World sections are areas of the world that use a particular PageStrategy, with a certain set of parameters specific to that strategy. So you would have more than one section in a world only if you needed different simultaneous paging strategies, or you wanted the same strategy but parameterised differently.
Parameters
strategyThe strategy to use
sceneMgrThe SceneManager to use for this section
sectionNameAn optional name to give the section (if none is provided, one will be generated)

◆ createSection() [3/3]

PagedWorldSection* Ogre::PagedWorld::createSection ( SceneManager sceneMgr,
const String typeName,
const String sectionName = BLANKSTRING 
)

Create a new section of the world based on a specialised type.

Remarks
World sections are areas of the world that use a particular PageStrategy, with a certain set of parameters specific to that strategy, and potentially some other rules. So you would have more than one section in a world only if you needed different simultaneous paging strategies, or you wanted the same strategy but parameterised differently.
Parameters
sceneMgrThe SceneManager to use for this section.
typeNameThe type of section to use (must be registered
with PageManager), or blank to use the default type (simple grid)
sectionNameAn optional name to give the section (if none is provided, one will be generated)

◆ destroyAllSections()

void Ogre::PagedWorld::destroyAllSections ( )

Destroy all world sections.

◆ destroySection() [1/2]

void Ogre::PagedWorld::destroySection ( const String name)

Destroy a section of world.

◆ destroySection() [2/2]

void Ogre::PagedWorld::destroySection ( PagedWorldSection sec)

Destroy a section of world.

◆ frameEnd()

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

Called when the frame ends.

◆ frameStart()

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

Called when the frame starts.

◆ getManager()

PageManager* Ogre::PagedWorld::getManager ( ) const
inline

Get the manager of this world.

◆ getName()

const String& Ogre::PagedWorld::getName ( ) const
inline

◆ getPageProvider()

PageProvider* Ogre::PagedWorld::getPageProvider ( ) const
inline

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

◆ getSection()

PagedWorldSection* Ogre::PagedWorld::getSection ( const String name)

Retrieve a section of the world.

◆ getSectionCount()

size_t Ogre::PagedWorld::getSectionCount ( ) const
inline

Get the number of sections this world has.

◆ getSections()

const SectionMap& Ogre::PagedWorld::getSections ( ) const
inline

Retrieve a const reference to all the sections in this world.

◆ load() [1/3]

void Ogre::PagedWorld::load ( const DataStreamPtr stream)

Load world data from a stream.

◆ load() [2/3]

void Ogre::PagedWorld::load ( const String filename)

Load world data from a file.

◆ load() [3/3]

bool Ogre::PagedWorld::load ( StreamSerialiser stream)

Load world data from a serialiser (returns true if successful)

◆ notifyCamera()

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

Notify a world of the current camera.

◆ save() [1/3]

void Ogre::PagedWorld::save ( const DataStreamPtr stream)

Save world data to a stream.

◆ save() [2/3]

void Ogre::PagedWorld::save ( const String filename)

Save world data to a file.

Parameters
filenameThe name of the file to create; this can either be an absolute filename or

◆ save() [3/3]

void Ogre::PagedWorld::save ( StreamSerialiser stream)

Save world data to a serialiser.

◆ setPageProvider()

void Ogre::PagedWorld::setPageProvider ( PageProvider provider)
inline

Set the PageProvider which can provide streams for Pages in this world.

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.

Member Data Documentation

◆ CHUNK_ID

const uint32 Ogre::PagedWorld::CHUNK_ID
static

◆ CHUNK_SECTIONDECLARATION_ID

const uint32 Ogre::PagedWorld::CHUNK_SECTIONDECLARATION_ID
static

◆ CHUNK_VERSION

const uint16 Ogre::PagedWorld::CHUNK_VERSION
static

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