# Ogre::PagedWorldSection Class Reference
Paging

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:
[legend]

List of all members.

## 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.
virtual | ~PagedWorldSection ()
PageManager * | getManager () const
virtual const String & | getName () const
| Get the name of this section.
virtual PageStrategy * | getStrategy () const
| Get the page strategy which this section is using.
virtual void | setStrategy (PageStrategy *strat)
| Change the page strategy.
virtual void | setStrategy (const String &stratName)
| Change the page strategy.
virtual void | setSceneManager (SceneManager *sm)
| Change the SceneManager.
virtual void | setSceneManager (const String &smName)
| Change the SceneManager.
virtual SceneManager * | getSceneManager () const
| Get the current SceneManager.
virtual PagedWorld * | getWorld () const
| Get the parent world.
virtual PageStrategyData * | getStrategyData () const
| Get the data required by the PageStrategy which is specific to this world section.
virtual void | setBoundingBox (const AxisAlignedBox &box)
| Set the bounds of this section.
virtual const AxisAlignedBox & | getBoundingBox () const
| Get the bounds of this section.
virtual bool | load (StreamSerialiser &stream)
| Load this section from a stream (returns true if successful)
virtual void | save (StreamSerialiser &stream)
| Save this section to a stream.
virtual void | frameStart (Real timeSinceLastFrame)
| Called when the frame starts.
virtual void | frameEnd (Real timeElapsed)
| Called when the frame ends.
virtual void | notifyCamera (Camera *cam)
| Notify a section of the current camera.
virtual Page * | loadOrCreatePage (const Vector3 &worldPos)
| Load or create a page against this section covering the given world space position.
virtual PageID | getPageID (const Vector3 &worldPos)
| Get the page ID for a given world position.
virtual void | loadPage (PageID pageID, bool forceSynchronous=false)
| Ask for a page to be loaded with the given (section-relative) PageID.
virtual void | unloadPage (PageID pageID, bool forceSynchronous=false)
| Ask for a page to be unloaded with the given (section-relative) PageID.
virtual void | unloadPage (Page *p, bool forceSynchronous=false)
| Ask for a page to be unloaded with the given (section-relative) PageID.
virtual bool | _prepareProceduralPage (Page *page)
| Give a section the opportunity to prepare page content procedurally.
virtual bool | _loadProceduralPage (Page *page)
| Give a section the opportunity to prepare page content procedurally.
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 void | holdPage (PageID pageID)
| Ask for a page to be kept in memory if it's loaded.
virtual Page * | getPage (PageID pageID)
| Retrieves a Page.
virtual void | removeAllPages ()
| Remove all pages immediately.
virtual void | setPageProvider (PageProvider *provider)
| Set the PageProvider which can provide streams Pages in this section.
virtual PageProvider * | getPageProvider () const
| Get the PageProvider which can provide streams for Pages in this section.
virtual StreamSerialiser * | _readPageStream (PageID pageID)
| Get a serialiser set up to read Page data for the given PageID.
virtual StreamSerialiser * | _writePageStream (PageID pageID)
| Get a serialiser set up to write Page data for the given PageID.
virtual const String & | getType ()
| Get the type name of this section.
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 *)

## Static Public Attributes

static const uint32 | CHUNK_ID
static const uint16 | CHUNK_VERSION

## Protected Member Functions

virtual void | loadSubtypeData (StreamSerialiser &ser)
| Load data specific to a subtype of this class (if any)
virtual void | saveSubtypeData (StreamSerialiser &ser)

## Protected Attributes

String | mName
AxisAlignedBox | mAABB
PagedWorld * | mParent
PageStrategy * | mStrategy
PageStrategyData * | mStrategyData
PageMap | mPages
PageProvider * | mPageProvider
SceneManager * | mSceneMgr

## Friends

_OgrePagingExport friend std::ostream & | operator<< (std::ostream &o, const PagedWorldSection &p)
| Function for writing to a stream.

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

Definition at line 69 of file OgrePagedWorldSection.h.

## Member Typedef Documentation

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

Definition at line 72 of file OgrePagedWorldSection.h.

## Constructor & Destructor Documentation

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

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

virtual Ogre::PagedWorldSection::~PagedWorldSection | ( |  | ) | `[virtual]`

## Member Function Documentation

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

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

virtual StreamSerialiser* Ogre::PagedWorldSection::_readPageStream | ( | PageID | pageID | ) | `[virtual]`

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]`

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]`

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]`

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 void Ogre::PagedWorldSection::frameEnd | ( | Real | timeElapsed | ) | `[virtual]`

Called when the frame ends.

virtual void Ogre::PagedWorldSection::frameStart | ( | Real | timeSinceLastFrame | ) | `[virtual]`

Called when the frame starts.

virtual const AxisAlignedBox& Ogre::PagedWorldSection::getBoundingBox | ( |  | ) | const`[virtual]`

Get the bounds of this section.

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

virtual const String& Ogre::PagedWorldSection::getName | ( | void |  | ) | const`[virtual]`

Get the name of this section.

Definition at line 99 of file OgrePagedWorldSection.h.

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.

virtual PageID Ogre::PagedWorldSection::getPageID | ( | const Vector3 & | worldPos | ) | `[virtual]`

Get the page ID for a given world position.

virtual PageProvider* Ogre::PagedWorldSection::getPageProvider | ( |  | ) | const`[virtual]`

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

Definition at line 271 of file OgrePagedWorldSection.h.

virtual SceneManager* Ogre::PagedWorldSection::getSceneManager | ( |  | ) | const`[virtual]`

Get the current SceneManager.

Definition at line 130 of file OgrePagedWorldSection.h.

virtual PageStrategy* Ogre::PagedWorldSection::getStrategy | ( |  | ) | const`[virtual]`

Get the page strategy which this section is using.

Definition at line 101 of file OgrePagedWorldSection.h.

virtual PageStrategyData* Ogre::PagedWorldSection::getStrategyData | ( |  | ) | const`[virtual]`

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

Definition at line 135 of file OgrePagedWorldSection.h.

virtual const String& Ogre::PagedWorldSection::getType | ( |  | ) | `[virtual]`

Get the type name of this section.

virtual PagedWorld* Ogre::PagedWorldSection::getWorld | ( |  | ) | const`[virtual]`

Get the parent world.

Definition at line 133 of file OgrePagedWorldSection.h.

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.

virtual bool Ogre::PagedWorldSection::load | ( | StreamSerialiser & | stream | ) | `[virtual]`

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

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.

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:

  pageID | The page ID to load
  forceSynchronous | If true, the page will always be loaded synchronously

Reimplemented in Ogre::TerrainPagedWorldSection.

virtual void Ogre::PagedWorldSection::loadSubtypeData | ( | StreamSerialiser & | ser | ) | `[protected, virtual]`

Load data specific to a subtype of this class (if any)

Reimplemented in Ogre::TerrainPagedWorldSection.

Definition at line 84 of file OgrePagedWorldSection.h.

virtual void Ogre::PagedWorldSection::notifyCamera | ( | Camera * | cam | ) | `[virtual]`

Notify a section of the current camera.

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,
|  | void * |
| ) |  | `[inherited]`

Definition at line 101 of file OgreMemoryAllocatedObject.h.

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 | ) | `[inherited]`

Definition at line 112 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 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,
|  | 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]`

array operator new, with debug line info

Definition at line 85 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.

virtual void Ogre::PagedWorldSection::removeAllPages | ( |  | ) | `[virtual]`

Remove all pages immediately.

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

virtual void Ogre::PagedWorldSection::save | ( | StreamSerialiser & | stream | ) | `[virtual]`

Save this section to a stream.

virtual void Ogre::PagedWorldSection::saveSubtypeData | ( | StreamSerialiser & | ser | ) | `[protected, virtual]`

Reimplemented in Ogre::TerrainPagedWorldSection.

Definition at line 85 of file OgrePagedWorldSection.h.

virtual void Ogre::PagedWorldSection::setBoundingBox | ( | const AxisAlignedBox & | box | ) | `[virtual]`

Set the bounds of this section.

virtual void Ogre::PagedWorldSection::setPageProvider | ( | PageProvider * | provider | ) | `[virtual]`

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

  smName | The instance name of the SceneManager

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.

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.

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.

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:

  p | The Page to unload
  forceSynchronous | If true, the page will always be unloaded synchronously

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:

  pageID | The page ID to unload
  forceSynchronous | If true, the page will always be unloaded synchronously

Reimplemented in Ogre::TerrainPagedWorldSection.

## Friends And Related Function Documentation

_OgrePagingExport friend std::ostream& operator<< | ( | std::ostream & | o,
|  | const PagedWorldSection & | p
| ) |  | `[friend]`

Function for writing to a stream.

## Member Data Documentation

const uint32 Ogre::PagedWorldSection::CHUNK_ID`[static]`

Definition at line 89 of file OgrePagedWorldSection.h.

const uint16 Ogre::PagedWorldSection::CHUNK_VERSION`[static]`

Definition at line 90 of file OgrePagedWorldSection.h.

AxisAlignedBox Ogre::PagedWorldSection::mAABB`[protected]`

Definition at line 75 of file OgrePagedWorldSection.h.

String Ogre::PagedWorldSection::mName`[protected]`

Definition at line 74 of file OgrePagedWorldSection.h.

PageProvider* Ogre::PagedWorldSection::mPageProvider`[protected]`

Definition at line 80 of file OgrePagedWorldSection.h.

PageMap Ogre::PagedWorldSection::mPages`[protected]`

Definition at line 79 of file OgrePagedWorldSection.h.

PagedWorld* Ogre::PagedWorldSection::mParent`[protected]`

Definition at line 76 of file OgrePagedWorldSection.h.

SceneManager* Ogre::PagedWorldSection::mSceneMgr`[protected]`

Definition at line 81 of file OgrePagedWorldSection.h.

PageStrategy* Ogre::PagedWorldSection::mStrategy`[protected]`

Definition at line 77 of file OgrePagedWorldSection.h.

PageStrategyData* Ogre::PagedWorldSection::mStrategyData`[protected]`

Definition at line 78 of file OgrePagedWorldSection.h.

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

- OgrePagedWorldSection.h

Copyright © 2008 Torus Knot Software Ltd
This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
Last modified Sun May 8 2011 20:28:21