Forests::StaticBillboardSet Class Reference

A faster alternative to Ogre's built-in BillboardSet class. More...

#include <StaticBillboardSet.h>

Public Member Functions
	StaticBillboardSet (Ogre::SceneManager *mgr, Ogre::SceneNode *rootSceneNode, BillboardMethod method=BB_METHOD_ACCELERATED)
	Initializes a StaticBillboardSet object. More...
	~StaticBillboardSet ()
	Destructor.
void	createBillboard (const Ogre::Vector3 &position, float xScale=1.0f, float yScale=1.0f, const Ogre::ColourValue &color=Ogre::ColourValue::White, Ogre::uint16 texcoordIndexU=0, Ogre::uint16 texcoordIndexV=0)
	Adds a billboard to the StaticBillboardSet at the specified position. More...
void	setBillboardOrigin (Ogre::BillboardOrigin origin)
	Sets the billboard's origin (pivotal point) More...
Ogre::BillboardOrigin	getBillboardOrigin () const
	Returns the current billboard origin. More...
BillboardMethod	getRenderMethod () const
	Returns the method used to render billboards. More...
void	setVisible (bool visible)
	Sets whether or not this StaticBillboardSet will be rendered. More...
void	setFade (bool enabled, Ogre::Real visibleDist, Ogre::Real invisibleDist)
	Enables/disables distance fade-out for this billboard set. More...
void	build ()
	Performs final steps required for the created billboards to appear in the scene. More...
void	clear ()
	Deletes all billboards from the scene. More...
void	setMaterial (const Ogre::String &materialName, const Ogre::String &resourceGroup=Ogre::ResourceGroupManager::AUTODETECT_RESOURCE_GROUP_NAME)
	Applies a material to the billboards in this set. More...
void	setTextureStacksAndSlices (Ogre::uint16 stacks, Ogre::uint16 slices)
	Sets how many horizontal slices and vertical stacks the currently applied material is using. More...

Static Public Member Functions
static void	updateAll (const Ogre::Vector3 &cameraDirection, const char *fragmentProgramName)
	Manually updates all StaticBillboardSet objects for a frame. More...

Detailed Description

A faster alternative to Ogre's built-in BillboardSet class.

This class provides a method of displaying billboards faster than Ogre's built-in BillboardSet functions by taking advantage of the static nature of tree billboards. However, if your video card does not support vertex shaders, using this class over Ogre's built-in Billboard class will have no performance benefit.

Note

StaticBillboardSet does not allow billboards to be moved or deleted individually in real-time

Constructor & Destructor Documentation

StaticBillboardSet()

StaticBillboardSet::StaticBillboardSet	(	Ogre::SceneManager *	mgr,
		Ogre::SceneNode *	rootSceneNode,
		BillboardMethod	method = BB_METHOD_ACCELERATED
	)

Initializes a StaticBillboardSet object.

Constructor.

Parameters

mgr	The SceneManager to be used to display the billboards.
method	The method used when rendering billboards. See the BillboardMethod documentation for more information. In almost all cases, this should be set to BB_METHOD_ACCELERATED for optimal speed and efficiency.

References Ogre::SceneNode::attachObject(), Ogre::SceneManager::createBillboardSet(), Ogre::SceneNode::createChildSceneNode(), getSingleton(), Ogre::RenderSystemCapabilities::hasCapability(), and RSC_VERTEX_PROGRAM.

Member Function Documentation

createBillboard()

void Forests::StaticBillboardSet::createBillboard ( const Ogre::Vector3 &  position, float  xScale = 1.0f, float  yScale = 1.0f, const Ogre::ColourValue &  color = Ogre::ColourValue::White, Ogre::uint16  texcoordIndexU = 0, Ogre::uint16  texcoordIndexV = 0  )

inline

Adds a billboard to the StaticBillboardSet at the specified position.

Parameters

position	The desired position of the billboard.
xScale	The width scale of the billboard.
yScale	The height scale of the billboard.
texcoordIndex	The texture tile this billboard will use. This value shoud be 0..n, where n is the number of slices set with setTextureSlices()

The texcoordIndex option is only applicable if you have used setTextureSlices() to divide the applied material into a number of horizontal segments. texcoordIndex selects which segment is applied to the billboard as a texture.

Note

Any billboards created will not appear in the scene until you call build()

References Ogre::BillboardSet::createBillboard(), Ogre::Billboard::setDimensions(), and Ogre::Billboard::setTexcoordRect().

setBillboardOrigin()

void StaticBillboardSet::setBillboardOrigin

(

Ogre::BillboardOrigin

origin

)

Sets the billboard's origin (pivotal point)

This function can be used to set what part of the billboard image is considered the origin, or "center". By default, the center of the image is used, so billboards will pivot around the center and positioning a billboard will place it's center at the desired location. Other origins, like BBO_BOTTOM_CENTER are good for trees, etc. BBO_CENTER is used by default.

References BBO_BOTTOM_CENTER, BBO_CENTER, and Ogre::BillboardSet::setBillboardOrigin().

getBillboardOrigin()

Ogre::BillboardOrigin Forests::StaticBillboardSet::getBillboardOrigin ( ) const

inline

Returns the current billboard origin.

This returns the current billboard origin as set by setBillboardOrigin().

getRenderMethod()

BillboardMethod Forests::StaticBillboardSet::getRenderMethod ( ) const

inline

Returns the method used to render billboards.

The billboard render method is set in the constructor. See the BillboardMethod enum documentation for more information on billboard render methods.

setVisible()

void Forests::StaticBillboardSet::setVisible ( bool  visible )

inline

Sets whether or not this StaticBillboardSet will be rendered.

Parameters

visible

The desired visibility state of the StaticBillboardSet (true/false)

References Ogre::SceneNode::setVisible().

setFade()

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

Enables/disables distance fade-out for this billboard set.

Parameters

enabled	Whether or not to enable fading
visibleDist	The distance where billboards will be fully opaque (alpha 1)
invisibleDist	The distance where billboards will be invisible (alpha 0)

You can use this function to enable distance based alpha fading, so billboards will smoothly fade out into the distance. Note that the fading is performed 2-dimensionally, which means height is not taken into account when fading - only xz distances. This works well with flat terrain maps, but may not be well suited for spherical worlds.

The distance ranges given specify how the final alpha values should be calculated - billboards at visibleDist will have alpha values of 1, and geometry at invisibleDist will have alpha values of 0.

Note

invisibleDist may be greater than or less than visibleDist, depending on whether the geometry is fading out or in to the distance.

setFade() only works in BB_MODE_ACCELERATED mode.

References OGRE_EXCEPT, and Ogre::Entity::setMaterial().

build()

void StaticBillboardSet::build

(

void

)

Performs final steps required for the created billboards to appear in the scene.

Until this is called, any billboards created with createBillboard() will not appear.

References Ogre::MovableObject::_getManager(), Ogre::Mesh::_setBoundingSphereRadius(), Ogre::Mesh::_setBounds(), Ogre::VertexDeclaration::addElement(), Ogre::SceneNode::attachObject(), Ogre::SceneManager::createEntity(), Ogre::Mesh::createSubMesh(), Ogre::SceneManager::destroyEntity(), Ogre::SceneNode::detachAllObjects(), Ogre::Resource::getGroup(), Ogre::AxisAlignedBox::getMaximum(), Ogre::AxisAlignedBox::getMinimum(), Ogre::Resource::getName(), getSingleton(), Ogre::IndexData::indexBuffer, Ogre::IndexData::indexCount, Ogre::SubMesh::indexData, Ogre::IndexData::indexStart, Vector< 3, Real >::length(), LL_LOW, LL_NORMAL, Ogre::Resource::load(), Ogre::HardwareBuffer::lock(), Ogre::VertexBufferBinding::setBinding(), Ogre::MovableObject::setCastShadows(), Ogre::Entity::setMaterial(), Ogre::MovableObject::setVisible(), Ogre::HardwareBuffer::unlock(), Ogre::SubMesh::useSharedVertices, Ogre::VertexData::vertexBufferBinding, Ogre::VertexData::vertexCount, Ogre::SubMesh::vertexData, Ogre::VertexData::vertexDeclaration, Ogre::VertexData::vertexStart, VES_DIFFUSE, VES_NORMAL, VES_POSITION, VES_TEXTURE_COORDINATES, VET_FLOAT2, VET_FLOAT3, and VET_UBYTE4_NORM.

clear()

void StaticBillboardSet::clear

(

void

)

Deletes all billboards from the scene.

The only way to delete a billboard in a StaticBillboardSet is to delete them all, which this function does.

References Ogre::MovableObject::_getManager(), Ogre::BillboardSet::clear(), Ogre::SceneManager::destroyEntity(), Ogre::SceneNode::detachAllObjects(), and getSingleton().

Referenced by ~StaticBillboardSet().

setMaterial()

void StaticBillboardSet::setMaterial	(	const Ogre::String &	materialName,
		const Ogre::String &	resourceGroup = Ogre::ResourceGroupManager::AUTODETECT_RESOURCE_GROUP_NAME
	)

Applies a material to the billboards in this set.

Parameters

materialName

The name of the material to apply to this StaticBillboardSet.

This may actually modify the material to include a vertex shader (which is used to keep the billboards facing the camera).

References Ogre::Resource::getGroup(), Ogre::Resource::getName(), getSingleton(), Ogre::BillboardSet::setMaterial(), and Ogre::Entity::setMaterial().

setTextureStacksAndSlices()

void StaticBillboardSet::setTextureStacksAndSlices	(	Ogre::uint16	stacks,
		Ogre::uint16	slices
	)

Sets how many horizontal slices and vertical stacks the currently applied material is using.

Parameters

stacks	The number of vertical stacks.
slices	The number of horizontal slices.

If the applied material contains multiple images all merged together into a grid you can use this function to gain access to the individual images. Simply set how many tiles are contained within the material horizontally and vertically, and use the texcoordIndexU and texcoordIndexV parameters of createBillboard() to specify which image is to be used for the billboard.

updateAll()

void StaticBillboardSet::updateAll ( const Ogre::Vector3 &  cameraDirection, const char *  fragmentProgramName  )

static

Manually updates all StaticBillboardSet objects for a frame.

Note

If you are using root->startRendering() or root->renderOneFrame() to update your scene, there is no need to use this function at all. Doing so would be redundant and ineffient, as it will be called automatically in this case.

However, if you update all your render targets yourself, you will have to call this manually per frame from your program loop. If updateAll() doesn't get called one way or another, your billboards will not be updated to face the camera.

References Ogre::GpuProgramParameters::_findNamedConstantDefinition(), Ogre::GpuProgramParameters::_writeRawConstants(), BBO_CENTER, Ogre::Technique::getPass(), Ogre::Material::getTechnique(), Ogre::Pass::getTextureUnitState(), Ogre::TextureUnitState::getTextureUScroll(), Ogre::TextureUnitState::getTextureVScroll(), Ogre::Pass::getVertexProgramParameters(), Ogre::Pass::hasVertexProgram(), Vector< 3, Real >::normalise(), Ogre::GpuConstantDefinition::physicalIndex, Ogre::Pass::setFragmentProgram(), Ogre::GpuProgramParameters::setNamedAutoConstant(), and Ogre::Pass::setVertexProgram().

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