Merge pull request #6429 from hanbollar/particle-system-updates-and-d…

…eprecations

Particle system updates and name changes

CHANGES.md

@@ -21,9 +21,15 @@ Change Log
 * Fix flicker when adding, removing, or modifiying entities. [#3945](https://github.com/AnalyticalGraphicsInc/cesium/issues/3945)
 
 ##### Additions :tada:
+* Added color and scale attributes to the `ParticleSystem` class constructor. When defined the variables override startColor and endColor and startScale and endScale. [#6429](https://github.com/AnalyticalGraphicsInc/cesium/pull/6429)
 * Improved `MapboxImageryProvider` performance by 300% via `tiles.mapbox.com` subdomain switching. [#6426](https://github.com/AnalyticalGraphicsInc/cesium/issues/6426)
 * Added ability to invoke `sampleTerrain` from node.js to enable offline terrain sampling
 
+##### Deprecated :hourglass_flowing_sand:
+* `Particle.size`, `ParticleSystem.rate`, `ParticleSystem.lifeTime`, `ParticleSystem.life`, `ParticleSystem.minimumLife`, and `ParticleSystem.maximumLife` have been renamed to `Particle.imageSize`, `ParticleSystem.emissionRate`, `ParticleSystem.lifetime`, `ParticleSystem.particleLife`, `ParticleSystem.minimumParticleLife`, and `ParticleSystem.maximumParticleLife`. Use of the `size`, `rate`, `lifeTime`, `life`, `minimumLife`, and `maximumLife` parameters is deprecated and will be removed in Cesium 1.46.
+* `ParticleSystem.forces` array has been switched out for singular function `ParticleSystems.updateCallback`. Use of the `forces` parameter is deprecated and will be removed in Cesium 1.46.
+* Any width and height variables in `ParticleSystem` will no longer be individual components. `ParticleSystem.minimumWidth` and `ParticleSystem.minimumHeight` will now be `ParticleSystem.minimumImageSize`, `ParticleSystem.maximumWidth` and `ParticleSystem.maximumHeight` will now be `ParticleSystem.maximumImageSize`, and `ParticleSystem.width` and `ParticleSystem.height` will now be `ParticleSystem.imageSize`. Use of the `minimumWidth`, `minimumHeight`, `maximumWidth`, `maximumHeight`, `width`, and `height` parameters is deprecated and will be removed in Cesium 1.46.
+
 ### 1.44 - 2018-04-02
 
 ##### Highlights :sparkler:

Source/Scene/Particle.js

@@ -4,14 +4,16 @@ define([
         '../Core/Color',
         '../Core/defaultValue',
         '../Core/defined',
-        '../Core/defineProperties'
+        '../Core/defineProperties',
+        '../Core/deprecationWarning'
     ], function(
         Cartesian2,
         Cartesian3,
         Color,
         defaultValue,
         defined,
-        defineProperties) {
+        defineProperties,
+        deprecationWarning) {
     'use strict';
 
     var defaultSize = new Cartesian2(1.0, 1.0);
@@ -23,16 +25,17 @@ define([
      * @constructor
      *
      * @param {Object} options An object with the following properties:
-     * @param {Number} [options.mass=1.0] The mass of particles in kilograms.
+     * @param {Number} [options.mass=1.0] The mass of the particle in kilograms.
      * @param {Cartesian3} [options.position=Cartesian3.ZERO] The initial position of the particle in world coordinates.
      * @param {Cartesian3} [options.velocity=Cartesian3.ZERO] The velocity vector of the particle in world coordinates.
-     * @param {Number} [options.life=Number.MAX_VALUE] The life of particles in seconds.
+     * @param {Number} [options.life=Number.MAX_VALUE] The life of the particle in seconds.
      * @param {Object} [options.image] The URI, HTMLImageElement, or HTMLCanvasElement to use for the billboard.
      * @param {Color} [options.startColor=Color.WHITE] The color of a particle when it is born.
      * @param {Color} [options.endColor=Color.WHITE] The color of a particle when it dies.
      * @param {Number} [options.startScale=1.0] The scale of the particle when it is born.
      * @param {Number} [options.endScale=1.0] The scale of the particle when it dies.
-     * @param {Cartesian2} [options.size=new Cartesian2(1.0, 1.0)] The dimensions of particles in pixels.
+     * @param {Cartesian2} [options.size=new Cartesian2(1.0, 1.0)] The dimensions of particles in pixels. This has been deprecated. Use imageSize instead.
+     * @param {Cartesian2} [options.imageSize=new Cartesian2(1.0, 1.0)] The dimensions, width by height, to scale the particle image in pixels.
      */
     function Particle(options) {
         options = defaultValue(options, defaultValue.EMPTY_OBJECT);
@@ -92,11 +95,15 @@ define([
          */
         this.endScale = defaultValue(options.endScale, 1.0);
         /**
-         * The dimensions of the particle in pixels.
+         * The dimensions, width by height, to scale the particle image in pixels.
          * @type {Cartesian2}
          * @default new Cartesian(1.0, 1.0)
          */
-        this.size = Cartesian2.clone(defaultValue(options.size, defaultSize));
+        this.imageSize = Cartesian2.clone(defaultValue(options.imageSize, defaultSize));
+        if (defined(options.size)) {
+            deprecationWarning('size', 'size was deprecated in Cesium 1.45.  It will be removed in 1.46.  Use imageSize instead.');
+            this.imageSize = Cartesian2.clone(defaultValue(options.size, defaultSize));
+        }
 
         this._age = 0.0;
         this._normalizedAge = 0.0;
@@ -125,6 +132,22 @@ define([
             get : function() {
                 return this._normalizedAge;
             }
+        },
+        /**
+         * The dimensions of the particle in pixels. This has been deprecated. Use {@link Particle#imageSize} instead.
+         * @type {Cartesian2}
+         * @default new Cartesian(1.0, 1.0)
+         * @deprecated
+         */
+         size : {
+             get : function() {
+                 deprecationWarning('size', 'size was deprecated in Cesium 1.45.  It will be removed in 1.46.  Use imageSize instead.');
+                 return this.imageSize;
+             },
+             set : function(value) {
+                 deprecationWarning('size', 'size was deprecated in Cesium 1.45.  It will be removed in 1.46.  Use imageSize instead.');
+                 this.imageSize = value;
+             }
         }
     });
 
@@ -133,19 +156,23 @@ define([
     /**
      * @private
      */
-    Particle.prototype.update = function(dt, forces) {
+    Particle.prototype.update = function(dt, particleUpdateFunction) {
         // Apply the velocity
         Cartesian3.multiplyByScalar(this.velocity, dt, deltaScratch);
         Cartesian3.add(this.position, deltaScratch, this.position);
 
         // Update any forces.
-        if (defined(forces)) {
-            var length = forces.length;
-            for (var i = 0; i < length; ++i) {
-                var force = forces[i];
-                if (typeof force === 'function') {
-                    // Force is just a simple callback function.
-                    force(this, dt);
+        if (defined(particleUpdateFunction)) {
+            if (typeof particleUpdateFunction === 'function') {
+                particleUpdateFunction(this, dt);
+            } else if (particleUpdateFunction instanceof Array) {
+                var length = particleUpdateFunction.length;
+                for (var i = 0; i < length; ++i) {
+                    var force = particleUpdateFunction[i];
+                    if (typeof force === 'function') {
+                        // Force is just a simple callback function.
+                        force(this, dt);
+                    }
                 }
             }
         }