DigitalSpaces::DIOGREBillboardSet Struct Reference
[Ogre]

#include <OGREInterfaces.h>

Inherits DigitalSpaces::DIObjectBase.

Public Member Functions
DIOGREBillboard *	CreateBillboard (in_Vector3f *position)
	Creates a new billboard and adds it to this set.
DIOGREBillboard *	CreateBillboard (in_Vector3f *position, in_Vector4f *colour)
DIOGREBillboard *	CreateBillboard (float x, float y, float z)
	Creates a new billboard and adds it to this set.
DIOGREBillboard *	CreateBillboard (float x, float y, float z, in_Vector4f *colour)
int	GetNumBillboards (void)
	Returns the number of active billboards which currently make up this set.
void	SetAutoextend (bool autoextend)
	Tells the set whether to allow automatic extension of the pool of billboards.
bool	GetAutoextend (void)
	Returns true if the billboard pool automatically extends.
void	SetPoolSize (unsigned int size)
	Adjusts the size of the pool of billboards available in this set.
unsigned int	GetPoolSize (void)
	Returns the current size of the billboard pool.
void	Clear ()
	Empties this set of all billboards.
DIOGREBillboard *	GetBillboard (unsigned int index)
	Returns a pointer to the billboard at the supplied index.
void	RemoveBillboard (unsigned int index)
	Removes the billboard at the supplied index.
void	RemoveBillboard (DIOGREBillboard *pBill)
	Removes a billboard from the set.
void	SetBillboardOrigin (OGREBillboardOrigin origin)
	Sets the point which acts as the origin point for all billboards in this set.
OGREBillboardOrigin	GetBillboardOrigin (void)
	Gets the point which acts as the origin point for all billboards in this set.
void	SetDefaultDimensions (float width, float height)
	Sets the default dimensions of the billboards in this set.
void	SetDefaultWidth (float width)
	See setDefaultDimensions - this sets 1 component individually.
float	GetDefaultWidth (void)
	See setDefaultDimensions - this gets 1 component individually.
void	SetDefaultHeight (float height)
	See setDefaultDimensions - this sets 1 component individually.
float	GetDefaultHeight (void)
	See setDefaultDimensions - this gets 1 component individually.
void	SetMaterialName (const char *name)
	Sets the name of the material to be used for this billboard set.
const char *	GetMaterialName (void)
	Sets the name of the material to be used for this billboard set.
bool	GetCullIndividually (void)
	Returns whether or not billbards in this are tested individually for culling.
void	SetCullIndividually (bool cullIndividual)
	Sets whether culling tests billboards in this individually as well as in a group.
void	SetBillboardType (OGREBillboardType bbt)
	Sets the type of billboard to render.
OGREBillboardType	GetBillboardType (void)
	Returns the billboard type in use.
void	SetCommonDirection (in_Vector3f *vec)
	Use this to specify the common direction given to billboards of type BBT_ORIENTED_COMMON.
void	GetCommonDirection (out_Vector3f *vec)
	Gets the common direction for all billboards (BBT_ORIENTED_COMMON).

---

Member Function Documentation

DIOGREBillboard* DigitalSpaces::DIOGREBillboardSet::CreateBillboard

(

in_Vector3f *

position

)

Creates a new billboard and adds it to this set.

Remarks:

Behaviour once the billboard pool has been exhausted depends on the BillboardSet::setAutoextendPool option.

Parameters:

	position	The position of the new billboard realtive to the certer of the set
	colour	Optional base colour of the billboard.

Returns:

On success, a pointer to a newly created Billboard is returned.

On failiure (i.e. no more space and can't autoextend), NULL is returned.

See also:

BillboardSet::setAutoextend

DIOGREBillboard* DigitalSpaces::DIOGREBillboardSet::CreateBillboard	(	in_Vector3f *	position,
		in_Vector4f *	colour
	)

DIOGREBillboard* DigitalSpaces::DIOGREBillboardSet::CreateBillboard	(	float	x,
		float	y,
		float	z
	)

Creates a new billboard and adds it to this set.

Remarks:

Behaviour once the billboard pool has been exhausted depends on the BillboardSet::setAutoextendPool option.

Parameters:

	x
	y
	z	The position of the new billboard realtive to the certer of the set
	colour	Optional base colour of the billboard.

Returns:

On success, a pointer to a newly created Billboard is returned.

On failiure (i.e. no more space and can't autoextend), NULL is returned.

See also:

BillboardSet::setAutoextend

DIOGREBillboard* DigitalSpaces::DIOGREBillboardSet::CreateBillboard	(	float	x,
		float	y,
		float	z,
		in_Vector4f *	colour
	)

int DigitalSpaces::DIOGREBillboardSet::GetNumBillboards

(

void

)

Returns the number of active billboards which currently make up this set.

void DigitalSpaces::DIOGREBillboardSet::SetAutoextend

(

bool

autoextend

)

Tells the set whether to allow automatic extension of the pool of billboards.

Remarks:

A BillboardSet stores a pool of pre-constructed billboards which are used as needed when a new billboard is requested. This allows applications to create / remove billboards efficiently without incurring construction / destruction costs (a must for sets with lots of billboards like particle effects). This method allows you to configure the behaviour when a new billboard is requested but the billboard pool has been exhausted.

The default behaviour is to allow the pool to extend (typically this allocates double the current pool of billboards when the pool is expended), equivalent to calling this method with autoExtend = true. If you set the parameter to false however, any attempt to create a new billboard when the pool has expired will simply fail silently, returning a null pointer.

Parameters:

autoextend

true to double the pool every time it runs out, false to fail silently.

bool DigitalSpaces::DIOGREBillboardSet::GetAutoextend

(

void

)

Returns true if the billboard pool automatically extends.

See also:

BillboardSet::setAutoextend

void DigitalSpaces::DIOGREBillboardSet::SetPoolSize

(

unsigned int

size

)

Adjusts the size of the pool of billboards available in this set.

Remarks:

See the BillboardSet::setAutoextend method for full details of the billboard pool. This method adjusts the preallocated size of the pool. If you try to reduce the size of the pool, the set has the option of ignoring you if too many billboards are already in use. Bear in mind that calling this method will incur significant construction / destruction calls so should be avoided in time-critical code. The same goes for auto-extension, try to avoid it by estimating the pool size correctly up-front.

Parameters:

size

The new size for the pool.

unsigned int DigitalSpaces::DIOGREBillboardSet::GetPoolSize

(

void

)

Returns the current size of the billboard pool.

Returns:

The current size of the billboard pool.

See also:

BillboardSet::setAutoextend

void DigitalSpaces::DIOGREBillboardSet::Clear

(

)

Empties this set of all billboards.

DIOGREBillboard* DigitalSpaces::DIOGREBillboardSet::GetBillboard

(

unsigned int

index

)

Returns a pointer to the billboard at the supplied index.

Note:

This method requires linear time since the billboard list is a linked list.

Parameters:

index

The index of the billboard that is requested.

Returns:

On success, a valid pointer to the requested billboard is returned.

On failiure, NULL is returned.

void DigitalSpaces::DIOGREBillboardSet::RemoveBillboard

(

unsigned int

index

)

Removes the billboard at the supplied index.

Note:

This method requires linear time since the billboard list is a linked list.

void DigitalSpaces::DIOGREBillboardSet::RemoveBillboard

(

DIOGREBillboard *

pBill

)

Removes a billboard from the set.

Note:

This version is more efficient than removing by index.

void DigitalSpaces::DIOGREBillboardSet::SetBillboardOrigin

(

OGREBillboardOrigin

origin

)

Sets the point which acts as the origin point for all billboards in this set.

Remarks:

This setting controls the fine tuning of where a billboard appears in relation to it's position. It could be that a billboard's position represents it's center (e.g. for fireballs), it could mean the center of the bottom edge (e.g. a tree which is positioned on the ground), the top-left corner (e.g. a cursor).

The default setting is BBO_CENTER.

Parameters:

origin

A member of the OGREBillboardOrigin enum specifying the origin for all the billboards in this set.

OGREBillboardOrigin DigitalSpaces::DIOGREBillboardSet::GetBillboardOrigin

(

void

)

Gets the point which acts as the origin point for all billboards in this set.

Returns:

A member of the OGREBillboardOrigin enum specifying the origin for all the billboards in this set.

void DigitalSpaces::DIOGREBillboardSet::SetDefaultDimensions	(	float	width,
		float	height
	)

Sets the default dimensions of the billboards in this set.

Remarks:

All billboards in a set are created with these default dimensions. The set will render most efficiently if all the billboards in the set are the default size. It is possible to alter the size of individual billboards at the expense of extra calculation. See the Billboard class for more info.

Parameters:

	width	The new default width for the billboards in this set.
	height	The new default height for the billboards in this set.

void DigitalSpaces::DIOGREBillboardSet::SetDefaultWidth

(

float

width

)

See setDefaultDimensions - this sets 1 component individually.

float DigitalSpaces::DIOGREBillboardSet::GetDefaultWidth

(

void

)

See setDefaultDimensions - this gets 1 component individually.

void DigitalSpaces::DIOGREBillboardSet::SetDefaultHeight

(

float

height

)

See setDefaultDimensions - this sets 1 component individually.

float DigitalSpaces::DIOGREBillboardSet::GetDefaultHeight

(

void

)

See setDefaultDimensions - this gets 1 component individually.

void DigitalSpaces::DIOGREBillboardSet::SetMaterialName

(

const char *

name

)

Sets the name of the material to be used for this billboard set.

Parameters:

name

The new name of the material to use for this set.

const char* DigitalSpaces::DIOGREBillboardSet::GetMaterialName

(

void

)

Sets the name of the material to be used for this billboard set.

Returns:

The name of the material that is used for this set.

bool DigitalSpaces::DIOGREBillboardSet::GetCullIndividually

(

void

)

Returns whether or not billbards in this are tested individually for culling.

void DigitalSpaces::DIOGREBillboardSet::SetCullIndividually

(

bool

cullIndividual

)

Sets whether culling tests billboards in this individually as well as in a group.

Remarks:

Billboard sets are always culled as a whole group, based on a bounding box which encloses all billboards in the set. For fairly localised sets, this is enough. However, you can optionally tell the set to also cull individual billboards in the set, i.e. to test each individual billboard before rendering. The default is not to do this.

This is useful when you have a large, fairly distributed set of billboards, like maybe trees on a landscape. You probably still want to group them into more than one set (maybe one set per section of landscape), which will be culled coarsely, but you also want to cull the billboards individually because they are spread out. Whilst you could have lots of single-tree sets which are culled separately, this would be inefficient to render because each tree would be issued as it's own rendering operation.

By calling this method with a parameter of true, you can have large billboard sets which are spaced out and so get the benefit of batch rendering and coarse culling, but also have fine-grained culling so unnecessary rendering is avoided.

Parameters:

cullIndividual

If true, each billboard is tested before being sent to the pipeline as well as the whole set having to pass the coarse group bounding test.

void DigitalSpaces::DIOGREBillboardSet::SetBillboardType

(

OGREBillboardType

bbt

)

Sets the type of billboard to render.

Remarks:

The default sort of billboard (BBT_POINT), always has both x and y axes parallel to the camera's local axes. This is fine for 'point' style billboards (e.g. flares, smoke, anything which is symmetrical about a central point) but does not look good for billboards which have an orientation (e.g. an elongated raindrop). In this case, the oriented billboards are more suitable (BBT_ORIENTED_COMMON or BBT_ORIENTED_SELF) since they retain an independant Y axis and only the X axis is generated, perpendicular to both the local Y and the camera Z.

Parameters:

bbt

The type of billboard to render

OGREBillboardType DigitalSpaces::DIOGREBillboardSet::GetBillboardType

(

void

)

Returns the billboard type in use.

void DigitalSpaces::DIOGREBillboardSet::SetCommonDirection

(

in_Vector3f *

vec

)

Use this to specify the common direction given to billboards of type BBT_ORIENTED_COMMON.

Remarks:

Use BBT_ORIENTED_COMMON when you want oriented billboards but you know they are always going to be oriented the same way (e.g. rain in calm weather). It is faster for the system to calculate the billboard vertices if they have a common direction.

Parameters:

vec

The direction for all billboards.

void DigitalSpaces::DIOGREBillboardSet::GetCommonDirection

(

out_Vector3f *

vec

)

Gets the common direction for all billboards (BBT_ORIENTED_COMMON).

---

The documentation for this struct was generated from the following file:

• OGREInterfaces/OGREInterfaces.h