Deprecate Globe.terrainExaggeration

Specs/createGlobe.js

@@ -14,8 +14,6 @@ function createGlobe(ellipsoid) {
     getHeight: function () {
       return 0.0;
     },
-    terrainExaggeration: 1.0,
-    terrainExaggerationRelativeHeight: 0.0,
     _surface: {},
     imageryLayersUpdatedEvent: new Event(),
     _terrainProvider: undefined,

packages/engine/Source/Scene/Globe.js

@@ -28,6 +28,7 @@ import ImageryLayerCollection from "./ImageryLayerCollection.js";
 import QuadtreePrimitive from "./QuadtreePrimitive.js";
 import SceneMode from "./SceneMode.js";
 import ShadowMode from "./ShadowMode.js";
+import deprecationWarning from "../Core/deprecationWarning.js";
 
 /**
  * The globe rendered in the scene, including its terrain ({@link Globe#terrainProvider})
@@ -340,25 +341,9 @@ function Globe(ellipsoid) {
    */
   this.atmosphereBrightnessShift = 0.0;
 
-  /**
-   * A scalar used to exaggerate the terrain. Defaults to <code>1.0</code> (no exaggeration).
-   * A value of <code>2.0</code> scales the terrain by 2x.
-   * A value of <code>0.0</code> makes the terrain completely flat.
-   * Note that terrain exaggeration will not modify any other primitive as they are positioned relative to the ellipsoid.
-   * @type {number}
-   * @default 1.0
-   */
-  this.terrainExaggeration = 1.0;
-
-  /**
-   * The height from which terrain is exaggerated. Defaults to <code>0.0</code> (scaled relative to ellipsoid surface).
-   * Terrain that is above this height will scale upwards and terrain that is below this height will scale downwards.
-   * Note that terrain exaggeration will not modify any other primitive as they are positioned relative to the ellipsoid.
-   * If {@link Globe#terrainExaggeration} is <code>1.0</code> this value will have no effect.
-   * @type {number}
-   * @default 0.0
-   */
-  this.terrainExaggerationRelativeHeight = 0.0;
+  this._terrainExaggerationChanged = false;
+  this._terrainExaggeration = 1.0;
+  this._terrainExaggerationRelativeHeight = 0.0;
 
   /**
    * Whether to show terrain skirts. Terrain skirts are geometry extending downwards from a tile's edges used to hide seams between neighboring tiles.
@@ -538,6 +523,68 @@ Object.defineProperties(Globe.prototype, {
       return this._terrainProviderChanged;
     },
   },
+  /**
+   * A scalar used to exaggerate the terrain. Defaults to <code>1.0</code> (no exaggeration).
+   * A value of <code>2.0</code> scales the terrain by 2x.
+   * A value of <code>0.0</code> makes the terrain completely flat.
+   * Note that terrain exaggeration will not modify any other primitive as they are positioned relative to the ellipsoid.
+   *
+   * @memberof Globe.prototype
+   * @type {number}
+   * @default 1.0
+   *
+   * @deprecated
+   */
+  terrainExaggeration: {
+    get: function () {
+      deprecationWarning(
+        "Globe.terrainExaggeration",
+        "Globe.terrainExaggeration was deprecated in CesiumJS 1.113.  It will be removed in CesiumJS 1.116. Use Scene.verticalExaggeration instead."
+      );
+      return this._terrainExaggeration;
+    },
+    set: function (value) {
+      deprecationWarning(
+        "Globe.terrainExaggeration",
+        "Globe.terrainExaggeration was deprecated in CesiumJS 1.113.  It will be removed in CesiumJS 1.116. Use Scene.verticalExaggeration instead."
+      );
+      if (value !== this._terrainExaggeration) {
+        this._terrainExaggeration = value;
+        this._terrainExaggerationChanged = true;
+      }
+    },
+  },
+  /**
+   * The height from which terrain is exaggerated. Defaults to <code>0.0</code> (scaled relative to ellipsoid surface).
+   * Terrain that is above this height will scale upwards and terrain that is below this height will scale downwards.
+   * Note that terrain exaggeration will not modify any other primitive as they are positioned relative to the ellipsoid.
+   * If {@link Globe#terrainExaggeration} is <code>1.0</code> this value will have no effect.
+   *
+   * @memberof Globe.prototype
+   * @type {number}
+   * @default 0.0
+   *
+   * @deprecated
+   */
+  terrainExaggerationRelativeHeight: {
+    get: function () {
+      deprecationWarning(
+        "Globe.terrainExaggerationRelativeHeight",
+        "Globe.terrainExaggerationRelativeHeight was deprecated in CesiumJS 1.113.  It will be removed in CesiumJS 1.116. Use Scene.verticalExaggerationRelativeHeight instead."
+      );
+      return this._terrainExaggerationRelativeHeight;
+    },
+    set: function (value) {
+      deprecationWarning(
+        "Globe.terrainExaggerationRelativeHeight",
+        "Globe.terrainExaggerationRelativeHeight was deprecated in CesiumJS 1.113.  It will be removed in CesiumJS 1.116. Use Scene.verticalExaggerationRelativeHeight instead."
+      );
+      if (value !== this._terrainExaggerationRelativeHeight) {
+        this._terrainExaggerationRelativeHeight = value;
+        this._terrainExaggerationChanged = true;
+      }
+    },
+  },
   /**
    * Gets an event that's raised when the length of the tile load queue has changed since the last render frame.  When the load queue is empty,
    * all terrain and imagery for the current view have been loaded.  The event passes the new length of the tile load queue.

packages/engine/Source/Scene/Scene.js

@@ -1900,17 +1900,14 @@ Scene.prototype.updateFrameState = function () {
 
   frameState.verticalExaggeration = this.verticalExaggeration;
   frameState.verticalExaggerationRelativeHeight = this.verticalExaggerationRelativeHeight;
-  if (defined(this.globe)) {
-    if (this.verticalExaggeration !== 1.0) {
-      // Update terrain exaggeration to match the rest of the scene
-      this.globe.terrainExaggeration = this.verticalExaggeration;
-      this.globe.terrainExaggerationRelativeHeight = this.verticalExaggerationRelativeHeight;
-    } else {
-      // The new .verticalExaggeration was not set.
-      // Use the old globe.terrainExaggeration
-      frameState.verticalExaggeration = this.globe.terrainExaggeration;
-      frameState.verticalExaggerationRelativeHeight = this.globe.terrainExaggerationRelativeHeight;
-    }
+  const { globe } = this;
+  if (defined(globe) && globe._terrainExaggerationChanged) {
+    // Honor a user-set value for the old deprecated globe.terrainExaggeration.
+    // This can be removed when Globe.terrainExaggeration is removed.
+    frameState.verticalExaggeration = globe._terrainExaggeration;
+    frameState.verticalExaggerationRelativeHeight =
+      globe._terrainExaggerationRelativeHeight;
+    globe._terrainExaggerationChanged = false;
   }
 
   if (

packages/engine/Source/Scene/ScreenSpaceCameraController.js

@@ -2948,9 +2948,7 @@ const scratchPreviousDirection = new Cartesian3();
  */
 ScreenSpaceCameraController.prototype.update = function () {
   const scene = this._scene;
-  const camera = scene.camera;
-  const globe = scene.globe;
-  const mode = scene.mode;
+  const { camera, globe, mode } = scene;
 
   if (!Matrix4.equals(camera.transform, Matrix4.IDENTITY)) {
     this._globe = undefined;
@@ -2962,26 +2960,21 @@ ScreenSpaceCameraController.prototype.update = function () {
       : scene.mapProjection.ellipsoid;
   }
 
-  const exaggeration = defined(this._globe)
-    ? this._globe.terrainExaggeration
-    : 1.0;
-  const exaggerationRelativeHeight = defined(this._globe)
-    ? this._globe.terrainExaggerationRelativeHeight
-    : 0.0;
+  const { verticalExaggeration, verticalExaggerationRelativeHeight } = scene;
   this._minimumCollisionTerrainHeight = VerticalExaggeration.getHeight(
     this.minimumCollisionTerrainHeight,
-    exaggeration,
-    exaggerationRelativeHeight
+    verticalExaggeration,
+    verticalExaggerationRelativeHeight
   );
   this._minimumPickingTerrainHeight = VerticalExaggeration.getHeight(
     this.minimumPickingTerrainHeight,
-    exaggeration,
-    exaggerationRelativeHeight
+    verticalExaggeration,
+    verticalExaggerationRelativeHeight
   );
   this._minimumTrackBallHeight = VerticalExaggeration.getHeight(
     this.minimumTrackBallHeight,
-    exaggeration,
-    exaggerationRelativeHeight
+    verticalExaggeration,
+    verticalExaggerationRelativeHeight
   );
 
   this._cameraUnderground = scene.cameraUnderground && defined(this._globe);

packages/engine/Specs/DataSources/EntityClusterSpec.js

@@ -29,8 +29,6 @@ describe(
       });
       scene.globe = {
         ellipsoid: Ellipsoid.WGS84,
-        terrainExaggeration: 1.0,
-        terrainExaggerationRelativeHeight: 0.0,
         _surface: {
           tileProvider: {},
           _tileLoadQueueHigh: [],

packages/engine/Specs/Scene/GlobeSurfaceTileProviderSpec.js

@@ -1441,6 +1441,64 @@ describe(
         });
       });
     });
+
+    it("Detects change in vertical exaggeration", function () {
+      switchViewMode(
+        SceneMode.SCENE3D,
+        new GeographicProjection(Ellipsoid.WGS84)
+      );
+      scene.camera.flyHome(0.0);
+
+      scene.verticalExaggeration = 1.0;
+      scene.verticalExaggerationRelativeHeight = 0.0;
+
+      return updateUntilDone(scene.globe).then(function () {
+        forEachRenderedTile(scene.globe._surface, 1, undefined, function (
+          tile
+        ) {
+          const surfaceTile = tile.data;
+          const encoding = surfaceTile.mesh.encoding;
+          const boundingSphere = surfaceTile.tileBoundingRegion.boundingSphere;
+          expect(encoding.exaggeration).toEqual(1.0);
+          expect(encoding.hasGeodeticSurfaceNormals).toEqual(false);
+          expect(boundingSphere.radius).toBeLessThan(7000000.0);
+        });
+
+        scene.verticalExaggeration = 2.0;
+        scene.verticalExaggerationRelativeHeight = -1000000.0;
+
+        return updateUntilDone(scene.globe).then(function () {
+          forEachRenderedTile(scene.globe._surface, 1, undefined, function (
+            tile
+          ) {
+            const surfaceTile = tile.data;
+            const encoding = surfaceTile.mesh.encoding;
+            const boundingSphere =
+              surfaceTile.tileBoundingRegion.boundingSphere;
+            expect(encoding.exaggeration).toEqual(2.0);
+            expect(encoding.hasGeodeticSurfaceNormals).toEqual(true);
+            expect(boundingSphere.radius).toBeGreaterThan(7000000.0);
+          });
+
+          scene.verticalExaggeration = 1.0;
+          scene.verticalExaggerationRelativeHeight = 0.0;
+
+          return updateUntilDone(scene.globe).then(function () {
+            forEachRenderedTile(scene.globe._surface, 1, undefined, function (
+              tile
+            ) {
+              const surfaceTile = tile.data;
+              const encoding = surfaceTile.mesh.encoding;
+              const boundingSphere =
+                surfaceTile.tileBoundingRegion.boundingSphere;
+              expect(encoding.exaggeration).toEqual(1.0);
+              expect(encoding.hasGeodeticSurfaceNormals).toEqual(false);
+              expect(boundingSphere.radius).toBeLessThan(7000000.0);
+            });
+          });
+        });
+      });
+    });
   },
   "WebGL"
 );

packages/engine/Specs/Scene/Model/ModelSpec.js

@@ -2117,8 +2117,6 @@ describe(
           getHeight: function () {
             return 0.0;
           },
-          terrainExaggeration: 1.0,
-          terrainExaggerationRelativeHeight: 0.0,
           _surface: {
             tileProvider: {},
             _tileLoadQueueHigh: [],

packages/engine/Specs/Scene/ScreenSpaceCameraControllerSpec.js

@@ -35,6 +35,8 @@ describe("Scene/ScreenSpaceCameraController", function () {
     this.canvas = canvas;
     this.camera = camera;
     this.globe = undefined;
+    this.verticalExaggeration = 1.0;
+    this.verticalExaggerationRelativeHeight = 0.0;
     this.mapProjection = new GeographicProjection(ellipsoid);
     this.screenSpaceCameraController = undefined;
     this.cameraUnderground = false;
@@ -59,9 +61,6 @@ describe("Scene/ScreenSpaceCameraController", function () {
       },
     };
 
-    this.terrainExaggeration = 1.0;
-    this.terrainExaggerationRelativeHeight = 0.0;
-
     this.show = true;
   }
   beforeAll(function () {