Forests::BatchPage Class Reference

The BatchPage class renders entities as StaticGeometry. More...

#include <BatchPage.h>

Inheritance diagram for Forests::BatchPage:

Public Member Functions
	BatchPage ()
	Default constructor.
void	init (PagedGeometry *geom, const Ogre::Any &data)
	Replace pure virtual GeometryPage::init.
void	addEntity (Ogre::Entity *ent, const Ogre::Vector3 &position, const Ogre::Quaternion &rotation, const Ogre::Vector3 &scale, const Ogre::ColourValue &color)
	Add an entity to the page, at the specified position, rotation, and scale. More...
void	removeEntities ()
	Remove all geometry/entities from the page completely. More...
void	build ()
	Perform any final steps to make added entities appear in the scene. More...
void	setVisible (bool visible)
	Toggle the entire page's visibility. More...
void	setFade (bool enabled, Ogre::Real visibleDist, Ogre::Real invisibleDist)
	Sets fade behavior for this page. More...
void	addEntityToBoundingBox ()
void	clearBoundingBox ()
	Advanced: Reset the bounding box used by addEntityToBoundingBox() More...
const Ogre::AxisAlignedBox &	getBoundingBox ()
	Advanced: Return the bounding box computed with addEntityToBoundingBox() More...
Public Member Functions inherited from Forests::GeometryPage
void	setQueryFlag (Ogre::uint32 flag)
bool	hasQueryFlag ()
Ogre::uint32	getQueryFlag ()
virtual void	setRegion (Ogre::Real left, Ogre::Real top, Ogre::Real right, Ogre::Real bottom)
	Prepare a geometry page for entities. More...
virtual void	update ()
	Do whatever needs to be done to keep the page geometry up-to-date. More...
Ogre::Vector3 &	getCenterPoint ()
	Gets the center point of the page. More...
bool	isVisible ()
	Return the current visibility status of the page. More...
virtual void	addEntityToBoundingBox (Ogre::Entity *ent, const Ogre::Vector3 &position, const Ogre::Quaternion &rotation, const Ogre::Vector3 &scale)
	Advanced: Expand the current bounding box to include the given entity. More...
virtual	~GeometryPage ()
	Destructor This is defined here so the destructors of derived classes are called properly. More...
	GeometryPage ()
	Constructor Initialise everything to zero, false or NULL except for _trueBoundsUndefined that is set to true.

Protected Member Functions
virtual void	_updateShaders ()

Protected Attributes
PagedGeometry *	m_pPagedGeom
Ogre::SceneManager *	m_pSceneMgr
BatchedGeometry *	m_pBatchGeom
size_t	m_nLODLevel
bool	m_bFadeEnabled
bool	m_bShadersSupported
Ogre::Real	m_fVisibleDist
Ogre::Real	m_fInvisibleDist
TMaterials	m_vecUnfadedMaterials

Static Protected Attributes
static unsigned long	s_nRefCount = 0
static unsigned long	s_nGUID = 0

Detailed Description

The BatchPage class renders entities as StaticGeometry.

This is one of the geometry page types included in the StaticGeometry engine. These page types should be added to a PagedGeometry object with PagedGeometry::addDetailLevel() so the PagedGeometry will know how you want your geometry displayed.

To use this page type, use (the last parameter is optional):

PagedGeometry::addDetailLevel<BatchPage>(farRange, transitionLength, Ogre::Any(LODLevel));

This page type uses batched geometry (Ogre::StaticGeometry) to represent the entities. Batched geometry is generally much faster than plain entities, since video card state changes and transform calculations can be minimized. Batched geometry can be anywhere from 2 to 20 times faster than plain entities.

"LODLevel" can be used to specify a certain LOD level to use from the added entities. This would be useful, for example, if you wanted to add high-res batched trees near the camera, and low-res batched trees farther away.

Member Function Documentation

addEntity()

void BatchPage::addEntity ( Ogre::Entity *  ent, const Ogre::Vector3 &  position, const Ogre::Quaternion &  rotation, const Ogre::Vector3 &  scale, const Ogre::ColourValue &  color  )

virtual

Add an entity to the page, at the specified position, rotation, and scale.

Parameters

ent	The entity that is being added. Keep in mind that the same entity may be added multiple times.
position	The position where the entity must be placed. Under normal circumstances, this will never be outside of the bounds supplied to init(). The only exception is when a PageLoader tries to add an entity outside of the bounds it was given.
rotation	The rotation which should be applied to the entity.
scale	The scale which should be applied to the entity.
color	The desired color to apply to the whole entity

Note

The entity does not have to actually appear in the scene until build() is called.

Implements Forests::GeometryPage.

References Ogre::Entity::getManualLodLevel(), Ogre::MovableObject::getName(), Ogre::Entity::getNumManualLodLevels(), Ogre::LogManager::getSingleton(), Ogre::LogManager::logMessage(), and Ogre::StringConverter::toString().

removeEntities()

void BatchPage::removeEntities ( )

virtual

Remove all geometry/entities from the page completely.

Make sure this completely reverses the effects of both build() and addEntity(). This is necessary, because after this is called, the entities will most likely be added again with addEntity() and build().

Do not leave any remains of the entities in memory after this function is called. One of the advantages of using paged geometry is that you can have near-infinite game worlds, which would normally exceed a computer's RAM capacity. This advantage would completely disappear if you did not clean up properly when the page manager calls this function.

Implements Forests::GeometryPage.

build()

void BatchPage::build ( void  )

virtual

Perform any final steps to make added entities appear in the scene.

build() is automatically called right after all the entities have been added with addEntity(). Use this if there are any final steps that need to be performed after addEntity() has been called in order to display the entities.

Note

This function is not pure virtual, so you don't have to override it if you don't need to.

Reimplemented from Forests::GeometryPage.

References Forests::BatchedGeometry::build(), MapIteratorWrapper< T, T::iterator >::getNext(), Ogre::Technique::getNumPasses(), Ogre::Material::getNumTechniques(), Ogre::Technique::getPass(), Ogre::Material::getTechnique(), Ogre::IteratorWrapper< class, class, class >::hasMoreElements(), Ogre::Pass::hasVertexProgram(), and Ogre::Pass::setSpecular().

setVisible()

void BatchPage::setVisible ( bool  visible )

virtual

Toggle the entire page's visibility.

Parameters

visible

Whether or not this page should be visible.

Implements Forests::GeometryPage.

References Ogre::MovableObject::setVisible().

setFade()

void BatchPage::setFade ( bool  enabled, Ogre::Real  visibleDist, Ogre::Real  invisibleDist  )

virtual

Sets fade behavior for this page.

Parameters

enabled	Whether or not to enable fading
visibleDist	The distance where geometry will be fully opaque (alpha 1)
invisibleDist	The distance where geometry will be invisible (alpha 0)

This is called whenever a page needs fading enabled/disabled. The distance ranges given specify how the final alpha values should be calculated - geometry at visibleDist should have alpha values of 1, while geometry at invisibleDist should have alpha values of 0. Important: Distances must be calculated in the xz plane only - the y coordinate should be disregarded when calculating distance.

setFade() won't be called unless the user's computer supports vertex shaders.

Note

invisibleDist may be greater than or less than visibleDist, depending on whether the geometry is fading out or in to the distance.

Implements Forests::GeometryPage.

References Forests::PagedGeometry::getRenderQueue(), RENDER_QUEUE_6, RENDER_QUEUE_MAIN, and Ogre::MovableObject::setRenderQueueGroup().

clearBoundingBox()

void Forests::BatchPage::clearBoundingBox ( )

inlinevirtual

Advanced: Reset the bounding box used by addEntityToBoundingBox()

Advanced: Override this function only if your page implementation already computes a bounding box (local to the page center) for added entities. This way you can prevent the bounding box from being computed twice.

See also

getBoundingBox() for important details.

Reimplemented from Forests::GeometryPage.

getBoundingBox()

const Ogre::AxisAlignedBox& Forests::BatchPage::getBoundingBox ( void  )

inlinevirtual

Advanced: Return the bounding box computed with addEntityToBoundingBox()

Advanced: Override this function only if your page implementation already computes a bounding box (local to the page center) for added entities. This way you can prevent the bounding box from being computed twice.

When performing fade transitions, the page manager needs to know the actual boundaries of an entire page of entities in order to avoid entities "popping" into view without a smooth transition due to loose grid boundaries. Anyway, as long as this function returns the combined bounding box of all entities added to this page properly, fade transitions should work fairly smoothly.

Important: If you implement this function, you must also override addEntityToBoundingBox() and clearBoundingBox() (although you don't need to implement them as long as getBoundingBox() functions as expected). Otherwise the default implementations of these function will be used and therefore result in the bounding box being calculated twice.

Reimplemented from Forests::GeometryPage.