Added GlobeTranslucency to group translucency options

CesiumGS · May 23, 2020 · c09945b · c09945b
1 parent aad027b
commit c09945b
Show file tree

Hide file tree

Showing 9 changed files with 368 additions and 324 deletions.
diff --git a/Apps/Sandcastle/gallery/Globe Interior.html b/Apps/Sandcastle/gallery/Globe Interior.html
@@ -48,17 +48,17 @@
         function reset() {
           globe.showGroundAtmosphere = true;
           globe.baseColor = Cesium.Color.BLUE;
-          globe.translucencyEnabled = false;
-          globe.frontFaceAlpha = 1.0;
+          globe.translucency.enabled = false;
+          globe.translucency.frontFaceAlpha = 1.0;
           globe.undergroundColor = Cesium.Color.BLACK;
-          globe.translucencyRectangle = undefined;
+          globe.translucency.rectangle = undefined;
           baseLayer.colorToAlpha = undefined;
         }
 
         function useTranslucencyMask() {
           globe.showGroundAtmosphere = false;
           globe.baseColor = Cesium.Color.TRANSPARENT;
-          globe.translucencyEnabled = true;
+          globe.translucency.enabled = true;
           globe.undergroundColor = undefined;
 
           // Set oceans on Bing base layer to transparent
@@ -67,10 +67,10 @@
         }
 
         function useTranslucencyRectangle() {
-          globe.translucencyEnabled = true;
+          globe.translucency.enabled = true;
           globe.undergroundColor = undefined;
-          globe.frontFaceAlpha = 0.25;
-          globe.translucencyRectangle = Cesium.Rectangle.fromDegrees(
+          globe.translucency.frontFaceAlpha = 0.25;
+          globe.translucency.rectangle = Cesium.Rectangle.fromDegrees(
             -120.0,
             0.0,
             -30.0,

diff --git a/Apps/Sandcastle/gallery/Globe Translucency.html b/Apps/Sandcastle/gallery/Globe Translucency.html
@@ -92,7 +92,7 @@
         var globe = scene.globe;
 
         scene.screenSpaceCameraController.enableCollisionDetection = false;
-        globe.frontFaceAlphaByDistance = new Cesium.NearFarScalar(
+        globe.translucency.frontFaceAlphaByDistance = new Cesium.NearFarScalar(
           400.0,
           0.0,
           800.0,
@@ -258,14 +258,14 @@
         }
 
         function update() {
-          globe.translucencyEnabled = viewModel.translucencyEnabled;
+          globe.translucency.enabled = viewModel.translucencyEnabled;
 
           var alpha = Number(viewModel.alpha);
           alpha = !isNaN(alpha) ? alpha : 1.0;
           alpha = Cesium.Math.clamp(alpha, 0.0, 1.0);
 
-          globe.frontFaceAlphaByDistance.nearValue = alpha;
-          globe.frontFaceAlphaByDistance.farValue = viewModel.fadeByDistance
+          globe.translucency.frontFaceAlphaByDistance.nearValue = alpha;
+          globe.translucency.frontFaceAlphaByDistance.farValue = viewModel.fadeByDistance
             ? 1.0
             : alpha;
 

diff --git a/CHANGES.md b/CHANGES.md
@@ -5,10 +5,10 @@
 ##### Additions :tada:
 
 - Added support for rendering the globe with translucency. [#8726](https://github.com/CesiumGS/cesium/pull/8726)
-  - Added `Globe.translucencyEnabled` for enabling globe translucency.
-  - Added `Globe.frontFaceAlpha` and `Globe.frontFaceAlphaByDistance` for controlling the alpha of front faces.
-  - Added `Globe.backFaceAlpha` and `Globe.backFaceAlphaByDistance` for controlling the alpha of back faces.
-  - Added `Globe.translucencyRectangle` for applying translucency only within a rectangular area.
+  - Added `globe.translucency.enabled` to enable globe translucency.
+  - Added `globe.translucency.frontFaceAlpha` and `globe.translucency.frontFaceAlphaByDistance` for controlling the alpha of front faces.
+  - Added `globe.translucency.backFaceAlpha` and `globe.translucency.backFaceAlphaByDistance` for controlling the alpha of back faces.
+  - Added `globe.translucency.rectangle` for applying translucency only within a rectangular area.
 - Added `Cesium3DTileset.extensions` to get the extensions property from the tileset JSON. [#8829](https://github.com/CesiumGS/cesium/pull/8829)
 - Added `frustumSplits` option to `DebugCameraPrimitive`. [8849](https://github.com/CesiumGS/cesium/pull/8849)
 - Added `SkyAtmosphere.perFragmentAtmosphere` to switch between per-vertex and per-fragment atmosphere shading. [#8866](https://github.com/CesiumGS/cesium/pull/8866)

diff --git a/Source/Scene/Globe.js b/Source/Scene/Globe.js
@@ -2,7 +2,6 @@ import BoundingSphere from "../Core/BoundingSphere.js";
 import buildModuleUrl from "../Core/buildModuleUrl.js";
 import Cartesian3 from "../Core/Cartesian3.js";
 import Cartographic from "../Core/Cartographic.js";
-import Check from "../Core/Check.js";
 import Color from "../Core/Color.js";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
@@ -24,6 +23,7 @@ import GroundAtmosphere from "../Shaders/GroundAtmosphere.js";
 import when from "../ThirdParty/when.js";
 import GlobeSurfaceShaderSet from "./GlobeSurfaceShaderSet.js";
 import GlobeSurfaceTileProvider from "./GlobeSurfaceTileProvider.js";
+import GlobeTranslucency from "./GlobeTranslucency.js";
 import ImageryLayerCollection from "./ImageryLayerCollection.js";
 import QuadtreePrimitive from "./QuadtreePrimitive.js";
 import SceneMode from "./SceneMode.js";
@@ -71,11 +71,7 @@ function Globe(ellipsoid) {
     1.0
   );
 
-  this._translucencyEnabled = false;
-  this._frontFaceAlpha = 1.0;
-  this._frontFaceAlphaByDistance = undefined;
-  this._backFaceAlpha = 1.0;
-  this._backFaceAlphaByDistance = undefined;
+  this._translucency = new GlobeTranslucency();
 
   makeShadersDirty(this);
 
@@ -545,216 +541,14 @@ Object.defineProperties(Globe.prototype, {
   },
 
   /**
-   * When true, the globe is rendered as a translucent surface.
-   * <br /><br />
-   * The alpha is computed by blending {@link Globe#material}, {@link Globe#imageryLayers},
-   * and {@link Globe#baseColor}, all of which may contain translucency, and then multiplying by
-   * {@link Globe#frontFaceAlpha} and {@link Globe#frontFaceAlphaByDistance} for front faces and
-   * {@link Globe#backFaceAlpha} and {@link Globe#backFaceAlphaByDistance} for back faces.
-   * When the camera is underground back faces and front faces are swapped, i.e. back-facing geometry
-   * is considered front facing.
-   * <br /><br />
-   * Translucency is disabled by default.
-   *
-   * @memberof Globe.prototype
-   *
-   * @type {Boolean}
-   * @default false
-   *
-   * @see Globe#frontFaceAlpha
-   * @see Globe#frontFaceAlphaByDistance
-   * @see Globe#backFaceAlpha
-   * @see Globe#backFaceAlphaByDistance
-   */
-  translucencyEnabled: {
-    get: function () {
-      return this._translucencyEnabled;
-    },
-    set: function (value) {
-      //>>includeStart('debug', pragmas.debug);
-      Check.typeOf.bool("translucencyEnabled", value);
-      //>>includeEnd('debug');
-      this._translucencyEnabled = value;
-    },
-  },
-
-  /**
-   * A constant translucency to apply to front faces of the globe.
-   * <br /><br />
-   * {@link Globe#translucencyEnabled} must be set to true for this option to take effect.
-   *
-   * @memberof Globe.prototype
-   *
-   * @type {Number}
-   * @default 1.0
-   *
-   * @see Globe#translucencyEnabled
-   * @see Globe#frontFaceAlphaByDistance
-   *
-   * @example
-   * // Set front face translucency to 0.5.
-   * globe.frontFaceAlpha = 0.5;
-   * globe.translucencyEnabled = true;
-   */
-  frontFaceAlpha: {
-    get: function () {
-      return this._frontFaceAlpha;
-    },
-    set: function (value) {
-      //>>includeStart('debug', pragmas.debug);
-      Check.typeOf.number.greaterThanOrEquals("frontFaceAlpha", value, 0.0);
-      Check.typeOf.number.lessThanOrEquals("frontFaceAlpha", value, 1.0);
-      //>>includeEnd('debug');
-      this._frontFaceAlpha = value;
-    },
-  },
-  /**
-   * Gets or sets near and far translucency properties of front faces of the globe based on the distance to the camera.
-   * The translucency will interpolate between the {@link NearFarScalar#nearValue} and
-   * {@link NearFarScalar#farValue} while the camera distance falls within the lower and upper bounds
-   * of the specified {@link NearFarScalar#near} and {@link NearFarScalar#far}.
-   * Outside of these ranges the translucency remains clamped to the nearest bound.  If undefined,
-   * frontFaceAlphaByDistance will be disabled.
-   * <br /><br />
-   * {@link Globe#translucencyEnabled} must be set to true for this option to take effect.
-   *
-   * @memberof Globe.prototype
-   *
-   * @type {NearFarScalar}
-   * @default undefined
-   *
-   * @see Globe#translucencyEnabled
-   * @see Globe#frontFaceAlpha
-   *
-   * @example
-   * // Example 1.
-   * // Set front face translucency to 0.5 when the
-   * // camera is 1500 meters from the surface and 1.0
-   * // as the camera distance approaches 8.0e6 meters.
-   * globe.frontFaceAlphaByDistance = new Cesium.NearFarScalar(1.5e2, 0.5, 8.0e6, 1.0);
-   * globe.translucencyEnabled = true;
-   *
-   * @example
-   * // Example 2.
-   * // Disable front face translucency by distance
-   * globe.frontFaceAlphaByDistance = undefined;
-   */
-  frontFaceAlphaByDistance: {
-    get: function () {
-      return this._frontFaceAlphaByDistance;
-    },
-    set: function (value) {
-      //>>includeStart('debug', pragmas.debug);
-      if (defined(value) && value.far < value.near) {
-        throw new DeveloperError(
-          "far distance must be greater than near distance."
-        );
-      }
-      //>>includeEnd('debug');
-      this._frontFaceAlphaByDistance = NearFarScalar.clone(
-        value,
-        this._frontFaceAlphaByDistance
-      );
-    },
-  },
-
-  /**
-   * A constant translucency to apply to back faces of the globe.
-   * <br /><br />
-   * {@link Globe#translucencyEnabled} must be set to true for this option to take effect.
+   * Properties for controlling globe translucency.
    *
    * @memberof Globe.prototype
-   *
-   * @type {Number}
-   * @default 1.0
-   *
-   * @see Globe#translucencyEnabled
-   * @see Globe#backFaceAlphaByDistance
-   *
-   * @example
-   * // Set back face translucency to 0.5.
-   * globe.backFaceAlpha = 0.5;
-   * globe.translucencyEnabled = true;
+   * @type {GlobeTranslucency}
    */
-  backFaceAlpha: {
+  translucency: {
     get: function () {
-      return this._backFaceAlpha;
-    },
-    set: function (value) {
-      //>>includeStart('debug', pragmas.debug);
-      Check.typeOf.number.greaterThanOrEquals("backFaceAlpha", value, 0.0);
-      Check.typeOf.number.lessThanOrEquals("backFaceAlpha", value, 1.0);
-      //>>includeEnd('debug');
-      this._backFaceAlpha = value;
-    },
-  },
-  /**
-   * Gets or sets near and far translucency properties of back faces of the globe based on the distance to the camera.
-   * The translucency will interpolate between the {@link NearFarScalar#nearValue} and
-   * {@link NearFarScalar#farValue} while the camera distance falls within the lower and upper bounds
-   * of the specified {@link NearFarScalar#near} and {@link NearFarScalar#far}.
-   * Outside of these ranges the translucency remains clamped to the nearest bound.  If undefined,
-   * backFaceAlphaByDistance will be disabled.
-   * <br /><br />
-   * {@link Globe#translucencyEnabled} must be set to true for this option to take effect.
-   *
-   * @memberof Globe.prototype
-   *
-   * @type {NearFarScalar}
-   * @default undefined
-   *
-   * @see Globe#translucencyEnabled
-   * @see Globe#backFaceAlpha
-   *
-   * @example
-   * // Example 1.
-   * // Set back face translucency to 0.5 when the
-   * // camera is 1500 meters from the surface and 1.0
-   * // as the camera distance approaches 8.0e6 meters.
-   * globe.backFaceAlphaByDistance = new Cesium.NearFarScalar(1.5e2, 0.5, 8.0e6, 1.0);
-   * globe.translucencyEnabled = true;
-   *
-   * @example
-   * // Example 2.
-   * // Disable back face translucency by distance
-   * globe.backFaceAlphaByDistance = undefined;
-   */
-  backFaceAlphaByDistance: {
-    get: function () {
-      return this._backFaceAlphaByDistance;
-    },
-    set: function (value) {
-      //>>includeStart('debug', pragmas.debug);
-      if (defined(value) && value.far < value.near) {
-        throw new DeveloperError(
-          "far distance must be greater than near distance."
-        );
-      }
-      //>>includeEnd('debug');
-      this._backFaceAlphaByDistance = NearFarScalar.clone(
-        value,
-        this._backFaceAlphaByDistance
-      );
-    },
-  },
-
-  /**
-   * A property specifying a {@link Rectangle} used to limit translucency to a cartographic area.
-   * Defaults to the maximum extent of cartographic coordinates.
-   *
-   * @member Globe.prototype
-   * @type {Rectangle}
-   * @default Rectangle.MAX_VALUE
-   */
-  translucencyRectangle: {
-    get: function () {
-      return this._surface.tileProvider.translucencyRectangle;
-    },
-    set: function (value) {
-      if (!defined(value)) {
-        value = Rectangle.clone(Rectangle.MAX_VALUE);
-      }
-      Rectangle.clone(value, this._surface.tileProvider.translucencyRectangle);
+      return this._translucency;
     },
   },
 });

diff --git a/Source/Scene/GlobeSurfaceTileProvider.js b/Source/Scene/GlobeSurfaceTileProvider.js
@@ -105,7 +105,6 @@ function GlobeSurfaceTileProvider(options) {
 
   this.showSkirts = true;
   this.backFaceCulling = true;
-  this.translucencyRectangle = Rectangle.clone(Rectangle.MAX_VALUE);
   this.undergroundColor = undefined;
   this.undergroundColorAlphaByDistance = undefined;
 
@@ -1947,6 +1946,7 @@ function addDrawCommandsForTile(tileProvider, tile, frameState) {
   var frontFaceAlphaByDistance =
     globeTranslucencyState.frontFaceAlphaByDistance;
   var backFaceAlphaByDistance = globeTranslucencyState.backFaceAlphaByDistance;
+  var translucencyRectangle = globeTranslucencyState.rectangle;
 
   var undergroundColor = defaultValue(
     tileProvider.undergroundColor,
@@ -2260,9 +2260,9 @@ function addDrawCommandsForTile(tileProvider, tile, frameState) {
     );
 
     var localizedTranslucencyRectangle = localizedTranslucencyRectangleScratch;
-    var translucencyRectangle = clipRectangleAntimeridian(
+    var clippedTranslucencyRectangle = clipRectangleAntimeridian(
       tile.rectangle,
-      tileProvider.translucencyRectangle
+      translucencyRectangle
     );
 
     Cartesian3.fromElements(
@@ -2294,16 +2294,16 @@ function addDrawCommandsForTile(tileProvider, tile, frameState) {
     );
 
     localizedTranslucencyRectangle.x =
-      (translucencyRectangle.west - cartographicTileRectangle.west) *
+      (clippedTranslucencyRectangle.west - cartographicTileRectangle.west) *
       inverseTileWidth;
     localizedTranslucencyRectangle.y =
-      (translucencyRectangle.south - cartographicTileRectangle.south) *
+      (clippedTranslucencyRectangle.south - cartographicTileRectangle.south) *
       inverseTileHeight;
     localizedTranslucencyRectangle.z =
-      (translucencyRectangle.east - cartographicTileRectangle.west) *
+      (clippedTranslucencyRectangle.east - cartographicTileRectangle.west) *
       inverseTileWidth;
     localizedTranslucencyRectangle.w =
-      (translucencyRectangle.north - cartographicTileRectangle.south) *
+      (clippedTranslucencyRectangle.north - cartographicTileRectangle.south) *
       inverseTileHeight;
 
     Cartesian4.clone(