org.j3d.geom.particle
Class ParticleSystem

java.lang.Object
  org.j3d.geom.particle.ParticleSystem

All Implemented Interfaces:

ParticleFactory

public abstract class ParticleSystem
extends java.lang.Object
implements ParticleFactory

Abstract representation of a ParticleSystem.

A ParticleSystem manages a List of Particles created by a ParticleFactory. It applies changes to the Particles using a List of ParticleFunctions and a a single emitter.

A ParticleSystem can be represented in any way appropriate, the only requirement is that is create a Node to be added to the scenegraph.

Internationalisation Resource Names

• negParticleCountMsg: Message when a negative particle size is provided.

Version:

$Revision: 2.3 $

Author:

Justin Couch, based on code by Daniel Selman

Field Summary

protected ErrorReporter	errorReporter Local reporter to put errors in
protected int	frameTime Inter-frame time delta.
protected boolean	genTexCoords Flag indicating that texture coordinate values should be generated for the particles
protected int	maxParticleCount Maximum number of particles this system can handle
protected int	particleCount Current number of live particles
protected ParticleList	particleList List of currently active particle instances
protected TexCoordInterpolator	texCoordInterp Interpolator of texture coordinate handling
protected long	timeNow The time of this frame.

Constructor Summary

ParticleSystem(java.lang.String name, int maxParticleCount)
Create a new ParticleSystem.

Method Summary

void	addParticleFunction(ParticleFunction function) Append a new particle function to the list.
void	enableParticleCreation(boolean state) Change the state about whether new particles should be created from this point onwards.
void	enableTextureCoordinates(boolean state) Set a flag to say whether texture coordinates should be generated for this system.
int	getMaxParticleCount() Get the current maximum number of particles that should be created.
ParticleInitializer	getParticleInitializer() Fetch the currently set initializer for particles.
java.lang.String	getSystemName() Gets the currently set systemName.
void	initialize(long time) Run the initial particle setup for the first frame now.
void	insertParticleFunction(int index, ParticleFunction function) Insert a particle function at a specific place in the list.
boolean	isParticleCreationEnabled() Fetch the current particle creation state.
boolean	isTextureCoordinateEnabled() Get the current value of the texture coordinate generation state.
abstract void	onRemove() Notification that this particle system has been removed from the scene graph and it cleanup anything needed right now.
void	removeParticleFunction(ParticleFunction function) Remove the first instance of the function defined.
void	setErrorReporter(ErrorReporter reporter) Register an error reporter with the object so that any errors generated by the object can be reported in a nice, pretty fashion.
void	setMaxParticleCount(int maxCount) Change the maximum number of particles that can be generated.
void	setParticleInitializer(ParticleInitializer emitter) Set the emitter used to initialise particles.
void	setSystemName(java.lang.String systemName) Sets the system name to a new value.
void	setTexCoordFunction(float[] times, int numEntries, float[] texCoords) Set the keys and texture coordinates to use for geometry that wishes to change the texture coordinates over the lifetime of the particle.
boolean	update(long timestamp) Inform each of the ParticleFunctions so they can do any processing.
protected abstract void	updateGeometry() Update the arrays for the geometry object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.j3d.geom.particle.ParticleFactory

coordinatesPerParticle, createParticle, numColorComponents, numTexCoordComponents

Field Detail

errorReporter

protected ErrorReporter errorReporter

Local reporter to put errors in

maxParticleCount

protected int maxParticleCount

Maximum number of particles this system can handle

particleCount

protected int particleCount

Current number of live particles

frameTime

protected int frameTime

Inter-frame time delta.

timeNow

protected long timeNow

The time of this frame. Set during the update() method

particleList

protected ParticleList particleList

List of currently active particle instances

texCoordInterp

protected TexCoordInterpolator texCoordInterp

Interpolator of texture coordinate handling

genTexCoords

protected boolean genTexCoords

Flag indicating that texture coordinate values should be generated for the particles

Constructor Detail

ParticleSystem

public ParticleSystem(java.lang.String name,
                      int maxParticleCount)
               throws java.lang.IllegalArgumentException

Create a new ParticleSystem.

Parameters:

name - An arbitrary string name for ID purposes

maxParticleCount - The maximum number of particles allowed to exist

Throws:

java.lang.IllegalArgumentException - The particle count was negative

Method Detail

setErrorReporter

public void setErrorReporter(ErrorReporter reporter)

Register an error reporter with the object so that any errors generated by the object can be reported in a nice, pretty fashion. Setting a value of null will clear the currently set reporter. If one is already set, the new value replaces the old.

Parameters:

reporter - The instance to use or null

initialize

public void initialize(long time)

Run the initial particle setup for the first frame now. This should be called just after completing all the setup for the other parts of the system but before the first update driven by the scene graph.

Parameters:

time - The time to start executing for

onRemove

public abstract void onRemove()

Notification that this particle system has been removed from the scene graph and it cleanup anything needed right now.

updateGeometry

protected abstract void updateGeometry()

Update the arrays for the geometry object.

enableParticleCreation

public void enableParticleCreation(boolean state)

Change the state about whether new particles should be created from this point onwards. The particle system will continue to run, but no new particles would be created if this state is set to false.

Parameters:

state - true to enable particle creation, false to stop

isParticleCreationEnabled

public boolean isParticleCreationEnabled()

Fetch the current particle creation state.

Returns:

true if new particles are being created

setParticleInitializer

public void setParticleInitializer(ParticleInitializer emitter)

Set the emitter used to initialise particles.

Parameters:

emitter - the ParticleInitializer instance to use

getParticleInitializer

public ParticleInitializer getParticleInitializer()

Fetch the currently set initializer for particles.

Returns:

The initializer or null if not set

addParticleFunction

public void addParticleFunction(ParticleFunction function)

Append a new particle function to the list. This is placed on the end of the evaluation list. A null parameter value will be ignored. A function may be added more than once.

Parameters:

function - The function to add

insertParticleFunction

public void insertParticleFunction(int index,
                                   ParticleFunction function)

Insert a particle function at a specific place in the list. All others are shifted up one place. Inserting at a position above the last item in the list will act as an append. A null parameter value will be ignored.

Parameters:

index - The position in the list to insert it on

function - The function to be added

removeParticleFunction

public void removeParticleFunction(ParticleFunction function)

Remove the first instance of the function defined. If there are more than one copy inserted, only the first instance found from the front of the list will be deleted. If the function is not in the list, then the request is silently ignored.

Parameters:

function - The function instance to remove

enableTextureCoordinates

public void enableTextureCoordinates(boolean state)

Set a flag to say whether texture coordinates should be generated for this system. If there is no interpolator set, or other reason, such as automatically generated texture coordinates, then this flag can be used to disable texture coordinates. By default they are generated for geometry types that can make use of them (quads, triangles etc).

Parameters:

state - True to enable tex Coord generation

isTextureCoordinateEnabled

public boolean isTextureCoordinateEnabled()

Get the current value of the texture coordinate generation state.

Returns:

True if texture coordinates are currently being generated.

setTexCoordFunction

public void setTexCoordFunction(float[] times,
                                int numEntries,
                                float[] texCoords)

Set the keys and texture coordinates to use for geometry that wishes to change the texture coordinates over the lifetime of the particle. This technique is used by particle systems that put a collection of different images into a single texture and then use the texture coordinates to change the visual appearance over time. Interpolation is based on the particle's lifetime from birth and uses a stepwise set of changes. At the time the particle's life is old enough to move to the next time key, the texture coordinates are completely changed over.

It is up to the caller to determine both the ordering and the number of texture coordinate values to use.

Makes an internal copy of the values.

Parameters:

times - The list of time keys to use in milliseconds

numEntries - The number of keys/keyValue pairs

texCoords - The raw texture coordinates

update

public boolean update(long timestamp)

Inform each of the ParticleFunctions so they can do any processing.

Parameters:

timestamp - The time for this frame

Returns:

true if the system is currently running

getSystemName

public java.lang.String getSystemName()

Gets the currently set systemName.

Returns:

String representing the current system name

setSystemName

public void setSystemName(java.lang.String systemName)

Sets the system name to a new value. Should not be null.

Parameters:

systemName - The new name to set

setMaxParticleCount

public void setMaxParticleCount(int maxCount)
                         throws java.lang.IllegalArgumentException

Change the maximum number of particles that can be generated. If the number is greater than the currently set value, it will permit more to be made according to the normal creation speed. If the number is less than the current amount, then no new particles will be created until the current total has died down below the new maximum value.

Parameters:

maxCount - The new maximum particle count to use

Throws:

java.lang.IllegalArgumentException - The particle count was negative

getMaxParticleCount

public int getMaxParticleCount()

Get the current maximum number of particles that should be created. Value will always be non-negative.

Returns:

The maximum number of particles currently permitted