From 3882e8502c0c8adb436cb55bb032349f82bf5f4f Mon Sep 17 00:00:00 2001
From: hpinkos <hannah@cesium.com>
Date: Mon, 5 Aug 2019 14:04:50 -0400
Subject: [PATCH 1/3] index option for adding primitive to PrimitiveCollection

---
 Source/Scene/PrimitiveCollection.js    | 21 +++++++++++++++++---
 Specs/Scene/PrimitiveCollectionSpec.js | 27 ++++++++++++++++++++++++++
 2 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/Source/Scene/PrimitiveCollection.js b/Source/Scene/PrimitiveCollection.js
index 1430c57d03d0..9f0566148aac 100644
--- a/Source/Scene/PrimitiveCollection.js
+++ b/Source/Scene/PrimitiveCollection.js
@@ -100,6 +100,8 @@ 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.
@@ -107,11 +109,20 @@ define([
      * @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();
diff --git a/Specs/Scene/PrimitiveCollectionSpec.js b/Specs/Scene/PrimitiveCollectionSpec.js
index 004c06b9e24b..c68966ee6083 100644
--- a/Specs/Scene/PrimitiveCollectionSpec.js
+++ b/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();

From 4d9c6c66fbad54356142fdb6dc9f414e154e8beb Mon Sep 17 00:00:00 2001
From: Hannah <hannah@cesium.com>
Date: Mon, 5 Aug 2019 14:11:22 -0400
Subject: [PATCH 2/3] Update PrimitiveCollection.js

---
 Source/Scene/PrimitiveCollection.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Source/Scene/PrimitiveCollection.js b/Source/Scene/PrimitiveCollection.js
index 9f0566148aac..0f5108485d6e 100644
--- a/Source/Scene/PrimitiveCollection.js
+++ b/Source/Scene/PrimitiveCollection.js
@@ -120,7 +120,7 @@ define([
             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.');
+                throw new DeveloperError('index must be less than or equal to the number of primitives.');
             }
         }
         //>>includeEnd('debug');

From a3ab91df6fc59563ca9089779af80950111f8c2f Mon Sep 17 00:00:00 2001
From: Hannah <hannah@cesium.com>
Date: Mon, 5 Aug 2019 14:16:24 -0400
Subject: [PATCH 3/3] Update CHANGES.md

---
 CHANGES.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/CHANGES.md b/CHANGES.md
index cfedaede669e..6919179dfd9d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,6 +1,11 @@
 Change Log
 ==========
 
+### 1.61 - 2019-09-03
+
+##### Additions :tada:
+* Added optional `index` parameter to `PrimitiveCollection.add`. [#8041](https://github.com/AnalyticalGraphicsInc/cesium/pull/8041)
+
 ### 1.60 - 2019-08-01
 
 ##### Additions :tada: