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

Definition at line 671 of file PagedGeometry.h.

Inheritance diagram for Forests::GeometryPage:

Public Member Functions
virtual void	init (PagedGeometry *geom, const Ogre::Any &data)=0

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

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

virtual void	build ()

virtual void	removeEntities ()=0

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

virtual void	setVisible (bool visible)=0

virtual void	update ()

Ogre::Vector3 &	getCenterPoint ()

bool	isVisible ()

virtual const Ogre::AxisAlignedBox &	getBoundingBox ()

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

virtual void	clearBoundingBox ()

virtual	~GeometryPage ()

	GeometryPage ()

Private Attributes
Ogre::Vector3	_centerPoint

int	_xIndex

int	_zIndex

unsigned long	_inactiveTime

bool	_visible

bool	_fadeEnable

bool	_pending

bool	_loaded

bool	_needsUnload

bool	_keepLoaded

std::list< GeometryPage * >::iterator	_iter

Ogre::AxisAlignedBox	_trueBounds

bool	_trueBoundsUndefined

Friends
class	GeometryPageManager

Constructor & Destructor Documentation

◆ ~GeometryPage()

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.

Definition at line 860 of file PagedGeometry.h.

◆ GeometryPage()

Forests::GeometryPage::GeometryPage ( )

Constructor Initialise everything to zero, false or NULL except for _trueBoundsUndefined that is set to true.

Definition at line 940 of file PagedGeometry.cpp.

Member Function Documentation

◆ addEntity()

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

◆ addEntityToBoundingBox()

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.

Definition at line 948 of file PagedGeometry.cpp.

◆ build()

virtual void Forests::GeometryPage::build ( )

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

Definition at line 744 of file PagedGeometry.h.

◆ clearBoundingBox()

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.

Definition at line 976 of file PagedGeometry.cpp.

◆ getBoundingBox()

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

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.

Definition at line 971 of file PagedGeometry.cpp.

◆ getCenterPoint()

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.

Definition at line 803 of file PagedGeometry.h.

◆ init()

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

◆ isVisible()

bool Forests::GeometryPage::isVisible ( )

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.

Definition at line 811 of file PagedGeometry.h.

◆ removeEntities()

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

◆ setFade()

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

◆ setRegion()

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.

Definition at line 715 of file PagedGeometry.h.

◆ setVisible()

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

◆ update()

virtual void Forests::GeometryPage::update ( )

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.

Definition at line 795 of file PagedGeometry.h.

Friends And Related Symbol Documentation

◆ GeometryPageManager

friend class GeometryPageManager

friend

Definition at line 673 of file PagedGeometry.h.

Field Documentation

◆ _centerPoint

Ogre::Vector3 Forests::GeometryPage::_centerPoint

private

Definition at line 870 of file PagedGeometry.h.

◆ _fadeEnable

bool Forests::GeometryPage::_fadeEnable

private

Definition at line 874 of file PagedGeometry.h.

◆ _inactiveTime

unsigned long Forests::GeometryPage::_inactiveTime

private

Definition at line 872 of file PagedGeometry.h.

◆ _iter

std::list<GeometryPage*>::iterator Forests::GeometryPage::_iter

private

Definition at line 880 of file PagedGeometry.h.

◆ _keepLoaded

bool Forests::GeometryPage::_keepLoaded

private

Definition at line 879 of file PagedGeometry.h.

◆ _loaded

bool Forests::GeometryPage::_loaded

private

Definition at line 877 of file PagedGeometry.h.

◆ _needsUnload

bool Forests::GeometryPage::_needsUnload

private

Definition at line 878 of file PagedGeometry.h.

◆ _pending

bool Forests::GeometryPage::_pending

private

Definition at line 876 of file PagedGeometry.h.

◆ _trueBounds

Ogre::AxisAlignedBox Forests::GeometryPage::_trueBounds

private

Definition at line 882 of file PagedGeometry.h.

◆ _trueBoundsUndefined

bool Forests::GeometryPage::_trueBoundsUndefined

private

Definition at line 883 of file PagedGeometry.h.

◆ _visible

bool Forests::GeometryPage::_visible

private

Definition at line 873 of file PagedGeometry.h.

◆ _xIndex

int Forests::GeometryPage::_xIndex

private

Definition at line 871 of file PagedGeometry.h.

◆ _zIndex

int Forests::GeometryPage::_zIndex

private

Definition at line 871 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

Description

Public Member Functions

Private Attributes

Friends

Constructor & Destructor Documentation

◆ ~GeometryPage()

◆ GeometryPage()

Member Function Documentation

◆ addEntity()

◆ addEntityToBoundingBox()

◆ build()

◆ clearBoundingBox()

◆ getBoundingBox()

◆ getCenterPoint()

◆ init()

◆ isVisible()

◆ removeEntities()

◆ setFade()

◆ setRegion()

◆ setVisible()

◆ update()

Friends And Related Symbol Documentation

◆ GeometryPageManager

Field Documentation

◆ _centerPoint

◆ _fadeEnable

◆ _inactiveTime

◆ _iter

◆ _keepLoaded

◆ _loaded

◆ _needsUnload

◆ _pending

◆ _trueBounds

◆ _trueBoundsUndefined

◆ _visible

◆ _xIndex

◆ _zIndex