support for polylines on terrain via entity API

Apps/Sandcastle/gallery/Ground Clamping.html

@@ -218,6 +218,36 @@
             viewer.camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
         });
     }
+}, {
+    text : 'Draw polyline on terrain',
+    onselect : function() {
+
+        if (!Cesium.Entity.supportsPolylinesOnTerrain(viewer.scene)) {
+            console.log('Polylines on terrain are not supported on this platform');
+        }
+
+        viewer.entities.add({
+            polyline : {
+                positions : Cesium.Cartesian3.fromDegreesArray([
+                    86.953793, 27.928257,
+                    86.953793, 27.988257,
+                    86.896497, 27.988257
+                ]),
+                clampToGround : true,
+                width : 5,
+                material : new Cesium.PolylineOutlineMaterialProperty({
+                    color : Cesium.Color.ORANGE,
+                    outlineWidth : 2,
+                    outlineColor : Cesium.Color.BLACK
+                })
+            }
+        });
+
+        var target = new Cesium.Cartesian3(300770.50872389384, 5634912.131394585, 2978152.2865545116);
+        var offset = new Cesium.Cartesian3(6344.974098678562, -793.3419798081741, 2499.9508860763162);
+        viewer.camera.lookAt(target, offset);
+        viewer.camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
+    }
 }], 'zoomButtons');
 
 Sandcastle.reset = function () {

Apps/Sandcastle/gallery/Polyline.html

@@ -30,12 +30,13 @@
 var viewer = new Cesium.Viewer('cesiumContainer');
 
 var redLine = viewer.entities.add({
-    name : 'Red line on the surface',
+    name : 'Red line on terrain',
     polyline : {
         positions : Cesium.Cartesian3.fromDegreesArray([-75, 35,
                                                         -125, 35]),
         width : 5,
-        material : Cesium.Color.RED
+        material : Cesium.Color.RED,
+        clampToGround : true
     }
 });
 

Apps/Sandcastle/gallery/Z-Indexing Geometry.html

@@ -32,6 +32,7 @@
 var viewer = new Cesium.Viewer('cesiumContainer');
 
 viewer.entities.add({
+    id : 'Red rectangle, zIndex 1',
     rectangle : {
         coordinates : Cesium.Rectangle.fromDegrees(-110.0, 20.0, -100.5, 30.0),
         material : Cesium.Color.RED,
@@ -40,6 +41,7 @@
 });
 
 viewer.entities.add({
+    id : 'Textured rectangle, zIndex 2',
     rectangle : {
         coordinates : Cesium.Rectangle.fromDegrees(-112.0, 25.0, -102.5, 35.0),
         material : '../images/Cesium_Logo_Color.jpg',
@@ -48,6 +50,7 @@
 });
 
 viewer.entities.add({
+    id : 'Blue rectangle, zIndex 3',
     rectangle : {
         coordinates : Cesium.Rectangle.fromDegrees(-110.0, 31.0, -100.5, 41.0),
         material : Cesium.Color.BLUE,
@@ -56,6 +59,7 @@
 });
 
 viewer.entities.add({
+    id : 'Textured rectangle, zIndex 3',
     rectangle : {
         coordinates : Cesium.Rectangle.fromDegrees(-99.5, 20.0, -90.0, 30.0),
         material : '../images/Cesium_Logo_Color.jpg',
@@ -64,6 +68,7 @@
 });
 
 viewer.entities.add({
+    id : 'Green rectangle, zIndex 2',
     rectangle : {
         coordinates : Cesium.Rectangle.fromDegrees(-97.5, 25.0, -88.0, 35.0),
         material : Cesium.Color.GREEN,
@@ -72,13 +77,39 @@
 });
 
 viewer.entities.add({
+    id : 'Blue rectangle, zIndex 1',
     rectangle : {
         coordinates : Cesium.Rectangle.fromDegrees(-99.5, 31.0, -90.0, 41.0),
         material : Cesium.Color.BLUE,
         zIndex: 1
     }
 });
 
+if (!Cesium.Entity.supportsPolylinesOnTerrain(viewer.scene)) {
+    console.log('Polylines on terrain are not supported on this platform, Z-index will be ignored');
+}
+
+if (!Cesium.Entity.supportsMaterialsforEntitiesOnTerrain(viewer.scene)) {
+    console.log('Textured materials on terrain polygons are not supported on this platform, Z-index will be ignored');
+}
+
+viewer.entities.add({
+    id : 'Polyline, zIndex 2',
+    polyline : {
+        positions : Cesium.Cartesian3.fromDegreesArray([
+            -120.0, 22.0,
+            -80.0, 22.0
+        ]),
+        width : 8.0,
+        material : new Cesium.PolylineGlowMaterialProperty({
+            glowPower : 0.2,
+            color : Cesium.Color.BLUE
+        }),
+        zIndex: 2,
+        clampToGround : true
+    }
+});
+
 viewer.zoomTo(viewer.entities);
 //Sandcastle_End
     Sandcastle.finishedLoading();

CHANGES.md

@@ -10,7 +10,13 @@ Change Log
 ##### Additions :tada:
 * `PostProcessStage` has a `selectedFeatures` property which is an array of primitives used for selectively applying a post-process stage. In the fragment shader, use the function `bool czm_selected(vec2 textureCoordinates` to determine whether or not the stage should be applied at that fragment.
    * The black-and-white and silhouette stages have per-feature support.
+* Added support for Polylines on Terrain via the `Entity` API [#6689](https://github.com/AnalyticalGraphicsInc/cesium/pull/6689)
+   * Use the `clampToGround` option for `PolylineGraphics`.
+   * Requires depth texture support (`WEBGL_depth_texture` or `WEBKIT_WEBGL_depth_texture`), otherwise `clampToGround` will be ignored.
+   * Added `Entity.supportsPolylinesOnTerrain` for checking if the current platform supports `clampToGround`.
 * Added `GroundPolylinePrimitive` and `GroundPolylineGeometry` for rendering polylines on terrain via the `Primitive` API. [#6615](https://github.com/AnalyticalGraphicsInc/cesium/pull/6615)
+   * Requires depth texture support (`WEBGL_depth_texture` or `WEBKIT_WEBGL_depth_texture`).
+   * Use `GroundPolylinePrimitive.isSupported` to check for support.
 
 ##### Fixes :wrench:
 * Fixed a bug causing crashes with custom vertex attributes on `Geometry` crossing the IDL. Attributes will be barycentrically interpolated. [#6644](https://github.com/AnalyticalGraphicsInc/cesium/pull/6644)

Source/DataSources/DataSourceDisplay.js

@@ -130,7 +130,7 @@ define([
                 new ModelVisualizer(scene, entities),
                 new PointVisualizer(entityCluster, entities),
                 new PathVisualizer(scene, entities),
-                new PolylineVisualizer(scene, entities)];
+                new PolylineVisualizer(scene, entities, dataSource._groundPrimitives)];
     };
 
     defineProperties(DataSourceDisplay.prototype, {

Source/DataSources/Entity.js

@@ -12,6 +12,7 @@ define([
         '../Core/Quaternion',
         '../Core/Transforms',
         '../Scene/GroundPrimitive',
+        '../Scene/GroundPolylinePrimitive',
         './BillboardGraphics',
         './BoxGraphics',
         './ConstantPositionProperty',
@@ -47,6 +48,7 @@ define([
         Quaternion,
         Transforms,
         GroundPrimitive,
+        GroundPolylinePrimitive,
         BillboardGraphics,
         BoxGraphics,
         ConstantPositionProperty,
@@ -631,5 +633,17 @@ define([
         return GroundPrimitive.supportsMaterials(scene);
     };
 
+    /**
+     * Checks if the given Scene supports polylines clamped to the ground..
+     * If this feature is not supported, Entities with PolylineGraphics will be rendered with vertices at
+     * the provided heights and using the `followSurface` parameter instead of clamped to the ground.
+     *
+     * @param {Scene} scene The current scene.
+     * @returns {Boolean} Whether or not the current scene supports Polylines on Terrain.
+     */
+    Entity.supportsPolylinesOnTerrain = function(scene) {
+        return GroundPolylinePrimitive.isSupported(scene);
+    };
+
     return Entity;
 });