remove unneeded options, add example doc for GroundPolylinePrimitive,…

… add simple Sandcastle example for Ground Polyline materials
CesiumGS · Jun 12, 2018 · 403e500 · 403e500
1 parent 163d254
commit 403e500
Show file tree

Hide file tree

Showing 4 changed files with 146 additions and 55 deletions.
diff --git a/Apps/Sandcastle/gallery/development/Ground Polyline Material.html b/Apps/Sandcastle/gallery/development/Ground Polyline Material.html
@@ -0,0 +1,96 @@
+<!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 Ground Polylines with different material appearances.">
+    <meta name="cesium-sandcastle-labels" content="Development">
+    <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">
+    require.config({
+        baseUrl : '../../../Source',
+        waitSeconds : 60
+    });
+    </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', {
+    terrainProvider: Cesium.createWorldTerrain()
+});
+var scene = viewer.scene;
+
+// Polyline Glow
+scene.groundPrimitives.add(new Cesium.GroundPolylinePrimitive({
+    geometryInstances : new Cesium.GeometryInstance({
+        geometry : new Cesium.GroundPolylineGeometry({
+            positions : Cesium.Cartesian3.fromDegreesArray([
+                -122.2558, 46.1955,
+                -122.1058, 46.1955
+            ]),
+            width : 10.0
+        })
+    }),
+    appearance : new Cesium.PolylineMaterialAppearance({
+        material : Cesium.Material.fromType(Cesium.Material.PolylineGlowType)
+    })
+}));
+
+// Polyline Dash
+scene.groundPrimitives.add(new Cesium.GroundPolylinePrimitive({
+    geometryInstances : new Cesium.GeometryInstance({
+        geometry : new Cesium.GroundPolylineGeometry({
+            positions : Cesium.Cartesian3.fromDegreesArray([
+                -122.2558, 46.1975,
+                -122.1058, 46.1975
+            ]),
+            width : 10.0
+        })
+    }),
+    appearance : new Cesium.PolylineMaterialAppearance({
+        material : Cesium.Material.fromType(Cesium.Material.PolylineDashType)
+    })
+}));
+
+// Polyline Outline
+scene.groundPrimitives.add(new Cesium.GroundPolylinePrimitive({
+    geometryInstances : new Cesium.GeometryInstance({
+        geometry : new Cesium.GroundPolylineGeometry({
+            positions : Cesium.Cartesian3.fromDegreesArray([
+                -122.2558, 46.1995,
+                -122.1058, 46.1995
+            ]),
+            width : 10.0
+        })
+    }),
+    appearance : new Cesium.PolylineMaterialAppearance({
+        material : Cesium.Material.fromType(Cesium.Material.PolylineOutlineType)
+    })
+}));
+
+viewer.camera.lookAt(Cesium.Cartesian3.fromDegrees(-122.2058, 46.1955, 1000.0), new Cesium.Cartesian3(5000.0, 5000.0, 5000.0));
+viewer.camera.lookAtTransform(Cesium.Matrix4.IDENTITY);
+
+//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/development/Ground Polyline Material.jpg b/Apps/Sandcastle/gallery/development/Ground Polyline Material.jpg
diff --git a/Source/Scene/GroundPolylinePrimitive.js b/Source/Scene/GroundPolylinePrimitive.js
@@ -1,6 +1,5 @@
 define([
         '../Core/ApproximateTerrainHeights',
-        '../Core/Check',
         '../Core/ComponentDatatype',
         '../Core/defaultValue',
         '../Core/defined',
@@ -9,9 +8,7 @@ define([
         '../Core/DeveloperError',
         '../Core/GeometryInstance',
         '../Core/GeometryInstanceAttribute',
-        '../Core/GroundPolylineGeometry',
         '../Core/isArray',
-        '../Core/Matrix4',
         '../Shaders/PolylineShadowVolumeVS',
         '../Shaders/PolylineShadowVolumeFS',
         '../Shaders/PolylineShadowVolumeMorphVS',
@@ -24,14 +21,12 @@ define([
         '../ThirdParty/when',
         './BlendingState',
         './CullFace',
-        './Material',
         './PolylineColorAppearance',
         './PolylineMaterialAppearance',
         './Primitive',
         './SceneMode'
     ], function(
         ApproximateTerrainHeights,
-        Check,
         ComponentDatatype,
         defaultValue,
         defined,
@@ -40,9 +35,7 @@ define([
         DeveloperError,
         GeometryInstance,
         GeometryInstanceAttribute,
-        GroundPolylineGeometry,
         isArray,
-        Matrix4,
         PolylineShadowVolumeVS,
         PolylineShadowVolumeFS,
         PolylineShadowVolumeMorphVS,
@@ -55,7 +48,6 @@ define([
         when,
         BlendingState,
         CullFace,
-        Material,
         PolylineColorAppearance,
         PolylineMaterialAppearance,
         Primitive,
@@ -66,22 +58,65 @@ define([
      * A GroundPolylinePrimitive represents a polyline draped over the terrain in the {@link Scene}.
      * <p>
      *
-     * Only to be used with GeometryInstances containing {@link GroundPolylineGeometry}
+     * Only to be used with GeometryInstances containing {@link GroundPolylineGeometry}.
      *
      * @param {Object} [options] Object with the following properties:
      * @param {Array|GeometryInstance} [options.geometryInstances] GeometryInstances containing GroundPolylineGeometry
      * @param {Appearance} [options.appearance] The Appearance used to render the polyline. Defaults to a white color {@link Material} on a {@link PolylineMaterialAppearance}.
      * @param {Boolean} [options.show=true] Determines if this primitive will be shown.
-     * @param {Boolean} [options.vertexCacheOptimize=false] When <code>true</code>, geometry vertices are optimized for the pre and post-vertex-shader caches.
      * @param {Boolean} [options.interleave=false] When <code>true</code>, geometry vertex attributes are interleaved, which can slightly improve rendering performance but increases load time.
-     * @param {Boolean} [options.compressVertices=true] When <code>true</code>, the geometry vertices are compressed, which will save memory.
      * @param {Boolean} [options.releaseGeometryInstances=true] When <code>true</code>, the primitive does not keep a reference to the input <code>geometryInstances</code> to save memory.
      * @param {Boolean} [options.allowPicking=true] When <code>true</code>, each geometry instance will only be pickable with {@link Scene#pick}.  When <code>false</code>, GPU memory is saved.
      * @param {Boolean} [options.asynchronous=true] Determines if the primitive will be created asynchronously or block until ready. If false initializeTerrainHeights() must be called first.
      * @param {Boolean} [options.debugShowBoundingVolume=false] For debugging only. Determines if this primitive's commands' bounding spheres are shown.
-     * @param {Boolean} [options.debugShowShadowVolume=false] For debugging only. Determines if the shadow volume for each geometry in the primitive is drawn. Must be <code>true</code> on
-     *                  creation for the volumes to be created before the geometry is released or options.releaseGeometryInstance must be <code>false</code>.
+     * @param {Boolean} [options.debugShowShadowVolume=false] For debugging only. Determines if the shadow volume for each geometry in the primitive is drawn. Must be <code>true</code> on creation to have effect.
      *
+     * @example
+     * // 1. Draw a polyline on terrain with a basic color material
+     *
+     * var instance = new Cesium.GeometryInstance({
+     *   geometry : new Cesium.GroundPolylineGeometry({
+     *      positions : Cesium.Cartesian3.fromDegreesArray([
+     *          -112.1340164450331, 36.05494287836128,
+     *          -112.08821010582645, 36.097804071380715
+     *      ]),
+     *      width : 4.0
+     *   }),
+     *   id : 'object returned when this instance is picked and to get/set per-instance attributes'
+     * });
+     *
+     * scene.groundPrimitives.add(new Cesium.GroundPolylinePrimitive({
+     *   geometryInstances : instance,
+     *   appearance : new Cesium.PolylineMaterialAppearance({
+     *     material : Cesium.Material.fromType('Color')
+     *   })
+     * }));
+     *
+     * // 2. Draw a looped polyline on terrain with per-instance color and a distance display condition.
+     * // Distance display conditions for polylines on terrain are based on an approximate terrain height
+     * // instead of true terrain height.
+     *
+     * var instance = new Cesium.GeometryInstance({
+     *   geometry : new Cesium.GroundPolylineGeometry({
+     *      positions : Cesium.Cartesian3.fromDegreesArray([
+     *          -112.1340164450331, 36.05494287836128,
+     *          -112.08821010582645, 36.097804071380715,
+     *          -112.13296079730024, 36.168769146801104
+     *      ]),
+     *      loop : true,
+     *      width : 4.0
+     *   }),
+     *   attributes : {
+     *      color : Cesium.ColorGeometryInstanceAttribute.fromColor(Cesium.Color.fromCssColorString('green').withAlpha(0.7)),
+            distanceDisplayCondition : new Cesium.DistanceDisplayConditionGeometryInstanceAttribute(1000, 30000)
+     *   },
+     *   id : 'object returned when this instance is picked and to get/set per-instance attributes'
+     * });
+     *
+     * scene.groundPrimitives.add(new Cesium.GroundPolylinePrimitive({
+     *   geometryInstances : instance,
+     *   appearance : Cesium.PolylineColorAppearance()
+     * }));
      */
     function GroundPolylinePrimitive(options) {
         options = defaultValue(options, defaultValue.EMPTY_OBJECT);
@@ -146,12 +181,12 @@ define([
         this._primitiveOptions = {
             geometryInstances : undefined,
             appearance : undefined,
-            vertexCacheOptimize : defaultValue(options.vertexCacheOptimize, false),
+            vertexCacheOptimize : false,
             interleave : defaultValue(options.interleave, false),
             releaseGeometryInstances : defaultValue(options.releaseGeometryInstances, true),
             allowPicking : defaultValue(options.allowPicking, true),
             asynchronous : defaultValue(options.asynchronous, true),
-            compressVertices : defaultValue(options.compressVertices, true),
+            compressVertices : false,
             _createShaderProgramFunction : undefined,
             _createCommandsFunction : undefined,
             _updateAndQueueCommandsFunction : undefined
@@ -191,22 +226,6 @@ define([
     }
 
     defineProperties(GroundPolylinePrimitive.prototype, {
-        /**
-         * When <code>true</code>, geometry vertices are optimized for the pre and post-vertex-shader caches.
-         *
-         * @memberof GroundPolylinePrimitive.prototype
-         *
-         * @type {Boolean}
-         * @readonly
-         *
-         * @default true
-         */
-        vertexCacheOptimize : {
-            get : function() {
-                return this._primitiveOptions.vertexCacheOptimize;
-            }
-        },
-
         /**
          * Determines if geometry vertex attributes are interleaved, which can slightly improve rendering performance.
          *
@@ -271,22 +290,6 @@ define([
             }
         },
 
-        /**
-         * When <code>true</code>, geometry vertices are compressed, which will save memory.
-         *
-         * @memberof GroundPolylinePrimitive.prototype
-         *
-         * @type {Boolean}
-         * @readonly
-         *
-         * @default true
-         */
-        compressVertices : {
-            get : function() {
-                return this._primitiveOptions.compressVertices;
-            }
-        },
-
         /**
          * Determines if the primitive is complete and ready to render.  If this property is
          * true, the primitive will be rendered the next time that {@link GroundPolylinePrimitive#update}

diff --git a/Specs/Scene/GroundPolylinePrimitiveSpec.js b/Specs/Scene/GroundPolylinePrimitiveSpec.js
@@ -1,6 +1,5 @@
 defineSuite([
         'Scene/GroundPolylinePrimitive',
-        'Core/ApproximateTerrainHeights',
         'Core/Color',
         'Core/ColorGeometryInstanceAttribute',
         'Core/Cartesian3',
@@ -21,7 +20,6 @@ defineSuite([
         'Specs/pollToPromise'
     ], function(
         GroundPolylinePrimitive,
-        ApproximateTerrainHeights,
         Color,
         ColorGeometryInstanceAttribute,
         Cartesian3,
@@ -160,9 +158,7 @@ defineSuite([
         expect(groundPolylinePrimitive.geometryInstances).not.toBeDefined();
         expect(groundPolylinePrimitive.appearance instanceof PolylineMaterialAppearance).toBe(true);
         expect(groundPolylinePrimitive.show).toEqual(true);
-        expect(groundPolylinePrimitive.vertexCacheOptimize).toEqual(false);
         expect(groundPolylinePrimitive.interleave).toEqual(false);
-        expect(groundPolylinePrimitive.compressVertices).toEqual(true);
         expect(groundPolylinePrimitive.releaseGeometryInstances).toEqual(true);
         expect(groundPolylinePrimitive.allowPicking).toEqual(true);
         expect(groundPolylinePrimitive.asynchronous).toEqual(true);
@@ -176,9 +172,7 @@ defineSuite([
         groundPolylinePrimitive = new GroundPolylinePrimitive({
             geometryInstances : geometryInstances,
             show : false,
-            vertexCacheOptimize : true,
             interleave : true,
-            compressVertices : false,
             releaseGeometryInstances : false,
             allowPicking : false,
             asynchronous : false,
@@ -188,9 +182,7 @@ defineSuite([
 
         expect(groundPolylinePrimitive.geometryInstances).toEqual(geometryInstances);
         expect(groundPolylinePrimitive.show).toEqual(false);
-        expect(groundPolylinePrimitive.vertexCacheOptimize).toEqual(true);
         expect(groundPolylinePrimitive.interleave).toEqual(true);
-        expect(groundPolylinePrimitive.compressVertices).toEqual(false);
         expect(groundPolylinePrimitive.releaseGeometryInstances).toEqual(false);
         expect(groundPolylinePrimitive.allowPicking).toEqual(false);
         expect(groundPolylinePrimitive.asynchronous).toEqual(false);