Forests::PagedGeometry Class Reference

Description

A class providing highly optimized methods for rendering massive amounts of geometry.

The PagedGeometry class provides highly optimized methods for rendering massive amounts of small meshes, covering a large area. This is especially well suited for dense forests, with thousands of trees, bushes, grass, rocks, etc., etc.

The paged geometry works by loading only the geometry that is visible (or will soon be visible), to save memory. The PagedGeometry engine can display entities using many different methods (static geometry, impostors, etc.) What method is used depends on the entities' distance from the camera, and how you configured these methods (see PagedGeometry::addDetailLevel() for more info about this).

The loading of pages is done through a PageLoader, which you define. This way, you can program the PagedGeometry to load pages any way you want, whether it's from a file on your hard drive, from a procedural generation algorithm, or anything else. See the documentation for the PageLoader class for more information about this.

Note

Always remember to call each PagedGeometry object's update() function every frame; otherwise the geometry you're trying to display will not appear correctly. See PagedGeometry::update() for more information.

Definition at line 70 of file PagedGeometry.h.

Public Member Functions
	PagedGeometry (Ogre::Camera *cam=NULL, Ogre::Real pageSize=100, Ogre::SceneNode *groupingSceneNode=NULL, Ogre::RenderQueueGroupID queue=Ogre::RENDER_QUEUE_6)
	~PagedGeometry ()
void	setCamera (Ogre::Camera *cam)
void	setTempDir (Ogre::String dir)
Ogre::String	getTempdir ()
Ogre::Camera *	getCamera () const
Ogre::SceneManager *	getSceneManager () const
Ogre::SceneNode *	getSceneNode () const
void	setBounds (const TBounds bounds)
void	setInfinite ()
const TBounds &	getBounds () const
TBounds	convertAABToTBounds (const Ogre::AxisAlignedBox &aab) const
void	setPageSize (Ogre::Real size)
Ogre::Real	getPageSize ()
template<class PageType >
GeometryPageManager *	addDetailLevel (Ogre::Real maxRange, Ogre::Real transitionLength=0, const Ogre::Any &data=Ogre::Any())
void	removeDetailLevels ()
const std::list< GeometryPageManager * > &	getDetailLevels ()
void	setPageLoader (PageLoader *loader)
PageLoader *	getPageLoader ()
void	update ()
void	reloadGeometry ()
void	reloadGeometryPage (const Ogre::Vector3 &point)
void	reloadGeometryPages (const Ogre::Vector3 &center, Ogre::Real radius)
void	reloadGeometryPages (const TBounds &area)
void	preloadGeometry (const TBounds &area)
void	resetPreloadedGeometry ()
void	setVisible (bool visible)
bool	getVisible ()
void	setShadersEnabled (bool value)
bool	getShadersEnabled ()
Ogre::uint8	getRenderQueue () const

Protected Member Functions
void	_addDetailLevel (GeometryPageManager *mgr, Ogre::Real maxRange, Ogre::Real transitionLength)

Protected Attributes
Ogre::SceneManager *	sceneMgr
Ogre::SceneNode *	m_pagedGroupingNode
bool	shadersEnabled
bool	geometryAllowedVisible
Ogre::Camera *	sceneCam
Ogre::Vector3	oldCamPos
Ogre::Camera *	lastSceneCam
Ogre::Vector3	lastOldCamPos
std::list< GeometryPageManager * >	managerList
PageLoader *	pageLoader
TBounds	m_bounds
Ogre::Real	pageSize
Ogre::uint8	m_nRenderQueue
Ogre::Timer	timer
unsigned long	lastTime
Ogre::String	tempdir

Constructor & Destructor Documentation

PagedGeometry()

Forests::PagedGeometry::PagedGeometry	(	Ogre::Camera *	cam = NULL,
		Ogre::Real	pageSize = 100,
		Ogre::SceneNode *	groupingSceneNode = NULL,
		Ogre::RenderQueueGroupID	queue = Ogre::RENDER_QUEUE_6
	)

Initializes a PagedGeometry object.

Parameters

cam	A camera which the PagedGeometry object will use for LOD calculations.
pageSize	The page size (pages are square)

pageSize sets the size of a single "page" of geometry. If your pages are too big, you may experience "hiccuping" during the game as these regions are loaded. However, regions that are too small may result in lower frame rates (depending on what detail levels you are using).

Also, using larger pages uses slightly less memory, although you should generally give performance precedence over memory usage.

Note

You do not need to specify the page size or camera in the constructor if you don't want to. PagedGeometry::setCamera() and PagedGeometry::setPageSize() allows you to configure these values later.

See also

setCamera(), setPageSize(), setBounds(), setInfinite(), setPageLoader()

Definition at line 29 of file PagedGeometry.cpp.

~PagedGeometry()

Forests::PagedGeometry::~PagedGeometry

(

)

Definition at line 64 of file PagedGeometry.cpp.

Member Function Documentation

_addDetailLevel()

void Forests::PagedGeometry::_addDetailLevel ( GeometryPageManager *  mgr, Ogre::Real  maxRange, Ogre::Real  transitionLength  )

protected

Definition at line 282 of file PagedGeometry.cpp.

addDetailLevel()

template<class PageType >

GeometryPageManager * Forests::PagedGeometry::addDetailLevel ( Ogre::Real  maxRange, Ogre::Real  transitionLength = 0, const Ogre::Any &  data = Ogre::Any()  )

inline

Adds a detail level to the PagedGeometry object.

Parameters

PageType	The page type class you want to use for this detail level.
maxRange	The maximum distance this detail level will be used at.
transitionLength	The desired length of fade transitions - optional
data	An extra parameter to pass to the PageType constructor - optional

Note

PageType is not really a function parameter, but a template parameter. See the code below for an example on how this "parameter" is used.

On it's own, a plain PagedGeometry object can't display anything. It needs you to add detail levels to it with this function. This way, you can easily customize the behavior of the PagedGeometry.

To use this function, simply use the form:

pagedGeometry::addDetailLevel<PageType>(farRange);

In the above example, "farRange" specifies the maximum view distance this detail level will be used at. However, the most important part is "<PageType>". Here you substitute "PageType" with the name of a installed page type you want to use for this detail level. A page type is simply a method of displaying or otherwise representing entities.

The PagedGeometry engine currently comes pre-installed with a few page types: BatchPage and ImpostorPage. Refer to their class documentation for detailed information about them (although you never actually access these classes yourself).

You can use these page types in any configuration you want. For example:

pagedTrees->addDetailLevel<BatchPage>(100); //Use batched geometry from 0-100
pagedTrees->addDetailLevel<ImpostorPage>(500); //Use impostors from 100-500

That example would set up the PagedGeometry object called pagedTrees to use batched geometry (StaticGeometry) from 0 to 100 units from the camera, and impostors from 100 to 500 units from the camera.

If the included page types aren't adequate, you can fairly easily add your own by simply extending the virtual GeometryPage class properly.

By default, no fade transitions are used. This means that there will be a noticeable "popping" effect when your tree changes from an impostor to a batch, for example. Enabling fade transitions will smooth out the change by slowly "morphing" between the two detail levels. To enable fade transitions, simply add a second parameter to you addDetailLevel() call:

//Use batched geometry from 0-100, and transition to the next LOD for 50 units
pagedTrees->addDetailLevel<BatchPage>(100, 50);
//Use impostors from 100-500
pagedTrees->addDetailLevel<ImpostorPage>(500);

The second parameter seen above will enable transitions between BatchPage and the next LOD (which is ImpostorPage, in this case). The number you supply will specify how long the transition is. Longer transitions result in smoother "morphs", although shorter transitions will give slightly better frame rates.

The transition parameter can also be applied to the last detail level to cause it to fade out:

//Use batched geometry from 0-100, and transition to the next LOD for 50 units
pagedTrees->addDetailLevel<BatchPage>(100, 50);
//Use impostors from 100-400, and fade out for 100 units beyond that
pagedTrees->addDetailLevel<ImpostorPage>(400, 100);

In the example above, batching is used up to 100 units, where the batched geometry starts transitioning for 50 units into the next level of detail (impostors). The impostors continue up to 400 units, where they begin to fade out for 100 more units.

Warning

Depending on your page size and transition length, enabling fade transitions will often reduce PagedGeometry's rendering performance anywhere from 10 - 30%.

Transitions can be disabled by omitting the transitionLength parameter, or setting it to 0.

Note

Make sure you make any calls to setPageSize() and setBounds() / setInfinite() before adding detail levels with this function. After a detail level is added you cannot call these functions without first removing them with removeDetailLevels().

The "data" parameter is entirely optional, so there should never be any requirement that it be used. Just what type of data this parameter accepts, and what it does, depends entirely on the specific GeometryPage implementation you're using. See the appropriate page type documentation for info on how this parameter can be used (if at all).

See also

The GeometryPage class documention for more information on adding custom page types.

Definition at line 1328 of file PagedGeometry.h.

convertAABToTBounds()

TBounds Forests::PagedGeometry::convertAABToTBounds

(

const Ogre::AxisAlignedBox &

aab

)

const

Convert an Ogre::AxisAlignedBox to a TBounds coplanar to the plane defined by the UP axis.

Definition at line 134 of file PagedGeometry.cpp.

getBounds()

const TBounds & Forests::PagedGeometry::getBounds ( ) const

inline

Gets the current geometry boundary.

Returns

The geometry boundary which was set in the constructor.

See also

The PagedGeometry constructor for information about the geometry boundary.

This returns a TBounds value, which contains information about the boundaries of the geometry. Since TBounds is simply a typedef for TRect<Real>, accessing the boundary information is easy, for example:

(...) = PagedGeometry::getBounds().top;
(...) = PagedGeometry::getBounds().bottom;
(etc.)

Ogre's documentation should contain more information about TRect members.

Definition at line 220 of file PagedGeometry.h.

getCamera()

Ogre::Camera * Forests::PagedGeometry::getCamera ( ) const

inline

Gets the camera which is used to calculate levels of detail.

Returns

The camera assigned to this PagedGeometry object.

Warning

Be careful when storing a local copy of this - the camera returned may change at any time, so it's usually best to call getCamera() repeatedly, instead of storing a local copy. This is an inline function, so don't worry too much about performance.

Definition at line 125 of file PagedGeometry.h.

getDetailLevels()

const std::list< GeometryPageManager * > & Forests::PagedGeometry::getDetailLevels ( )

inline

Returns a reference to a list of all added detail levels.

This returns a std::list of all detail levels (GeometryPageManager's). These objects can be used to set/get advanced properties, such as view ranges and cache speeds.

Normally you won't ever have to access this data, but it's there in case you need it.

Definition at line 368 of file PagedGeometry.h.

getPageLoader()

PageLoader * Forests::PagedGeometry::getPageLoader ( )

inline

Gets the PageLoader currently being used to load geometry.

Returns

A PageLoader object which is currently being used to load geometry.

This can be useful if you want to retrieve the current page loader to delete it, or any other task that needs to be done to the currently used page loader.

Definition at line 395 of file PagedGeometry.h.

getPageSize()

Ogre::Real Forests::PagedGeometry::getPageSize ( )

inline

Gets the current page size.

Returns

The current page size.

See also

setPageSize() for more information about page size.

Definition at line 249 of file PagedGeometry.h.

getRenderQueue()

Ogre::uint8 Forests::PagedGeometry::getRenderQueue ( ) const

inline

Returns the rendering queue that paged geometry was constructed with.

Definition at line 574 of file PagedGeometry.h.

getSceneManager()

Ogre::SceneManager * Forests::PagedGeometry::getSceneManager ( ) const

inline

Gets the scene manager which is being used to display the geometry.

Returns

A SceneManager

This function simply returns the SceneManager that this PagedGeometry object is using. If no camera has been set yet, this will return NULL, since PagedGeometry has no way of knowing which SceneManager to use. However, once a camera is set, the SceneManager this function returns will always remain the same - even if the camera is later set to NULL.

Definition at line 140 of file PagedGeometry.h.

getSceneNode()

Ogre::SceneNode * Forests::PagedGeometry::getSceneNode ( ) const

inline

Gets the scene node to which all PagedGeometry geometry is attached.

Returns

A SceneNode

This function returns the SceneNode which PagedGeometry uses to render all it's geometry. Everything that PagedGeometry renders to the screen can be found under this scene node.

Definition at line 154 of file PagedGeometry.h.

getShadersEnabled()

bool Forests::PagedGeometry::getShadersEnabled ( )

inline

Definition at line 551 of file PagedGeometry.h.

getTempdir()

Ogre::String Forests::PagedGeometry::getTempdir ( )

inline

Definition at line 114 of file PagedGeometry.h.

getVisible()

bool Forests::PagedGeometry::getVisible ( )

inline

Returns whether or not geometry managed by this PagedGeometry instance is visible.

By default, everything will be visible of course. This function simply returns the visible/invisible state as set by the setVisible() command.

Definition at line 545 of file PagedGeometry.h.

preloadGeometry()

void Forests::PagedGeometry::preloadGeometry

(

const TBounds &

area

)

Preloads a region of geometry (loads once and never loads again)

Parameters

area	A rectangular area of the world that needs to be preloaded

You can use this function to preload entire areas of geometry. Doing this will basically turn off dynamic paging for the given region, since all the pages effecting it will stay loaded forever (until you delete the PagedGeometry object, or if using infinite mode, until you move away from the region).

Note

The rectangular bounds value you supply does not indicate a rectangular area to preload, but instead a rectangular area in which you need the camera to be able to freely move around without having to dynamically load any pages. In other words, this function will preload all geometry within viewing range of the given bounds area.

Definition at line 253 of file PagedGeometry.cpp.

reloadGeometry()

void Forests::PagedGeometry::reloadGeometry

(

)

Reloads all visible geometry.

If your PageLoader changes it's output during runtime, you normally won't see the changes immediately (and in many cases, you will never see the changes). This function provides a way to reload the geometry to force the changes to take effect immediately.

This function will cause ALL visible geometry to be reloaded during the next update. This can take up to several seconds, depending on the complexity of the current scene, so use this function only when absolutely necessary.

Definition at line 199 of file PagedGeometry.cpp.

reloadGeometryPage()

void Forests::PagedGeometry::reloadGeometryPage

(

const Ogre::Vector3 &

point

)

Reloads geometry at the given location.

Parameters

point

The point in 3D space where geometry needs to be reloaded.

If your PageLoader changes it's output during runtime, you normally won't see the changes immediately (and in many cases, you will never see the changes). This function provides a way to reload the geometry to force the changes to take effect immediately.

This function will cause a certain page of visible geometry to be reloaded during the next update. Unlike reloadGeometry(), this function allows pinpoint reloading to take place, resulting in better performance if a small portion of the geometry changes.

Since this doesn't actually reload anything immediately, you can call this function as many times as you need without worrying too much about performance. For example, if you update 150 trees in your game, simply supply this function with the locations of each tree. When the scene is about to be rendered, the appropriate geometry pages will automatically be reloaded.

Definition at line 210 of file PagedGeometry.cpp.

reloadGeometryPages() [1/2]

void Forests::PagedGeometry::reloadGeometryPages	(	const Ogre::Vector3 &	center,
		Ogre::Real	radius
	)

Reloads geometry in the given radius area.

Parameters

center	The center of the area to be reloaded
radius	The radius from the center where geometry needs to be reloaded

Note

This is identical to reloadGeometryPage() except it allows you to reload an entire area rather than a single point.

If your PageLoader changes it's output during runtime, you normally won't see the changes immediately (and in many cases, you will never see the changes). This function provides a way to reload the geometry to force the changes to take effect immediately.

This function will cause a certain area of visible geometry to be reloaded during the next update. Unlike reloadGeometry(), this function allows selective reloading to take place, resulting in better performance if a small portion of the geometry changes.

Since this doesn't actually reload anything immediately, you can call this function as many times as you need without worrying too much about performance. For example, if you update 150 trees in your game, simply supply this function with the locations of each tree. When the scene is about to be rendered, the appropriate geometry pages will automatically be reloaded.

reloadGeometryPages() [2/2]

void Forests::PagedGeometry::reloadGeometryPages

(

const TBounds &

area

)

Reloads geometry in the given rect area.

Parameters

area	A rectangular area that needs reloading

Note

This is identical to reloadGeometryPage() except it allows you to reload an entire area rather than a single point.

If your PageLoader changes it's output during runtime, you normally won't see the changes immediately (and in many cases, you will never see the changes). This function provides a way to reload the geometry to force the changes to take effect immediately.

This function will cause a certain area of visible geometry to be reloaded during the next update. Unlike reloadGeometry(), this function allows selective reloading to take place, resulting in better performance if a small portion of the geometry changes.

Since this doesn't actually reload anything immediately, you can call this function as many times as you need without worrying too much about performance. For example, if you update 150 trees in your game, simply supply this function with the locations of each tree. When the scene is about to be rendered, the appropriate geometry pages will automatically be reloaded.

Definition at line 236 of file PagedGeometry.cpp.

removeDetailLevels()

void Forests::PagedGeometry::removeDetailLevels

(

)

Removes all detail levels from the PagedGeometry object.

This removes all detail levels (added with addDetailLevel) from the PagedGeometry object. This also removes all geometry associated with PagedGeometry from the scene. Remember that you will need to re-add all the detail levels again with addDetailLevel() before any of the geometry will be displayed.

Definition at line 141 of file PagedGeometry.cpp.

resetPreloadedGeometry()

void Forests::PagedGeometry::resetPreloadedGeometry

(

)

Releases geometry preloaded with preloadGeometry() to be unloaded if necessary.

When you call preloadGeometry() to preload region(s) of geometry, it makes those regions un-unloadable; in other words, they will never be unloaded automatically by PagedGeometry (except for some cases in infinite mode). This way you can load a region of your world once and never have to load it again (optimally).

This function allows you to undo all this by allowing all the geometry to be unloaded once again when necessary. It won't unload anything, but it will allow geometry to unload that previously was not allowed.

Definition at line 270 of file PagedGeometry.cpp.

setBounds()

void Forests::PagedGeometry::setBounds

(

const TBounds

bounds

)

Switches to bounded mode and uses the given boundaries.

By default, PagedGeometry does not place boundaries on the geometry that can be added to it though the PageLoader. However, there are cases where specifying a strict boundary can improve performance.

When bounded mode is used, PagedGeometry allocates certain lightweight data structures to fill the boundaries. This may result in a slight frame rate boost compared to an infinite world, although it will take a little more memory (especially with large areas).

Since bounded mode requires more memory for larger boundaries, it is best suited for small to medium sized worlds, while infinite mode is best for huge or even near-infinite worlds.

Note

Bounds must be square.

See also

setInfinite()

Definition at line 122 of file PagedGeometry.cpp.

setCamera()

void Forests::PagedGeometry::setCamera

(

Ogre::Camera *

cam

)

Sets the camera to use when calculating levels of detail.

Parameters

cam	The camera to assign to this PagedGeometry object.

Note

The specified camera must belong to the same scene manager as previous ones; once a camera is set, the scene manager that camera belongs to will be used permanently for this PagedGeometry instance.

Warning

Changing cameras will often result in low cache efficiency in infinite mode. If you are constantly switching between multiple cameras that are relatively far apart, consider using bounded mode.

Definition at line 80 of file PagedGeometry.cpp.

setInfinite()

void Forests::PagedGeometry::setInfinite

(

)

Switches to infinite mode.

By default, PagedGeometry will just allocate enough memory to display and cache what is on the screen. This behavior is called "infinite mode", and can be activated by calling this function if not already activated (it will be by default).

Most game worlds have boundaries of some sort, but infinite mode allows you to expand the size of your game world almost to infinity. Since only what's on the screen is actually loaded, it makes little difference if your world is 100 square miles, or 1,000,000 square miles.

The only disadvantage to using infinite mode is that cache efficiency will be slightly reduced in some cases. For example, bounded mode will achieve better performance if you are often switching between multiple cameras, since the cache is more globally based (unlike the locally based cache of infinite mode).

See also

setBounds()

Definition at line 114 of file PagedGeometry.cpp.

setPageLoader()

void Forests::PagedGeometry::setPageLoader

(

PageLoader *

loader

)

Assigns a PageLoader object for the PagedGeometry.

Parameters

loader

A PageLoader object.

When the page manager decides it should cache a certain region of geometry, it calls on your PageLoader to do the job. This way you can load entities from RAM, a hard-drive, the internet, or even procedurally. Simply create a PageLoader class and use this function to link it to a PagedGeometry object.

Warning

Since you must instantiate your PageLoader yourself, you must also be sure to deallocate it properly (as with any other class instance). PagedGeometry will not do this for you.

See also

PageLoader documentation for more information on setting up a page loader.

Definition at line 75 of file PagedGeometry.cpp.

setPageSize()

void Forests::PagedGeometry::setPageSize

(

Ogre::Real

size

)

Sets the page size.

This sets the size of a single "page" of geometry. If your pages are too big, you may experience "hiccuping" during the game as these regions are loaded. However, regions that are too small may result in lower frame rates (depending on what detail levels you are using).

Also, using larger pages uses slightly less memory, although you should generally give performance precedence over memory usage.

Definition at line 106 of file PagedGeometry.cpp.

setShadersEnabled()

void Forests::PagedGeometry::setShadersEnabled ( bool  value )

inline

disables the use of shaders

Definition at line 550 of file PagedGeometry.h.

setTempDir()

void Forests::PagedGeometry::setTempDir

(

Ogre::String

dir

)

Sets the output directory for the imposter pages.

Definition at line 70 of file PagedGeometry.cpp.

setVisible()

void Forests::PagedGeometry::setVisible ( bool  visible )

inline

Hides or unhides all geometry managed by this PagedGeometry instance \params visible Whether or not you want this PagedGeometry to be visible.

By default everything is visible. This can be used to hide an entire PagedGeometry "group" of geometry if desired.

Definition at line 537 of file PagedGeometry.h.

update()

void Forests::PagedGeometry::update

(

)

Updates this PagedGeometry object.

This function must be called each frame in order for the PagedGeometry object to calculate LODs and perform paging. If this function is not called every frame, none of the geometry managed by this PagedGeometry instance will appear (or if it does, it will appear incorrectly)

Definition at line 155 of file PagedGeometry.cpp.

Field Documentation

geometryAllowedVisible

bool Forests::PagedGeometry::geometryAllowedVisible

protected

Definition at line 584 of file PagedGeometry.h.

lastOldCamPos

Ogre::Vector3 Forests::PagedGeometry::lastOldCamPos

protected

Definition at line 591 of file PagedGeometry.h.

lastSceneCam

Ogre::Camera* Forests::PagedGeometry::lastSceneCam

protected

Definition at line 590 of file PagedGeometry.h.

lastTime

unsigned long Forests::PagedGeometry::lastTime

protected

Definition at line 607 of file PagedGeometry.h.

m_bounds

TBounds Forests::PagedGeometry::m_bounds

protected

Definition at line 600 of file PagedGeometry.h.

m_nRenderQueue

Ogre::uint8 Forests::PagedGeometry::m_nRenderQueue

protected

The used rendering queue.

Definition at line 603 of file PagedGeometry.h.

m_pagedGroupingNode

Ogre::SceneNode* Forests::PagedGeometry::m_pagedGroupingNode

protected

Definition at line 581 of file PagedGeometry.h.

managerList

std::list<GeometryPageManager*> Forests::PagedGeometry::managerList

protected

Definition at line 594 of file PagedGeometry.h.

oldCamPos

Ogre::Vector3 Forests::PagedGeometry::oldCamPos

protected

Definition at line 588 of file PagedGeometry.h.

pageLoader

PageLoader* Forests::PagedGeometry::pageLoader

protected

Definition at line 597 of file PagedGeometry.h.

pageSize

Ogre::Real Forests::PagedGeometry::pageSize

protected

Definition at line 602 of file PagedGeometry.h.

sceneCam

Ogre::Camera* Forests::PagedGeometry::sceneCam

protected

Definition at line 587 of file PagedGeometry.h.

sceneMgr

Ogre::SceneManager* Forests::PagedGeometry::sceneMgr

protected

Definition at line 580 of file PagedGeometry.h.

shadersEnabled

bool Forests::PagedGeometry::shadersEnabled

protected

Definition at line 582 of file PagedGeometry.h.

tempdir

Ogre::String Forests::PagedGeometry::tempdir

protected

Definition at line 608 of file PagedGeometry.h.

timer

Ogre::Timer Forests::PagedGeometry::timer

protected

Definition at line 606 of file PagedGeometry.h.

---

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

• source/main/terrain/paged/PagedGeometry.h
• source/main/terrain/paged/PagedGeometry.cpp