org.jrabbit.standard.game.objects.particles
Class ParticleSprite

java.lang.Object
  extended by org.jrabbit.standard.game.objects.base.Spatial
      extended by org.jrabbit.standard.game.objects.base.BaseSprite
          extended by org.jrabbit.standard.game.objects.particles.ParticleSprite
All Implemented Interfaces:
java.lang.Iterable<Particle>, Renderable, Updateable, Accepter<Particle>, Container<Particle>, Remover<Particle>, Skin, GLTransform, Blended, Colored, Dimensioned, GLGroupTransformed, Located, Rotated, Scaled, ScreenObject, Visible
Direct Known Subclasses:
ParticleSprite.Images, ParticleSprite.Transforming

public class ParticleSprite
extends BaseSprite
implements Updateable, Blended, Container<Particle>

A ParticleSprite is a simple but flexible controller for a group of Particles. How these Particles look and behave is entirely customizable, and so virtually any effect can be created. Essentially, a ParticleSprite maintains, updates, and renders a list of Particles. The behavior and rendering of these Particles is left up to them. Consider the ParticleSprite as an "entry point" for these particles; upon creation, their Locations, Rotations, Scalars, and Colors are all set to the same values as those in the ParticleSprite. After that, however, the ParticleSprite is somewhat removed from its children; the particles do not move, rotate, or scale with it, and are not affected by changes in their parent's Color. One of the advantages of this is that the ParticleSprite can be moved around the gameworld at will, but already created Particles remain as they were. For example, a single ParticleSprite can manage all "explosions" in a game; to create an explosion effect, simply move the ParticleSprite to the target location, create the desired Particles, then move it to the next position. However, it is possible to create ParticleSprites that cause their particles to move/rotate/scale with them. To do so, simply use the internal class ParticleSprites.Transforming. Lastly: A ParticleSprite controls the Blending function used by all of its child Particles, and allows easy modification of the active blending function.

Author:
Chris Molini

Nested Class Summary
static class ParticleSprite.Images
          ParticleSprite.Images is a convenience class that simplifies the process to create a ParticleSprite that uses Images in rendering.
static class ParticleSprite.Transforming
          ParticleSprite.Transforming creates a ParticleSprite that causes all contained Particles to move, rotate, and scale along with it.
 
Field Summary
protected  BlendOp blending
          The default blending function used by the rendered Particles.
protected  LockingList<Particle> particles
          The list of Particles.
protected  Skin[] skins
          The Skins used to render Particles.
 
Fields inherited from class org.jrabbit.standard.game.objects.base.BaseSprite
color, screenCoords, transforms, visible
 
Fields inherited from class org.jrabbit.standard.game.objects.base.Spatial
location, rotation, scalar
 
Constructor Summary
ParticleSprite(Skin... skins)
          Creates a ParticleSprite that uses the supplied Skins in rendering.
 
Method Summary
 void add(Particle... particles)
          Adds a series of Particles to the ParticleSprite.
 boolean add(Particle particle)
          Adds a Particle to the ParticleSprite.
 BlendOp blending()
          Accesses the blending controls.
 void clear()
          Removes all Particles.
 boolean contains(Particle particle)
          Checks to see if the ParticleSprite contains a particular Particle.
 void draw()
          Renders all contained particles.
 float height()
          Accesses the "dimensions" of the ParticleSprite.
 java.util.Iterator<Particle> iterator()
          Accesses the list of Particles, in order of addition.
 void remove(Particle... particles)
          Removes a series of Particles from the ParticleSprite.
 boolean remove(Particle particle)
          Removes a Particle from the ParticleSprite.
 void setSkins(Skin... skins)
          Redefines the list of Skins.
protected  boolean shouldRender()
          Determines whether or not the ParticleSprite should render itself.
 int size()
          Learns the size of the Particle system.
 Skin skinAt(int place)
          Accesses one of the Skins being used to render Particles.
 Skin[] skins()
          Accesses the list of skins.
 void update(int delta)
          Updates all contained particles.
 float width()
          Accesses the "dimensions" of the ParticleSprite.
 
Methods inherited from class org.jrabbit.standard.game.objects.base.BaseSprite
bind, color, onscreen, release, render, screenCoords, setVisible, transforms, visible
 
Methods inherited from class org.jrabbit.standard.game.objects.base.Spatial
location, rotation, scalar, scaledDiameter, scaledHeight, scaledWidth
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

blending

protected BlendOp blending
The default blending function used by the rendered Particles.


skins

protected Skin[] skins
The Skins used to render Particles.


particles

protected LockingList<Particle> particles
The list of Particles.

Constructor Detail

ParticleSprite

public ParticleSprite(Skin... skins)
Creates a ParticleSprite that uses the supplied Skins in rendering.

Parameters:
skins - The Skins that are accessible to the child Particles.
Method Detail

skinAt

public Skin skinAt(int place)
Accesses one of the Skins being used to render Particles.

Parameters:
place - The target location in the array.
Returns:
The indicated Skin.

skins

public Skin[] skins()
Accesses the list of skins.

Returns:
The array of Skins being used to render Particles.

setSkins

public void setSkins(Skin... skins)
Redefines the list of Skins.

Parameters:
skins - The new list of Skins to use in rendering.

blending

public BlendOp blending()
Accesses the blending controls.

Specified by:
blending in interface Blended
Returns:
The BlendOp that controls the blend function used by all child Particles.

width

public float width()
Accesses the "dimensions" of the ParticleSprite.

Specified by:
width in interface Dimensioned
Returns:
The "width" of the ParticleSprite. HOWEVER, since this does not represent an actual object, this returns 0.

height

public float height()
Accesses the "dimensions" of the ParticleSprite.

Specified by:
height in interface Dimensioned
Returns:
The "height" of the ParticleSprite. HOWEVER, since this does not represent an actual object, this returns 0.

shouldRender

protected boolean shouldRender()
Determines whether or not the ParticleSprite should render itself. NOTE: Since a ParticleSprite's own location can be entirely different than those of its children, onscreen/offscreen based culling is ignored. Thus, this simply returns the value of the visibility flag.

Overrides:
shouldRender in class BaseSprite
Returns:
True if rendering should continue, false if not.

update

public void update(int delta)
Updates all contained particles.

Specified by:
update in interface Updateable
Parameters:
delta - The amount of microseconds that have passed.

draw

public void draw()
Renders all contained particles.

Specified by:
draw in class BaseSprite

add

public boolean add(Particle particle)
Adds a Particle to the ParticleSprite.

Specified by:
add in interface Accepter<Particle>
Parameters:
particle - The Particle to add.
Returns:
True if the add succeeded, false if not.

add

public void add(Particle... particles)
Adds a series of Particles to the ParticleSprite.

Specified by:
add in interface Accepter<Particle>
Parameters:
particles - The Particles to add.

remove

public boolean remove(Particle particle)
Removes a Particle from the ParticleSprite.

Specified by:
remove in interface Remover<Particle>
Parameters:
particle - The Particle to remove.
Returns:
True if the removal succeeded, false if not.

remove

public void remove(Particle... particles)
Removes a series of Particles from the ParticleSprite.

Specified by:
remove in interface Remover<Particle>
Parameters:
particles - The Particles to remove.

contains

public boolean contains(Particle particle)
Checks to see if the ParticleSprite contains a particular Particle.

Specified by:
contains in interface Container<Particle>
Parameters:
particle - The Particle to check for.
Returns:
True if the particle is ocntained, false if not.

size

public int size()
Learns the size of the Particle system.

Specified by:
size in interface Container<Particle>
Returns:
The number of contained Particles.

clear

public void clear()
Removes all Particles.

Specified by:
clear in interface Container<Particle>

iterator

public java.util.Iterator<Particle> iterator()
Accesses the list of Particles, in order of addition.

Specified by:
iterator in interface java.lang.Iterable<Particle>
Returns:
An Iterator through all contained Particles.