@cesium/engine 10.1.0 → 11.0.0

package/Source/Scene/PostProcessStageCollection.js

@@ -12,7 +12,7 @@ import TextureWrap from "../Renderer/TextureWrap.js";
 import PassThrough from "../Shaders/PostProcessStages/PassThrough.js";
 import PostProcessStageLibrary from "./PostProcessStageLibrary.js";
 import PostProcessStageTextureCache from "./PostProcessStageTextureCache.js";
-import Tonemapper from "./Tonemapper.js";
+import Tonemapper, { validateTonemapper } from "./Tonemapper.js";
 
 const stackScratch = [];
 
@@ -41,11 +41,12 @@ function PostProcessStageCollection() {
   // Some shaders, such as the atmosphere and ground atmosphere, output values slightly over 1.0.
   this._autoExposureEnabled = false;
   this._autoExposure = PostProcessStageLibrary.createAutoExposureStage();
+  this._exposure = 1.0;
   this._tonemapping = undefined;
   this._tonemapper = undefined;
 
-  // set tonemapper and tonemapping
-  this.tonemapper = Tonemapper.ACES;
+  // set tonemapper and tonemapping using the setter
+  this.tonemapper = Tonemapper.PBR_NEUTRAL;
 
   const tonemapping = this._tonemapping;
 
@@ -313,11 +314,14 @@ Object.defineProperties(PostProcessStageCollection.prototype, {
   },
 
   /**
-   * Gets and sets the tonemapping algorithm used when rendering with high dynamic range.
+   * Specifies the tonemapping algorithm used when rendering with high dynamic range.
+   * {@link https://sandcastle.cesium.com/?src=High%20Dynamic%20Range.html|Sandcastle Demo}
    *
+   * @example viewer.scene.postProcessStages.tonemapper = Cesium.Tonemapper.ACES;
+   *
+   * @default Tonemapper.PBR_NEUTRAL
    * @memberof PostProcessStageCollection.prototype
    * @type {Tonemapper}
-   * @private
    */
   tonemapper: {
     get: function () {
@@ -328,7 +332,7 @@ Object.defineProperties(PostProcessStageCollection.prototype, {
         return;
       }
       //>>includeStart('debug', pragmas.debug);
-      if (!Tonemapper.validate(value)) {
+      if (!validateTonemapper(value)) {
         throw new DeveloperError("tonemapper was set to an invalid value.");
       }
       //>>includeEnd('debug');
@@ -339,26 +343,31 @@ Object.defineProperties(PostProcessStageCollection.prototype, {
       }
 
       const useAutoExposure = this._autoExposureEnabled;
-      let tonemapper;
+      let tonemapping;
 
       switch (value) {
         case Tonemapper.REINHARD:
-          tonemapper = PostProcessStageLibrary.createReinhardTonemappingStage(
+          tonemapping = PostProcessStageLibrary.createReinhardTonemappingStage(
             useAutoExposure
           );
           break;
         case Tonemapper.MODIFIED_REINHARD:
-          tonemapper = PostProcessStageLibrary.createModifiedReinhardTonemappingStage(
+          tonemapping = PostProcessStageLibrary.createModifiedReinhardTonemappingStage(
             useAutoExposure
           );
           break;
         case Tonemapper.FILMIC:
-          tonemapper = PostProcessStageLibrary.createFilmicTonemappingStage(
+          tonemapping = PostProcessStageLibrary.createFilmicTonemappingStage(
+            useAutoExposure
+          );
+          break;
+        case Tonemapper.PBR_NEUTRAL:
+          tonemapping = PostProcessStageLibrary.createPbrNeutralTonemappingStage(
             useAutoExposure
           );
           break;
         default:
-          tonemapper = PostProcessStageLibrary.createAcesTonemappingStage(
+          tonemapping = PostProcessStageLibrary.createAcesTonemappingStage(
             useAutoExposure
           );
           break;
@@ -366,22 +375,43 @@ Object.defineProperties(PostProcessStageCollection.prototype, {
 
       if (useAutoExposure) {
         const autoexposure = this._autoExposure;
-        tonemapper.uniforms.autoExposure = function () {
+        tonemapping.uniforms.autoExposure = function () {
           return autoexposure.outputTexture;
         };
+      } else {
+        tonemapping.uniforms.exposure = this._exposure;
       }
 
       this._tonemapper = value;
-      this._tonemapping = tonemapper;
+      this._tonemapping = tonemapping;
 
       if (defined(this._stageNames)) {
-        this._stageNames[tonemapper.name] = tonemapper;
-        tonemapper._textureCache = this._textureCache;
+        this._stageNames[tonemapping.name] = tonemapping;
+        tonemapping._textureCache = this._textureCache;
       }
 
       this._textureCacheDirty = true;
     },
   },
+
+  /**
+   * Control the exposure when HDR is on. Less than 1.0 makes the tonemapping darker while greater than 1.0 makes it brighter.
+   *
+   * @example viewer.scene.postProcessStages.exposure = 1.0;
+   *
+   * @default 1.0
+   * @memberof PostProcessStageCollection.prototype
+   * @type {number}
+   */
+  exposure: {
+    get: function () {
+      return this._exposure;
+    },
+    set: function (value) {
+      this._tonemapping.uniforms.exposure = value;
+      this._exposure = value;
+    },
+  },
 });
 
 function removeStages(collection) {

package/Source/Scene/PostProcessStageLibrary.js

@@ -14,6 +14,7 @@ import DepthOfField from "../Shaders/PostProcessStages/DepthOfField.js";
 import DepthView from "../Shaders/PostProcessStages/DepthView.js";
 import EdgeDetection from "../Shaders/PostProcessStages/EdgeDetection.js";
 import FilmicTonemapping from "../Shaders/PostProcessStages/FilmicTonemapping.js";
+import PbrNeutralTonemapping from "../Shaders/PostProcessStages/PbrNeutralTonemapping.js";
 import FXAA from "../Shaders/PostProcessStages/FXAA.js";
 import GaussianBlur1D from "../Shaders/PostProcessStages/GaussianBlur1D.js";
 import LensFlare from "../Shaders/PostProcessStages/LensFlare.js";
@@ -669,6 +670,7 @@ PostProcessStageLibrary.createAcesTonemappingStage = function (
     fragmentShader: fs,
     uniforms: {
       autoExposure: undefined,
+      exposure: 1.0,
     },
   });
 };
@@ -689,6 +691,28 @@ PostProcessStageLibrary.createFilmicTonemappingStage = function (
     fragmentShader: fs,
     uniforms: {
       autoExposure: undefined,
+      exposure: 1.0,
+    },
+  });
+};
+
+/**
+ * Creates a post-process stage that applies filmic tonemapping operator.
+ * @param {boolean} useAutoExposure Whether or not to use auto-exposure.
+ * @return {PostProcessStage} A post-process stage that applies filmic tonemapping operator.
+ * @private
+ */
+PostProcessStageLibrary.createPbrNeutralTonemappingStage = function (
+  useAutoExposure
+) {
+  let fs = useAutoExposure ? "#define AUTO_EXPOSURE\n" : "";
+  fs += PbrNeutralTonemapping;
+  return new PostProcessStage({
+    name: "czm_pbr_neutral",
+    fragmentShader: fs,
+    uniforms: {
+      autoExposure: undefined,
+      exposure: 1.0,
     },
   });
 };
@@ -709,6 +733,7 @@ PostProcessStageLibrary.createReinhardTonemappingStage = function (
     fragmentShader: fs,
     uniforms: {
       autoExposure: undefined,
+      exposure: 1.0,
     },
   });
 };
@@ -730,6 +755,7 @@ PostProcessStageLibrary.createModifiedReinhardTonemappingStage = function (
     uniforms: {
       white: Color.WHITE,
       autoExposure: undefined,
+      exposure: 1.0,
     },
   });
 };

package/Source/Scene/Scene.js

@@ -57,7 +57,6 @@ import GlobeTranslucencyState from "./GlobeTranslucencyState.js";
 import InvertClassification from "./InvertClassification.js";
 import JobScheduler from "./JobScheduler.js";
 import MapMode2D from "./MapMode2D.js";
-import OctahedralProjectedCubeMap from "./OctahedralProjectedCubeMap.js";
 import PerformanceDisplay from "./PerformanceDisplay.js";
 import PerInstanceColorAppearance from "./PerInstanceColorAppearance.js";
 import Picking from "./Picking.js";
@@ -69,6 +68,7 @@ import SceneTransforms from "./SceneTransforms.js";
 import SceneTransitioner from "./SceneTransitioner.js";
 import ScreenSpaceCameraController from "./ScreenSpaceCameraController.js";
 import ShadowMap from "./ShadowMap.js";
+import SpecularEnvironmentCubeMap from "./SpecularEnvironmentCubeMap.js";
 import StencilConstants from "./StencilConstants.js";
 import SunLight from "./SunLight.js";
 import SunPostProcess from "./SunPostProcess.js";
@@ -107,7 +107,7 @@ const requestRenderAfterFrame = function (scene) {
  * @param {boolean} [options.requestRenderMode=false] If true, rendering a frame will only occur when needed as determined by changes within the scene. Enabling improves performance of the application, but requires using {@link Scene#requestRender} to render a new frame explicitly in this mode. This will be necessary in many cases after making changes to the scene in other parts of the API. See {@link https://cesium.com/blog/2018/01/24/cesium-scene-rendering-performance/|Improving Performance with Explicit Rendering}.
  * @param {number} [options.maximumRenderTimeChange=0.0] If requestRenderMode is true, this value defines the maximum change in simulation time allowed before a render is requested. See {@link https://cesium.com/blog/2018/01/24/cesium-scene-rendering-performance/|Improving Performance with Explicit Rendering}.
  * @param {number} [options.depthPlaneEllipsoidOffset=0.0] Adjust the DepthPlane to address rendering artefacts below ellipsoid zero elevation.
- * @param {number} [options.msaaSamples=1] If provided, this value controls the rate of multisample antialiasing. Typical multisampling rates are 2, 4, and sometimes 8 samples per pixel. Higher sampling rates of MSAA may impact performance in exchange for improved visual quality. This value only applies to WebGL2 contexts that support multisample render targets.
+ * @param {number} [options.msaaSamples=4] If provided, this value controls the rate of multisample antialiasing. Typical multisampling rates are 2, 4, and sometimes 8 samples per pixel. Higher sampling rates of MSAA may impact performance in exchange for improved visual quality. This value only applies to WebGL2 contexts that support multisample render targets. Set to 1 to disable MSAA.
  *
  * @see CesiumWidget
  * @see {@link http://www.khronos.org/registry/webgl/specs/latest/#5.2|WebGLContextAttributes}
@@ -228,7 +228,7 @@ function Scene(options) {
   this._minimumDisableDepthTestDistance = 0.0;
   this._debugInspector = new DebugInspector();
 
-  this._msaaSamples = defaultValue(options.msaaSamples, 1);
+  this._msaaSamples = defaultValue(options.msaaSamples, 4);
 
   /**
    * Exceptions occurring in <code>render</code> are always caught in order to raise the
@@ -738,7 +738,7 @@ function Scene(options) {
    * @type {string}
    */
   this.specularEnvironmentMaps = undefined;
-  this._specularEnvironmentMapAtlas = undefined;
+  this._specularEnvironmentCubeMap = undefined;
 
   /**
    * The light source for shading. Defaults to a directional light from the Sun.
@@ -927,7 +927,7 @@ Object.defineProperties(Scene.prototype, {
    */
   specularEnvironmentMapsSupported: {
     get: function () {
-      return OctahedralProjectedCubeMap.isSupported(this._context);
+      return SpecularEnvironmentCubeMap.isSupported(this._context);
     },
   },
 
@@ -1630,7 +1630,7 @@ Object.defineProperties(Scene.prototype, {
    * The sample rate of multisample antialiasing (values greater than 1 enable MSAA).
    * @memberof Scene.prototype
    * @type {number}
-   * @default 1
+   * @default 4
    */
   msaaSamples: {
     get: function () {
@@ -1964,11 +1964,11 @@ Scene.prototype.updateFrameState = function () {
   frameState.verticalExaggerationRelativeHeight = this.verticalExaggerationRelativeHeight;
 
   if (
-    defined(this._specularEnvironmentMapAtlas) &&
-    this._specularEnvironmentMapAtlas.ready
+    defined(this._specularEnvironmentCubeMap) &&
+    this._specularEnvironmentCubeMap.ready
   ) {
-    frameState.specularEnvironmentMaps = this._specularEnvironmentMapAtlas.texture;
-    frameState.specularEnvironmentMapsMaximumLOD = this._specularEnvironmentMapAtlas.maximumMipmapLevel;
+    frameState.specularEnvironmentMaps = this._specularEnvironmentCubeMap.texture;
+    frameState.specularEnvironmentMapsMaximumLOD = this._specularEnvironmentCubeMap.maximumMipmapLevel;
   } else {
     frameState.specularEnvironmentMaps = undefined;
     frameState.specularEnvironmentMapsMaximumLOD = undefined;
@@ -3328,20 +3328,18 @@ Scene.prototype.updateEnvironment = function () {
   );
 
   const envMaps = this.specularEnvironmentMaps;
-  let envMapAtlas = this._specularEnvironmentMapAtlas;
-  if (
-    defined(envMaps) &&
-    (!defined(envMapAtlas) || envMapAtlas.url !== envMaps)
-  ) {
-    envMapAtlas = envMapAtlas && envMapAtlas.destroy();
-    this._specularEnvironmentMapAtlas = new OctahedralProjectedCubeMap(envMaps);
-  } else if (!defined(envMaps) && defined(envMapAtlas)) {
-    envMapAtlas.destroy();
-    this._specularEnvironmentMapAtlas = undefined;
+  let specularEnvironmentCubeMap = this._specularEnvironmentCubeMap;
+  if (defined(envMaps) && specularEnvironmentCubeMap?.url !== envMaps) {
+    specularEnvironmentCubeMap =
+      specularEnvironmentCubeMap && specularEnvironmentCubeMap.destroy();
+    this._specularEnvironmentCubeMap = new SpecularEnvironmentCubeMap(envMaps);
+  } else if (!defined(envMaps) && defined(specularEnvironmentCubeMap)) {
+    specularEnvironmentCubeMap.destroy();
+    this._specularEnvironmentCubeMap = undefined;
   }
 
-  if (defined(this._specularEnvironmentMapAtlas)) {
-    this._specularEnvironmentMapAtlas.update(frameState);
+  if (defined(this._specularEnvironmentCubeMap)) {
+    this._specularEnvironmentCubeMap.update(frameState);
   }
 };
 

package/Source/Scene/SceneTransforms.js

@@ -4,7 +4,6 @@ import Cartesian3 from "../Core/Cartesian3.js";
 import Cartesian4 from "../Core/Cartesian4.js";
 import Cartographic from "../Core/Cartographic.js";
 import defined from "../Core/defined.js";
-import deprecationWarning from "../Core/deprecationWarning.js";
 import DeveloperError from "../Core/DeveloperError.js";
 import CesiumMath from "../Core/Math.js";
 import Matrix4 from "../Core/Matrix4.js";
@@ -53,33 +52,6 @@ SceneTransforms.worldToWindowCoordinates = function (scene, position, result) {
   );
 };
 
-/**
- * Transforms a position in WGS84 coordinates to window coordinates.  This is commonly used to place an
- * HTML element at the same screen position as an object in the scene.
- *
- * @param {Scene} scene The scene.
- * @param {Cartesian3} position The position in WGS84 (world) coordinates.
- * @param {Cartesian2} [result] An optional object to return the input position transformed to window coordinates.
- * @returns {Cartesian2|undefined} The modified result parameter or a new Cartesian2 instance if one was not provided.  This may be <code>undefined</code> if the input position is near the center of the ellipsoid.
- *
- * @example
- * // Output the window position of longitude/latitude (0, 0) every time the mouse moves.
- * const scene = widget.scene;
- * const ellipsoid = scene.ellipsoid;
- * const position = Cesium.Cartesian3.fromDegrees(0.0, 0.0);
- * const handler = new Cesium.ScreenSpaceEventHandler(scene.canvas);
- * handler.setInputAction(function(movement) {
- *     console.log(Cesium.SceneTransforms.wgs84ToWindowCoordinates(scene, position));
- * }, Cesium.ScreenSpaceEventType.MOUSE_MOVE);
- */
-SceneTransforms.wgs84ToWindowCoordinates = function (scene, position, result) {
-  deprecationWarning(
-    "SceneTransforms.wgs84ToWindowCoordinates",
-    "SceneTransforms.wgs84ToWindowCoordinates has been deprecated. It will be removed in 1.21. Use SceneTransforms.worldToWindowCoordinates instead."
-  );
-  return SceneTransforms.worldToWindowCoordinates(scene, position, result);
-};
-
 const scratchCartesian4 = new Cartesian4();
 const scratchEyeOffset = new Cartesian3();
 
@@ -320,40 +292,6 @@ SceneTransforms.worldToDrawingBufferCoordinates = function (
   return SceneTransforms.transformWindowToDrawingBuffer(scene, result, result);
 };
 
-/**
- * Transforms a position in world coordinates to drawing buffer coordinates.  This may produce different
- * results from SceneTransforms.wgs84ToWindowCoordinates when the browser zoom is not 100%, or on high-DPI displays.
- *
- * @param {Scene} scene The scene.
- * @param {Cartesian3} position The position in world (WGS84 or alternative ellipsoid) coordinates.
- * @param {Cartesian2} [result] An optional object to return the input position transformed to window coordinates.
- * @returns {Cartesian2|undefined} The modified result parameter or a new Cartesian2 instance if one was not provided.  This may be <code>undefined</code> if the input position is near the center of the ellipsoid.
- *
- * @example
- * // Output the window position of longitude/latitude (0, 0) every time the mouse moves.
- * const position = Cesium.Cartesian3.fromDegrees(0.0, 0.0);
- * const handler = new Cesium.ScreenSpaceEventHandler(scene.canvas);
- * handler.setInputAction(function(movement) {
- *     console.log(Cesium.SceneTransforms.wgs84ToWindowCoordinates(scene, position));
- * }, Cesium.ScreenSpaceEventType.MOUSE_MOVE);
- */
-SceneTransforms.wgs84ToDrawingBufferCoordinates = function (
-  scene,
-  position,
-  result
-) {
-  deprecationWarning(
-    "SceneTransforms.wgs84ToDrawingBufferCoordinates",
-    "SceneTransforms.wgs84ToDrawingBufferCoordinates has been deprecated. It will be removed in 1.21. Use SceneTransforms.worldToDrawingBufferCoordinates instead."
-  );
-
-  return SceneTransforms.worldToDrawingBufferCoordinates(
-    scene,
-    position,
-    result
-  );
-};
-
 const projectedPosition = new Cartesian3();
 const positionInCartographic = new Cartographic();
 

package/Source/Scene/ScreenSpaceCameraController.js

@@ -137,6 +137,14 @@ function ScreenSpaceCameraController(scene) {
    * @default {@link Number.POSITIVE_INFINITY}
    */
   this.maximumZoomDistance = Number.POSITIVE_INFINITY;
+
+  /**
+   * A multiplier for the speed at which the camera will zoom.
+   * @type {Number}
+   * @default 5.0
+   */
+  this.zoomFactor = 5.0;
+
   /**
    * The input that allows the user to pan around the map. This only applies in 2D and Columbus view modes.
    * <p>
@@ -324,7 +332,6 @@ function ScreenSpaceCameraController(scene) {
   );
 
   // Constants, Make any of these public?
-  this._zoomFactor = 5.0;
   this._rotateFactor = undefined;
   this._rotateRateRangeAdjustment = undefined;
   this._maximumRotateRate = 1.77;
@@ -1005,7 +1012,7 @@ function zoom2D(controller, startPosition, movement) {
     controller,
     startPosition,
     movement,
-    controller._zoomFactor,
+    controller.zoomFactor,
     camera.getMagnitude()
   );
 }
@@ -1763,7 +1770,7 @@ function zoomCV(controller, startPosition, movement) {
     controller,
     startPosition,
     movement,
-    controller._zoomFactor,
+    controller.zoomFactor,
     distance
   );
 }
@@ -2363,7 +2370,7 @@ function zoom3D(controller, startPosition, movement) {
     controller,
     startPosition,
     movement,
-    controller._zoomFactor,
+    controller.zoomFactor,
     distance,
     Cartesian3.dot(unitPosition, camera.direction)
   );

package/Source/Scene/SkyBox.js

@@ -1,6 +1,7 @@
 import buildModuleUrl from "../Core/buildModuleUrl.js";
 import BoxGeometry from "../Core/BoxGeometry.js";
 import Cartesian3 from "../Core/Cartesian3.js";
+import Check from "../Core/Check.js";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
 import destroyObject from "../Core/destroyObject.js";
@@ -95,49 +96,42 @@ function SkyBox(options) {
  */
 SkyBox.prototype.update = function (frameState, useHdr) {
   const that = this;
+  const { mode, passes, context } = frameState;
 
   if (!this.show) {
     return undefined;
   }
 
-  if (
-    frameState.mode !== SceneMode.SCENE3D &&
-    frameState.mode !== SceneMode.MORPHING
-  ) {
+  if (mode !== SceneMode.SCENE3D && mode !== SceneMode.MORPHING) {
     return undefined;
   }
 
   // The sky box is only rendered during the render pass; it is not pickable, it doesn't cast shadows, etc.
-  if (!frameState.passes.render) {
+  if (!passes.render) {
     return undefined;
   }
 
-  const context = frameState.context;
-
   if (this._sources !== this.sources) {
     this._sources = this.sources;
     const sources = this.sources;
 
     //>>includeStart('debug', pragmas.debug);
+    Check.defined("this.sources", sources);
     if (
-      !defined(sources.positiveX) ||
-      !defined(sources.negativeX) ||
-      !defined(sources.positiveY) ||
-      !defined(sources.negativeY) ||
-      !defined(sources.positiveZ) ||
-      !defined(sources.negativeZ)
+      Object.values(CubeMap.FaceName).some(
+        (faceName) => !defined(sources[faceName])
+      )
     ) {
       throw new DeveloperError(
-        "this.sources is required and must have positiveX, negativeX, positiveY, negativeY, positiveZ, and negativeZ properties."
+        "this.sources must have positiveX, negativeX, positiveY, negativeY, positiveZ, and negativeZ properties."
       );
     }
 
+    const sourceType = typeof sources.positiveX;
     if (
-      typeof sources.positiveX !== typeof sources.negativeX ||
-      typeof sources.positiveX !== typeof sources.positiveY ||
-      typeof sources.positiveX !== typeof sources.negativeY ||
-      typeof sources.positiveX !== typeof sources.positiveZ ||
-      typeof sources.positiveX !== typeof sources.negativeZ
+      Object.values(CubeMap.FaceName).some(
+        (faceName) => typeof sources[faceName] !== sourceType
+      )
     ) {
       throw new DeveloperError(
         "this.sources properties must all be the same type."