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

Definition at line 48 of file StaticBillboardSet.h.

Data Structures
class	StaticBillboard

Public Member Functions
	StaticBillboardSet (Ogre::SceneManager mgr, Ogre::SceneNode rootSceneNode)

	~StaticBillboardSet ()

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)

void	setBillboardOrigin (Ogre::BillboardOrigin origin)

Ogre::BillboardOrigin	getBillboardOrigin () const

void	setVisible (bool visible)

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

void	build ()

void	clear ()

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

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

Static Public Member Functions
static void	updateAll (const Ogre::Vector3 &cameraDirection)

Private Types
typedef std::vector< StaticBillboard * >	TBillBuf

typedef std::map< Ogre::String, Ogre::MaterialPtr >	FadedMaterialMap

Private Member Functions
Ogre::MaterialPtr	getFadeMaterial (const Ogre::MaterialPtr &protoMaterial, Ogre::Real visibleDist, Ogre::Real invisibleDist)

Static Private Member Functions
static Ogre::String	getUniqueID (const Ogre::String &prefix)

Private Attributes
bool	mVisible

bool	mFadeEnabled

Ogre::SceneManager *	mpSceneMgr

Ogre::SceneNode *	mpSceneNode

Ogre::Entity *	mpEntity

Ogre::MeshPtr	mPtrMesh

Ogre::String	mEntityName

Ogre::MaterialPtr	mPtrMaterial

Ogre::MaterialPtr	mPtrFadeMaterial

float	mfUFactor

float	mfVFactor

Ogre::BillboardOrigin	mBBOrigin

Ogre::Real	mFadeVisibleDist

Ogre::Real	mFadeInvisibleDist

TBillBuf	mBillboardBuffer

Static Private Attributes
static bool	s_isGLSL = false

static unsigned int	s_nSelfInstances = 0

static FadedMaterialMap	s_mapFadedMaterial

static unsigned long	GUID = 0

Member Typedef Documentation

◆ FadedMaterialMap

typedef std::map<Ogre::String, Ogre::MaterialPtr> Forests::StaticBillboardSet::FadedMaterialMap

private

Definition at line 226 of file StaticBillboardSet.h.

◆ TBillBuf

typedef std::vector< StaticBillboard* > Forests::StaticBillboardSet::TBillBuf

private

Definition at line 203 of file StaticBillboardSet.h.

Constructor & Destructor Documentation

◆ StaticBillboardSet()

StaticBillboardSet::StaticBillboardSet	(	Ogre::SceneManager *	mgr,
		Ogre::SceneNode *	rootSceneNode
	)

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.

Definition at line 55 of file StaticBillboardSet.cpp.

◆ ~StaticBillboardSet()

StaticBillboardSet::~StaticBillboardSet ( )

Destructor.

Definition at line 283 of file StaticBillboardSet.cpp.

Member Function Documentation

◆ build()

void StaticBillboardSet::build ( )

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.

Definition at line 342 of file StaticBillboardSet.cpp.

◆ clear()

void StaticBillboardSet::clear ( )

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.

Definition at line 313 of file StaticBillboardSet.cpp.

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

Definition at line 98 of file StaticBillboardSet.h.

◆ getBillboardOrigin()

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

inline

Returns the current billboard origin.

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

Definition at line 117 of file StaticBillboardSet.h.

◆ getFadeMaterial()

MaterialPtr StaticBillboardSet::getFadeMaterial	(	const Ogre::MaterialPtr &	protoMaterial,
		Ogre::Real	visibleDist,
		Ogre::Real	invisibleDist
	)

private

Definition at line 633 of file StaticBillboardSet.cpp.

◆ getUniqueID()

static Ogre::String Forests::StaticBillboardSet::getUniqueID ( const Ogre::String & prefix )

inlinestaticprivate

Definition at line 235 of file StaticBillboardSet.h.

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

Definition at line 815 of file StaticBillboardSet.cpp.

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

Definition at line 569 of file StaticBillboardSet.cpp.

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

Definition at line 535 of file StaticBillboardSet.cpp.

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

Definition at line 623 of file StaticBillboardSet.cpp.

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

Definition at line 121 of file StaticBillboardSet.h.

◆ updateAll()

void StaticBillboardSet::updateAll ( const Ogre::Vector3 & cameraDirection )

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.

Definition at line 704 of file StaticBillboardSet.cpp.

Field Documentation

◆ GUID

unsigned long StaticBillboardSet::GUID = 0

staticprivate

Definition at line 234 of file StaticBillboardSet.h.

◆ mBBOrigin

Ogre::BillboardOrigin Forests::StaticBillboardSet::mBBOrigin

private

Definition at line 217 of file StaticBillboardSet.h.

◆ mBillboardBuffer

TBillBuf Forests::StaticBillboardSet::mBillboardBuffer

private

Definition at line 220 of file StaticBillboardSet.h.

◆ mEntityName

Ogre::String Forests::StaticBillboardSet::mEntityName

private

Definition at line 212 of file StaticBillboardSet.h.

◆ mFadeEnabled

bool Forests::StaticBillboardSet::mFadeEnabled

private

Definition at line 206 of file StaticBillboardSet.h.

◆ mFadeInvisibleDist

Ogre::Real Forests::StaticBillboardSet::mFadeInvisibleDist

private

Definition at line 219 of file StaticBillboardSet.h.

◆ mFadeVisibleDist

Ogre::Real Forests::StaticBillboardSet::mFadeVisibleDist

private

Definition at line 218 of file StaticBillboardSet.h.

◆ mfUFactor

float Forests::StaticBillboardSet::mfUFactor

private

Definition at line 215 of file StaticBillboardSet.h.

◆ mfVFactor

float Forests::StaticBillboardSet::mfVFactor

private

Definition at line 215 of file StaticBillboardSet.h.

◆ mpEntity

Ogre::Entity* Forests::StaticBillboardSet::mpEntity

private

Definition at line 210 of file StaticBillboardSet.h.

◆ mpSceneMgr

Ogre::SceneManager* Forests::StaticBillboardSet::mpSceneMgr

private

Definition at line 208 of file StaticBillboardSet.h.

◆ mpSceneNode

Ogre::SceneNode* Forests::StaticBillboardSet::mpSceneNode

private

Definition at line 209 of file StaticBillboardSet.h.

◆ mPtrFadeMaterial

Ogre::MaterialPtr Forests::StaticBillboardSet::mPtrFadeMaterial

private

Definition at line 214 of file StaticBillboardSet.h.

◆ mPtrMaterial

Ogre::MaterialPtr Forests::StaticBillboardSet::mPtrMaterial

private

Definition at line 213 of file StaticBillboardSet.h.

◆ mPtrMesh

Ogre::MeshPtr Forests::StaticBillboardSet::mPtrMesh

private

Definition at line 211 of file StaticBillboardSet.h.

◆ mVisible

bool Forests::StaticBillboardSet::mVisible

private

Definition at line 205 of file StaticBillboardSet.h.

◆ s_isGLSL

bool StaticBillboardSet::s_isGLSL = false

staticprivate

OpenGL.

Definition at line 228 of file StaticBillboardSet.h.

◆ s_mapFadedMaterial

StaticBillboardSet::FadedMaterialMap StaticBillboardSet::s_mapFadedMaterial

staticprivate

Definition at line 231 of file StaticBillboardSet.h.

◆ s_nSelfInstances

unsigned int StaticBillboardSet::s_nSelfInstances = 0

staticprivate

Instances counter.

Definition at line 230 of file StaticBillboardSet.h.

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

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

Description

Data Structures

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Member Typedef Documentation

◆ FadedMaterialMap

◆ TBillBuf

Constructor & Destructor Documentation

◆ StaticBillboardSet()

◆ ~StaticBillboardSet()

Member Function Documentation

◆ build()

◆ clear()

◆ createBillboard()

◆ getBillboardOrigin()

◆ getFadeMaterial()

◆ getUniqueID()

◆ setBillboardOrigin()

◆ setFade()

◆ setMaterial()

◆ setTextureStacksAndSlices()

◆ setVisible()

◆ updateAll()

Field Documentation

◆ GUID

◆ mBBOrigin

◆ mBillboardBuffer

◆ mEntityName

◆ mFadeEnabled

◆ mFadeInvisibleDist

◆ mFadeVisibleDist

◆ mfUFactor

◆ mfVFactor

◆ mpEntity

◆ mpSceneMgr

◆ mpSceneNode

◆ mPtrFadeMaterial

◆ mPtrMaterial

◆ mPtrMesh

◆ mVisible

◆ s_isGLSL

◆ s_mapFadedMaterial

◆ s_nSelfInstances