Rename undergroundColorByDistance to undergroundColorAlphaByDistance

Apps/Sandcastle/gallery/Underground Color.html

@@ -213,10 +213,10 @@
           var farAlpha = Number(viewModel.farAlpha);
           farAlpha = isNaN(farAlpha) ? 1.0 : farAlpha;
 
-          globe.undergroundColorByDistance.near = nearDistance;
-          globe.undergroundColorByDistance.far = farDistance;
-          globe.undergroundColorByDistance.nearValue = nearAlpha;
-          globe.undergroundColorByDistance.farValue = farAlpha;
+          globe.undergroundColorAlphaByDistance.near = nearDistance;
+          globe.undergroundColorAlphaByDistance.far = farDistance;
+          globe.undergroundColorAlphaByDistance.nearValue = nearAlpha;
+          globe.undergroundColorAlphaByDistance.farValue = farAlpha;
         }
         update(); //Sandcastle_End
         Sandcastle.finishedLoading();

CHANGES.md

@@ -6,7 +6,7 @@
 
 - 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 `Globe.undergroundColor` and `Globe.undergroundColorByDistance` for controlling how the back side of the globe is rendered when the camera is underground or the globe is translucent. [#8867](https://github.com/CesiumGS/cesium/pull/8867)
+- Added `Globe.undergroundColor` and `Globe.undergroundColorAlphaByDistance` for controlling how the back side of the globe is rendered when the camera is underground or the globe is translucent. [#8867](https://github.com/CesiumGS/cesium/pull/8867)
 
 ##### Fixes :wrench:
 

Source/Scene/Globe.js

@@ -63,7 +63,7 @@ function Globe(ellipsoid) {
   this._terrainProviderChanged = new Event();
 
   this._undergroundColor = Color.clone(Color.BLACK);
-  this._undergroundColorByDistance = new NearFarScalar(
+  this._undergroundColorAlphaByDistance = new NearFarScalar(
     ellipsoid.maximumRadius / 1000.0,
     0.0,
     ellipsoid.maximumRadius / 5.0,
@@ -490,7 +490,7 @@ Object.defineProperties(Globe.prototype, {
    * @type {Color}
    * @default {@link Color.BLACK}
    *
-   * @see Globe#undergroundColorByDistance
+   * @see Globe#undergroundColorAlphaByDistance
    */
   undergroundColor: {
     get: function () {
@@ -503,21 +503,24 @@ Object.defineProperties(Globe.prototype, {
 
   /**
    * Gets or sets the near and far distance for blending {@link Globe#undergroundColor} with the globe color.
-   * The blending amount will interpolate between the {@link NearFarScalar#nearValue} and
+   * The alpha 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 blending amount remains clamped to the nearest bound. If undefined,
+   * Outside of these ranges the alpha remains clamped to the nearest bound. If undefined,
    * the underground color will not be blended with the globe color.
+   * <br /> <br />
+   * When the camera is above the ellipsoid the distance is computed from the nearest
+   * point on the ellipsoid instead of the camera's position.
    *
    * @memberof Globe.prototype
    * @type {NearFarScalar}
    *
    * @see Globe#undergroundColor
    *
    */
-  undergroundColorByDistance: {
+  undergroundColorAlphaByDistance: {
     get: function () {
-      return this._undergroundColorByDistance;
+      return this._undergroundColorAlphaByDistance;
     },
     set: function (value) {
       //>>includeStart('debug', pragmas.debug);
@@ -527,9 +530,9 @@ Object.defineProperties(Globe.prototype, {
         );
       }
       //>>includeEnd('debug');
-      this._undergroundColorByDistance = NearFarScalar.clone(
+      this._undergroundColorAlphaByDistance = NearFarScalar.clone(
         value,
-        this._undergroundColorByDistance
+        this._undergroundColorAlphaByDistance
       );
     },
   },
@@ -933,7 +936,7 @@ Globe.prototype.beginFrame = function (frameState) {
     tileProvider.showSkirts = this.showSkirts;
     tileProvider.backFaceCulling = this.backFaceCulling;
     tileProvider.undergroundColor = this._undergroundColor;
-    tileProvider.undergroundColorByDistance = this._undergroundColorByDistance;
+    tileProvider.undergroundColorAlphaByDistance = this._undergroundColorAlphaByDistance;
     surface.beginFrame(frameState);
   }
 };

Source/Scene/GlobeSurfaceTileProvider.js

@@ -106,7 +106,7 @@ function GlobeSurfaceTileProvider(options) {
   this.showSkirts = true;
   this.backFaceCulling = true;
   this.undergroundColor = undefined;
-  this.undergroundColorByDistance = undefined;
+  this.undergroundColorAlphaByDistance = undefined;
 
   this._quadtree = undefined;
   this._terrainProvider = options.terrainProvider;
@@ -1590,8 +1590,8 @@ function createTileUniformMap(frameState, globeSurfaceTileProvider) {
     u_undergroundColor: function () {
       return this.properties.undergroundColor;
     },
-    u_undergroundColorByDistance: function () {
-      return this.properties.undergroundColorByDistance;
+    u_undergroundColorAlphaByDistance: function () {
+      return this.properties.undergroundColorAlphaByDistance;
     },
 
     // make a separate object so that changes to the properties are seen on
@@ -1639,7 +1639,7 @@ function createTileUniformMap(frameState, globeSurfaceTileProvider) {
       localizedCartographicLimitRectangle: new Cartesian4(),
 
       undergroundColor: Color.clone(Color.TRANSPARENT),
-      undergroundColorByDistance: new Cartesian4(),
+      undergroundColorAlphaByDistance: new Cartesian4(),
     },
   };
 
@@ -1833,7 +1833,7 @@ var surfaceShaderSetOptionsScratch = {
   colorToAlpha: undefined,
 };
 
-var defaultUndergroundColorByDistance = new NearFarScalar();
+var defaultundergroundColorAlphaByDistance = new NearFarScalar();
 
 function addDrawCommandsForTile(tileProvider, tile, frameState) {
   var surfaceTile = tile.data;
@@ -1878,16 +1878,16 @@ function addDrawCommandsForTile(tileProvider, tile, frameState) {
     tileProvider.undergroundColor,
     Color.TRANSPARENT
   );
-  var undergroundColorByDistance = defaultValue(
-    tileProvider.undergroundColorByDistance,
-    defaultUndergroundColorByDistance
+  var undergroundColorAlphaByDistance = defaultValue(
+    tileProvider.undergroundColorAlphaByDistance,
+    defaultundergroundColorAlphaByDistance
   );
   var showUndergroundColor =
     cameraUnderground &&
     frameState.mode === SceneMode.SCENE3D &&
     undergroundColor.alpha > 0.0 &&
-    (undergroundColorByDistance.nearValue > 0.0 ||
-      undergroundColorByDistance.farValue > 0.0);
+    (undergroundColorAlphaByDistance.nearValue > 0.0 ||
+      undergroundColorAlphaByDistance.farValue > 0.0);
 
   var showReflectiveOcean =
     tileProvider.hasWaterMask && defined(waterMaskTexture);
@@ -2117,11 +2117,11 @@ function addDrawCommandsForTile(tileProvider, tile, frameState) {
       tileProvider.zoomedOutOceanSpecularIntensity;
 
     Cartesian4.fromElements(
-      undergroundColorByDistance.near,
-      undergroundColorByDistance.nearValue,
-      undergroundColorByDistance.far,
-      undergroundColorByDistance.farValue,
-      uniformMapProperties.undergroundColorByDistance
+      undergroundColorAlphaByDistance.near,
+      undergroundColorAlphaByDistance.nearValue,
+      undergroundColorAlphaByDistance.far,
+      undergroundColorAlphaByDistance.farValue,
+      uniformMapProperties.undergroundColorAlphaByDistance
     );
     Color.clone(undergroundColor, uniformMapProperties.undergroundColor);
 

Source/Shaders/GlobeFS.glsl

@@ -86,7 +86,7 @@ uniform vec4 u_fillHighlightColor;
 
 #ifdef UNDERGROUND_COLOR
 uniform vec4 u_undergroundColor;
-uniform vec4 u_undergroundColorByDistance;
+uniform vec4 u_undergroundColorAlphaByDistance;
 #endif
 
 varying vec3 v_positionMC;
@@ -458,7 +458,7 @@ void main()
     {
         float distanceFromEllipsoid = max(czm_cameraHeight, 0.0);
         float distance = max(v_distance - distanceFromEllipsoid, 0.0);
-        float blendAmount = interpolateByDistance(u_undergroundColorByDistance, distance);
+        float blendAmount = interpolateByDistance(u_undergroundColorAlphaByDistance, distance);
         vec4 undergroundColor = vec4(u_undergroundColor.rgb, u_undergroundColor.a * blendAmount);
         finalColor = alphaBlend(undergroundColor, finalColor);
     }

Specs/Scene/GlobeSpec.js

@@ -443,14 +443,14 @@ describe(
     });
 
     it("gets underground color by distance", function () {
-      expect(globe.undergroundColorByDistance).toBeDefined();
+      expect(globe.undergroundColorAlphaByDistance).toBeDefined();
     });
 
     it("sets underground color by distance", function () {
       globe.baseColor = Color.BLACK;
       globe.undergroundColor = Color.RED;
       var radius = globe.ellipsoid.maximumRadius;
-      globe.undergroundColorByDistance = new NearFarScalar(
+      globe.undergroundColorAlphaByDistance = new NearFarScalar(
         radius * 0.25,
         0.0,
         radius * 2.0,
@@ -480,7 +480,7 @@ describe(
 
     it("throws if underground color by distance far is less than near", function () {
       expect(function () {
-        globe.undergroundColorByDistance = new NearFarScalar(
+        globe.undergroundColorAlphaByDistance = new NearFarScalar(
           1.0,
           0.0,
           0.0,