Merge pull request #7393 from OmarShehata/deprecate-speedup

Rename speedup to multiplier

Author: lilleyse

Apps/Sandcastle/gallery/HeadingPitchRoll.html

@@ -120,7 +120,7 @@ <h1>Loading...</h1>
 planePrimitive.readyPromise.then(function(model) {
     // Play and loop all animations at half-speed
     model.activeAnimations.addAll({
-        speedup : 0.5,
+        multiplier : 0.5,
         loop : Cesium.ModelAnimationLoop.REPEAT
     });
 

Apps/Sandcastle/gallery/LocalToFixedFrame.html

@@ -142,7 +142,7 @@ <h1>Loading...</h1>
 primitives[0].primitive.readyPromise.then(function(model) {
     // Play and loop all animations at half-speed
     model.activeAnimations.addAll({
-        speedup : 0.5,
+        multiplier : 0.5,
         loop : Cesium.ModelAnimationLoop.REPEAT
     });
 

Apps/Sandcastle/gallery/development/3D Models Instancing.html

@@ -64,7 +64,7 @@
     collection.readyPromise.then(function(collection) {
         // Play and loop all animations at half-speed
         collection.activeAnimations.addAll({
-            speedup : 0.5,
+            multiplier : 0.5,
             loop : Cesium.ModelAnimationLoop.REPEAT
         });
         orientCamera(collection._boundingSphere.center, collection._boundingSphere.radius);
@@ -93,7 +93,7 @@
         model.readyPromise.then(function(model) {
             // Play and loop all animations at half-speed
             model.activeAnimations.addAll({
-                speedup : 0.5,
+                multiplier : 0.5,
                 loop : Cesium.ModelAnimationLoop.REPEAT
             });
         }).otherwise(function(error){

Apps/Sandcastle/gallery/development/3D Models.html

@@ -145,7 +145,7 @@
         model.colorBlendAmount = viewModel.colorBlendAmount;
         // Play and loop all animations at half-speed
         model.activeAnimations.addAll({
-            speedup : 0.5,
+            multiplier : 0.5,
             loop : Cesium.ModelAnimationLoop.REPEAT
         });
 

Apps/Sandcastle/gallery/development/Multiple Shadows.html

@@ -76,7 +76,7 @@
             model.readyPromise.then(function(model) {
                 // Play and loop all animations at half-speed
                 model.activeAnimations.addAll({
-                    speedup : 0.5,
+                    multiplier : 0.5,
                     loop : Cesium.ModelAnimationLoop.REPEAT
                 });
             }).otherwise(function(error) {

Apps/Sandcastle/gallery/development/Shadows.html

@@ -611,7 +611,7 @@
     model.readyPromise.then(function(model) {
         // Play and loop all animations at half-speed
         model.activeAnimations.addAll({
-            speedup : 0.5,
+            multiplier : 0.5,
             loop : Cesium.ModelAnimationLoop.REPEAT
         });
     }).otherwise(function(error){

CHANGES.md

@@ -6,6 +6,9 @@ Change Log
 ##### Breaking Changes :mega:
 * `TerrainProviders` that implement `availability` must now also implement the `loadTileDataAvailability` method.
 
+##### Deprecated :hourglass_flowing_sand:
+* The property `ModelAnimation.speedup` has been deprecated and renamed to `ModelAnimation.multiplier`. `speedup` will be removed in version 1.54. [#7393](https://github.com/AnalyticalGraphicsInc/cesium/pull/7393)
+
 ##### Additions :tada:
 * Added functions to get the most detailed height of 3D Tiles on-screen or off-screen. [#7115](https://github.com/AnalyticalGraphicsInc/cesium/pull/7115)
     * Added `Scene.sampleHeightMostDetailed`, an asynchronous version of `Scene.sampleHeight` that uses the maximum level of detail for 3D Tiles.

Source/Scene/Model.js

@@ -833,7 +833,7 @@ define([
          * // Play all animations at half-speed when the model is ready to render
          * Cesium.when(model.readyPromise).then(function(model) {
          *   model.activeAnimations.addAll({
-         *     speedup : 0.5
+         *     multiplier : 0.5
          *   });
          * }).otherwise(function(error){
          *   window.alert(error);

Source/Scene/ModelAnimation.js

@@ -1,13 +1,17 @@
 define([
         '../Core/defaultValue',
         '../Core/defineProperties',
+        '../Core/defined',
+        '../Core/deprecationWarning',
         '../Core/Event',
         '../Core/JulianDate',
         './ModelAnimationLoop',
         './ModelAnimationState'
     ], function(
         defaultValue,
         defineProperties,
+        defined,
+        deprecationWarning,
         Event,
         JulianDate,
         ModelAnimationLoop,
@@ -46,7 +50,12 @@ define([
          */
         this.removeOnStop = defaultValue(options.removeOnStop, false);
 
-        this._speedup = defaultValue(options.speedup, 1.0);
+        if (defined(options.speedup)) {
+            deprecationWarning('ModelAnimation.speedup', 'ModelAnimation.speedup is deprecated and will be removed in Cesium 1.54. Use ModelAnimation.multiplier instead.');
+            options.multiplier = options.speedup;
+        }
+
+        this._multiplier = defaultValue(options.multiplier, 1.0);
         this._reverse = defaultValue(options.reverse, false);
         this._loop = defaultValue(options.loop, ModelAnimationLoop.NONE);
 
@@ -189,24 +198,44 @@ define([
                 return this._stopTime;
             }
         },
-
         /**
          * Values greater than <code>1.0</code> increase the speed that the animation is played relative
          * to the scene clock speed; values less than <code>1.0</code> decrease the speed.  A value of
          * <code>1.0</code> plays the animation at the speed in the glTF animation mapped to the scene
          * clock speed.  For example, if the scene is played at 2x real-time, a two-second glTF animation
-         * will play in one second even if <code>speedup</code> is <code>1.0</code>.
+         * will play in one second even if <code>multiplier</code> is <code>1.0</code>.
+         *
+         * @memberof ModelAnimation.prototype
          *
+         * @type {Number}
+         * @readonly
+         *
+         * @default 1.0
+         */
+        multiplier : {
+            get : function() {
+                return this._multiplier;
+            }
+        },
+
+        /**
+         * Values greater than <code>1.0</code> increase the speed that the animation is played relative
+         * to the scene clock speed; values less than <code>1.0</code> decrease the speed.  A value of
+         * <code>1.0</code> plays the animation at the speed in the glTF animation mapped to the scene
+         * clock speed.  For example, if the scene is played at 2x real-time, a two-second glTF animation
+         * will play in one second even if <code>multiplier</code> is <code>1.0</code>.
          * @memberof ModelAnimation.prototype
          *
          * @type {Number}
          * @readonly
+         * @deprecated This property has been deprecated. Use {@link ModelAnimation#multiplier} instead.
          *
          * @default 1.0
          */
         speedup : {
             get : function() {
-                return this._speedup;
+                deprecationWarning('ModelAnimation.speedup', 'ModelAnimation.speedup is deprecated and will be removed in Cesium 1.54. Use ModelAnimation.multiplier instead.');
+                return this._multiplier;
             }
         },
 

Source/Scene/ModelAnimationCollection.js

@@ -2,6 +2,7 @@ define([
         '../Core/defaultValue',
         '../Core/defined',
         '../Core/defineProperties',
+        '../Core/deprecationWarning',
         '../Core/DeveloperError',
         '../Core/Event',
         '../Core/JulianDate',
@@ -13,6 +14,7 @@ define([
         defaultValue,
         defined,
         defineProperties,
+        deprecationWarning,
         DeveloperError,
         Event,
         JulianDate,
@@ -104,7 +106,7 @@ define([
      * @param {Number} [options.delay=0.0] The delay, in seconds, from <code>startTime</code> to start playing.
      * @param {JulianDate} [options.stopTime] The scene time to stop playing the animation.  When this is <code>undefined</code>, the animation is played for its full duration.
      * @param {Boolean} [options.removeOnStop=false] When <code>true</code>, the animation is removed after it stops playing.
-     * @param {Number} [options.speedup=1.0] Values greater than <code>1.0</code> increase the speed that the animation is played relative to the scene clock speed; values less than <code>1.0</code> decrease the speed.
+     * @param {Number} [options.multiplier=1.0] Values greater than <code>1.0</code> increase the speed that the animation is played relative to the scene clock speed; values less than <code>1.0</code> decrease the speed.
      * @param {Boolean} [options.reverse=false] When <code>true</code>, the animation is played in reverse.
      * @param {ModelAnimationLoop} [options.loop=ModelAnimationLoop.NONE] Determines if and how the animation is looped.
      * @returns {ModelAnimation} The animation that was added to the collection.
@@ -113,7 +115,7 @@ define([
      * @exception {DeveloperError} options.name must be a valid animation name.
      * @exception {DeveloperError} options.index must be a valid animation index.
      * @exception {DeveloperError} Either options.name or options.index must be defined.
-     * @exception {DeveloperError} options.speedup must be greater than zero.
+     * @exception {DeveloperError} options.multiplier must be greater than zero.
      *
      * @example
      * // Example 1. Add an animation by name
@@ -136,7 +138,7 @@ define([
      *   delay : 0.0,                          // Play at startTime (default)
      *   stopTime : Cesium.JulianDate.addSeconds(startTime, 4.0, new Cesium.JulianDate()),
      *   removeOnStop : false,                 // Do not remove when animation stops (default)
-     *   speedup : 2.0,                        // Play at double speed
+     *   multiplier : 2.0,                        // Play at double speed
      *   reverse : true,                       // Play in reverse
      *   loop : Cesium.ModelAnimationLoop.REPEAT      // Loop the animation
      * });
@@ -164,8 +166,14 @@ define([
         if (!defined(options.name) && !defined(options.index)) {
             throw new DeveloperError('Either options.name or options.index must be defined.');
         }
-        if (defined(options.speedup) && (options.speedup <= 0.0)) {
-            throw new DeveloperError('options.speedup must be greater than zero.');
+
+        if (defined(options.speedup)) {
+            deprecationWarning('options.speedup', 'options.speedup is deprecated and will be removed in Cesium 1.54. Use options.multiplier instead.');
+            options.multiplier = options.speedup;
+        }
+
+        if (defined(options.multiplier) && (options.multiplier <= 0.0)) {
+            throw new DeveloperError('options.multiplier must be greater than zero.');
         }
         if (defined(options.index) && (options.index >= animations.length || options.index < 0)) {
             throw new DeveloperError('options.index must be a valid animation index.');
@@ -207,17 +215,17 @@ define([
      * @param {Number} [options.delay=0.0] The delay, in seconds, from <code>startTime</code> to start playing.
      * @param {JulianDate} [options.stopTime] The scene time to stop playing the animations.  When this is <code>undefined</code>, the animations are played for its full duration.
      * @param {Boolean} [options.removeOnStop=false] When <code>true</code>, the animations are removed after they stop playing.
-     * @param {Number} [options.speedup=1.0] Values greater than <code>1.0</code> increase the speed that the animations play relative to the scene clock speed; values less than <code>1.0</code> decrease the speed.
+     * @param {Number} [options.multiplier=1.0] Values greater than <code>1.0</code> increase the speed that the animations play relative to the scene clock speed; values less than <code>1.0</code> decrease the speed.
      * @param {Boolean} [options.reverse=false] When <code>true</code>, the animations are played in reverse.
      * @param {ModelAnimationLoop} [options.loop=ModelAnimationLoop.NONE] Determines if and how the animations are looped.
      * @returns {ModelAnimation[]} An array of {@link ModelAnimation} objects, one for each animation added to the collection.  If there are no glTF animations, the array is empty.
      *
      * @exception {DeveloperError} Animations are not loaded.  Wait for the {@link Model#readyPromise} to resolve.
-     * @exception {DeveloperError} options.speedup must be greater than zero.
+     * @exception {DeveloperError} options.multiplier must be greater than zero.
      *
      * @example
      * model.activeAnimations.addAll({
-     *   speedup : 0.5,                        // Play at half-speed
+     *   multiplier : 0.5,                        // Play at half-speed
      *   loop : Cesium.ModelAnimationLoop.REPEAT      // Loop the animations
      * });
      */
@@ -229,8 +237,13 @@ define([
             throw new DeveloperError('Animations are not loaded.  Wait for Model.readyPromise to resolve.');
         }
 
-        if (defined(options.speedup) && (options.speedup <= 0.0)) {
-            throw new DeveloperError('options.speedup must be greater than zero.');
+        if (defined(options.speedup)) {
+            deprecationWarning('options.speedup', 'options.speedup is deprecated and will be removed in Cesium 1.54. Use options.multiplier instead.');
+            options.multiplier = options.speedup;
+        }
+
+        if (defined(options.multiplier) && (options.multiplier <= 0.0)) {
+            throw new DeveloperError('options.multiplier must be greater than zero.');
         }
         //>>includeEnd('debug');
 
@@ -385,7 +398,7 @@ define([
             }
 
             if (!defined(scheduledAnimation._duration)) {
-                scheduledAnimation._duration = runtimeAnimation.stopTime * (1.0 / scheduledAnimation.speedup);
+                scheduledAnimation._duration = runtimeAnimation.stopTime * (1.0 / scheduledAnimation.multiplier);
             }
 
             var startTime = scheduledAnimation._computedStartTime;
@@ -431,7 +444,7 @@ define([
                     delta = 1.0 - delta;
                 }
 
-                var localAnimationTime = delta * duration * scheduledAnimation.speedup;
+                var localAnimationTime = delta * duration * scheduledAnimation.multiplier;
                 // Clamp in case floating-point roundoff goes outside the animation's first or last keyframe
                 localAnimationTime = CesiumMath.clamp(localAnimationTime, runtimeAnimation.startTime, runtimeAnimation.stopTime);
 

Specs/Scene/ModelSpec.js

@@ -1300,10 +1300,10 @@ defineSuite([
         }).toThrowDeveloperError();
     });
 
-    it('addAll throws when speedup is less than or equal to zero.', function() {
+    it('addAll throws when multiplier is less than or equal to zero.', function() {
         expect(function() {
             return animBoxesModel.activeAnimations.addAll({
-                speedup : 0.0
+                multiplier : 0.0
             });
         }).toThrowDeveloperError();
     });
@@ -1323,7 +1323,7 @@ defineSuite([
         expect(a.delay).toEqual(0.0);
         expect(a.stopTime).not.toBeDefined();
         expect(a.removeOnStop).toEqual(false);
-        expect(a.speedup).toEqual(1.0);
+        expect(a.multiplier).toEqual(1.0);
         expect(a.reverse).toEqual(false);
         expect(a.loop).toEqual(ModelAnimationLoop.NONE);
         expect(a.start).toBeDefined();
@@ -1398,11 +1398,11 @@ defineSuite([
         }).toThrowDeveloperError();
     });
 
-    it('add throws when speedup is less than or equal to zero.', function() {
+    it('add throws when multiplier is less than or equal to zero.', function() {
         expect(function() {
             return animBoxesModel.activeAnimations.add({
                 name : 'animation_1',
-                speedup : 0.0
+                multiplier : 0.0
             });
         }).toThrowDeveloperError();
     });
@@ -1512,13 +1512,13 @@ defineSuite([
         animBoxesModel.show = false;
     });
 
-    it('Animates with a speedup', function() {
+    it('Animates with a multiplier', function() {
         var time = JulianDate.fromDate(new Date('January 1, 2014 12:00:00 UTC'));
         var animations = animBoxesModel.activeAnimations;
         var a = animations.add({
             name : 'animation_1',
             startTime : time,
-            speedup : 1.5
+            multiplier : 1.5
         });
 
         var spyUpdate = jasmine.createSpy('listener');

Tools/jsdoc/cesium_template/tmpl/details.tmpl

@@ -32,8 +32,10 @@ var self = this;
     <?js } ?>
 
     <?js if (data.deprecated) { ?>
-    <span class="details-header important">Deprecated:</span>
-    <span><?js= data.deprecated ?></span>
+    <p>
+        <span class="details-header important">Deprecated:</span>
+        <span><?js= data.deprecated ?></span>
+    </p>
     <?js } ?>
 
     <?js if (data.author && author.length) {?>