PagedGeometry  1.2.0
Forests::ImpostorPage Class Reference

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...
 
PagedGeometrygetParentPagedGeometry () const
 
void setBlendMode (ImpostorBlendMode blendMode)
 
ImpostorBlendMode getBlendMode () const
 
ImpostorBatchgetImpostorBatch (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::Vector3getCenterPoint ()
 Gets the center point of the page. More...
 
bool isVisible ()
 Return the current visibility status of the page. More...
 
virtual const Ogre::AxisAlignedBoxgetBoundingBox ()
 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::ColourValuegetImpostorBackgroundColor ()
 
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::SceneManagerm_pSceneMgr
 
PagedGeometrym_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

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

Prepare a geometry page for use.

Parameters
geomThe PagedGeometry object that's creating this GeometryPage.
dataA 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(), and Forests::PagedGeometry::getSceneNode().

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

Prepare a geometry page for entities.

Parameters
leftThe minimum x-coordinate any entities will have.
topThe minimum z-coordinate any entities will have.
rightThe maximum x-coordinate any entities will have.
bottomThe 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.

References Ogre::Vector3::x, Ogre::Vector3::y, and Ogre::Vector3::z.

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
entThe entity that is being added. Keep in mind that the same entity may be added multiple times.
positionThe 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.
rotationThe rotation which should be applied to the entity.
scaleThe scale which should be applied to the entity.
colorThe 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(), Ogre::AxisAlignedBox::getCenter(), and Ogre::Vector3::y.

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.

References Ogre::Vector3::y.

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.

References Ogre::Vector3::y.

void ImpostorPage::setVisible ( bool  visible)
virtual

Toggle the entire page's visibility.

Parameters
visibleWhether or not this page should be visible.

Implements Forests::GeometryPage.

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

Sets fade behavior for this page.

Parameters
enabledWhether or not to enable fading
visibleDistThe distance where geometry will be fully opaque (alpha 1)
invisibleDistThe 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.

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(), Ogre::Radian::valueDegrees(), Ogre::Vector3::x, Ogre::Vector3::y, and Ogre::Vector3::z.

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

Sets the resolution for single impostor images.

Parameters
pixelsThe 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.
static void Forests::ImpostorPage::setImpostorBackgroundColor ( const Ogre::ColourValue color)
inlinestatic

Sets the background color used when rendering impostor images.

Parameters
colorThe 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.

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, OGRE_EXCEPT, regenerate(), and regenerateAll().

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

Regenerates the impostor texture for the specified entity.

Parameters
entThe 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(), and tex.

Referenced by setImpostorPivot().

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.

References BBO_BOTTOM_CENTER, BBO_CENTER, Ogre::SubEntity::getMaterialName(), Ogre::Entity::getMesh(), Ogre::Mesh::getName(), Ogre::Entity::getNumSubEntities(), Forests::PagedGeometry::getSceneManager(), Forests::PagedGeometry::getSceneNode(), Ogre::Entity::getSubEntity(), Forests::ImpostorTexture::getTexture(), Forests::ImpostorTexture::removeTexture(), and Forests::StaticBillboardSet::setTextureStacksAndSlices().

Referenced by setImpostorPivot().