This base-class can be extended to provide different ways of representing entities. More...

#include <PagedGeometry.h>

Inheritance diagram for Forests::GeometryPage:

[legend]

Public Member Functions
virtual void	init (PagedGeometry *geom, const Ogre::Any &data)=0
	Prepare a geometry page for use. More...

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	addEntity (Ogre::Entity *ent, const Ogre::Vector3 &position, const Ogre::Quaternion &rotation, const Ogre::Vector3 &scale, const Ogre::ColourValue &color)=0
	Add an entity to the page, at the specified position, rotation, and scale. More...

virtual void	build ()
	Perform any final steps to make added entities appear in the scene. More...

virtual void	removeEntities ()=0
	Remove all geometry/entities from the page completely. More...

virtual void	setFade (bool enabled, Ogre::Real visibleDist=0, Ogre::Real invisibleDist=0)=0
	Sets fade behavior for this page. More...

virtual void	setVisible (bool visible)=0
	Toggle the entire page's visibility. 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 const Ogre::AxisAlignedBox &	getBoundingBox ()
	Advanced: Return the bounding box computed with addEntityToBoundingBox() 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 void	clearBoundingBox ()
	Advanced: Reset the bounding box used by addEntityToBoundingBox() 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.

Friends
class	GeometryPageManager

Detailed Description

This base-class can be extended to provide different ways of representing entities.

The PagedGeometry engine comes pre-installed with a few GeometryPage sub-classes (BatchPage, and ImpostorPage). These "page types" can all be supplied to a PagedGeometry object through addDetailLevel().

See also: PagedGeometry::addDetailLevel() for more information about setting up detail levels.

If you need more than the pre-installed page types, you can easily create your own! Simply make a new class inheriting GeometryPage. Then implement the necessary member functions, and it should work immediately. No additional setup is required.

There are several virtual member functions you will need to implement in your class:

virtual void init(SceneManager *mgr, Camera *cam) = 0;
virtual void setRegion(Real left, Real top, Real right, Real bottom) = 0;
virtual void addEntity(Entity *ent, const Vector3 &position, const Quaternion &rotation, const Vector3 &scale, const Ogre::ColourValue &color, void* userData = NULL) = 0;
virtual void build() {}
virtual void removeEntities() = 0;
virtual void setVisible(bool visible) = 0;
virtual void setFade(bool enabled, Real visibleDist, Real invisibleDist) = 0;
virtual void update() {}

Note: For detailed information on implementing each of these functions, please refer to their documentation.

Here is how the page manager uses these functions:

1. When a PagedGeometry first creates a GeometryPage, it immediately calls GeometryPage::init(). This function is called just like a constructor, and you should use it the same way.

2. GeometryPage::setRegion() is called to provide you with the area where upcoming entities will be added. You can use this information any way you like, or you can omit this step completely by omitting the setRegion() function from your class definition.

3. To load a page, the addEntity() function is used to insert all the entities into the scene. Then, build() is called. Entities don't actually have to be displayed until after build() is called.

4. setVisible() and setFade() will be called occasionally to update the visibility/fade status of the page.

5. When the page has become obsolete, the contents of it is deleted with removeEntities(). This should return the page to the state it was before addEntity() and build().

6. Steps 2-5 are repeated as pages are loaded/unloaded

Implementing your own geometry page is really very simple. As long as the functions do their jobs right, everything will work fine. If you learn best be example, you may want to take a look at how the included page types are implemented also.

See also: The BatchPage or GrassPage code for examples of how page types are implemented (the ImpostorPage can also be used as an example, although it is a somewhat complex technique, and is not recommended for learning how GeometryPage's work).

Constructor & Destructor Documentation

virtual Forests::GeometryPage::~GeometryPage ( )

inlinevirtual

Destructor This is defined here so the destructors of derived classes are called properly.

Whether or not you actually implement a destructor is up to you.

Member Function Documentation

virtual void Forests::GeometryPage::init	(	PagedGeometry *	geom,
		const Ogre::Any &	data
	)

pure virtual

Prepare a geometry page for use.

Parameters

geom	The PagedGeometry object that's creating this GeometryPage.
data	A single parameter of custom data (optional).

This is called immediately after creating a new GeometryPage. It is never called more than once for a single instance of your geometry page.

The "data" parameter is set for all pages when PagedGeometry::addDetailLevel() is called. This parameter is optional and can be used for whatever you like if you need a constructor parameter of some kind. Be sure to document what kind of variable the user needs to supply and what it's purpose is in your GeometryPage implementation.

Note: If you need to get the current camera, scene manager, etc., use the geom parameter. The PagedGeometry class contains inline methods you can use to access the camera and scene manager.

Warning: Do NOT store a local copy of geom->getCamera()! The camera returned by this function may change at any time!

Implemented in Forests::GrassPage, Forests::ImpostorPage, Forests::WindBatchPage, and Forests::BatchPage.

Referenced by Forests::GeometryPageManager::initPages().

virtual void Forests::GeometryPage::setRegion	(	Ogre::Real	left,
		Ogre::Real	top,
		Ogre::Real	right,
		Ogre::Real	bottom
	)

inlinevirtual

Prepare a geometry page for entities.

Parameters

left	The minimum x-coordinate any entities will have.
top	The minimum z-coordinate any entities will have.
right	The maximum x-coordinate any entities will have.
bottom	The maximum z-coordinate any entities will have.

This basically provides you with a region where upcoming entities will be located, since many geometry rendering methods require this data. It's up to you how this data is used, if at all.

setRegion() is never called when the page contains entities; only once just before a load process (when entities are added with addEntity).

Note: Implementing this funtion in your GeometryPage is completely optional, since most of the time you don't need region information.

Reimplemented in Forests::ImpostorPage.

Referenced by Forests::GeometryPageManager::resetPreloadedGeometry().

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

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

Implemented in Forests::GrassPage, Forests::ImpostorPage, and Forests::BatchPage.

virtual void Forests::GeometryPage::build ( void )

inlinevirtual

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 in Forests::ImpostorPage, and Forests::BatchPage.

References Forests::PagedGeometry::setVisible().

Referenced by Forests::GeometryPageManager::resetPreloadedGeometry().

virtual void Forests::GeometryPage::removeEntities ( )

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

Implemented in Forests::GrassPage, Forests::ImpostorPage, and Forests::BatchPage.

Referenced by Forests::GeometryPageManager::resetPreloadedGeometry().

virtual void Forests::GeometryPage::setFade	(	bool	enabled,
		Ogre::Real	visibleDist = `0`,
		Ogre::Real	invisibleDist = `0`
	)

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

Implemented in Forests::GrassPage, Forests::ImpostorPage, and Forests::BatchPage.

Referenced by Forests::GeometryPageManager::update().

virtual void Forests::GeometryPage::setVisible ( bool visible )

pure virtual

Toggle the entire page's visibility.

Parameters

visible Whether or not this page should be visible.

Implemented in Forests::GrassPage, Forests::ImpostorPage, and Forests::BatchPage.

Referenced by Forests::GeometryPageManager::resetPreloadedGeometry(), and Forests::GeometryPageManager::update().

virtual void Forests::GeometryPage::update ( void )

inlinevirtual

Do whatever needs to be done to keep the page geometry up-to-date.

update() is called each frame for each GeometryPage instance. This function should perform any operations that are needed to keep the geometry page up-to-date.

Note: Overriding this function is optional, however, since not all implementations of geometry may need to be updated.

Reimplemented in Forests::ImpostorPage.

Referenced by Forests::GeometryPageManager::update().

Ogre::Vector3& Forests::GeometryPage::getCenterPoint ( )

inline

Gets the center point of the page.

Returns: The center points of the page.

Note: This is a non-virtual utility function common to all GeometryPage classes, don't try to override it.

Referenced by Forests::GeometryPageManager::reloadGeometryPages().

bool Forests::GeometryPage::isVisible ( void )

inline

Return the current visibility status of the page.

Returns: The current visibility status of the page.

Note: This is a non-virtual utility function common to all GeometryPage classes, don't try to override it.

References getBoundingBox().

const AxisAlignedBox & Forests::GeometryPage::getBoundingBox ( void )

virtual

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 in Forests::BatchPage.

void Forests::GeometryPage::addEntityToBoundingBox	(	Ogre::Entity *	ent,
		const Ogre::Vector3 &	position,
		const Ogre::Quaternion &	rotation,
		const Ogre::Vector3 &	scale
	)

virtual

Advanced: Expand the current bounding box to include the given entity.

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.

References Ogre::Entity::getBoundingBox(), Ogre::AxisAlignedBox::getMaximum(), Ogre::AxisAlignedBox::getMinimum(), Ogre::Vector3::makeCeil(), Ogre::Vector3::makeFloor(), Ogre::Matrix4::setScale(), and Ogre::AxisAlignedBox::transform().

void Forests::GeometryPage::clearBoundingBox ( )

virtual

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 in Forests::BatchPage.

Referenced by Forests::GeometryPageManager::initPages(), and Forests::GeometryPageManager::resetPreloadedGeometry().

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation