Deprecate EllipsoidPrimitive, RectanglePrimitive, and Polygon

As discussed in #3083, these primitives are no longer needed and add
confusion to the public API.

I also replaced usage of them in any tests with the equivalent G&A code.

CHANGES.md

@@ -5,9 +5,10 @@ Change Log
 
 * Breaking changes
   * Deleted old `<subfolder>/package.json` and `*.profile.js` files, not used since we moved away from a Dojo-based build years ago.  This should allow future compatibility with newer systems like Browserify and Webpack.
-  * ...
 * Deprecated
-  * ...
+  * Made `EllipsoidPrimitive` private, use `EllipsoidGeometry` or `Entity.ellipsoid` instead.
+  * Deprecated `RectanglePrimitive`, use `RectangleGeometry` or `Entity.rectangle` instead. It will be removed in 1.17.
+  * Deprecated `EllipsoidPrimitive`, use `EllipsoidGeometry` or `Entity.ellipsoid` instead. It will be removed in 1.17.
 * Decreased GPU memory usage in `BillboardCollection` and `LabelCollection` by using the WebGL ANGLE_instanced_arrays extension.
 * Added CZML examples to Sandcastle.  See the new CZML tab.
 * Fixed token issue in `ArcGisMapServerImageryProvider`.

Source/Scene/EllipsoidPrimitive.js

@@ -71,22 +71,7 @@ define([
      * @param {Object} [options.id] A user-defined object to return when the instance is picked with {@link Scene#pick}
      * @param {Boolean} [options.debugShowBoundingVolume=false] For debugging only. Determines if this primitive's commands' bounding spheres are shown.
      *
-     * @demo {@link http://cesiumjs.org/Cesium/Apps/Sandcastle/index.html?src=Volumes.html|Cesium Sandcastle Volumes Demo}
-     *
-     * @example
-     * // 1. Create a sphere using the ellipsoid primitive
-     * primitives.add(new Cesium.EllipsoidPrimitive({
-     *   center : Cesium.Cartesian3.fromDegrees(-75.0, 40.0, 500000.0),
-     *   radii : new Cesium.Cartesian3(500000.0, 500000.0, 500000.0)
-     * }));
-     *
-     * @example
-     * // 2. Create a tall ellipsoid in an east-north-up reference frame
-     * var e = new Cesium.EllipsoidPrimitive();
-     * e.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(
-     *   Cesium.Cartesian3.fromDegrees(-95.0, 40.0, 200000.0));
-     * e.radii = new Cesium.Cartesian3(100000.0, 100000.0, 200000.0);
-     * primitives.add(e);
+     * @private
      */
     var EllipsoidPrimitive = function(options) {
         options = defaultValue(options, defaultValue.EMPTY_OBJECT);

Source/Scene/Polygon.js

@@ -4,6 +4,7 @@ define([
         '../Core/defaultValue',
         '../Core/defined',
         '../Core/defineProperties',
+        '../Core/deprecationWarning',
         '../Core/destroyObject',
         '../Core/DeveloperError',
         '../Core/Ellipsoid',
@@ -18,6 +19,7 @@ define([
         defaultValue,
         defined,
         defineProperties,
+        deprecationWarning,
         destroyObject,
         DeveloperError,
         Ellipsoid,
@@ -77,8 +79,13 @@ define([
      *     10.0, 0.0,
      *     0.0, 10.0
      * ]);
+     *
+     * @deprecated
+     * @private
      */
     var Polygon = function(options) {
+        deprecationWarning('Polygon', 'Polygon has been deprecated.  Use PolygonGeometry or Entity.polygon instead.');
+
         options = defaultValue(options, defaultValue.EMPTY_OBJECT);
 
         /**

Source/Scene/RectanglePrimitive.js

@@ -3,6 +3,7 @@ define([
         '../Core/Color',
         '../Core/defaultValue',
         '../Core/defined',
+        '../Core/deprecationWarning',
         '../Core/destroyObject',
         '../Core/DeveloperError',
         '../Core/Ellipsoid',
@@ -17,6 +18,7 @@ define([
         Color,
         defaultValue,
         defined,
+        deprecationWarning,
         destroyObject,
         DeveloperError,
         Ellipsoid,
@@ -53,8 +55,13 @@ define([
      *   rectangle : Cesium.Rectangle.fromDegrees(0.0, 20.0, 10.0, 30.0)
      * });
      * primitives.add(rectanglePrimitive);
+     *
+     * @deprecated
+     * @private
      */
     var RectanglePrimitive = function(options) {
+        deprecationWarning('RectanglePrimitive', 'RectanglePrimitive has been deprecated.  Use RectangleGeometry or Entity.rectangle instead.');
+
         options = defaultValue(options, defaultValue.EMPTY_OBJECT);
 
         /**

Specs/Scene/MaterialSpec.js

@@ -4,10 +4,13 @@ defineSuite([
         'Core/Cartesian3',
         'Core/Color',
         'Core/Ellipsoid',
+        'Core/GeometryInstance',
         'Core/Math',
+        'Core/PolygonGeometry',
         'Renderer/ClearCommand',
-        'Scene/Polygon',
+        'Scene/EllipsoidSurfaceAppearance',
         'Scene/PolylineCollection',
+        'Scene/Primitive',
         'Specs/createCamera',
         'Specs/createContext',
         'Specs/createFrameState',
@@ -18,10 +21,13 @@ defineSuite([
         Cartesian3,
         Color,
         Ellipsoid,
+        GeometryInstance,
         CesiumMath,
+        PolygonGeometry,
         ClearCommand,
-        Polygon,
+        EllipsoidSurfaceAppearance,
         PolylineCollection,
+        Primitive,
         createCamera,
         createContext,
         createFrameState,
@@ -53,16 +59,26 @@ defineSuite([
         })));
 
         var ellipsoid = Ellipsoid.UNIT_SPHERE;
-        polygon = new Polygon();
-        polygon.ellipsoid = ellipsoid;
-        polygon.granularity = CesiumMath.toRadians(20.0);
-        polygon.positions = Cartesian3.fromDegreesArray([
-            -50.0, -50.0,
-            50.0, -50.0,
-            50.0, 50.0,
-            -50.0, 50.0
-        ], ellipsoid);
-        polygon.asynchronous = false;
+
+        polygon = new Primitive({
+            geometryInstances: new GeometryInstance({
+                geometry: PolygonGeometry.fromPositions({
+                    positions: Cartesian3.fromDegreesArray([
+                        -50.0, -50.0,
+                        50.0, -50.0,
+                        50.0, 50.0,
+                        -50.0, 50.0
+                    ], ellipsoid),
+                    vertexFormat: EllipsoidSurfaceAppearance.VERTEX_FORMAT,
+                    ellipsoid: ellipsoid,
+                    granularity: CesiumMath.toRadians(20.0)
+                })
+            }),
+            appearance: new EllipsoidSurfaceAppearance({
+                aboveGround: false
+            }),
+            asynchronous: false
+        });
 
         polylines = new PolylineCollection();
         polyline = polylines.add({
@@ -81,7 +97,7 @@ defineSuite([
     });
 
     function renderMaterial(material) {
-        polygon.material = material;
+        polygon.appearance.material = material;
 
         ClearCommand.ALL.execute(context);
         expect(context.readPixels()).toEqual([0, 0, 0, 0]);

Specs/Scene/PickSpec.js

@@ -14,7 +14,6 @@ defineSuite([
         'Scene/OrthographicFrustum',
         'Scene/PerspectiveFrustum',
         'Scene/Primitive',
-        'Scene/RectanglePrimitive',
         'Scene/SceneMode',
         'Specs/createScene'
     ], 'Scene/Pick', function(
@@ -32,7 +31,6 @@ defineSuite([
         OrthographicFrustum,
         PerspectiveFrustum,
         Primitive,
-        RectanglePrimitive,
         SceneMode,
         createScene) {
     "use strict";
@@ -76,11 +74,19 @@ defineSuite([
     function createRectangle() {
         var ellipsoid = Ellipsoid.UNIT_SPHERE;
 
-        var e = new RectanglePrimitive({
-            ellipsoid : ellipsoid,
-            granularity : CesiumMath.toRadians(20.0),
-            rectangle : Rectangle.fromDegrees(-50.0, -50.0, 50.0, 50.0),
-            asynchronous : false
+        var e = new Primitive({
+            geometryInstances: new GeometryInstance({
+                geometry: new RectangleGeometry({
+                    rectangle: Rectangle.fromDegrees(-50.0, -50.0, 50.0, 50.0),
+                    vertexFormat: EllipsoidSurfaceAppearance.VERTEX_FORMAT,
+                    ellipsoid: ellipsoid,
+                    granularity: CesiumMath.toRadians(20.0)
+                })
+            }),
+            appearance: new EllipsoidSurfaceAppearance({
+                aboveGround: false
+            }),
+            asynchronous: false
         });
 
         primitives.add(e);
@@ -115,7 +121,7 @@ defineSuite([
 
     it('does not pick primitives when alpha is zero', function() {
         var rectangle = createRectangle();
-        rectangle.material.uniforms.color.alpha = 0.0;
+        rectangle.appearance.material.uniforms.color.alpha = 0.0;
 
         var pickedObject = scene.pick(new Cartesian2(0, 0));
         expect(pickedObject).not.toBeDefined();
@@ -162,7 +168,7 @@ defineSuite([
         var rectangle1 = createRectangle();
         var rectangle2 = createRectangle();
         rectangle2.height = 0.01;
-        rectangle2.material.uniforms.color.alpha = 0.0;
+        rectangle2.appearance.material.uniforms.color.alpha = 0.0;
 
         var pickedObjects = scene.drillPick(new Cartesian2(0, 0));
         expect(pickedObjects.length).toEqual(1);

Specs/Scene/PrimitiveCullingSpec.js

@@ -5,19 +5,22 @@ defineSuite([
         'Core/Cartesian3',
         'Core/defaultValue',
         'Core/Ellipsoid',
+        'Core/GeometryInstance',
         'Core/loadImage',
         'Core/Math',
         'Core/Occluder',
+        'Core/PolygonGeometry',
         'Renderer/Sampler',
         'Renderer/TextureMagnificationFilter',
         'Renderer/TextureMinificationFilter',
         'Scene/BillboardCollection',
+        'Scene/EllipsoidSurfaceAppearance',
         'Scene/HorizontalOrigin',
         'Scene/LabelCollection',
         'Scene/Material',
         'Scene/OrthographicFrustum',
-        'Scene/Polygon',
         'Scene/PolylineCollection',
+        'Scene/Primitive',
         'Scene/PrimitiveCollection',
         'Scene/SceneMode',
         'Scene/TextureAtlas',
@@ -32,19 +35,22 @@ defineSuite([
         Cartesian3,
         defaultValue,
         Ellipsoid,
+        GeometryInstance,
         loadImage,
         CesiumMath,
         Occluder,
+        PolygonGeometry,
         Sampler,
         TextureMagnificationFilter,
         TextureMinificationFilter,
         BillboardCollection,
+        EllipsoidSurfaceAppearance,
         HorizontalOrigin,
         LabelCollection,
         Material,
         OrthographicFrustum,
-        Polygon,
         PolylineCollection,
+        Primitive,
         PrimitiveCollection,
         SceneMode,
         TextureAtlas,
@@ -276,18 +282,27 @@ defineSuite([
 
     function createPolygon(degree, ellipsoid) {
         degree = defaultValue(degree, 50.0);
-        ellipsoid = defaultValue(ellipsoid, Ellipsoid.UNIT_SPHERE);
-        var polygon = new Polygon();
-        polygon.ellipsoid = ellipsoid;
-        polygon.granularity = CesiumMath.toRadians(20.0);
-        polygon.positions = Cartesian3.fromDegreesArray([
-            -degree, -degree,
-            degree, -degree,
-            degree,  degree,
-            -degree,  degree
-        ]);
-        polygon.asynchronous = false;
-        polygon.material.translucent = false;
+        var polygon = new Primitive({
+            geometryInstances: new GeometryInstance({
+                geometry: PolygonGeometry.fromPositions({
+                    positions: Cartesian3.fromDegreesArray([
+                        -degree, -degree,
+                        degree, -degree,
+                        degree, degree,
+                        -degree, degree
+                    ]),
+                    vertexFormat: EllipsoidSurfaceAppearance.VERTEX_FORMAT,
+                    ellipsoid: ellipsoid,
+                    granularity: CesiumMath.toRadians(20.0)
+                })
+            }),
+            appearance: new EllipsoidSurfaceAppearance({
+                aboveGround: false
+            }),
+            asynchronous: false
+        });
+        polygon.appearance.material.translucent = false;
+
         return polygon;
     }