@cesium/engine 13.0.0 → 14.0.0

package/Source/Core/Spherical.js

@@ -107,8 +107,8 @@ Spherical.normalize = function (spherical, result) {
 /**
  * Returns true if the first spherical is equal to the second spherical, false otherwise.
  *
- * @param {Spherical} left The first Spherical to be compared.
- * @param {Spherical} right The second Spherical to be compared.
+ * @param {Spherical} [left] The first Spherical to be compared.
+ * @param {Spherical} [right] The second Spherical to be compared.
  * @returns {boolean} true if the first spherical is equal to the second spherical, false otherwise.
  */
 Spherical.equals = function (left, right) {
@@ -145,7 +145,7 @@ Spherical.equalsEpsilon = function (left, right, epsilon) {
 /**
  * Returns true if this spherical is equal to the provided spherical, false otherwise.
  *
- * @param {Spherical} other The Spherical to be compared.
+ * @param {Spherical} [other] The Spherical to be compared.
  * @returns {boolean} true if this spherical is equal to the provided spherical, false otherwise.
  */
 Spherical.prototype.equals = function (other) {

package/Source/Core/defined.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @example
+ * if (Cesium.defined(positions)) {
+ *      doSomething();
+ * } else {
+ *      doSomethingElse();
+ * }
+ * @param value - The object.
+ * @returns Returns true if the object is defined, returns false otherwise.
+ */
+export default function defined<Type>(value: Type): value is NonNullable<Type>;

package/Source/Core/writeTextToCanvas.js

@@ -104,7 +104,6 @@ let imageSmoothingEnabledName;
  * @param {string} text The text to write.
  * @param {object} [options] Object with the following properties:
  * @param {string} [options.font='10px sans-serif'] The CSS font to use.
- * @param {string} [options.textBaseline='bottom'] The baseline of the text.
  * @param {boolean} [options.fill=true] Whether to fill the text.
  * @param {boolean} [options.stroke=false] Whether to stroke the text.
  * @param {Color} [options.fillColor=Color.WHITE] The fill color.

package/Source/DataSources/BoundingSphereState.js

@@ -3,7 +3,7 @@
  * @enum {number}
  * @private
  */
-const BoundingSphereState = {
+const BoundingSphereState = Object.freeze({
   /**
    * The BoundingSphere has been computed.
    * @type BoundingSphereState
@@ -22,5 +22,5 @@ const BoundingSphereState = {
    * @constant
    */
   FAILED: 2,
-};
-export default Object.freeze(BoundingSphereState);
+});
+export default BoundingSphereState;

package/Source/DataSources/DataSourceClock.js

@@ -108,7 +108,7 @@ DataSourceClock.prototype.clone = function (result) {
 /**
  * Returns true if this DataSourceClock is equivalent to the other
  *
- * @param {DataSourceClock} other The other DataSourceClock to compare to.
+ * @param {DataSourceClock} [other] The other DataSourceClock to compare to.
  * @returns {boolean} <code>true</code> if the DataSourceClocks are equal; otherwise, <code>false</code>.
  */
 DataSourceClock.prototype.equals = function (other) {

package/Source/DataSources/DataSourceDisplay.js

@@ -330,7 +330,10 @@ DataSourceDisplay.prototype.update = function (time) {
   if (!this._ready && result) {
     this._scene.requestRender();
   }
-  this._ready = result;
+
+  // once the DataSourceDisplay is ready it should stay ready to prevent
+  // entities from breaking updates when they become "un-ready"
+  this._ready = this._ready || result;
 
   return result;
 };
@@ -386,7 +389,7 @@ DataSourceDisplay.prototype.getBoundingSphere = function (
   Check.defined("result", result);
   //>>includeEnd('debug');
 
-  if (!this._ready && !allowPartial) {
+  if (!this._ready) {
     return BoundingSphereState.PENDING;
   }
 

package/Source/DataSources/ModelGraphics.js

@@ -18,6 +18,10 @@ function createArticulationStagePropertyBag(value) {
   return new PropertyBag(value);
 }
 
+function createEnvironmentMapPropertyBag(value) {
+  return new PropertyBag(value);
+}
+
 /**
  * @typedef {object} ModelGraphics.ConstructorOptions
  *
@@ -40,6 +44,7 @@ function createArticulationStagePropertyBag(value) {
  * @property {Property | ColorBlendMode} [colorBlendMode=ColorBlendMode.HIGHLIGHT] An enum Property specifying how the color blends with the model.
  * @property {Property | number} [colorBlendAmount=0.5] A numeric Property specifying the color strength when the <code>colorBlendMode</code> is <code>MIX</code>. A value of 0.0 results in the model's rendered color while a value of 1.0 results in a solid color, with any value in-between resulting in a mix of the two.
  * @property {Property | Cartesian2} [imageBasedLightingFactor=new Cartesian2(1.0, 1.0)] A property specifying the contribution from diffuse and specular image-based lighting.
+ * @property {PropertyBag | Object<string, *>} [environmentMapOptions] The properties for managing dynamic environment maps on this entity.
  * @property {Property | Color} [lightColor] A property specifying the light color when shading the model. When <code>undefined</code> the scene's light color is used instead.
  * @property {Property | DistanceDisplayCondition} [distanceDisplayCondition] A Property specifying at what distance from the camera that this model will be displayed.
  * @property {PropertyBag | Object<string, TranslationRotationScale>} [nodeTransformations] An object, where keys are names of nodes, and values are {@link TranslationRotationScale} Properties describing the transformation to apply to that node. The transformation is applied after the node's existing transformation as specified in the glTF, and does not replace the node's existing transformation.
@@ -101,6 +106,8 @@ function ModelGraphics(options) {
   this._colorBlendAmountSubscription = undefined;
   this._imageBasedLightingFactor = undefined;
   this._imageBasedLightingFactorSubscription = undefined;
+  this._environmentMapOptions = undefined;
+  this._environmentMapOptionsSubscription = undefined;
   this._lightColor = undefined;
   this._lightColorSubscription = undefined;
   this._distanceDisplayCondition = undefined;
@@ -279,6 +286,17 @@ Object.defineProperties(ModelGraphics.prototype, {
     "imageBasedLightingFactor",
   ),
 
+  /**
+   * Gets or sets the {@link DynamicEnvironmentMapManager.ConstructorOptions} to apply to this model. This is represented as an {@link PropertyBag}.
+   * @memberof ModelGraphics.prototype
+   * @type {PropertyBag}
+   */
+  environmentMapOptions: createPropertyDescriptor(
+    "environmentMapOptions",
+    undefined,
+    createEnvironmentMapPropertyBag,
+  ),
+
   /**
    * A property specifying the {@link Cartesian3} light color when shading the model. When <code>undefined</code> the scene's light color is used instead.
    * @memberOf ModelGraphics.prototype
@@ -361,6 +379,7 @@ ModelGraphics.prototype.clone = function (result) {
   result.colorBlendMode = this.colorBlendMode;
   result.colorBlendAmount = this.colorBlendAmount;
   result.imageBasedLightingFactor = this.imageBasedLightingFactor;
+  result.environmentMapOptions = this.environmentMapOptions;
   result.lightColor = this.lightColor;
   result.distanceDisplayCondition = this.distanceDisplayCondition;
   result.nodeTransformations = this.nodeTransformations;
@@ -430,7 +449,10 @@ ModelGraphics.prototype.merge = function (source) {
     this.imageBasedLightingFactor,
     source.imageBasedLightingFactor,
   );
-
+  this.environmentMapOptions = defaultValue(
+    this.environmentMapOptions,
+    source.environmentMapOptions,
+  );
   this.lightColor = defaultValue(this.lightColor, source.lightColor);
   this.distanceDisplayCondition = defaultValue(
     this.distanceDisplayCondition,

package/Source/DataSources/ModelVisualizer.js

@@ -35,6 +35,9 @@ const defaultColor = Color.WHITE;
 const defaultColorBlendMode = ColorBlendMode.HIGHLIGHT;
 const defaultColorBlendAmount = 0.5;
 const defaultImageBasedLightingFactor = new Cartesian2(1.0, 1.0);
+const defaultEnvironmentMapOptions = {
+  maximumPositionEpsilon: Number.POSITIVE_INFINITY,
+};
 
 const modelMatrixScratch = new Matrix4();
 const nodeMatrixScratch = new Matrix4();
@@ -76,6 +79,7 @@ async function createModelPrimitive(
   entity,
   resource,
   incrementallyLoadTextures,
+  environmentMapOptions,
 ) {
   const primitives = visualizer._primitives;
   const modelHash = visualizer._modelHash;
@@ -85,6 +89,7 @@ async function createModelPrimitive(
       url: resource,
       incrementallyLoadTextures: incrementallyLoadTextures,
       scene: visualizer._scene,
+      environmentMapOptions: environmentMapOptions,
     });
 
     if (visualizer.isDestroyed() || !defined(modelHash[entity.id])) {
@@ -176,6 +181,9 @@ ModelVisualizer.prototype.update = function (time) {
         articulationsScratch: {},
         loadFailed: false,
         modelUpdated: false,
+        environmentMapOptionsScratch: {
+          ...defaultEnvironmentMapOptions,
+        },
       };
       modelHash[entity.id] = modelData;
 
@@ -185,7 +193,20 @@ ModelVisualizer.prototype.update = function (time) {
         defaultIncrementallyLoadTextures,
       );
 
-      createModelPrimitive(this, entity, resource, incrementallyLoadTextures);
+      const environmentMapOptions = Property.getValueOrDefault(
+        modelGraphics._environmentMapOptions,
+        time,
+        defaultEnvironmentMapOptions,
+        modelData.environmentMapOptionsScratch,
+      );
+
+      createModelPrimitive(
+        this,
+        entity,
+        resource,
+        incrementallyLoadTextures,
+        environmentMapOptions,
+      );
     }
 
     const model = modelData.modelPrimitive;

package/Source/Renderer/AutomaticUniforms.js

@@ -1488,11 +1488,11 @@ const AutomaticUniforms = {
    *
    * @example
    * // GLSL declaration
-   * uniform sampler2D czm_specularEnvironmentMaps;
+   * uniform samplerCube czm_specularEnvironmentMaps;
    */
   czm_specularEnvironmentMaps: new AutomaticUniform({
     size: 1,
-    datatype: WebGLConstants.SAMPLER_2D,
+    datatype: WebGLConstants.SAMPLER_CUBE,
     getValue: function (uniformState) {
       return uniformState.specularEnvironmentMaps;
     },

package/Source/Scene/ArcGisMapService.js

@@ -4,7 +4,7 @@ import Resource from "../Core/Resource.js";
 
 let defaultTokenCredit;
 const defaultAccessToken =
-  "AAPTxy8BH1VEsoebNVZXo8HurEOF051kAEKlhkOhBEc9BmSrZYLHFXe7j_lQcsSJKc8-7rwh0IFSNWLGZErkzXRnYjMjURTz-hGiKMEeAJIZBG7uiYEn0Mt1rrwlJGIpirZQC4iO428519DlO3QC9DnRBqLXGTBhirgoU7-Z2209sy87s49kw6NOC8_Eew6nCLf-pZ883DRPRyAYH7LC8cvRLInud0EdndtUFa4y83TamrA.AT1_ahjrWDrq";
+  "AAPTxy8BH1VEsoebNVZXo8HurEOF051kAEKlhkOhBEc9BmQqcRjhPIHVEibuj83EgmzqMYMKlkDSXfDI_aVhgS53pQJj5gRndVO3co_eEvHb0zzYJdeBjDAW2_64bW-L6Me4YVq47D8LJswKSJVELWk4g6f3TB8wprt9QrTkB6DlBRIpV-G3oRFCspR8Muj3QGzKWMs-USdfAtfId0Yum55vSTjE2ssMyIRfiNOZaCEpVcs.AT1_aIa2UGdx";
 /**
  * Default options for accessing the ArcGIS image tile service.
  *

package/Source/Scene/Billboard.js

@@ -1562,7 +1562,7 @@ Billboard.getScreenSpaceBoundingBox = function (
  * Determines if this billboard equals another billboard.  Billboards are equal if all their properties
  * are equal.  Billboards in different collections can be equal.
  *
- * @param {Billboard} other The billboard to compare for equality.
+ * @param {Billboard} [other] The billboard to compare for equality.
  * @returns {boolean} <code>true</code> if the billboards are equal; otherwise, <code>false</code>.
  */
 Billboard.prototype.equals = function (other) {

package/Source/Scene/Cesium3DTile.js

@@ -319,6 +319,24 @@ function Cesium3DTile(tileset, baseResource, header, parent) {
    */
   this.hasImplicitContent = false;
 
+  /**
+   * Determines whether the tile has renderable content.
+   *
+   * The loading starts with the assumption that the tile does have
+   * renderable content, if the content is not empty.<br>
+   * <br>
+   * This turns <code>false</code> only when the tile content is loaded
+   * and turns out to be a single content that points to an external
+   * tileset or implicit content
+   * </p>
+   *
+   * @type {boolean}
+   * @readonly
+   *
+   * @private
+   */
+  this.hasRenderableContent = !hasEmptyContent;
+
   /**
    * When <code>true</code>, the tile contains content metadata from implicit tiling. This flag is set
    * for tiles transcoded by <code>Implicit3DTileContent</code>.
@@ -653,27 +671,6 @@ Object.defineProperties(Cesium3DTile.prototype, {
     },
   },
 
-  /**
-   * Determines if the tile's content is renderable. <code>false</code> if the
-   * tile has empty content or if it points to an external tileset or implicit content
-   *
-   * @memberof Cesium3DTile.prototype
-   *
-   * @type {boolean}
-   * @readonly
-   *
-   * @private
-   */
-  hasRenderableContent: {
-    get: function () {
-      return (
-        !this.hasEmptyContent &&
-        !this.hasTilesetContent &&
-        !this.hasImplicitContent
-      );
-    },
-  },
-
   /**
    * Determines if the tile has available content to render.  <code>true</code> if the tile's
    * content is ready or if it has expired content that renders while new content loads; otherwise,
@@ -1346,10 +1343,12 @@ async function makeContent(tile, arrayBuffer) {
     preprocessed.contentType === Cesium3DTileContentType.IMPLICIT_SUBTREE_JSON
   ) {
     tile.hasImplicitContent = true;
+    tile.hasRenderableContent = false;
   }
 
   if (preprocessed.contentType === Cesium3DTileContentType.EXTERNAL_TILESET) {
     tile.hasTilesetContent = true;
+    tile.hasRenderableContent = false;
   }
 
   let content;
@@ -1729,28 +1728,57 @@ function createBoxFromTransformedRegion(
 }
 
 /**
+ * Creates a TileBoundingVolume from the given region and transform
+ * information.
+ *
+ * This may either be a TileBoundingRegion or a TileOrientedBoundingBox.
+ *
+ * If the given transform is the initial transform, then this will return
+ * a TileBoundingRegion. This will either be the given result parameter,
+ * or a new TileBoundingRegion, if the given result parameter was not
+ * a TileBoundingRegion.
+ *
+ * If the given transform deviates from the initial transform, then this
+ * will return a TileOrientedBoundingBox that was computed by applying
+ * the given transform to the given region. This will either be the
+ * given result parameter, or a new TileOrientedBoundingBox, if the given
+ * result parameter was not a TileOrientedBoundingBox
+ *
  * @private
- * @param {Array} region An array of six numbers that define a bounding geographic region in EPSG:4979 coordinates with the order [west, south, east, north, minimum height, maximum height]
- * @param {Matrix4} transform
- * @param {Matrix4} initialTransform
- * @param {TileBoundingVolume} [result]
- * @returns {TileBoundingVolume}
+ * @param {Array} region An array of six numbers that define a bounding
+ * geographic region in EPSG:4979 coordinates with the order
+ * [west, south, east, north, minimum height, maximum height]
+ * @param {Matrix4} transform The current computedTransform of the tile,
+ * which includes the parent transform (which, in turn, includes the
+ * modelMatrix of the containing tileset)
+ * @param {Matrix4} initialTransform The initial transform of the tile,
+ * before any changes to the modelMatrix of the containing tileset
+ * @param {TileBoundingVolume} [result] An optional result.
+ * @returns {TileBoundingVolume} The resulting bounding volume
  */
 function createRegion(region, transform, initialTransform, result) {
   if (
     !Matrix4.equalsEpsilon(transform, initialTransform, CesiumMath.EPSILON8)
   ) {
+    if (result instanceof TileOrientedBoundingBox) {
+      return createBoxFromTransformedRegion(
+        region,
+        transform,
+        initialTransform,
+        result,
+      );
+    }
     return createBoxFromTransformedRegion(
       region,
       transform,
       initialTransform,
-      result,
+      undefined,
     );
   }
 
   const rectangleRegion = Rectangle.unpack(region, 0, scratchRectangle);
 
-  if (defined(result)) {
+  if (result instanceof TileBoundingRegion) {
     result.rectangle = Rectangle.clone(rectangleRegion, result.rectangle);
     result.minimumHeight = region[4];
     result.maximumHeight = region[5];

package/Source/Scene/Cesium3DTilesVoxelProvider.js

@@ -89,10 +89,26 @@ function Cesium3DTilesVoxelProvider(options) {
   /** @inheritdoc */
   this.maximumTileCount = undefined;
 
+  this._availableLevels = undefined;
   this._implicitTileset = undefined;
   this._subtreeCache = new ImplicitSubtreeCache();
 }
 
+Object.defineProperties(Cesium3DTilesVoxelProvider.prototype, {
+  /**
+   * The number of levels of detail containing available tiles in the tileset.
+   *
+   * @memberof VoxelPrimitive.prototype
+   * @type {number|undefined}
+   * @readonly
+   */
+  availableLevels: {
+    get: function () {
+      return this._availableLevels;
+    },
+  },
+});
+
 /**
  * Creates a {@link VoxelProvider} that fetches voxel data from a 3D Tiles tileset.
  *
@@ -161,6 +177,7 @@ Cesium3DTilesVoxelProvider.fromUrl = async function (url) {
   provider.paddingAfter = paddingAfter;
 
   provider._implicitTileset = implicitTileset;
+  provider._availableLevels = implicitTileset.availableLevels;
 
   ResourceCache.unload(schemaLoader);
 

package/Source/Scene/Cesium3DTileset.js

@@ -105,7 +105,7 @@ import DynamicEnvironmentMapManager from "./DynamicEnvironmentMapManager.js";
  * @property {object} [pointCloudShading] Options for constructing a {@link PointCloudShading} object to control point attenuation based on geometric error and lighting.
  * @property {Cartesian3} [lightColor] The light color when shading models. When <code>undefined</code> the scene's light color is used instead.
  * @property {ImageBasedLighting} [imageBasedLighting] The properties for managing image-based lighting for this tileset.
- * @param {DynamicEnvironmentMapManager.ConstructorOptions} [options.environmentMapOptions] The properties for managing dynamic environment maps on this model.
+ * @property {DynamicEnvironmentMapManager.ConstructorOptions} [environmentMapOptions] The properties for managing dynamic environment maps on this tileset.
  * @property {boolean} [backFaceCulling=true] Whether to cull back-facing geometry. When true, back face culling is determined by the glTF material's doubleSided property; when false, back face culling is disabled.
  * @property {boolean} [enableShowOutline=true] Whether to enable outlines for models using the {@link https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor/CESIUM_primitive_outline|CESIUM_primitive_outline} extension. This can be set to false to avoid the additional processing of geometry at load time. When false, the showOutlines and outlineColor options are ignored.
  * @property {boolean} [showOutline=true] Whether to display the outline for models using the {@link https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor/CESIUM_primitive_outline|CESIUM_primitive_outline} extension. When true, outlines are displayed. When false, outlines are not displayed.

package/Source/Scene/ClippingPolygon.js

@@ -117,8 +117,8 @@ ClippingPolygon.clone = function (polygon, result) {
  * Compares the provided ClippingPolygons and returns
  * <code>true</code> if they are equal, <code>false</code> otherwise.
  *
- * @param {Plane} left The first polygon.
- * @param {Plane} right The second polygon.
+ * @param {ClippingPolygon} left The first polygon.
+ * @param {ClippingPolygon} right The second polygon.
  * @returns {boolean} <code>true</code> if left and right are equal, <code>false</code> otherwise.
  */
 ClippingPolygon.equals = function (left, right) {