org.j3d.geom.particle
Interface ParticleInitializer

All Known Implementing Classes:

BaseEmitter

public interface ParticleInitializer

The ParticleInitializer is registered with a ParticleSystem and is responsible for creating and initialising the particles.

Version:

$Revision: 2.0 $

Author:

Justin Couch, Daniel Selman

Method Summary

void	getColor(float[] val) Get the value of the initial colour that particles are set to.
float	getLifetimeVariation() Get the amount of variation in the lifetime of the particles generated.
float	getMass() Get the current mass assigned to each particle.
int	getMaxParticleCount() Fetch the current value of the maximum particle count.
int	getParticleLifetime() Get the current maximum lifetime of the particles.
float	getParticleVariation() Get the amount of variation in the properties of the particles generated.
float	getSpeed() Get the current speed that particles are initialised with.
float	getSurfaceArea() Get the current surface area assigned to particles.
boolean	initialize(Particle particle) Initialize a particle based on the rules defined by this initializer.
int	numParticlesToCreate(int timeDelta) The number of particles that should be created and initialised this frame.
void	setColor(float r, float g, float b, float alpha) Set the initial color that that the particle is given.
void	setLifetimeVariation(float variation) Change the variation factor for the emitted particles.
void	setMass(float mass) Change the mass of the particle.
void	setMaxParticleCount(int maxCount) Adjust the maximum number of particles that this initializer is going to work with.
void	setParticleLifetime(int time) Change the maximum lifetime of the particles.
void	setParticleVariation(float variation) Change the variation factor for the particles' properties, and does not effect the lifetime variation.
void	setSpeed(float speed) Change the initial speed that the particles are endowed with.
void	setSurfaceArea(float area) Change the apparent surface area.

Method Detail

setMaxParticleCount

public void setMaxParticleCount(int maxCount)

Adjust the maximum number of particles that this initializer is going to work with. This should not normally be called by the end user. The particle system that this initializer is registered with will call this method when it's corresponding method is called.

Parameters:

maxCount - The new maximum particle count to use

getMaxParticleCount

public int getMaxParticleCount()

Fetch the current value of the maximum particle count.

Returns:

A value >= 0

setParticleLifetime

public void setParticleLifetime(int time)
                         throws java.lang.IllegalArgumentException

Change the maximum lifetime of the particles. The lifetime of particles is defined in milliseconds, and must be positive.

Parameters:

time - The new lifetime, in seconds

Throws:

java.lang.IllegalArgumentException - The lifetime is zero or negative

getParticleLifetime

public int getParticleLifetime()

Get the current maximum lifetime of the particles. Time is represented in milliseconds.

Returns:

The current particle lifetime, in milliseconds

setLifetimeVariation

public void setLifetimeVariation(float variation)
                          throws java.lang.IllegalArgumentException

Change the variation factor for the emitted particles. This will only effect particles created after this is set, and not before. Variation values are limited to [0,1].

Parameters:

variation - The new variation amount

Throws:

java.lang.IllegalArgumentException - The variation amount was within [0,1]

getLifetimeVariation

public float getLifetimeVariation()

Get the amount of variation in the lifetime of the particles generated.

Returns:

The current lifetime variation factor in the range [0,1]

setParticleVariation

public void setParticleVariation(float variation)

Change the variation factor for the particles' properties, and does not effect the lifetime variation. This will only effect particles created after this is set, and not before. Variation may be negative, but results are unknown if it is. Works best if the variation is limited to [0,1].

Parameters:

variation - The new variation amount

getParticleVariation

public float getParticleVariation()

Get the amount of variation in the properties of the particles generated. This does not effect the lifetime, which is set by a different method.

Returns:

The current particle variation factor

numParticlesToCreate

public int numParticlesToCreate(int timeDelta)

The number of particles that should be created and initialised this frame. This is called once per frame by the particle system manager. If this is the first frame, the timeDelta value given will be -1.

Parameters:

timeDelta - The delta between the last frame and this one in milliseconds

Returns:

The number of particles to create

initialize

public boolean initialize(Particle particle)

Initialize a particle based on the rules defined by this initializer. The particle system may choose to re-initialise previously dead particles. The implementation should not care whether the particle was previously in existance or not.

Parameters:

particle - The particle instance to initialize

Returns:

true if the ParticleSytem should keep running

setColor

public void setColor(float r,
                     float g,
                     float b,
                     float alpha)

Set the initial color that that the particle is given. If the emitter does not support the alpha channel, ignore the parameter.

Parameters:

r - The red component of the color

g - The green component of the color

b - The blue component of the color

alpha - The alpha component of the color

getColor

public void getColor(float[] val)

Get the value of the initial colour that particles are set to. The array should be length 4.

Parameters:

val - An array of length 4 to copy the internal values into

setSurfaceArea

public void setSurfaceArea(float area)
                    throws java.lang.IllegalArgumentException

Change the apparent surface area. Surface area is measured in square metres. Surface area must be non-negative otherwise an exception will be generated.

Parameters:

area - The new surface area value to use, in metres squared

Throws:

java.lang.IllegalArgumentException - The surface area value was negative

getSurfaceArea

public float getSurfaceArea()

Get the current surface area assigned to particles.

Returns:

A value greater than or equal to zero

setMass

public void setMass(float mass)
             throws java.lang.IllegalArgumentException

Change the mass of the particle. Mass is measured in kilograms. Mass must be non-negative otherwise an exception will be generated.

Parameters:

mass - The mass of an individual particle

Throws:

java.lang.IllegalArgumentException - The mass value was negative

getMass

public float getMass()

Get the current mass assigned to each particle.

Returns:

A non-negative value representing the mass

setSpeed

public void setSpeed(float speed)

Change the initial speed that the particles are endowed with. Some emitters may need to have a direction value as well to determine the velocity that the particles are emitted with. Speed may be any value. Negatives are just treated like starting the particles in the opposite direction to those of positive speed. A speed of zero has all particles starting stationary.

Parameters:

speed - The magnitude of the speed to use

getSpeed

public float getSpeed()

Get the current speed that particles are initialised with.

Returns:

A value of the speed