Merge pull request #6362 from AnalyticalGraphicsInc/z-index

Z-ordering for ground geometry entities
CesiumGS · May 22, 2018 · 87cc8b0 · 87cc8b0
2 parents 3300963 + 30ae474
commit 87cc8b0
Show file tree

Hide file tree

Showing 39 changed files with 986 additions and 107 deletions.
diff --git a/Apps/Sandcastle/gallery/Z-Indexing Geometry.html b/Apps/Sandcastle/gallery/Z-Indexing Geometry.html
@@ -0,0 +1,93 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, minimum-scale=1, user-scalable=no">
+    <meta name="description" content="Draw a rectangle or extruded rectangle that conforms to the surface of the globe.">
+    <meta name="cesium-sandcastle-labels" content="Geometries,New in 1.45">
+    <title>Cesium Demo</title>
+    <script type="text/javascript" src="../Sandcastle-header.js"></script>
+    <script type="text/javascript" src="../../../ThirdParty/requirejs-2.1.20/require.js"></script>
+    <script type="text/javascript">
+        if(typeof require === "function") {
+            require.config({
+                baseUrl : '../../../Source',
+                waitSeconds : 120
+            });
+        }
+    </script>
+</head>
+<body class="sandcastle-loading" data-sandcastle-bucket="bucket-requirejs.html">
+<style>
+    @import url(../templates/bucket.css);
+</style>
+<div id="cesiumContainer" class="fullSize"></div>
+<div id="loadingOverlay"><h1>Loading...</h1></div>
+<div id="toolbar"></div>
+<script id="cesium_sandcastle_script">
+function startup(Cesium) {
+    'use strict';
+//Sandcastle_Begin
+var viewer = new Cesium.Viewer('cesiumContainer');
+
+viewer.entities.add({
+    rectangle : {
+        coordinates : Cesium.Rectangle.fromDegrees(-110.0, 20.0, -100.5, 30.0),
+        material : Cesium.Color.RED,
+        zIndex: 1
+    }
+});
+
+viewer.entities.add({
+    rectangle : {
+        coordinates : Cesium.Rectangle.fromDegrees(-112.0, 25.0, -102.5, 35.0),
+        material : '../images/Cesium_Logo_Color.jpg',
+        zIndex: 2
+    }
+});
+
+viewer.entities.add({
+    rectangle : {
+        coordinates : Cesium.Rectangle.fromDegrees(-110.0, 31.0, -100.5, 41.0),
+        material : Cesium.Color.BLUE,
+        zIndex: 3
+    }
+});
+
+viewer.entities.add({
+    rectangle : {
+        coordinates : Cesium.Rectangle.fromDegrees(-99.5, 20.0, -90.0, 30.0),
+        material : '../images/Cesium_Logo_Color.jpg',
+        zIndex: 3
+    }
+});
+
+viewer.entities.add({
+    rectangle : {
+        coordinates : Cesium.Rectangle.fromDegrees(-97.5, 25.0, -88.0, 35.0),
+        material : Cesium.Color.GREEN,
+        zIndex: 2
+    }
+});
+
+viewer.entities.add({
+    rectangle : {
+        coordinates : Cesium.Rectangle.fromDegrees(-99.5, 31.0, -90.0, 41.0),
+        material : Cesium.Color.BLUE,
+        zIndex: 1
+    }
+});
+
+viewer.zoomTo(viewer.entities);
+//Sandcastle_End
+    Sandcastle.finishedLoading();
+}
+if (typeof Cesium !== "undefined") {
+    startup(Cesium);
+} else if (typeof require === "function") {
+    require(["Cesium"], startup);
+}
+</script>
+</body>
+</html>
diff --git a/Apps/Sandcastle/gallery/Z-Indexing Geometry.jpg b/Apps/Sandcastle/gallery/Z-Indexing Geometry.jpg
diff --git a/CHANGES.md b/CHANGES.md
@@ -3,6 +3,10 @@ Change Log
 
 ### 1.46 - 2018-06-01
 
+##### Breaking Changes :mega:
+* Removed `Scene.copyGlobeDepth`. Globe depth will now be copied by default when supported. [#6393](https://github.com/AnalyticalGraphicsInc/cesium/pull/6393)
+* The default `classificationType` for `GroundPrimitive`, `CorridorGraphics`, `EllipseGraphics`, `PolygonGraphics` and `RectangleGraphics` is now `ClassificationType.TERRAIN`.  If you wish the geometry to color both terrain and 3D tiles, pass in the option `classificationType: Cesium.ClassificationType.BOTH`.
+
 ##### Deprecated :hourglass_flowing_sand:
 * The `Scene.fxaa` property has been deprecated and will be removed in Cesium 1.47. Use `Scene.postProcessStages.fxaa.enabled`.
 
@@ -17,6 +21,12 @@ Change Log
    * Added `PostProcessStageComposite` for multi-stage post-processes like depth of field.
    * Added a new Sandcastle label `Post Processing` to showcase the different built-in post-process stages.
  * Added `Rectangle.equalsEpsilon` for comparing the equality of two rectangles [#6533](https://github.com/AnalyticalGraphicsInc/cesium/pull/6533)
+ * Added `zIndex` for ground geometry, including corridor, ellipse, polygon and rectangle entities. [#6362](https://github.com/AnalyticalGraphicsInc/cesium/pull/6362)
+* Added support for materials on terrain entities (entities with unspecified `height`) and `GroundPrimitives`. [#6393](https://github.com/AnalyticalGraphicsInc/cesium/pull/6393)
+  * Only available for `ClassificationType.TERRAIN` at this time. Adding a material to a terrain `Entity` will cause it to behave as if it is `ClassificationType.TERRAIN`.
+  * Requires depth texture support (`WEBGL_depth_texture` or `WEBKIT_WEBGL_depth_texture`), so materials on terrain entities and `GroundPrimitives` are not supported in Internet Explorer.
+  * Best suited for notational patterns and not intended for precisely mapping textures to terrain - for that use case, use `SingleTileImageryProvider`.
+* Added `GroundPrimitive.supportsMaterials` and `Entity.supportsMaterialsforEntitiesOnTerrain`, both of which can be used to check if materials on terrain entities and `GroundPrimitives` is supported. [#6393](https://github.com/AnalyticalGraphicsInc/cesium/pull/6393)
 
 ##### Fixes :wrench:
 * Fixed a bug causing custom TilingScheme classes to not be able to use a GeographicProjection. [#6524](https://github.com/AnalyticalGraphicsInc/cesium/pull/6524)
@@ -28,16 +38,6 @@ Change Log
 * Fixed polygon outline when using `perPositionHeight` and `extrudedHeight`. [#6595](https://github.com/AnalyticalGraphicsInc/cesium/issues/6595)
 * Fixed broken links in documentation of `createTileMapServiceImageryProvider`. [#5818](https://github.com/AnalyticalGraphicsInc/cesium/issues/5818)
 
-##### Breaking Changes :mega:
-* Removed `Scene.copyGlobeDepth`. Globe depth will now be copied by default when supported. [#6393](https://github.com/AnalyticalGraphicsInc/cesium/pull/6393)
-
-##### Additions :tada:
-* Added support for materials on terrain entities (entities with unspecified `height`) and `GroundPrimitives`. [#6393](https://github.com/AnalyticalGraphicsInc/cesium/pull/6393)
-  * Only available for `ClassificationType.TERRAIN` at this time. Adding a material to a terrain `Entity` will cause it to behave as if it is `ClassificationType.TERRAIN`.
-  * Requires depth texture support (`WEBGL_depth_texture` or `WEBKIT_WEBGL_depth_texture`), so materials on terrain entities and `GroundPrimitives` are not supported in Internet Explorer.
-  * Best suited for notational patterns and not intended for precisely mapping textures to terrain - for that use case, use `SingleTileImageryProvider`.
-* Added `GroundPrimitive.supportsMaterials` and `Entity.supportsMaterialsforEntitiesOnTerrain`, both of which can be used to check if materials on terrain entities and `GroundPrimitives` is supported. [#6393](https://github.com/AnalyticalGraphicsInc/cesium/pull/6393)
-
 ### 1.45 - 2018-05-01
 
 ##### Major Announcements :loudspeaker:

diff --git a/Source/Core/oneTimeWarning.js b/Source/Core/oneTimeWarning.js
@@ -47,5 +47,7 @@ define([
 
     oneTimeWarning.geometryOutlines = 'Entity geometry outlines are unsupported on terrain. Outlines will be disabled. To enable outlines, disable geometry terrain clamping by explicitly setting height to 0.';
 
+    oneTimeWarning.geometryZIndex = 'Entity geometry with zIndex are unsupported when height or extrudedHeight are defined.  zIndex will be ignored';
+
     return oneTimeWarning;
 });
diff --git a/Source/DataSources/BoxGeometryUpdater.js b/Source/DataSources/BoxGeometryUpdater.js
@@ -64,6 +64,8 @@ define([
             geometryPropertyName : 'box',
             observedPropertyNames : ['availability', 'position', 'orientation', 'box']
         });
+
+        this._onEntityPropertyChanged(entity, 'box', entity.box, undefined);
     }
 
     if (defined(Object.create)) {

diff --git a/Source/DataSources/CorridorGeometryUpdater.js b/Source/DataSources/CorridorGeometryUpdater.js
@@ -16,6 +16,7 @@ define([
         './ColorMaterialProperty',
         './DynamicGeometryUpdater',
         './GeometryUpdater',
+        './GroundGeometryUpdater',
         './Property'
     ], function(
         Check,
@@ -35,6 +36,7 @@ define([
         ColorMaterialProperty,
         DynamicGeometryUpdater,
         GeometryUpdater,
+        GroundGeometryUpdater,
         Property) {
     'use strict';
 
@@ -61,17 +63,19 @@ define([
      * @param {Scene} scene The scene where visualization is taking place.
      */
     function CorridorGeometryUpdater(entity, scene) {
-        GeometryUpdater.call(this, {
+        GroundGeometryUpdater.call(this, {
             entity : entity,
             scene : scene,
             geometryOptions : new CorridorGeometryOptions(entity),
             geometryPropertyName : 'corridor',
             observedPropertyNames : ['availability', 'corridor']
         });
+
+        this._onEntityPropertyChanged(entity, 'corridor', entity.corridor, undefined);
     }
 
     if (defined(Object.create)) {
-        CorridorGeometryUpdater.prototype = Object.create(GeometryUpdater.prototype);
+        CorridorGeometryUpdater.prototype = Object.create(GroundGeometryUpdater.prototype);
         CorridorGeometryUpdater.prototype.constructor = CorridorGeometryUpdater;
     }
 
@@ -183,6 +187,7 @@ define([
                !Property.isConstant(corridor.width) || //
                !Property.isConstant(corridor.outlineWidth) || //
                !Property.isConstant(corridor.cornerType) || //
+               !Property.isConstant(corridor.zIndex) || //
                (this._onTerrain && !Property.isConstant(this._materialProperty));
     };
 

diff --git a/Source/DataSources/CorridorGraphics.js b/Source/DataSources/CorridorGraphics.js
@@ -39,6 +39,7 @@ define([
      * @param {Property} [options.granularity=Cesium.Math.RADIANS_PER_DEGREE] A numeric Property specifying the distance between each latitude and longitude.
      * @param {Property} [options.shadows=ShadowMode.DISABLED] An enum Property specifying whether the corridor casts or receives shadows from each light source.
      * @param {Property} [options.distanceDisplayCondition] A Property specifying at what distance from the camera that this corridor will be displayed.
+     * @param {ConstantProperty} [options.zIndex] A Property specifying the zIndex of the corridor, used for ordering.  Only has an effect if height and extrudedHeight are undefined, and if the corridor is static.
      *
      * @see Entity
      * @demo {@link https://cesiumjs.org/Cesium/Apps/Sandcastle/index.html?src=Corridor.html|Cesium Sandcastle Corridor Demo}
@@ -74,6 +75,8 @@ define([
         this._distanceDisplayConditionSubscription = undefined;
         this._classificationType = undefined;
         this._classificationTypeSubscription = undefined;
+        this._zIndex = undefined;
+        this._zIndexSubscription = undefined;
         this._definitionChanged = new Event();
 
         this.merge(defaultValue(options, defaultValue.EMPTY_OBJECT));
@@ -207,9 +210,17 @@ define([
          * Gets or sets the {@link ClassificationType} Property specifying whether this corridor will classify terrain, 3D Tiles, or both when on the ground.
          * @memberof CorridorGraphics.prototype
          * @type {Property}
-         * @default ClassificationType.BOTH
+         * @default ClassificationType.TERRAIN
          */
-        classificationType : createPropertyDescriptor('classificationType')
+        classificationType : createPropertyDescriptor('classificationType'),
+
+        /**
+         * Gets or sets the zIndex Property specifying the ordering of the corridor.  Only has an effect if the coridor is static and neither height or exturdedHeight are specified.
+         * @memberof CorridorGraphics.prototype
+         * @type {ConstantProperty}
+         * @default 0
+         */
+        zIndex: createPropertyDescriptor('zIndex')
     });
 
     /**
@@ -237,6 +248,7 @@ define([
         result.shadows = this.shadows;
         result.distanceDisplayCondition = this.distanceDisplayCondition;
         result.classificationType = this.classificationType;
+        result.zIndex = this.zIndex;
         return result;
     };
 
@@ -268,6 +280,7 @@ define([
         this.shadows = defaultValue(this.shadows, source.shadows);
         this.distanceDisplayCondition = defaultValue(this.distanceDisplayCondition, source.distanceDisplayCondition);
         this.classificationType = defaultValue(this.classificationType, source.classificationType);
+        this.zIndex = defaultValue(this.zIndex, source.zIndex);
     };
 
     return CorridorGraphics;

diff --git a/Source/DataSources/CylinderGeometryUpdater.js b/Source/DataSources/CylinderGeometryUpdater.js
@@ -68,6 +68,8 @@ define([
             geometryPropertyName: 'cylinder',
             observedPropertyNames: ['availability', 'position', 'orientation', 'cylinder']
         });
+
+        this._onEntityPropertyChanged(entity, 'cylinder', entity.cylinder, undefined);
     }
 
     if (defined(Object.create)) {

diff --git a/Source/DataSources/DataSourceDisplay.js b/Source/DataSources/DataSourceDisplay.js
@@ -7,6 +7,7 @@ define([
         '../Core/destroyObject',
         '../Core/EventHelper',
         '../Scene/GroundPrimitive',
+        '../Scene/OrderedGroundPrimitiveCollection',
         '../Scene/PrimitiveCollection',
         './BillboardVisualizer',
         './BoundingSphereState',
@@ -26,6 +27,7 @@ define([
         destroyObject,
         EventHelper,
         GroundPrimitive,
+        OrderedGroundPrimitiveCollection,
         PrimitiveCollection,
         BillboardVisualizer,
         BoundingSphereState,
@@ -362,7 +364,7 @@ define([
         var displayGroundPrimitives = this._groundPrimitives;
 
         var primitives = displayPrimitives.add(new PrimitiveCollection());
-        var groundPrimitives = displayGroundPrimitives.add(new PrimitiveCollection());
+        var groundPrimitives = displayGroundPrimitives.add(new OrderedGroundPrimitiveCollection());
 
         dataSource._primitives = primitives;
         dataSource._groundPrimitives = groundPrimitives;

diff --git a/Source/DataSources/DynamicGeometryBatch.js b/Source/DataSources/DynamicGeometryBatch.js
@@ -11,14 +11,14 @@ define([
     /**
      * @private
      */
-    function DynamicGeometryBatch(primitives, groundPrimitives) {
+    function DynamicGeometryBatch(primitives, orderedGroundPrimitives) {
         this._primitives = primitives;
-        this._groundPrimitives = groundPrimitives;
+        this._orderedGroundPrimitives = orderedGroundPrimitives;
         this._dynamicUpdaters = new AssociativeArray();
     }
 
     DynamicGeometryBatch.prototype.add = function(time, updater) {
-        this._dynamicUpdaters.set(updater.id, updater.createDynamicUpdater(this._primitives, this._groundPrimitives));
+        this._dynamicUpdaters.set(updater.id, updater.createDynamicUpdater(this._primitives, this._orderedGroundPrimitives));
     };
 
     DynamicGeometryBatch.prototype.remove = function(updater) {

diff --git a/Source/DataSources/DynamicGeometryUpdater.js b/Source/DataSources/DynamicGeometryUpdater.js
@@ -41,15 +41,15 @@ define([
      * @constructor
      * @private
      */
-    function DynamicGeometryUpdater(geometryUpdater, primitives, groundPrimitives) {
+    function DynamicGeometryUpdater(geometryUpdater, primitives, orderedGroundPrimitives) {
         //>>includeStart('debug', pragmas.debug);
         Check.defined('geometryUpdater', geometryUpdater);
         Check.defined('primitives', primitives);
-        Check.defined('groundPrimitives', groundPrimitives);
+        Check.defined('orderedGroundPrimitives', orderedGroundPrimitives);
         //>>includeEnd('debug');
 
         this._primitives = primitives;
-        this._groundPrimitives = groundPrimitives;
+        this._orderedGroundPrimitives = orderedGroundPrimitives;
         this._primitive = undefined;
         this._outlinePrimitive = undefined;
         this._geometryUpdater = geometryUpdater;
@@ -80,9 +80,9 @@ define([
         var onTerrain = geometryUpdater._onTerrain;
 
         var primitives = this._primitives;
-        var groundPrimitives = this._groundPrimitives;
+        var orderedGroundPrimitives = this._orderedGroundPrimitives;
         if (onTerrain) {
-            groundPrimitives.removeAndDestroy(this._primitive);
+            orderedGroundPrimitives.remove(this._primitive);
         } else {
             primitives.removeAndDestroy(this._primitive);
             primitives.removeAndDestroy(this._outlinePrimitive);
@@ -120,12 +120,12 @@ define([
 
             if (onTerrain) {
                 options.vertexFormat = PerInstanceColorAppearance.VERTEX_FORMAT;
-                this._primitive = groundPrimitives.add(new GroundPrimitive({
+                this._primitive = orderedGroundPrimitives.add(new GroundPrimitive({
                     geometryInstances : this._geometryUpdater.createFillGeometryInstance(time),
                     appearance : appearance,
                     asynchronous : false,
                     shadows : shadows
-                }));
+                }), Property.getValueOrUndefined(this._geometryUpdater.zIndex, time));
             } else {
                 options.vertexFormat = appearance.vertexFormat;
 
@@ -230,9 +230,9 @@ define([
      */
     DynamicGeometryUpdater.prototype.destroy = function() {
         var primitives = this._primitives;
-        var groundPrimitives = this._groundPrimitives;
+        var orderedGroundPrimitives = this._orderedGroundPrimitives;
         if (this._geometryUpdater._onTerrain) {
-            groundPrimitives.removeAndDestroy(this._primitive);
+            orderedGroundPrimitives.remove(this._primitive);
         } else {
             primitives.removeAndDestroy(this._primitive);
         }