@cesium/engine 11.0.0 → 12.0.0

package/Source/Scene/Fog.js

@@ -1,5 +1,6 @@
 import Cartesian3 from "../Core/Cartesian3.js";
 import defined from "../Core/defined.js";
+import DeveloperError from "../Core/DeveloperError.js";
 import CesiumMath from "../Core/Math.js";
 import SceneMode from "./SceneMode.js";
 
@@ -7,6 +8,8 @@ import SceneMode from "./SceneMode.js";
  * Blends the atmosphere to geometry far from the camera for horizon views. Allows for additional
  * performance improvements by rendering less geometry and dispatching less terrain requests.
  *
+ * @demo {@link https://sandcastle.cesium.com/index.html?src=Fog.html|Cesium Sandcastle Fog Demo}
+ *
  * @alias Fog
  * @constructor
  */
@@ -15,6 +18,9 @@ function Fog() {
    * <code>true</code> if fog is enabled, <code>false</code> otherwise.
    * @type {boolean}
    * @default true
+   * @example
+   * // Disable fog in the scene
+   * viewer.scene.fog.enabled = false;
    */
   this.enabled = true;
   /**
@@ -22,6 +28,10 @@ function Fog() {
    * This allows to benefits from optimized tile loading strategy based on fog density without the actual visual rendering.
    * @type {boolean}
    * @default true
+   * @example
+   * // Use fog culling but don't render it
+   * viewer.scene.fog.enabled = true;
+   * viewer.scene.fog.renderable = false;
    */
   this.renderable = true;
   /**
@@ -31,9 +41,36 @@ function Fog() {
    * 1000.0m above the ellipsoid, increasing the value to 3.0e-3 will cause many tiles close to the viewer be culled.
    * Decreasing the value will push the fog further from the viewer, but decrease performance as more of the terrain is rendered.
    * @type {number}
-   * @default 2.0e-4
+   * @default 0.0006
+   * @example
+   * // Double the default fog density
+   * viewer.scene.fog.density = 0.0012;
+   */
+  this.density = 0.0006;
+  /**
+   * A scalar used in the function to adjust density based on the height of the camera above the terrain.
+   * @type {number}
+   * @default 0.001
    */
-  this.density = 2.0e-4;
+  this.heightScalar = 0.001;
+  this._heightFalloff = 0.59;
+  /**
+   * The maximum height fog is applied. If the camera is above this height fog will be disabled.
+   * @type {number}
+   * @default 800000.0
+   */
+  this.maxHeight = 800000.0;
+  /**
+   * A scalar that impacts the visual density of fog. This value does not impact the culling of terrain.
+   * Use in combination with the {@link Fog.density} to make fog appear more or less dense.
+   * @type {number}
+   * @default 0.15
+   * @experimental The value of this scalar may not be final and is subject to change.
+   * @example
+   * // Increase fog appearance effect
+   * viewer.scene.fog.visualDensityScalar = 0.6;
+   */
+  this.visualDensityScalar = 0.15;
   /**
    * A factor used to increase the screen space error of terrain tiles when they are partially in fog. The effect is to reduce
    * the number of terrain tiles requested for rendering. If set to zero, the feature will be disabled. If the value is increased
@@ -52,109 +89,36 @@ function Fog() {
   this.minimumBrightness = 0.03;
 }
 
-// These values were found by sampling the density at certain views and finding at what point culled tiles impacted the view at the horizon.
-const heightsTable = [
-  359.393,
-  800.749,
-  1275.6501,
-  2151.1192,
-  3141.7763,
-  4777.5198,
-  6281.2493,
-  12364.307,
-  15900.765,
-  49889.0549,
-  78026.8259,
-  99260.7344,
-  120036.3873,
-  151011.0158,
-  156091.1953,
-  203849.3112,
-  274866.9803,
-  319916.3149,
-  493552.0528,
-  628733.5874,
-];
-const densityTable = [
-  2.0e-5,
-  2.0e-4,
-  1.0e-4,
-  7.0e-5,
-  5.0e-5,
-  4.0e-5,
-  3.0e-5,
-  1.9e-5,
-  1.0e-5,
-  8.5e-6,
-  6.2e-6,
-  5.8e-6,
-  5.3e-6,
-  5.2e-6,
-  5.1e-6,
-  4.2e-6,
-  4.0e-6,
-  3.4e-6,
-  2.6e-6,
-  2.2e-6,
-];
-
-// Scale densities by 1e6 to bring lowest value to ~1. Prevents divide by zero.
-for (let i = 0; i < densityTable.length; ++i) {
-  densityTable[i] *= 1.0e6;
-}
-// Change range to [0, 1].
-const tableStartDensity = densityTable[1];
-const tableEndDensity = densityTable[densityTable.length - 1];
-for (let j = 0; j < densityTable.length; ++j) {
-  densityTable[j] =
-    (densityTable[j] - tableEndDensity) / (tableStartDensity - tableEndDensity);
-}
-
-let tableLastIndex = 0;
-
-function findInterval(height) {
-  const heights = heightsTable;
-  const length = heights.length;
-
-  if (height < heights[0]) {
-    tableLastIndex = 0;
-    return tableLastIndex;
-  } else if (height > heights[length - 1]) {
-    tableLastIndex = length - 2;
-    return tableLastIndex;
-  }
-
-  // Take advantage of temporal coherence by checking current, next and previous intervals
-  // for containment of time.
-  if (height >= heights[tableLastIndex]) {
-    if (tableLastIndex + 1 < length && height < heights[tableLastIndex + 1]) {
-      return tableLastIndex;
-    } else if (
-      tableLastIndex + 2 < length &&
-      height < heights[tableLastIndex + 2]
-    ) {
-      ++tableLastIndex;
-      return tableLastIndex;
-    }
-  } else if (tableLastIndex - 1 >= 0 && height >= heights[tableLastIndex - 1]) {
-    --tableLastIndex;
-    return tableLastIndex;
-  }
-
-  // The above failed so do a linear search.
-  let i;
-  for (i = 0; i < length - 2; ++i) {
-    if (height >= heights[i] && height < heights[i + 1]) {
-      break;
-    }
-  }
-
-  tableLastIndex = i;
-  return tableLastIndex;
-}
+Object.defineProperties(Fog.prototype, {
+  /**
+   * Exponent factor used in the function to adjust how density changes based on the height of the camera above the ellipsoid. Smaller values produce a more gradual transition as camera height increases.
+   * Value must be greater than 0.
+   * @memberof Fog.prototype
+   * @type {number}
+   * @default 0.59
+   */
+  heightFalloff: {
+    get: function () {
+      return this._heightFalloff;
+    },
+    set: function (value) {
+      //>>includeStart('debug', pragmas.debug);
+      if (defined(value) && value < 0) {
+        throw new DeveloperError("value must be positive.");
+      }
+      //>>includeEnd('debug');
+
+      this._heightFalloff = value;
+    },
+  },
+});
 
 const scratchPositionNormal = new Cartesian3();
 
+/**
+ * @param {FrameState} frameState
+ * @private
+ */
 Fog.prototype.update = function (frameState) {
   const enabled = (frameState.fog.enabled = this.enabled);
   if (!enabled) {
@@ -169,7 +133,7 @@ Fog.prototype.update = function (frameState) {
   // Turn off fog in space.
   if (
     !defined(positionCartographic) ||
-    positionCartographic.height > 800000.0 ||
+    positionCartographic.height > this.maxHeight ||
     frameState.mode !== SceneMode.SCENE3D
   ) {
     frameState.fog.enabled = false;
@@ -178,28 +142,24 @@ Fog.prototype.update = function (frameState) {
   }
 
   const height = positionCartographic.height;
-  const i = findInterval(height);
-  const t = CesiumMath.clamp(
-    (height - heightsTable[i]) / (heightsTable[i + 1] - heightsTable[i]),
-    0.0,
-    1.0
-  );
-  let density = CesiumMath.lerp(densityTable[i], densityTable[i + 1], t);
-
-  // Again, scale value to be in the range of densityTable (prevents divide by zero) and change to new range.
-  const startDensity = this.density * 1.0e6;
-  const endDensity = (startDensity / tableStartDensity) * tableEndDensity;
-  density = density * (startDensity - endDensity) * 1.0e-6;
+  let density =
+    this.density *
+    this.heightScalar *
+    Math.pow(
+      Math.max(height / this.maxHeight, CesiumMath.EPSILON4),
+      -Math.max(this._heightFalloff, 0.0),
+    );
 
   // Fade fog in as the camera tilts toward the horizon.
   const positionNormal = Cartesian3.normalize(
     camera.positionWC,
-    scratchPositionNormal
+    scratchPositionNormal,
   );
   const dot = Math.abs(Cartesian3.dot(camera.directionWC, positionNormal));
   density *= 1.0 - dot;
 
   frameState.fog.density = density;
+  frameState.fog.visualDensityScalar = this.visualDensityScalar;
   frameState.fog.sse = this.screenSpaceErrorFactor;
   frameState.fog.minimumBrightness = this.minimumBrightness;
 };

package/Source/Scene/FrameRateMonitor.js

@@ -44,7 +44,7 @@ function FrameRateMonitor(options) {
    */
   this.samplingWindow = defaultValue(
     options.samplingWindow,
-    FrameRateMonitor.defaultSettings.samplingWindow
+    FrameRateMonitor.defaultSettings.samplingWindow,
   );
 
   /**
@@ -54,7 +54,7 @@ function FrameRateMonitor(options) {
    */
   this.quietPeriod = defaultValue(
     options.quietPeriod,
-    FrameRateMonitor.defaultSettings.quietPeriod
+    FrameRateMonitor.defaultSettings.quietPeriod,
   );
 
   /**
@@ -64,7 +64,7 @@ function FrameRateMonitor(options) {
    */
   this.warmupPeriod = defaultValue(
     options.warmupPeriod,
-    FrameRateMonitor.defaultSettings.warmupPeriod
+    FrameRateMonitor.defaultSettings.warmupPeriod,
   );
 
   /**
@@ -75,7 +75,7 @@ function FrameRateMonitor(options) {
    */
   this.minimumFrameRateDuringWarmup = defaultValue(
     options.minimumFrameRateDuringWarmup,
-    FrameRateMonitor.defaultSettings.minimumFrameRateDuringWarmup
+    FrameRateMonitor.defaultSettings.minimumFrameRateDuringWarmup,
   );
 
   /**
@@ -86,7 +86,7 @@ function FrameRateMonitor(options) {
    */
   this.minimumFrameRateAfterWarmup = defaultValue(
     options.minimumFrameRateAfterWarmup,
-    FrameRateMonitor.defaultSettings.minimumFrameRateAfterWarmup
+    FrameRateMonitor.defaultSettings.minimumFrameRateAfterWarmup,
   );
 
   this._lowFrameRate = new Event();
@@ -104,30 +104,30 @@ function FrameRateMonitor(options) {
   this._preUpdateRemoveListener = this._scene.preUpdate.addEventListener(
     function (scene, time) {
       update(that, time);
-    }
+    },
   );
 
   this._hiddenPropertyName =
     document.hidden !== undefined
       ? "hidden"
       : document.mozHidden !== undefined
-      ? "mozHidden"
-      : document.msHidden !== undefined
-      ? "msHidden"
-      : document.webkitHidden !== undefined
-      ? "webkitHidden"
-      : undefined;
+        ? "mozHidden"
+        : document.msHidden !== undefined
+          ? "msHidden"
+          : document.webkitHidden !== undefined
+            ? "webkitHidden"
+            : undefined;
 
   const visibilityChangeEventName =
     document.hidden !== undefined
       ? "visibilitychange"
       : document.mozHidden !== undefined
-      ? "mozvisibilitychange"
-      : document.msHidden !== undefined
-      ? "msvisibilitychange"
-      : document.webkitHidden !== undefined
-      ? "webkitvisibilitychange"
-      : undefined;
+        ? "mozvisibilitychange"
+        : document.msHidden !== undefined
+          ? "msvisibilitychange"
+          : document.webkitHidden !== undefined
+            ? "webkitvisibilitychange"
+            : undefined;
 
   function visibilityChangeListener() {
     visibilityChanged(that);
@@ -138,14 +138,14 @@ function FrameRateMonitor(options) {
     document.addEventListener(
       visibilityChangeEventName,
       visibilityChangeListener,
-      false
+      false,
     );
 
     this._visibilityChangeRemoveListener = function () {
       document.removeEventListener(
         visibilityChangeEventName,
         visibilityChangeListener,
-        false
+        false,
       );
     };
   }
@@ -359,7 +359,7 @@ function update(monitor, time) {
           monitor._needsQuietPeriod = true;
           monitor.lowFrameRate.raiseEvent(
             monitor.scene,
-            monitor._lastFramesPerSecond
+            monitor._lastFramesPerSecond,
           );
         }
       } else if (monitor._frameRateIsLow) {
@@ -367,7 +367,7 @@ function update(monitor, time) {
         monitor._needsQuietPeriod = true;
         monitor.nominalFrameRate.raiseEvent(
           monitor.scene,
-          monitor._lastFramesPerSecond
+          monitor._lastFramesPerSecond,
         );
       }
     }

package/Source/Scene/FrameState.js

@@ -261,9 +261,10 @@ function FrameState(context, creditDisplay, jobScheduler) {
    * @type {object}
    * @property {boolean} enabled <code>true</code> if fog is enabled, <code>false</code> otherwise. This affects both fog culling and rendering.
    * @property {boolean} renderable <code>true</code> if fog should be rendered, <code>false</code> if not. This flag should be checked in combination with fog.enabled.
-   * @property {number} density A positive number used to mix the color and fog color based on camera distance.
-   * @property {number} sse A scalar used to modify the screen space error of geometry partially in fog.
-   * @property {number} minimumBrightness The minimum brightness of terrain with fog applied.
+   * @property {number | undefined} density A positive number used to mix the color and fog color based on camera distance.
+   * @property {number | undefined} visualDensityScalar A positive number to modify how impactful the fog is based off the density
+   * @property {number | undefined} sse A scalar used to modify the screen space error of geometry partially in fog.
+   * @property {number | undefined} minimumBrightness The minimum brightness of terrain with fog applied.
    */
 
   /**
@@ -277,6 +278,7 @@ function FrameState(context, creditDisplay, jobScheduler) {
     enabled: false,
     renderable: false,
     density: undefined,
+    visualDensityScalar: undefined,
     sse: undefined,
     minimumBrightness: undefined,
   };
@@ -421,6 +423,37 @@ function FrameState(context, creditDisplay, jobScheduler) {
    * @default 0.0
    */
   this.minimumTerrainHeight = 0.0;
+
+  /**
+   * Whether metadata picking is currently in progress.
+   *
+   * This is set to `true` in the `Picking.pickMetadata` function,
+   * immediately before updating and executing the draw commands,
+   * and set back to `false` immediately afterwards. It will be
+   * used to determine whether the metadata picking draw commands
+   * should be executed, in the `Scene.executeCommand` function.
+   *
+   * @type {boolean}
+   * @default false
+   */
+  this.pickingMetadata = false;
+
+  /**
+   * Metadata picking information.
+   *
+   * This describes the metadata property that is supposed to be picked
+   * in a `Picking.pickMetadata` call.
+   *
+   * This is stored in the frame state and in the metadata picking draw
+   * commands. In the `Scene.updateDerivedCommands` call, it will be
+   * checked whether the instance that is stored in the frame state
+   * is different from the one in the draw command, and if necessary,
+   * the derived commands for metadata picking will be updated based
+   * on this information.
+   *
+   * @type {PickedMetadataInfo|undefined}
+   */
+  this.pickedMetadataInfo = undefined;
 }
 
 /**

package/Source/Scene/Geometry3DTileContent.js

@@ -24,7 +24,7 @@ function Geometry3DTileContent(
   tile,
   resource,
   arrayBuffer,
-  byteOffset
+  byteOffset,
 ) {
   this._tileset = tileset;
   this._tile = tile;
@@ -175,7 +175,7 @@ function getBatchIds(featureTableJson, featureTableBinary) {
   const numberOfCylinders = defaultValue(featureTableJson.CYLINDERS_LENGTH, 0);
   const numberOfEllipsoids = defaultValue(
     featureTableJson.ELLIPSOIDS_LENGTH,
-    0
+    0,
   );
   const numberOfSpheres = defaultValue(featureTableJson.SPHERES_LENGTH, 0);
 
@@ -185,7 +185,7 @@ function getBatchIds(featureTableJson, featureTableBinary) {
     boxBatchIds = new Uint16Array(
       featureTableBinary.buffer,
       boxBatchIdsByteOffset,
-      numberOfBoxes
+      numberOfBoxes,
     );
   }
 
@@ -196,7 +196,7 @@ function getBatchIds(featureTableJson, featureTableBinary) {
     cylinderBatchIds = new Uint16Array(
       featureTableBinary.buffer,
       cylinderBatchIdsByteOffset,
-      numberOfCylinders
+      numberOfCylinders,
     );
   }
 
@@ -207,7 +207,7 @@ function getBatchIds(featureTableJson, featureTableBinary) {
     ellipsoidBatchIds = new Uint16Array(
       featureTableBinary.buffer,
       ellipsoidBatchIdsByteOffset,
-      numberOfEllipsoids
+      numberOfEllipsoids,
     );
   }
 
@@ -218,7 +218,7 @@ function getBatchIds(featureTableJson, featureTableBinary) {
     sphereBatchIds = new Uint16Array(
       featureTableBinary.buffer,
       sphereBatchIdsByteOffset,
-      numberOfSpheres
+      numberOfSpheres,
     );
   }
 
@@ -235,7 +235,7 @@ function getBatchIds(featureTableJson, featureTableBinary) {
 
   if (atLeastOneDefined && atLeastOneUndefined) {
     throw new RuntimeError(
-      "If one group of batch ids is defined, then all batch ids must be defined"
+      "If one group of batch ids is defined, then all batch ids must be defined",
     );
   }
 
@@ -292,7 +292,7 @@ function initialize(content, arrayBuffer, byteOffset) {
   const version = view.getUint32(byteOffset, true);
   if (version !== 1) {
     throw new RuntimeError(
-      `Only Geometry tile version 1 is supported.  Version ${version} is not.`
+      `Only Geometry tile version 1 is supported.  Version ${version} is not.`,
     );
   }
   byteOffset += sizeOfUint32;
@@ -310,7 +310,7 @@ function initialize(content, arrayBuffer, byteOffset) {
 
   if (featureTableJSONByteLength === 0) {
     throw new RuntimeError(
-      "Feature table must have a byte length greater than zero"
+      "Feature table must have a byte length greater than zero",
     );
   }
 
@@ -324,14 +324,14 @@ function initialize(content, arrayBuffer, byteOffset) {
   const featureTableJson = getJsonFromTypedArray(
     uint8Array,
     byteOffset,
-    featureTableJSONByteLength
+    featureTableJSONByteLength,
   );
   byteOffset += featureTableJSONByteLength;
 
   const featureTableBinary = new Uint8Array(
     arrayBuffer,
     byteOffset,
-    featureTableBinaryByteLength
+    featureTableBinaryByteLength,
   );
   byteOffset += featureTableBinaryByteLength;
 
@@ -346,7 +346,7 @@ function initialize(content, arrayBuffer, byteOffset) {
     batchTableJson = getJsonFromTypedArray(
       uint8Array,
       byteOffset,
-      batchTableJSONByteLength
+      batchTableJSONByteLength,
     );
     byteOffset += batchTableJSONByteLength;
 
@@ -355,7 +355,7 @@ function initialize(content, arrayBuffer, byteOffset) {
       batchTableBinary = new Uint8Array(
         arrayBuffer,
         byteOffset,
-        batchTableBinaryByteLength
+        batchTableBinaryByteLength,
       );
       // Copy the batchTableBinary section and let the underlying ArrayBuffer be freed
       batchTableBinary = new Uint8Array(batchTableBinary);
@@ -366,7 +366,7 @@ function initialize(content, arrayBuffer, byteOffset) {
   const numberOfCylinders = defaultValue(featureTableJson.CYLINDERS_LENGTH, 0);
   const numberOfEllipsoids = defaultValue(
     featureTableJson.ELLIPSOIDS_LENGTH,
-    0
+    0,
   );
   const numberOfSpheres = defaultValue(featureTableJson.SPHERES_LENGTH, 0);
 
@@ -378,7 +378,7 @@ function initialize(content, arrayBuffer, byteOffset) {
     totalPrimitives,
     batchTableJson,
     batchTableBinary,
-    createColorChangedCallback(content)
+    createColorChangedCallback(content),
   );
   content._batchTable = batchTable;
 
@@ -413,7 +413,7 @@ function initialize(content, arrayBuffer, byteOffset) {
       boxes = new Float32Array(
         featureTableBinary.buffer,
         boxesByteOffset,
-        Vector3DTileGeometry.packedBoxLength * numberOfBoxes
+        Vector3DTileGeometry.packedBoxLength * numberOfBoxes,
       );
     }
 
@@ -423,7 +423,7 @@ function initialize(content, arrayBuffer, byteOffset) {
       cylinders = new Float32Array(
         featureTableBinary.buffer,
         cylindersByteOffset,
-        Vector3DTileGeometry.packedCylinderLength * numberOfCylinders
+        Vector3DTileGeometry.packedCylinderLength * numberOfCylinders,
       );
     }
 
@@ -433,7 +433,7 @@ function initialize(content, arrayBuffer, byteOffset) {
       ellipsoids = new Float32Array(
         featureTableBinary.buffer,
         ellipsoidsByteOffset,
-        Vector3DTileGeometry.packedEllipsoidLength * numberOfEllipsoids
+        Vector3DTileGeometry.packedEllipsoidLength * numberOfEllipsoids,
       );
     }
 
@@ -443,7 +443,7 @@ function initialize(content, arrayBuffer, byteOffset) {
       spheres = new Float32Array(
         featureTableBinary.buffer,
         spheresByteOffset,
-        Vector3DTileGeometry.packedSphereLength * numberOfSpheres
+        Vector3DTileGeometry.packedSphereLength * numberOfSpheres,
       );
     }
 
@@ -490,7 +490,7 @@ Geometry3DTileContent.prototype.getFeature = function (batchId) {
     throw new DeveloperError(
       `batchId is required and between zero and featuresLength - 1 (${
         featuresLength - 1
-      }).`
+      }).`,
     );
   }
   //>>includeEnd('debug');