@cesium/engine 11.1.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,76 +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) {
@@ -136,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;
@@ -145,18 +142,13 @@ 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(
@@ -167,6 +159,7 @@ Fog.prototype.update = function (frameState) {
   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/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,
   };

package/Source/Scene/ImageBasedLighting.js

@@ -20,7 +20,6 @@ import SpecularEnvironmentCubeMap from "./SpecularEnvironmentCubeMap.js";
  * @constructor
  *
  * @param {Cartesian2} [options.imageBasedLightingFactor=Cartesian2(1.0, 1.0)] Scales diffuse and specular image-based lighting from the earth, sky, atmosphere and star skybox.
- * @param {number} [options.luminanceAtZenith=0.2] The sun's luminance at the zenith in kilo candela per meter squared to use for this model's procedural environment map.
  * @param {Cartesian3[]} [options.sphericalHarmonicCoefficients] The third order spherical harmonic coefficients used for the diffuse color of image-based lighting.
  * @param {string} [options.specularEnvironmentMaps] A URL to a KTX2 file that contains a cube map of the specular lighting and the convoluted specular mipmaps.
  */
@@ -59,14 +58,6 @@ function ImageBasedLighting(options) {
 
   this._imageBasedLightingFactor = imageBasedLightingFactor;
 
-  const luminanceAtZenith = defaultValue(options.luminanceAtZenith, 0.2);
-
-  //>>includeStart('debug', pragmas.debug);
-  Check.typeOf.number("options.luminanceAtZenith", luminanceAtZenith);
-  //>>includeEnd('debug');
-
-  this._luminanceAtZenith = luminanceAtZenith;
-
   const sphericalHarmonicCoefficients = options.sphericalHarmonicCoefficients;
 
   //>>includeStart('debug', pragmas.debug);
@@ -100,7 +91,6 @@ function ImageBasedLighting(options) {
   this._previousImageBasedLightingFactor = Cartesian2.clone(
     imageBasedLightingFactor,
   );
-  this._previousLuminanceAtZenith = luminanceAtZenith;
   this._previousSphericalHarmonicCoefficients = sphericalHarmonicCoefficients;
   this._removeErrorListener = undefined;
 }
@@ -156,27 +146,6 @@ Object.defineProperties(ImageBasedLighting.prototype, {
     },
   },
 
-  /**
-   * The sun's luminance at the zenith in kilo candela per meter squared
-   * to use for this model's procedural environment map. This is used when
-   * {@link ImageBasedLighting#specularEnvironmentMaps} and {@link ImageBasedLighting#sphericalHarmonicCoefficients}
-   * are not defined.
-   *
-   * @memberof ImageBasedLighting.prototype
-   *
-   * @type {number}
-   * @default 0.2
-   */
-  luminanceAtZenith: {
-    get: function () {
-      return this._luminanceAtZenith;
-    },
-    set: function (value) {
-      this._previousLuminanceAtZenith = this._luminanceAtZenith;
-      this._luminanceAtZenith = value;
-    },
-  },
-
   /**
    * The third order spherical harmonic coefficients used for the diffuse color of image-based lighting. When <code>undefined</code>, a diffuse irradiance
    * computed from the atmosphere color is used.
@@ -269,47 +238,30 @@ Object.defineProperties(ImageBasedLighting.prototype, {
   },
 
   /**
-   * Whether or not to use the default spherical harmonic coefficients.
+   * The texture atlas for the specular environment maps.
    *
    * @memberof ImageBasedLighting.prototype
-   * @type {boolean}
+   * @type {SpecularEnvironmentCubeMap}
    *
    * @private
    */
-  useDefaultSphericalHarmonics: {
+  specularEnvironmentCubeMap: {
     get: function () {
-      return this._useDefaultSphericalHarmonics;
+      return this._specularEnvironmentCubeMap;
     },
   },
 
   /**
-   * Whether or not the image-based lighting settings use spherical harmonic coefficients.
+   * Whether or not to use the default spherical harmonics coefficients.
    *
    * @memberof ImageBasedLighting.prototype
    * @type {boolean}
    *
    * @private
    */
-  useSphericalHarmonicCoefficients: {
-    get: function () {
-      return (
-        defined(this._sphericalHarmonicCoefficients) ||
-        this._useDefaultSphericalHarmonics
-      );
-    },
-  },
-
-  /**
-   * The cube map for the specular environment maps.
-   *
-   * @memberof ImageBasedLighting.prototype
-   * @type {SpecularEnvironmentCubeMap}
-   *
-   * @private
-   */
-  specularEnvironmentCubeMap: {
+  useDefaultSphericalHarmonics: {
     get: function () {
-      return this._specularEnvironmentCubeMap;
+      return this._useDefaultSphericalHarmonics;
     },
   },
 
@@ -400,15 +352,6 @@ ImageBasedLighting.prototype.update = function (frameState) {
     );
   }
 
-  if (this._luminanceAtZenith !== this._previousLuminanceAtZenith) {
-    this._shouldRegenerateShaders =
-      this._shouldRegenerateShaders ||
-      defined(this._luminanceAtZenith) !==
-        defined(this._previousLuminanceAtZenith);
-
-    this._previousLuminanceAtZenith = this._luminanceAtZenith;
-  }
-
   if (
     this._previousSphericalHarmonicCoefficients !==
     this._sphericalHarmonicCoefficients

package/Source/Scene/Model/AtmospherePipelineStage.js

@@ -16,12 +16,17 @@ const AtmospherePipelineStage = {
   name: "AtmospherePipelineStage", // Helps with debugging
 };
 
+/**
+ * @param {ModelRenderResources} modelRenderResources
+ * @param {Model} model
+ * @param {FrameState} frameState
+ */
 AtmospherePipelineStage.process = function (
-  renderResources,
+  modelRenderResources,
   model,
   frameState,
 ) {
-  const shaderBuilder = renderResources.shaderBuilder;
+  const shaderBuilder = modelRenderResources.shaderBuilder;
 
   shaderBuilder.addDefine("HAS_ATMOSPHERE", undefined, ShaderDestination.BOTH);
   shaderBuilder.addDefine(
@@ -37,12 +42,12 @@ AtmospherePipelineStage.process = function (
   shaderBuilder.addVertexLines([AtmosphereStageVS]);
   shaderBuilder.addFragmentLines([AtmosphereStageFS]);
 
-  // Add a uniform so fog is only calculated when the efcfect would
-  // be non-negligible For example when the camera is in space, fog density decreases
+  // Add a uniform so fog is only calculated when the effect would
+  // be non-negligible. For example when the camera is in space, fog density decreases
   // to 0 so fog shouldn't be rendered. Since this state may change rapidly if
   // the camera is moving, this is implemented as a uniform, not a define.
   shaderBuilder.addUniform("bool", "u_isInFog", ShaderDestination.FRAGMENT);
-  renderResources.uniformMap.u_isInFog = function () {
+  modelRenderResources.uniformMap.u_isInFog = function () {
     // We only need a rough measure of distance to the model, so measure
     // from the camera to the bounding sphere center.
     const distance = Cartesian3.distance(

package/Source/Scene/Model/ImageBasedLightingPipelineStage.js

@@ -3,11 +3,14 @@ import defined from "../../Core/defined.js";
 import ImageBasedLightingStageFS from "../../Shaders/Model/ImageBasedLightingStageFS.js";
 import ShaderDestination from "../../Renderer/ShaderDestination.js";
 import SpecularEnvironmentCubeMap from "../SpecularEnvironmentCubeMap.js";
+import Cartesian2 from "../../Core/Cartesian2.js";
 
 const ImageBasedLightingPipelineStage = {
   name: "ImageBasedLightingPipelineStage", // Helps with debugging
 };
 
+const scratchCartesian = new Cartesian2();
+
 /**
  * Add shader code, uniforms, and defines related to image based lighting
  * @param {ModelRenderResources} renderResources
@@ -21,8 +24,18 @@ ImageBasedLightingPipelineStage.process = function (
   frameState,
 ) {
   const imageBasedLighting = model.imageBasedLighting;
+  const environmentMapManager = model.environmentMapManager;
   const shaderBuilder = renderResources.shaderBuilder;
 
+  // If environment maps or spherical harmonics are not specifically provided, use procedural lighting.
+  let specularEnvironmentMapAtlas;
+  if (!defined(imageBasedLighting.specularEnvironmentMaps)) {
+    specularEnvironmentMapAtlas = environmentMapManager.radianceCubeMap;
+  }
+  const sphericalHarmonicCoefficients =
+    imageBasedLighting.sphericalHarmonicCoefficients ??
+    environmentMapManager.sphericalHarmonicCoefficients;
+
   shaderBuilder.addDefine(
     "USE_IBL_LIGHTING",
     undefined,
@@ -47,7 +60,18 @@ ImageBasedLightingPipelineStage.process = function (
       );
     }
 
-    if (defined(imageBasedLighting.sphericalHarmonicCoefficients)) {
+    if (defined(specularEnvironmentMapAtlas)) {
+      shaderBuilder.addDefine(
+        "COMPUTE_POSITION_WC_ATMOSPHERE",
+        undefined,
+        ShaderDestination.BOTH,
+      );
+    }
+
+    if (
+      defined(sphericalHarmonicCoefficients) &&
+      defined(sphericalHarmonicCoefficients[0])
+    ) {
       shaderBuilder.addDefine(
         "DIFFUSE_IBL",
         undefined,
@@ -72,8 +96,9 @@ ImageBasedLightingPipelineStage.process = function (
     }
 
     if (
-      defined(imageBasedLighting.specularEnvironmentCubeMap) &&
-      imageBasedLighting.specularEnvironmentCubeMap.ready
+      (defined(imageBasedLighting.specularEnvironmentCubeMap) &&
+        imageBasedLighting.specularEnvironmentCubeMap.ready) ||
+      defined(specularEnvironmentMapAtlas)
     ) {
       shaderBuilder.addDefine(
         "SPECULAR_IBL",
@@ -104,33 +129,21 @@ ImageBasedLightingPipelineStage.process = function (
     }
   }
 
-  if (defined(imageBasedLighting.luminanceAtZenith)) {
-    shaderBuilder.addDefine(
-      "USE_SUN_LUMINANCE",
-      undefined,
-      ShaderDestination.FRAGMENT,
-    );
-    shaderBuilder.addUniform(
-      "float",
-      "model_luminanceAtZenith",
-      ShaderDestination.FRAGMENT,
-    );
-  }
-
   shaderBuilder.addFragmentLines(ImageBasedLightingStageFS);
 
   const uniformMap = {
     model_iblFactor: function () {
-      return imageBasedLighting.imageBasedLightingFactor;
+      return Cartesian2.multiplyByScalar(
+        imageBasedLighting.imageBasedLightingFactor,
+        environmentMapManager?.intensity || 1.0,
+        scratchCartesian,
+      );
     },
     model_iblReferenceFrameMatrix: function () {
       return model._iblReferenceFrameMatrix;
     },
-    model_luminanceAtZenith: function () {
-      return imageBasedLighting.luminanceAtZenith;
-    },
     model_sphericalHarmonicCoefficients: function () {
-      return imageBasedLighting.sphericalHarmonicCoefficients;
+      return sphericalHarmonicCoefficients;
     },
     model_specularEnvironmentMaps: function () {
       return imageBasedLighting.specularEnvironmentCubeMap.texture;
@@ -140,6 +153,15 @@ ImageBasedLightingPipelineStage.process = function (
     },
   };
 
+  if (defined(specularEnvironmentMapAtlas)) {
+    uniformMap.model_specularEnvironmentMaps = function () {
+      return specularEnvironmentMapAtlas;
+    };
+    uniformMap.model_specularEnvironmentMapsMaximumLOD = function () {
+      return environmentMapManager.maximumMipmapLevel;
+    };
+  }
+
   renderResources.uniformMap = combine(uniformMap, renderResources.uniformMap);
 };