DigitalSpaces::DIOGREParticleSystem Struct Reference
[Ogre]

#include <OGREInterfaces.h>

Inherits DigitalSpaces::DIObjectBase.

Public Member Functions
DIOGREParticleEmitter *	AddEmitter (const char *emitterType)
	Adds an emitter to this particle system.
DIOGREParticleEmitter *	GetEmitter (unsigned short index)
	Retrieves an emitter by it's index (zero-based).
unsigned short	GetNumEmitters (void)
	Returns the number of emitters for this particle system.
void	RemoveEmitter (unsigned short index)
	Removes an emitter from the system.
void	RemoveAllEmitters (void)
	Removes all the emitters from this system.
DIOGREParticleAffector *	AddAffector (const char *affectorType)
	Adds an affector to this particle system.
DIOGREParticleAffector *	GetAffector (unsigned short index)
	Retrieves an affector by it's index (zero-based).
unsigned short	GetNumAffectors (void)
	Returns the number of affectors for this particle system.
void	RemoveAffector (unsigned short index)
	Removes an affector from the system.
void	RemoveAllAffectors (void)
	Removes all the affectors from this system.
void	Clear ()
	Empties this set of all particles.
unsigned int	GetNumParticles (void)
	Gets the number of individual particles in the system right now.
DIOGREParticle *	CreateParticle (void)
	Manually add a particle to the system.
DIOGREParticle *	GetParticle (unsigned int index)
	Retrieve a particle from the system for manual tweaking.
unsigned int	GetParticleQuota (void)
	Returns the maximum number of particles this system is allowed to have active at once.
void	SetParticleQuota (unsigned int quota)
	Sets the maximum number of particles this system is allowed to have active at once.
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.
void	FastForward (float time, float interval=0.1)
	Fast-forwards this system by the required number of seconds.
void	SetSpeedFactor (float speedFactor)
	Sets a 'speed factor' on this particle system, which means it scales the elapsed real time which has passed by this factor before passing it to the emitters, affectors, and the particle life calculation.
float	GetSpeedFactor (void)
	Gets the 'speed factor' on this particle system.
void	SetDefaultDimensions (float width, float height)
	Sets the default dimensions of the particles 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.
bool	GetCullIndividually (void)
	Returns whether or not particles in this are tested individually for culling.
void	SetCullIndividually (bool cullIndividual)
	Sets whether culling tests particles in this individually as well as in a group.

---

Member Function Documentation

DIOGREParticleEmitter* DigitalSpaces::DIOGREParticleSystem::AddEmitter

(

const char *

emitterType

)

Adds an emitter to this particle system.

Remarks:

Particles are created in a particle system by emitters - see the ParticleEmitter class for more details.

Parameters:

emitterType

String identifying the emitter type to create. Emitter types are defined by registering new factories with the manager - see ParticleEmitterFactory for more details. Emitter types can be extended by OGRE, plugin authors or application developers.

DIOGREParticleEmitter* DigitalSpaces::DIOGREParticleSystem::GetEmitter

(

unsigned short

index

)

Retrieves an emitter by it's index (zero-based).

Remarks:

Used to retrieve a pointer to an emitter for a particle system to procedurally change emission parameters etc. You should check how many emitters are registered against this system before calling this method with an arbitrary index using getNumEmitters.

Parameters:

index

Zero-based index of the emitter to retrieve.

unsigned short DigitalSpaces::DIOGREParticleSystem::GetNumEmitters

(

void

)

Returns the number of emitters for this particle system.

void DigitalSpaces::DIOGREParticleSystem::RemoveEmitter

(

unsigned short

index

)

Removes an emitter from the system.

Remarks:

Drops the emitter with the index specified from this system. You should check how many emitters are registered against this system before calling this method with an arbitrary index using getNumEmitters.

Parameters:

index

Zero-based index of the emitter to retrieve.

void DigitalSpaces::DIOGREParticleSystem::RemoveAllEmitters

(

void

)

Removes all the emitters from this system.

DIOGREParticleAffector* DigitalSpaces::DIOGREParticleSystem::AddAffector

(

const char *

affectorType

)

Adds an affector to this particle system.

Remarks:

Particles are modified over time in a particle system by affectors - see the ParticleAffector class for more details.

Parameters:

affectorType

String identifying the affector type to create. Affector types are defined by registering new factories with the manager - see ParticleAffectorFactory for more details. Affector types can be extended by OGRE, plugin authors or application developers.

DIOGREParticleAffector* DigitalSpaces::DIOGREParticleSystem::GetAffector

(

unsigned short

index

)

Retrieves an affector by it's index (zero-based).

Remarks:

Used to retrieve a pointer to an affector for a particle system to procedurally change affector parameters etc. You should check how many affectors are registered against this system before calling this method with an arbitrary index using getNumAffectors.

Parameters:

index

Zero-based index of the affector to retrieve.

unsigned short DigitalSpaces::DIOGREParticleSystem::GetNumAffectors

(

void

)

Returns the number of affectors for this particle system.

void DigitalSpaces::DIOGREParticleSystem::RemoveAffector

(

unsigned short

index

)

Removes an affector from the system.

Remarks:

Drops the affector with the index specified from this system. You should check how many affectors are registered against this system before calling this method with an arbitrary index using getNumAffectors.

Parameters:

index

Zero-based index of the affector to retrieve.

void DigitalSpaces::DIOGREParticleSystem::RemoveAllAffectors

(

void

)

Removes all the affectors from this system.

void DigitalSpaces::DIOGREParticleSystem::Clear

(

)

Empties this set of all particles.

unsigned int DigitalSpaces::DIOGREParticleSystem::GetNumParticles

(

void

)

Gets the number of individual particles in the system right now.

Remarks:

The number of particles active in a system at a point in time depends on the number of emitters, their emission rates, the time-to-live (TTL) each particle is given on emission (and whether any affectors modify that TTL) and the maximum number of particles allowed in this system at once (particle quota).

DIOGREParticle* DigitalSpaces::DIOGREParticleSystem::CreateParticle

(

void

)

Manually add a particle to the system.

Remarks:

Instead of using an emitter, you can manually add a particle to the system. You must initialise the returned particle instance immediately with the 'emission' state.

Note:

There is no corresponding 'destroyParticle' method - if you want to dispose of a particle manually (say, if you've used setSpeedFactor(0) to make particles live forever) you should use getParticle() and modify it's timeToLive to zero, meaning that it will get cleaned up in the next update.

DIOGREParticle* DigitalSpaces::DIOGREParticleSystem::GetParticle

(

unsigned int

index

)

Retrieve a particle from the system for manual tweaking.

Remarks:

Normally you use an affector to alter particles in flight, but for small manually controlled particle systems you might want to use this method.

unsigned int DigitalSpaces::DIOGREParticleSystem::GetParticleQuota

(

void

)

Returns the maximum number of particles this system is allowed to have active at once.

Remarks:

See ParticleSystem::setParticleQuota for more info.

void DigitalSpaces::DIOGREParticleSystem::SetParticleQuota

(

unsigned int

quota

)

Sets the maximum number of particles this system is allowed to have active at once.

Remarks:

Particle systems all have a particle quota, i.e. a maximum number of particles they are allowed to have active at a time. This allows the application to set a keep particle systems under control should they be affected by complex parameters which alter their emission rates etc. If a particle system reaches it's particle quota, none of the emitters will be able to emit any more particles. As existing particles die, the spare capacity will be allocated equally across all emitters to be as consistent to the origina particle system style as possible.

Parameters:

quota

The maximum number of particles this system is allowed to have.

void DigitalSpaces::DIOGREParticleSystem::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::DIOGREParticleSystem::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.

void DigitalSpaces::DIOGREParticleSystem::FastForward	(	float	time,
		float	interval = 0.1
	)

Fast-forwards this system by the required number of seconds.

Remarks:

This method allows you to fast-forward a system so that it effectively looks like it has already been running for the time you specify. This is useful to avoid the 'startup sequence' of a system, when you want the system to be fully populated right from the start.

Parameters:

	time	The number of seconds to fast-forward by.
	interval	The sampling interval used to generate particles, apply affectors etc. The lower this is the more realistic the fast-forward, but it takes more iterations to do it.

void DigitalSpaces::DIOGREParticleSystem::SetSpeedFactor

(

float

speedFactor

)

Sets a 'speed factor' on this particle system, which means it scales the elapsed real time which has passed by this factor before passing it to the emitters, affectors, and the particle life calculation.

Remarks:

An interesting side effect - if you want to create a completely manual particle system where you control the emission and life of particles yourself, you can set the speed factor to 0.0f, thus disabling normal particle emission, alteration, and death.

float DigitalSpaces::DIOGREParticleSystem::GetSpeedFactor

(

void

)

Gets the 'speed factor' on this particle system.

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

Sets the default dimensions of the particles in this set.

Remarks:

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

Parameters:

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

void DigitalSpaces::DIOGREParticleSystem::SetDefaultWidth

(

float

width

)

See setDefaultDimensions - this sets 1 component individually.

float DigitalSpaces::DIOGREParticleSystem::GetDefaultWidth

(

void

)

See setDefaultDimensions - this gets 1 component individually.

void DigitalSpaces::DIOGREParticleSystem::SetDefaultHeight

(

float

height

)

See setDefaultDimensions - this sets 1 component individually.

float DigitalSpaces::DIOGREParticleSystem::GetDefaultHeight

(

void

)

See setDefaultDimensions - this gets 1 component individually.

bool DigitalSpaces::DIOGREParticleSystem::GetCullIndividually

(

void

)

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

void DigitalSpaces::DIOGREParticleSystem::SetCullIndividually

(

bool

cullIndividual

)

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

Remarks:

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

This is useful when you have a large, fairly distributed set of particles, 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 particles 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 particle 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 particle is tested before being sent to the pipeline as well as the whole set having to pass the coarse group bounding test.

---

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

• OGREInterfaces/OGREInterfaces.h