1 /**
  2  * The Render Engine
  3  * AbstractParticle
  4  *
  5  * @fileoverview The particle engine and base particle class.
  6  *
  7  * @author: Brett Fattori (brettf@renderengine.com)
  8  *
  9  * @author: $Author: bfattori $
 10  * @version: $Revision: 1555 $
 11  *
 12  * Copyright (c) 2011 Brett Fattori (brettf@renderengine.com)
 13  *
 14  * Permission is hereby granted, free of charge, to any person obtaining a copy
 15  * of this software and associated documentation files (the "Software"), to deal
 16  * in the Software without restriction, including without limitation the rights
 17  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 18  * copies of the Software, and to permit persons to whom the Software is
 19  * furnished to do so, subject to the following conditions:
 20  *
 21  * The above copyright notice and this permission notice shall be included in
 22  * all copies or substantial portions of the Software.
 23  *
 24  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 25  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 26  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 27  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 28  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 29  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 30  * THE SOFTWARE.
 31  *
 32  */
 33 
 34 // The class this file defines and its required classes
 35 R.Engine.define({
 36     "class":"R.particles.AbstractParticle",
 37     "requires":[
 38         "R.engine.PooledObject",
 39         "R.math.Point2D"
 40     ]
 41 });
 42 
 43 /**
 44  * @class Base particle class.  A particle only needs to implement the
 45  *        <tt>draw()</tt> method. The remainder of the functionality is
 46  *        handled by this abstract class.
 47  *
 48  * @param lifetime {Number} The life of the particle, in milliseconds
 49  * @extends R.engine.PooledObject
 50  * @constructor
 51  * @description Create a particle
 52  */
 53 R.particles.AbstractParticle = function () {
 54     return R.engine.PooledObject.extend(/** @scope R.particles.AbstractParticle.prototype */{
 55 
 56         life:0,
 57         engine:null,
 58         birth:0,
 59         dead:false,
 60         pos:null,
 61 
 62         /** @private */
 63         constructor:function (lifetime) {
 64             this.base("Particle");
 65             this.life = lifetime;
 66             this.birth = 0;
 67             this.dead = false;
 68 
 69             if (this.pos == null) {
 70                 // Once a particle has been created, then returned to the pool,
 71                 // this point will still exist.  Instead of creating a new point
 72                 // we'll reuse it for the life of the engine.
 73                 this.pos = R.math.Point2D.create(0, 0);
 74             }
 75         },
 76 
 77         /**
 78          * Destroy the particle
 79          */
 80         destroy:function () {
 81             this.base();
 82         },
 83 
 84         /**
 85          * Release the particle back into the pool.
 86          */
 87         release:function () {
 88             this.base();
 89             this.life = 0;
 90             this.engine = null;
 91             this.birth = 0;
 92             this.dead = true;
 93         },
 94 
 95         /**
 96          * Initializes the particle within the <tt>R.particles.ParticleEngine</tt>
 97          * @param pEngine {R.particles.ParticleEngine} The particle engine which owns the particle
 98          * @param time {Number} The world time when the particle was created
 99          * @param dt {Number} The delta between the world time and the last time the world was updated
100          *          in milliseconds.
101          * @private
102          */
103         init:function (pEngine, time, dt) {
104             this.engine = pEngine;
105             this.life += time;
106             this.birth = time;
107             this.dead = false;
108         },
109 
110         /**
111          * Get the current position of the particle
112          * @return {R.math.Point2D}
113          */
114         getPosition:function () {
115             return this.pos;
116         },
117 
118         /**
119          * Set the X and Y world coordinates of the particle
120          * @param x {R.math.Point2D|Number} A {@link R.math.Point2D}, or the X world coordinate
121          * @param y {Number} Y world coordinate
122          */
123         setPosition:function (x, y) {
124             this.pos.set(x, y);
125         },
126 
127         /**
128          * Update the particle in the render context, calling its draw method.
129          * @param renderContext {R.rendercontexts.AbstractRenderContext} The context where the particle is drawn
130          * @param time {Number} The world time, in milliseconds
131          * @param dt {Number} The delta between the world time and the last time the world was updated
132          *          in milliseconds.
133          */
134         update:function (renderContext, time, dt) {
135             if (time < this.life &&
136                 renderContext.getViewport().containsPoint(this.getPosition())) {
137                 // if the particle is still alive, and it isn't outside the viewport
138                 this.draw(renderContext, time, dt);
139                 return true;
140             }
141             else {
142                 return false;
143             }
144         },
145 
146         /**
147          * Get the time-to-live for the particle (when it will expire)
148          * @return {Number} milliseconds
149          */
150         getTTL:function () {
151             return this.life;
152         },
153 
154         /**
155          * Get the time at which the particle was created
156          * @return {Number} milliseconds
157          */
158         getBirth:function () {
159             return this.birth;
160         },
161 
162 
163         /**
164          * [ABSTRACT] Draw the particle
165          * @param renderContext {R.rendercontexts.AbstractRenderContext} The context to render the particle to
166          * @param time {Number} The world time, in milliseconds
167          * @param dt {Number} The delta between the world time and the last time the world was updated
168          *          in milliseconds.
169          */
170         draw:function (renderContext, time, dt) {
171             // ABSTRACT
172         }
173 
174     }, /** @scope R.particles.AbstractParticle.prototype */ {
175         /**
176          * Get the class name of this object
177          *
178          * @return {String} "R.particles.AbstractParticle"
179          */
180         getClassName:function () {
181             return "R.particles.AbstractParticle";
182         }
183     });
184 
185 }