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

Definition at line 84 of file ImpostorPage.h.

Inheritance diagram for Forests::ImpostorPage:

Public Member Functions
	ImpostorPage ()

	~ImpostorPage ()

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

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

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

void	build ()

void	removeEntities ()

void	setVisible (bool visible)

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

void	update ()

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

Static Public Member Functions
static void	setImpostorResolution (Ogre::uint pixels)

static Ogre::uint	getImpostorResolution ()

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

static const Ogre::ColourValue &	getImpostorBackgroundColor ()

static void	setImpostorPivot (Ogre::BillboardOrigin origin)

static Ogre::BillboardOrigin	getImpostorPivot ()

static void	regenerate (Ogre::Entity *ent)

static void	regenerateAll ()

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

Private Types
typedef std::map< Ogre::String, ImpostorBatch * >	TImpostorBatchs

Static Private Attributes
static Ogre::uint	s_nImpostorResolution = 128

static Ogre::uint	s_nSelfInstances = 0

static Ogre::uint	s_nUpdateInstanceID = 0

static Ogre::ColourValue	s_clrImpostorBackground = ColourValue(0.0f, 0.3f, 0.0f, 0.0f)

static Ogre::BillboardOrigin	s_impostorPivot = BBO_CENTER

Member Typedef Documentation

◆ TImpostorBatchs

typedef std::map<Ogre::String, ImpostorBatch*> Forests::ImpostorPage::TImpostorBatchs

private

Definition at line 86 of file ImpostorPage.h.

Constructor & Destructor Documentation

◆ ImpostorPage()

ImpostorPage::ImpostorPage ( )

Default constructor.

Definition at line 44 of file ImpostorPage.cpp.

◆ ~ImpostorPage()

ImpostorPage::~ImpostorPage ( )

Destructor.

Definition at line 58 of file ImpostorPage.cpp.

Member Function Documentation

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

Definition at line 121 of file ImpostorPage.cpp.

◆ build()

void ImpostorPage::build ( )

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.

Definition at line 137 of file ImpostorPage.cpp.

◆ getBlendMode()

ImpostorBlendMode Forests::ImpostorPage::getBlendMode ( ) const

inline

Definition at line 106 of file ImpostorPage.h.

◆ getImpostorBackgroundColor()

static const Ogre::ColourValue & Forests::ImpostorPage::getImpostorBackgroundColor ( )

inlinestatic

Definition at line 164 of file ImpostorPage.h.

◆ getImpostorBatch()

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

inline

Definition at line 109 of file ImpostorPage.h.

◆ getImpostorPivot()

static Ogre::BillboardOrigin Forests::ImpostorPage::getImpostorPivot ( )

inlinestatic

Definition at line 194 of file ImpostorPage.h.

◆ getImpostorResolution()

static Ogre::uint Forests::ImpostorPage::getImpostorResolution ( )

inlinestatic

Definition at line 137 of file ImpostorPage.h.

◆ getParentPagedGeometry()

PagedGeometry * Forests::ImpostorPage::getParentPagedGeometry ( ) const

inline

Definition at line 104 of file ImpostorPage.h.

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

Definition at line 91 of file ImpostorPage.cpp.

◆ injectImpostorBatch()

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

inline

Definition at line 116 of file ImpostorPage.h.

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

Definition at line 235 of file ImpostorPage.cpp.

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

Definition at line 242 of file ImpostorPage.cpp.

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

Definition at line 184 of file ImpostorPage.cpp.

◆ setBlendMode()

void Forests::ImpostorPage::setBlendMode ( ImpostorBlendMode blendMode )

inline

Definition at line 105 of file ImpostorPage.h.

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

Definition at line 170 of file ImpostorPage.cpp.

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

Definition at line 157 of file ImpostorPage.h.

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

Definition at line 181 of file ImpostorPage.h.

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

Definition at line 136 of file ImpostorPage.h.

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

Definition at line 109 of file ImpostorPage.cpp.

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

Definition at line 156 of file ImpostorPage.cpp.

◆ update()

void ImpostorPage::update ( )

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.

Definition at line 201 of file ImpostorPage.cpp.

Field Documentation

◆ m_blendMode

ImpostorBlendMode Forests::ImpostorPage::m_blendMode

protected

Definition at line 228 of file ImpostorPage.h.

◆ m_mapImpostorBatches

TImpostorBatchs Forests::ImpostorPage::m_mapImpostorBatches

protected

Definition at line 233 of file ImpostorPage.h.

◆ m_nAveCount

Ogre::uint Forests::ImpostorPage::m_nAveCount

protected

Definition at line 230 of file ImpostorPage.h.

◆ m_nInstanceID

Ogre::uint Forests::ImpostorPage::m_nInstanceID

protected

Definition at line 229 of file ImpostorPage.h.

◆ m_pPagedGeom

PagedGeometry* Forests::ImpostorPage::m_pPagedGeom

protected

Definition at line 227 of file ImpostorPage.h.

◆ m_pSceneMgr

Ogre::SceneManager* Forests::ImpostorPage::m_pSceneMgr

protected

Definition at line 226 of file ImpostorPage.h.

◆ m_timerUpdate

Ogre::Timer Forests::ImpostorPage::m_timerUpdate

protected

Definition at line 232 of file ImpostorPage.h.

◆ m_vecCenter

Ogre::Vector3 Forests::ImpostorPage::m_vecCenter

protected

Definition at line 231 of file ImpostorPage.h.

◆ s_clrImpostorBackground

ColourValue Forests::ImpostorPage::s_clrImpostorBackground = ColourValue(0.0f, 0.3f, 0.0f, 0.0f)

staticprivate

Definition at line 240 of file ImpostorPage.h.

◆ s_impostorPivot

BillboardOrigin Forests::ImpostorPage::s_impostorPivot = BBO_CENTER

staticprivate

Definition at line 241 of file ImpostorPage.h.

◆ s_nImpostorResolution

Ogre::uint Forests::ImpostorPage::s_nImpostorResolution = 128

staticprivate

Definition at line 237 of file ImpostorPage.h.

◆ s_nSelfInstances

Ogre::uint Forests::ImpostorPage::s_nSelfInstances = 0

staticprivate

Definition at line 238 of file ImpostorPage.h.

◆ s_nUpdateInstanceID

Ogre::uint Forests::ImpostorPage::s_nUpdateInstanceID = 0

staticprivate

Definition at line 239 of file ImpostorPage.h.

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

source/main/terrain/paged/ImpostorPage.h
source/main/terrain/paged/ImpostorPage.cpp

Description

Public Member Functions

Static Public Member Functions

Protected Attributes

Private Types

Static Private Attributes

Member Typedef Documentation

◆ TImpostorBatchs

Constructor & Destructor Documentation

◆ ImpostorPage()

◆ ~ImpostorPage()

Member Function Documentation

◆ addEntity()

◆ build()

◆ getBlendMode()

◆ getImpostorBackgroundColor()

◆ getImpostorBatch()

◆ getImpostorPivot()

◆ getImpostorResolution()

◆ getParentPagedGeometry()

◆ init()

◆ injectImpostorBatch()

◆ regenerate()

◆ regenerateAll()

◆ removeEntities()

◆ setBlendMode()

◆ setFade()

◆ setImpostorBackgroundColor()

◆ setImpostorPivot()

◆ setImpostorResolution()

◆ setRegion()

◆ setVisible()

◆ update()

Field Documentation

◆ m_blendMode

◆ m_mapImpostorBatches

◆ m_nAveCount

◆ m_nInstanceID

◆ m_pPagedGeom

◆ m_pSceneMgr

◆ m_timerUpdate

◆ m_vecCenter

◆ s_clrImpostorBackground

◆ s_impostorPivot

◆ s_nImpostorResolution

◆ s_nSelfInstances

◆ s_nUpdateInstanceID