Add options.index

Author: lilleyse

CHANGES.md

@@ -2,6 +2,7 @@ Change Log
 ==========
 ### 1.38 - 2017-10-02
 
+* Added ability to add an animation to `ModelAnimationCollection` by its index. [#5815](https://github.com/AnalyticalGraphicsInc/cesium/pull/5815)
 * Fixed a bug in `ModelAnimationCollection` that caused adding an animation by its name to throw an error. [#5815](https://github.com/AnalyticalGraphicsInc/cesium/pull/5815)
 
 ### 1.37 - 2017-09-01

Source/Scene/ModelAnimationCollection.js

@@ -99,7 +99,8 @@ define([
      * </p>
      *
      * @param {Object} options Object with the following properties:
-     * @param {String} options.name The glTF animation name that identifies the animation.
+     * @param {String} [options.name] The glTF animation name that identifies the animation. Must be defined if <code>options.id</code> is <code>undefined</code>.
+     * @param {Number} [options.index] The glTF animation index that identifies the animation. Must be defined if <code>options.name</code> is <code>undefined</code>.
      * @param {JulianDate} [options.startTime] The scene time to start playing the animation.  When this is <code>undefined</code>, the animation starts at the next frame.
      * @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.
@@ -111,16 +112,22 @@ define([
      *
      * @exception {DeveloperError} Animations are not loaded.  Wait for the {@link Model#readyPromise} to resolve.
      * @exception {DeveloperError} options.name must be a valid animation name.
+     * @exception {DeveloperError} options.index must be a valid animation index.
      * @exception {DeveloperError} options.speedup must be greater than zero.
      *
      * @example
-     * // Example 1. Add an animation
+     * // Example 1. Add an animation by name
      * model.activeAnimations.add({
      *   name : 'animation name'
      * });
      *
+     * // Example 2. Add an animation by index
+     * model.activeAnimations.add({
+     *   index : 0
+     * });
+     *
      * @example
-     * // Example 2. Add an animation and provide all properties and events
+     * // Example 3. Add an animation and provide all properties and events
      * var startTime = Cesium.JulianDate.now();
      *
      * var animation = model.activeAnimations.add({
@@ -154,14 +161,21 @@ define([
         if (!defined(animations)) {
             throw new DeveloperError('Animations are not loaded.  Wait for Model.readyPromise to resolve.');
         }
-        if (!defined(options.name)) {
-            throw new DeveloperError('options.name must be defined.');
+        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.index) && (options.index >= animations.length || options.index < 0)) {
+            throw new DeveloperError('options.index must be a valid animation index.');
+        }
         //>>includeEnd('debug');
 
+        if (defined(options.index)) {
+            return add(this, options.index, options);
+        }
+
         // Find the index of the animation with the given name
         var index;
         var length = animations.length;

Specs/Scene/ModelSpec.js

@@ -1166,6 +1166,41 @@ defineSuite([
         animations.animationRemoved.removeEventListener(spyRemove);
     });
 
+    it('adds an animation by index', function() {
+        var animations = animBoxesModel.activeAnimations;
+        expect(animations.length).toEqual(0);
+
+        var spyAdd = jasmine.createSpy('listener');
+        animations.animationAdded.addEventListener(spyAdd);
+        var a = animations.add({
+            index : 1
+        });
+        expect(a).toBeDefined();
+        expect(a.name).toEqual('animation_1');
+        animations.remove(a);
+    });
+
+    it('add throws when name and index are not defined', function() {
+        var m = new Model();
+        expect(function() {
+            return m.activeAnimations.add();
+        }).toThrowDeveloperError();
+    });
+
+    it('add throws when index is invalid', function() {
+        var m = new Model();
+        expect(function() {
+            return m.activeAnimations.add({
+                index : -1
+            });
+        }).toThrowDeveloperError();
+        expect(function() {
+            return m.activeAnimations.add({
+                index : 2
+            });
+        }).toThrowDeveloperError();
+    });
+
     it('add throws when model is not loaded', function() {
         var m = new Model();
         expect(function() {