The ImpostorPage class renders entities as impostors (billboard images that look just like the real entity). More...

#include <ImpostorPage.h>

Inheritance diagram for Forests::ImpostorPage:

Public Member Functions
	ImpostorPage ()
	Default constructor.

	~ImpostorPage ()
	Destructor.

void	init (PagedGeometry *geom, const Ogre::Any &data)
	Prepare a geometry page for use. More...

void	setRegion (Ogre::Real left, Ogre::Real top, Ogre::Real right, Ogre::Real bottom)
	Prepare a geometry page for entities. More...

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	build ()
	Perform any final steps to make added entities appear in the scene. More...

void	removeEntities ()
	Remove all geometry/entities from the page completely. 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	update ()
	Do whatever needs to be done to keep the page geometry up-to-date. More...

PagedGeometry *	getParentPagedGeometry () const

void	setBlendMode (ImpostorBlendMode blendMode)

ImpostorBlendMode	getBlendMode () const

ImpostorBatch *	getImpostorBatch (const Ogre::String &key) const

bool	injectImpostorBatch (const Ogre::String &key, ImpostorBatch *injectedBatch)

Public Member Functions inherited from Forests::GeometryPage
void	setQueryFlag (Ogre::uint32 flag)

bool	hasQueryFlag ()

Ogre::uint32	getQueryFlag ()

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.

Static Public Member Functions
static void	setImpostorResolution (Ogre::uint pixels)
	Sets the resolution for single impostor images. More...

static Ogre::uint	getImpostorResolution ()

static void	setImpostorBackgroundColor (const Ogre::ColourValue &color)
	Sets the background color used when rendering impostor images. More...

static const Ogre::ColourValue &	getImpostorBackgroundColor ()

static void	setImpostorPivot (Ogre::BillboardOrigin origin)
	Sets the billboard pivot point used when rendering camera-facing impostors. More...

static Ogre::BillboardOrigin	getImpostorPivot ()

static void	regenerate (Ogre::Entity *ent)
	Regenerates the impostor texture for the specified entity. More...

static void	regenerateAll ()
	Regenerates all impostor textures currently being used in the scene. More...

Protected Attributes
Ogre::SceneManager *	m_pSceneMgr

PagedGeometry *	m_pPagedGeom

ImpostorBlendMode	m_blendMode

Ogre::uint	m_nInstanceID

Ogre::uint	m_nAveCount

Ogre::Vector3	m_vecCenter

Ogre::Timer	m_timerUpdate

TImpostorBatchs	m_mapImpostorBatches

Detailed Description

The ImpostorPage class renders entities as impostors (billboard images that look just like the real entity).

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:

PagedGeometry::addDetailLevel<ImpostorPage>(farRange);

TexturePtr renderTexture;

Of all the page types included in the PagedGeometry engine, this one is the fastest. It uses impostors (billboards that look just like the real entity) to represent entities. This way, your video card only has to render a bunch of 2D images, instead of a full 3D mesh. Imposters are generally used off in the distance slightly, since they don't always look exactly like the real thing, especially up close (since they are flat, and sometimes slightly pixelated).

Note: Impostors are generated only once for each entity. If you make any changes to your entities, you'll have to force impostor regeneration by deleting the prerender files located in your executable's working directory (named "Impostor.[ResourceGroup].[Entity].png")

Member Function Documentation

◆ init()

void ImpostorPage::init	(	PagedGeometry *	geom,
		const Ogre::Any &	data
	)

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!

Implements Forests::GeometryPage.

References Ogre::SceneNode::createChildSceneNode(), Forests::PagedGeometry::getSceneManager(), Forests::PagedGeometry::getSceneNode(), and getSingleton().

◆ setRegion()

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

virtual

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 from Forests::GeometryPage.

◆ addEntity()

void ImpostorPage::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::getBoundingBox(), and Ogre::AxisAlignedBox::getCenter().

◆ build()

void ImpostorPage::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.

◆ removeEntities()

void ImpostorPage::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.

◆ setVisible()

void ImpostorPage::setVisible ( bool visible )

virtual

Toggle the entire page's visibility.

Parameters

visible Whether or not this page should be visible.

Implements Forests::GeometryPage.

◆ setFade()

void ImpostorPage::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.

◆ update()

void ImpostorPage::update ( void )

virtual

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 from Forests::GeometryPage.

References Forests::PagedGeometry::_convertToLocal(), Forests::PagedGeometry::getCamera(), Ogre::Camera::getDerivedDirection(), Ogre::Camera::getDerivedPosition(), Forests::PagedGeometry::getPageSize(), and Ogre::Radian::valueDegrees().

◆ setImpostorResolution()

static void Forests::ImpostorPage::setImpostorResolution ( Ogre::uint pixels )

inlinestatic

Sets the resolution for single impostor images.

Parameters

pixels The width/height of one square impostor render

The default impostor resolution is 128x128. Note that 32 impostor images will be stored in a single texture (8 x 4), so a impostor resolution of 128, for example, results in final texture size of 1024 x 512.

Warning: Calling this function will have no effect unless it is done before any entities are added to any page.

◆ setImpostorBackgroundColor()

static void Forests::ImpostorPage::setImpostorBackgroundColor ( const Ogre::ColourValue & color )

inlinestatic

Sets the background color used when rendering impostor images.

Parameters

color The background color

Choosing an impostor color that closely matches the main color of your objects is important to reduce mipmap artifacts. When distant objects are displayed as impostors, hardware mipmapping can cause the color surrounding your object (the background color) to "bleed" into the main image, which can result in incorrectly tinted distant objects.

The default background color is ColourValue(0.0f, 0.3f, 0.0f, 0.0f), or dark green (this color was chosen because the main use of ImpostorPage is for trees, bushes, etc.)

Warning: Calling this function will have no effect unless it is done before any entities are added to any page. Also remember that you may have to delete the old impostor renders (located in your exe's directory) in order for the new ones to be generated.

References Ogre::ColourValue::a.

◆ setImpostorPivot()

static void Forests::ImpostorPage::setImpostorPivot ( Ogre::BillboardOrigin origin )

inlinestatic

Sets the billboard pivot point used when rendering camera-facing impostors.

This function can be used to set how impostors should rotate to face the camera. By default, impostors are pointed towards the camera by rotating around the impostor billboard's center. By choosing an alternate pivot point with this function, you can acheive better results under certain conditions. For example, when looking up or down very steep hills, you'll probably want to set BBO_BOTTOM_CENTER as the pivot point. For most other cases, however, the default pivot point of BBO_CENTER works best.

Note: Only BBO_CENTER and BBO_BOTTOM_CENTER is supported by this function currently.

Warning: Calling this function will have no effect unless it is done before any entities are added to any page.

References Ogre::BBO_BOTTOM_CENTER, Ogre::BBO_CENTER, Ogre::Exception::ERR_INVALIDPARAMS, and OGRE_EXCEPT.

◆ regenerate()

void ImpostorPage::regenerate ( Ogre::Entity * ent )

static

Regenerates the impostor texture for the specified entity.

Parameters

ent	The entity which will have it's impostor texture regenerated

This function can be called to force the regeneration of a specific impostor. Normally, impostors are generated once (saved to a file), and simply preloaded from the file afterwards (unless you delete the file). Calling this will instantly regenerate the impostor and update it's saved image file.

Note: This function cannot regenerate an impostor unless it's already being used in the scene.

Warning: This is NOT a real-time operation - it may take a few seconds to complete.

References Forests::ImpostorTexture::getTexture().

◆ regenerateAll()

void ImpostorPage::regenerateAll ( )

static

Regenerates all impostor textures currently being used in the scene.

This function can be called to force the regeneration of all impostors currently being used in your scene. Normally, impostors are generated once (saved to a file), and simply preloaded from the files afterwards (unless you delete the files). Calling this will instantly regenerate the impostors and update their saved image files.

Warning: This is NOT a real-time operation - it may take a few seconds to complete.

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ init()

◆ setRegion()

◆ addEntity()

◆ build()

◆ removeEntities()

◆ setVisible()

◆ setFade()

◆ update()

◆ setImpostorResolution()

◆ setImpostorBackgroundColor()

◆ setImpostorPivot()

◆ regenerate()

◆ regenerateAll()