index option for adding primitive to PrimitiveCollection

Source/Scene/PrimitiveCollection.js

@@ -100,18 +100,29 @@ define([
      * Adds a primitive to the collection.
      *
      * @param {Object} primitive The primitive to add.
+     * @param {Number} [index] the index to add the layer at.  If omitted, the primitive will
+     *                         added at the bottom  of all existing primitives.
      * @returns {Object} The primitive added to the collection.
      *
      * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
      *
      * @example
      * var billboards = scene.primitives.add(new Cesium.BillboardCollection());
      */
-    PrimitiveCollection.prototype.add = function(primitive) {
+    PrimitiveCollection.prototype.add = function(primitive, index) {
+        var hasIndex = defined(index);
+
         //>>includeStart('debug', pragmas.debug);
         if (!defined(primitive)) {
             throw new DeveloperError('primitive is required.');
         }
+        if (hasIndex) {
+            if (index < 0) {
+                throw new DeveloperError('index must be greater than or equal to zero.');
+            } else if (index > this._primitives.length) {
+                throw new DeveloperError('index must be less than or equal to the number of layers.');
+            }
+        }
         //>>includeEnd('debug');
 
         var external = (primitive._external = primitive._external || {});
@@ -120,7 +131,11 @@ define([
             collection : this
         };
 
-        this._primitives.push(primitive);
+        if (!hasIndex) {
+            this._primitives.push(primitive);
+        } else {
+            this._primitives.splice(index, 0, primitive);
+        }
 
         return primitive;
     };
@@ -183,7 +198,7 @@ define([
     PrimitiveCollection.prototype.removeAll = function() {
         var primitives = this._primitives;
         var length = primitives.length;
-        for ( var i = 0; i < length; ++i) {
+        for (var i = 0; i < length; ++i) {
             delete primitives[i]._external._composites[this._guid];
             if (this.destroyPrimitives) {
                 primitives[i].destroy();

Specs/Scene/PrimitiveCollectionSpec.js

@@ -130,6 +130,33 @@ defineSuite([
         expect(primitives.length).toEqual(1);
     });
 
+    it('add works with an index', function() {
+        var p0 = createLabels();
+        var p1 = createLabels();
+
+        expect(function() {
+            primitives.add(p0, 1);
+        }).toThrowDeveloperError();
+
+        expect(function() {
+            primitives.add(p0, -1);
+        }).toThrowDeveloperError();
+
+        primitives.add(p0, 0);
+        expect(primitives.get(0)).toBe(p0);
+
+        expect(function() {
+            primitives.add(p1, -1);
+        }).toThrowDeveloperError();
+
+        expect(function() {
+            primitives.add(p1, 2);
+        }).toThrowDeveloperError();
+
+        primitives.add(p1, 0);
+        expect(primitives.get(0)).toBe(p1);
+    });
+
     it('removes the first primitive', function() {
         var p0 = createLabels();
         var p1 = createLabels();