@cesium/engine 2.0.0 → 2.2.0

package/Source/Widget/CesiumWidget.js

@@ -1,9 +1,9 @@
 import buildModuleUrl from "../Core/buildModuleUrl.js";
-import createWorldImagery from "../Scene/createWorldImagery.js";
 import Cartesian3 from "../Core/Cartesian3.js";
 import Clock from "../Core/Clock.js";
 import defaultValue from "../Core/defaultValue.js";
 import defined from "../Core/defined.js";
+import deprecationWarning from "../Core/deprecationWarning.js";
 import destroyObject from "../Core/destroyObject.js";
 import DeveloperError from "../Core/DeveloperError.js";
 import Ellipsoid from "../Core/Ellipsoid.js";
@@ -11,6 +11,7 @@ import FeatureDetection from "../Core/FeatureDetection.js";
 import formatError from "../Core/formatError.js";
 import getElement from "../DataSources/getElement.js";
 import Globe from "../Scene/Globe.js";
+import ImageryLayer from "../Scene/ImageryLayer.js";
 import Moon from "../Scene/Moon.js";
 import Scene from "../Scene/Scene.js";
 import SceneMode from "../Scene/SceneMode.js";
@@ -120,33 +121,35 @@ function configureCameraFrustum(widget) {
  * @alias CesiumWidget
  * @constructor
  *
- * @param {Element|String} container The DOM element or ID that will contain the widget.
- * @param {Object} [options] Object with the following properties:
+ * @param {Element|string} container The DOM element or ID that will contain the widget.
+ * @param {object} [options] Object with the following properties:
  * @param {Clock} [options.clock=new Clock()] The clock to use to control current time.
- * @param {ImageryProvider | false} [options.imageryProvider=createWorldImagery()] The imagery provider to serve as the base layer. If set to <code>false</code>, no imagery provider will be added.
+ * @param {ImageryProvider | false} [options.imageryProvider=createWorldImagery()] The imagery provider to serve as the base layer. If set to <code>false</code>, no imagery provider will be added. Deprecated.
+ * @param {ImageryLayer|false} [baseLayer=ImageryLayer.fromWorldImagery()] The bottommost imagery layer applied to the globe. If set to <code>false</code>, no imagery provider will be added.
  * @param {TerrainProvider} [options.terrainProvider=new EllipsoidTerrainProvider] The terrain provider.
+ * @param {Terrain} [options.terrain] A terrain object which handles asynchronous terrain provider. Can only specify if options.terrainProvider is undefined.
  * @param {SkyBox| false} [options.skyBox] The skybox used to render the stars.  When <code>undefined</code>, the default stars are used. If set to <code>false</code>, no skyBox, Sun, or Moon will be added.
  * @param {SkyAtmosphere | false} [options.skyAtmosphere] Blue sky, and the glow around the Earth's limb.  Set to <code>false</code> to turn it off.
  * @param {SceneMode} [options.sceneMode=SceneMode.SCENE3D] The initial scene mode.
- * @param {Boolean} [options.scene3DOnly=false] When <code>true</code>, each geometry instance will only be rendered in 3D to save GPU memory.
- * @param {Boolean} [options.orderIndependentTranslucency=true] If true and the configuration supports it, use order independent translucency.
+ * @param {boolean} [options.scene3DOnly=false] When <code>true</code>, each geometry instance will only be rendered in 3D to save GPU memory.
+ * @param {boolean} [options.orderIndependentTranslucency=true] If true and the configuration supports it, use order independent translucency.
  * @param {MapProjection} [options.mapProjection=new GeographicProjection()] The map projection to use in 2D and Columbus View modes.
  * @param {Globe | false} [options.globe=new Globe(mapProjection.ellipsoid)] The globe to use in the scene.  If set to <code>false</code>, no globe will be added.
- * @param {Boolean} [options.useDefaultRenderLoop=true] True if this widget should control the render loop, false otherwise.
- * @param {Boolean} [options.useBrowserRecommendedResolution=true] If true, render at the browser's recommended resolution and ignore <code>window.devicePixelRatio</code>.
- * @param {Number} [options.targetFrameRate] The target frame rate when using the default render loop.
- * @param {Boolean} [options.showRenderLoopErrors=true] If true, this widget will automatically display an HTML panel to the user containing the error, if a render loop error occurs.
+ * @param {boolean} [options.useDefaultRenderLoop=true] True if this widget should control the render loop, false otherwise.
+ * @param {boolean} [options.useBrowserRecommendedResolution=true] If true, render at the browser's recommended resolution and ignore <code>window.devicePixelRatio</code>.
+ * @param {number} [options.targetFrameRate] The target frame rate when using the default render loop.
+ * @param {boolean} [options.showRenderLoopErrors=true] If true, this widget will automatically display an HTML panel to the user containing the error, if a render loop error occurs.
  * @param {ContextOptions} [options.contextOptions] Context and WebGL creation properties passed to {@link Scene}.
- * @param {Element|String} [options.creditContainer] The DOM element or ID that will contain the {@link CreditDisplay}.  If not specified, the credits are added
+ * @param {Element|string} [options.creditContainer] The DOM element or ID that will contain the {@link CreditDisplay}.  If not specified, the credits are added
  *        to the bottom of the widget itself.
- * @param {Element|String} [options.creditViewport] The DOM element or ID that will contain the credit pop up created by the {@link CreditDisplay}.  If not specified, it will appear over the widget itself.
- * @param {Boolean} [options.shadows=false] Determines if shadows are cast by light sources.
+ * @param {Element|string} [options.creditViewport] The DOM element or ID that will contain the credit pop up created by the {@link CreditDisplay}.  If not specified, it will appear over the widget itself.
+ * @param {boolean} [options.shadows=false] Determines if shadows are cast by light sources.
  * @param {ShadowMode} [options.terrainShadows=ShadowMode.RECEIVE_ONLY] Determines if the terrain casts or receives shadows from light sources.
  * @param {MapMode2D} [options.mapMode2D=MapMode2D.INFINITE_SCROLL] Determines if the 2D map is rotatable or can be scrolled infinitely in the horizontal direction.
- * @param {Boolean} [options.blurActiveElementOnCanvasFocus=true] If true, the active element will blur when the viewer's canvas is clicked. Setting this to false is useful for cases when the canvas is clicked only for retrieving position or an entity data without actually meaning to set the canvas to be the active element.
- * @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.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 {boolean} [options.blurActiveElementOnCanvasFocus=true] If true, the active element will blur when the viewer's canvas is clicked. Setting this to false is useful for cases when the canvas is clicked only for retrieving position or an entity data without actually meaning to set the canvas to be the active element.
+ * @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.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.
  *
  * @exception {DeveloperError} Element with id "container" does not exist in the document.
  *
@@ -156,26 +159,26 @@ function configureCameraFrustum(widget) {
  * // For each example, include a link to CesiumWidget.css stylesheet in HTML head,
  * // and in the body, include: <div id="cesiumContainer"></div>
  *
- * //Widget with no terrain and default Bing Maps imagery provider.
- * const widget = new Cesium.CesiumWidget('cesiumContainer');
+ * // Widget with no terrain and default Bing Maps imagery provider.
+ * const widget = new Cesium.CesiumWidget("cesiumContainer");
  *
- * //Widget with ion imagery and Cesium World Terrain.
- * const widget2 = new Cesium.CesiumWidget('cesiumContainer', {
- *     imageryProvider : Cesium.createWorldImagery(),
- *     terrainProvider : Cesium.createWorldTerrain(),
- *     skyBox : new Cesium.SkyBox({
- *         sources : {
- *           positiveX : 'stars/TychoSkymapII.t3_08192x04096_80_px.jpg',
- *           negativeX : 'stars/TychoSkymapII.t3_08192x04096_80_mx.jpg',
- *           positiveY : 'stars/TychoSkymapII.t3_08192x04096_80_py.jpg',
- *           negativeY : 'stars/TychoSkymapII.t3_08192x04096_80_my.jpg',
- *           positiveZ : 'stars/TychoSkymapII.t3_08192x04096_80_pz.jpg',
- *           negativeZ : 'stars/TychoSkymapII.t3_08192x04096_80_mz.jpg'
- *         }
+ * // Widget with ion imagery and Cesium World Terrain.
+ * const widget2 = new Cesium.CesiumWidget("cesiumContainer", {
+ *     baseLayer: Cesium.ImageryLayer.fromWorldTerrain(),
+ *     terrain: Cesium.Terrain.fromWorldTerrain()
+ *     skyBox: new Cesium.SkyBox({
+ *       sources: {
+ *         positiveX: "stars/TychoSkymapII.t3_08192x04096_80_px.jpg",
+ *         negativeX: "stars/TychoSkymapII.t3_08192x04096_80_mx.jpg",
+ *         positiveY: "stars/TychoSkymapII.t3_08192x04096_80_py.jpg",
+ *         negativeY: "stars/TychoSkymapII.t3_08192x04096_80_my.jpg",
+ *         positiveZ: "stars/TychoSkymapII.t3_08192x04096_80_pz.jpg",
+ *         negativeZ: "stars/TychoSkymapII.t3_08192x04096_80_mz.jpg"
+ *       }
  *     }),
  *     // Show Columbus View map with Web Mercator projection
- *     sceneMode : Cesium.SceneMode.COLUMBUS_VIEW,
- *     mapProjection : new Cesium.WebMercatorProjection()
+ *     sceneMode: Cesium.SceneMode.COLUMBUS_VIEW,
+ *     mapProjection: new Cesium.WebMercatorProjection()
  * });
  */
 function CesiumWidget(container, options) {
@@ -340,22 +343,47 @@ function CesiumWidget(container, options) {
       scene.skyAtmosphere = skyAtmosphere;
     }
 
-    //Set the base imagery layer
-    let imageryProvider =
-      options.globe === false ? false : options.imageryProvider;
-    if (!defined(imageryProvider)) {
-      imageryProvider = createWorldImagery();
+    if (defined(options.imageryProvider)) {
+      deprecationWarning(
+        "CesiumWidget options.imageryProvider",
+        "options.imageryProvider was deprecated in CesiumJS 1.104.  It will be in CesiumJS 1.107.  Use options.baseLayer instead."
+      );
     }
 
-    if (imageryProvider !== false) {
-      scene.imageryLayers.addImageryProvider(imageryProvider);
+    // Set the base imagery layer
+    let baseLayer = options.baseLayer;
+    if (
+      options.globe !== false &&
+      baseLayer !== false &&
+      options.imageryProvider !== false
+    ) {
+      if (defined(options.imageryProvider) && !defined(baseLayer)) {
+        baseLayer = new ImageryLayer(options.imageryProvider);
+      }
+
+      if (!defined(baseLayer)) {
+        baseLayer = ImageryLayer.fromWorldImagery();
+      }
+      scene.imageryLayers.add(baseLayer);
     }
 
-    //Set the terrain provider if one is provided.
+    // Set the terrain provider if one is provided.
     if (defined(options.terrainProvider) && options.globe !== false) {
       scene.terrainProvider = options.terrainProvider;
     }
 
+    if (defined(options.terrain) && options.globe !== false) {
+      //>>includeStart('debug', pragmas.debug);
+      if (defined(options.terrainProvider)) {
+        throw new DeveloperError(
+          "Specify either options.terrainProvider or options.terrain."
+        );
+      }
+      //>>includeEnd('debug')
+
+      scene.setTerrain(options.terrain);
+    }
+
     this._screenSpaceEventHandler = new ScreenSpaceEventHandler(canvas);
 
     if (defined(options.sceneMode)) {
@@ -538,7 +566,7 @@ Object.defineProperties(CesiumWidget.prototype, {
    * than the underlying requestAnimationFrame implementation will have no effect.
    * @memberof CesiumWidget.prototype
    *
-   * @type {Number}
+   * @type {number}
    */
   targetFrameRate: {
     get: function () {
@@ -568,7 +596,7 @@ Object.defineProperties(CesiumWidget.prototype, {
    * after the error.
    * @memberof CesiumWidget.prototype
    *
-   * @type {Boolean}
+   * @type {boolean}
    */
   useDefaultRenderLoop: {
     get: function () {
@@ -593,7 +621,7 @@ Object.defineProperties(CesiumWidget.prototype, {
    * it to 2.0 will cause the scene to be rendered at 1280x960 and then scaled down.
    * @memberof CesiumWidget.prototype
    *
-   * @type {Number}
+   * @type {number}
    * @default 1.0
    */
   resolutionScale: {
@@ -622,7 +650,7 @@ Object.defineProperties(CesiumWidget.prototype, {
    * this flag is true or false.
    * @memberof CesiumWidget.prototype
    *
-   * @type {Boolean}
+   * @type {boolean}
    * @default true
    */
   useBrowserRecommendedResolution: {
@@ -644,9 +672,9 @@ Object.defineProperties(CesiumWidget.prototype, {
  * when a render loop error occurs, if showRenderLoopErrors was not false when the
  * widget was constructed.
  *
- * @param {String} title The title to be displayed on the error panel.  This string is interpreted as text.
- * @param {String} [message] A helpful, user-facing message to display prior to the detailed error information.  This string is interpreted as HTML.
- * @param {String} [error] The error to be displayed on the error panel.  This string is formatted using {@link formatError} and then displayed as text.
+ * @param {string} title The title to be displayed on the error panel.  This string is interpreted as text.
+ * @param {string} [message] A helpful, user-facing message to display prior to the detailed error information.  This string is interpreted as HTML.
+ * @param {string} [error] The error to be displayed on the error panel.  This string is formatted using {@link formatError} and then displayed as text.
  */
 CesiumWidget.prototype.showErrorPanel = function (title, message, error) {
   const element = this._element;
@@ -748,7 +776,7 @@ CesiumWidget.prototype.showErrorPanel = function (title, message, error) {
 };
 
 /**
- * @returns {Boolean} true if the object has been destroyed, false otherwise.
+ * @returns {boolean} true if the object has been destroyed, false otherwise.
  */
 CesiumWidget.prototype.isDestroyed = function () {
   return false;

package/Source/Workers/cesiumWorkerBootstrapper.js

@@ -200,8 +200,8 @@ var requirejs, require, define;
 
   /**
    * Constructs an error with a pointer to an URL with more information.
-   * @param {String} id the error ID that maps to an ID on a web page.
-   * @param {String} msg human readable error.
+   * @param {string} id the error ID that maps to an ID on a web page.
+   * @param {string} msg human readable error.
    * @param {Error} [err] the original error, if there is one.
    * @param {RequireModules} requireModules The modules required but not found.
    * @private
@@ -307,12 +307,12 @@ var requirejs, require, define;
      * @private
      * Given a relative module name, like ./something, normalize it to
      * a real name that can be mapped to a path.
-     * @param {String} name the relative name
-     * @param {String} baseName a real name that the name arg is relative
+     * @param {string} name the relative name
+     * @param {string} baseName a real name that the name arg is relative
      * to.
-     * @param {Boolean} applyMap apply the map config to the value. Should
+     * @param {boolean} applyMap apply the map config to the value. Should
      * only be done if this normalization is for a dependency ID.
-     * @returns {String} normalized name
+     * @returns {string} normalized name
      */
     function normalize(name, baseName, applyMap) {
       var pkgMain,
@@ -464,15 +464,15 @@ var requirejs, require, define;
      * name, and path. If parentModuleMap is provided it will
      * also normalize the name via require.normalize()
      *
-     * @param {String} name the module name
-     * @param {String} [parentModuleMap] parent module map
+     * @param {string} name the module name
+     * @param {string} [parentModuleMap] parent module map
      * for the module name, used to resolve relative names.
-     * @param {Boolean} isNormalized: is the ID already normalized.
+     * @param {boolean} isNormalized: is the ID already normalized.
      * This is true if this call is done for a define() module ID.
-     * @param {Boolean} applyMap: apply the map config to the ID.
+     * @param {boolean} applyMap: apply the map config to the ID.
      * Should only be true if this map is for a dependency.
      * @private
-     * @returns {Object}
+     * @returns {object}
      */
     function makeModuleMap(name, parentModuleMap, isNormalized, applyMap) {
       var url,
@@ -1341,7 +1341,7 @@ var requirejs, require, define;
      * and then removes the event listeners on the node.
      * @param {Event} evt
      * @private
-     * @returns {Object}
+     * @returns {object}
      */
     function getScriptData(evt) {
       //Using currentTarget instead of target for Firefox 2.0's sake. Not
@@ -1400,7 +1400,7 @@ var requirejs, require, define;
       /**
        * @private
        * Set a configuration for the context.
-       * @param {Object} cfg config object to integrate.
+       * @param {object} cfg config object to integrate.
        */
       configure: function (cfg) {
         //Make sure the baseUrl ends in a slash.
@@ -1695,7 +1695,7 @@ var requirejs, require, define;
        * Internal method used by environment adapters to complete a load event.
        * A load event could be a script load or just a load pass from a synchronous
        * load call.
-       * @param {String} moduleName the name of the module to potentially complete.
+       * @param {string} moduleName the name of the module to potentially complete.
        * @private
        */
       completeLoad: function (moduleName) {
@@ -2031,9 +2031,9 @@ var requirejs, require, define;
    * Make this a separate function to allow other environments
    * to override it.
    *
-   * @param {Object} context the require context to find state.
-   * @param {String} moduleName the name of the module.
-   * @param {Object} url the URL to the module.
+   * @param {object} context the require context to find state.
+   * @param {string} moduleName the name of the module.
+   * @param {object} url the URL to the module.
    */
   req.load = function (context, moduleName, url) {
     var config = (context && context.config) || {},
@@ -2278,7 +2278,7 @@ var requirejs, require, define;
    * Executes the text. Normally just uses eval, but can be modified
    * to use a better, environment-specific call. Only used for transpiling
    * loader plugins, not for plain JS modules.
-   * @param {String} text the text to execute/evaluate.
+   * @param {string} text the text to execute/evaluate.
    */
   req.exec = function (text) {
     /*jslint evil: true */

package/Source/WorkersES6/createTaskProcessorWorker.js

@@ -100,10 +100,10 @@ function createTaskProcessorWorker(workerFunction) {
  * A function that performs a calculation in a Web Worker.
  * @callback createTaskProcessorWorker.WorkerFunction
  *
- * @param {Object} parameters Parameters to the calculation.
+ * @param {object} parameters Parameters to the calculation.
  * @param {Array} transferableObjects An array that should be filled with references to objects inside
  *        the result that should be transferred back to the main document instead of copied.
- * @returns {Object} The result of the calculation.
+ * @returns {object} The result of the calculation.
  *
  * @example
  * function calculate(parameters, transferableObjects) {
@@ -124,6 +124,6 @@ function createTaskProcessorWorker(workerFunction) {
  * specifically, task ID management and posting a response message containing the result.
  * @callback createTaskProcessorWorker.TaskProcessorWorkerFunction
  *
- * @param {Object} event The onmessage event object.
+ * @param {object} event The onmessage event object.
  */
 export default createTaskProcessorWorker;