src/org/sourceforge/desert/ParticleEngine.java

   1 /*
   2  * Copyright (c) 2010 The Desert team
   3  *
   4  * Permission is hereby granted, free of charge, to any person
   5  * obtaining a copy of this software and associated documentation
   6  * files (the "Software"), to deal in the Software without
   7  * restriction, including without limitation the rights to use,
   8  * copy, modify, merge, publish, distribute, sublicense, and/or sell
   9  * copies of the Software, and to permit persons to whom the
  10  * Software is furnished to do so, subject to the following
  11  * conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be
  14  * included in all copies or substantial portions of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  17  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  18  * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  19  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  20  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
  21  * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  22  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  23  * OTHER DEALINGS IN THE SOFTWARE.
  24  *
  25  */
  26 package org.sourceforge.desert;
  27
  28 import java.awt.Dimension;
  29
  30 /**
  31  * A particle engine is an object responsible for the creation, storage, enumeration and update of particles.
  32  * <br>Warning: for engines that don't use Particle internally, the recommended way to implement
  33  * iteration is is to always return the same particle object updated for each actual particle.
  34  * <br>This is to avoid creating and destroying temporary objects, thus improving memory usage and speed.
  35  * <br>Therefore, when iterating over a ParticleEngine, users shouldn't expect a particle to be a different
  36  * object than the previous one (only the state might change).
  37  * <br>The same caution is required with the iterator objects: concurrent iteration is generally not supported.
  38  * @author codistmonk (creation 2010-04-17)
  39  */
  40 public interface ParticleEngine extends Iterable<Particle> {
  41
  42     /**
  43      *
  44      * @return a non-null value iff bounds are defined
  45      * <br>A possibly null value
  46      * <br>Can be a reference
  47      */
  48     public abstract Dimension getBoardSize();
  49
  50     /**
  51      * Sets the size of the rectangle enclosing the board and thus limiting the movements of the particles;
  52      * if it is <code>null</code> then these limits are removed and the particle are free to go outside of the board.
  53      * <br>If the size is set to a non-null value while some particles are outside the board,
  54      * then these particles should be brought back inside in a limited amount of time.
  55      * @param size
  56      * <br>Can be null
  57      * <br>Can be a reference parameter
  58      */
  59     public abstract void setBoardSize(Dimension size);
  60
  61     /**
  62      *
  63      * @return
  64      * <br>Range: <code>]Float.NEGATIVE_INFINITY .. Float.POSITIVE_INFINITY[</code>
  65      */
  66     public abstract float getGravity();
  67
  68     /**
  69      * The gravity is vertical.
  70      * <br>Positive values are upward.
  71      * @param gravity
  72      * <br>Range: <code>]Float.NEGATIVE_INFINITY .. Float.POSITIVE_INFINITY[</code>
  73      */
  74     public abstract void setGravity(float gravity);
  75
  76     /**
  77      *
  78      * @param type
  79      * <br>Should not be null
  80      * @param x
  81      * <br>Range: <code>]Float.NEGATIVE_INFINITY .. Float.POSITIVE_INFINITY[</code>
  82      * @param y
  83      * <br>Range: <code>]Float.NEGATIVE_INFINITY .. Float.POSITIVE_INFINITY[</code>
  84      * @param speedX
  85      * <br>Range: <code>]Float.NEGATIVE_INFINITY .. Float.POSITIVE_INFINITY[</code>
  86      * @param speedY
  87      * <br>Range: <code>]Float.NEGATIVE_INFINITY .. Float.POSITIVE_INFINITY[</code>
  88      */
  89     public abstract void addParticle(Particle.Type type, float x, float y, float speedX, float speedY);
  90
  91     /**
  92      *
  93      * @return
  94      * <br>Range: <code>[0 .. Integer.MAX_VALUE]</code>
  95      */
  96     public abstract int getParticleCount();
  97
  98     /**
  99      *
 100      * @param deltaTime in seconds
 101      * <br>Range: <code>[0.0 .. Float.POSITIVE_INFINITY[</code>
 102      */
 103     public abstract void update(float deltaTime);
 104
 105     public static final float DEFAULT_GRAVITY = -8F;
 106
 107 }