@cesium/engine 22.2.0 → 23.0.0

package/Source/Scene/DracoLoader.js

@@ -6,94 +6,95 @@ import TaskProcessor from "../Core/TaskProcessor.js";
 /**
  * @private
  */
-function DracoLoader() {}
+class DracoLoader {
+  static _getDecoderTaskProcessor() {
+    if (!defined(DracoLoader._decoderTaskProcessor)) {
+      const processor = new TaskProcessor(
+        "decodeDraco",
+        DracoLoader._maxDecodingConcurrency,
+      );
+      processor
+        .initWebAssemblyModule({
+          wasmBinaryFile: "ThirdParty/draco_decoder.wasm",
+        })
+        .then(function (result) {
+          if (result) {
+            DracoLoader._taskProcessorReady = true;
+          } else {
+            DracoLoader._error = new RuntimeError(
+              "Draco decoder could not be initialized.",
+            );
+          }
+        })
+        .catch((error) => {
+          DracoLoader._error = error;
+        });
+      DracoLoader._decoderTaskProcessor = processor;
+    }
 
-// Maximum concurrency to use when decoding draco models
-DracoLoader._maxDecodingConcurrency = Math.max(
-  FeatureDetection.hardwareConcurrency - 1,
-  1,
-);
-
-// Exposed for testing purposes
-DracoLoader._decoderTaskProcessor = undefined;
-DracoLoader._taskProcessorReady = false;
-DracoLoader._error = undefined;
-DracoLoader._getDecoderTaskProcessor = function () {
-  if (!defined(DracoLoader._decoderTaskProcessor)) {
-    const processor = new TaskProcessor(
-      "decodeDraco",
-      DracoLoader._maxDecodingConcurrency,
-    );
-    processor
-      .initWebAssemblyModule({
-        wasmBinaryFile: "ThirdParty/draco_decoder.wasm",
-      })
-      .then(function (result) {
-        if (result) {
-          DracoLoader._taskProcessorReady = true;
-        } else {
-          DracoLoader._error = new RuntimeError(
-            "Draco decoder could not be initialized.",
-          );
-        }
-      })
-      .catch((error) => {
-        DracoLoader._error = error;
-      });
-    DracoLoader._decoderTaskProcessor = processor;
+    return DracoLoader._decoderTaskProcessor;
   }
 
-  return DracoLoader._decoderTaskProcessor;
-};
+  /**
+   * Decodes a compressed point cloud. Returns undefined if the task cannot be scheduled.
+   * @private
+   *
+   * @exception {RuntimeError} Draco decoder could not be initialized.
+   */
+  static decodePointCloud(parameters) {
+    const decoderTaskProcessor = DracoLoader._getDecoderTaskProcessor();
+    if (defined(DracoLoader._error)) {
+      throw DracoLoader._error;
+    }
 
-/**
- * Decodes a compressed point cloud. Returns undefined if the task cannot be scheduled.
- * @private
- *
- * @exception {RuntimeError} Draco decoder could not be initialized.
- */
-DracoLoader.decodePointCloud = function (parameters) {
-  const decoderTaskProcessor = DracoLoader._getDecoderTaskProcessor();
-  if (defined(DracoLoader._error)) {
-    throw DracoLoader._error;
+    if (!DracoLoader._taskProcessorReady) {
+      // The task processor is not ready to schedule tasks
+      return;
+    }
+    return decoderTaskProcessor.scheduleTask(parameters, [
+      parameters.buffer.buffer,
+    ]);
   }
 
-  if (!DracoLoader._taskProcessorReady) {
-    // The task processor is not ready to schedule tasks
-    return;
-  }
-  return decoderTaskProcessor.scheduleTask(parameters, [
-    parameters.buffer.buffer,
-  ]);
-};
+  /**
+   * Decodes a buffer view. Returns undefined if the task cannot be scheduled.
+   *
+   * @param {object} options Object with the following properties:
+   * @param {Uint8Array} options.array The typed array containing the buffer view data.
+   * @param {object} options.bufferView The glTF buffer view object.
+   * @param {Object<string, number>} options.compressedAttributes The compressed attributes.
+   * @param {boolean} options.dequantizeInShader Whether POSITION and NORMAL attributes should be dequantized on the GPU.
+   *
+   * @returns {Promise} A promise that resolves to the decoded indices and attributes.
+   * @private
+   *
+   * @exception {RuntimeError} Draco decoder could not be initialized.
+   */
+  static decodeBufferView(options) {
+    const decoderTaskProcessor = DracoLoader._getDecoderTaskProcessor();
 
-/**
- * Decodes a buffer view. Returns undefined if the task cannot be scheduled.
- *
- * @param {object} options Object with the following properties:
- * @param {Uint8Array} options.array The typed array containing the buffer view data.
- * @param {object} options.bufferView The glTF buffer view object.
- * @param {Object<string, number>} options.compressedAttributes The compressed attributes.
- * @param {boolean} options.dequantizeInShader Whether POSITION and NORMAL attributes should be dequantized on the GPU.
- *
- * @returns {Promise} A promise that resolves to the decoded indices and attributes.
- * @private
- *
- * @exception {RuntimeError} Draco decoder could not be initialized.
- */
-DracoLoader.decodeBufferView = function (options) {
-  const decoderTaskProcessor = DracoLoader._getDecoderTaskProcessor();
+    if (defined(DracoLoader._error)) {
+      throw DracoLoader._error;
+    }
 
-  if (defined(DracoLoader._error)) {
-    throw DracoLoader._error;
-  }
+    if (!DracoLoader._taskProcessorReady) {
+      // The task processor is not ready to schedule tasks
+      return;
+    }
 
-  if (!DracoLoader._taskProcessorReady) {
-    // The task processor is not ready to schedule tasks
-    return;
+    return decoderTaskProcessor.scheduleTask(options, [options.array.buffer]);
   }
+}
+
+// Maximum concurrency to use when decoding draco models
+DracoLoader._maxDecodingConcurrency = Math.max(
+  FeatureDetection.hardwareConcurrency - 1,
+  1,
+);
 
-  return decoderTaskProcessor.scheduleTask(options, [options.array.buffer]);
-};
+// Exposed for testing purposes
+DracoLoader._decoderTaskProcessor = undefined;
+DracoLoader._taskProcessorReady = false;
+DracoLoader._error = undefined;
 
 export default DracoLoader;

package/Source/Scene/DynamicEnvironmentMapManager.js

@@ -33,7 +33,7 @@ import ConvolveSpecularMapVS from "../Shaders/ConvolveSpecularMapVS.js";
  * @typedef {object} DynamicEnvironmentMapManager.ConstructorOptions
  * Options for the DynamicEnvironmentMapManager constructor
  * @property {boolean} [enabled=true] If true, the environment map and related properties will continue to update.
- * @property {number} [mipmapLevels=7] The number of mipmap levels to generate for specular maps. More mipmap levels will produce a higher resolution specular reflection.
+ * @property {number} [mipmapLevels=7] The maximum desired number of mipmap levels to generate for specular maps. More mipmap levels will produce a higher resolution specular reflection. The actual number of mipmaps used will be bounded by the cubemap texture size supported on the client machine. The number of mipmaps must be at least one for the environment map to be generated.
  * @property {number} [maximumSecondsDifference=3600] The maximum amount of elapsed seconds before a new environment map is created.
  * @property {number} [maximumPositionEpsilon=1000] The maximum difference in position before a new environment map is created, in meters. Small differences in position will not visibly affect results.
  * @property {number} [atmosphereScatteringIntensity=2.0] The intensity of the scattered light emitted from the atmosphere. This should be adjusted relative to the value of {@link Scene.light} intensity.
@@ -81,14 +81,21 @@ function DynamicEnvironmentMapManager(options) {
 
   options = options ?? Frozen.EMPTY_OBJECT;
 
-  const mipmapLevels = Math.min(
-    options.mipmapLevels ?? 7,
-    Math.log2(ContextLimits.maximumCubeMapSize),
+  const mipmapLevels = Math.max(
+    Math.floor(
+      Math.min(
+        options.mipmapLevels ?? 7,
+        Math.log2(ContextLimits.maximumCubeMapSize),
+      ),
+    ),
+    0,
   );
 
   this._mipmapLevels = mipmapLevels;
+
+  const arrayLength = Math.max(mipmapLevels - 1, 0) * 6;
   this._radianceMapComputeCommands = new Array(6);
-  this._convolutionComputeCommands = new Array((mipmapLevels - 1) * 6);
+  this._convolutionComputeCommands = new Array(arrayLength);
   this._irradianceComputeCommand = undefined;
 
   this._radianceMapFS = undefined;
@@ -97,7 +104,7 @@ function DynamicEnvironmentMapManager(options) {
   this._va = undefined;
 
   this._radianceMapTextures = new Array(6);
-  this._specularMapTextures = new Array((mipmapLevels - 1) * 6);
+  this._specularMapTextures = new Array(arrayLength);
   this._radianceCubeMap = undefined;
   this._irradianceMapTexture = undefined;
 
@@ -105,7 +112,7 @@ function DynamicEnvironmentMapManager(options) {
     DynamicEnvironmentMapManager.DEFAULT_SPHERICAL_HARMONIC_COEFFICIENTS.slice();
 
   this._lastTime = new JulianDate();
-  const width = Math.pow(2, mipmapLevels - 1);
+  const width = Math.max(Math.pow(2, mipmapLevels - 1), 1);
   this._textureDimensions = new Cartesian2(width, width);
 
   this._radiiAndDynamicAtmosphereColor = new Cartesian3();
@@ -621,6 +628,28 @@ function updateSpecularMaps(manager, frameState) {
   const context = frameState.context;
 
   let facesCopied = 0;
+  const checkComplete = () => {
+    // All faces for each mipmap level have been copied
+    const length = manager._specularMapTextures.length;
+    if (facesCopied >= length) {
+      manager._irradianceCommandDirty = true;
+
+      if (mipmapLevels > 1) {
+        radianceCubeMap.sampler = new Sampler({
+          minificationFilter: TextureMinificationFilter.LINEAR_MIPMAP_LINEAR,
+        });
+
+        manager._shouldRegenerateShaders = true;
+
+        // Cleanup shared resources
+        manager._va.destroy();
+        manager._va = undefined;
+        manager._convolveSP.destroy();
+        manager._convolveSP = undefined;
+      }
+    }
+  };
+
   const getPostExecute = (command, index, texture, face, level) => () => {
     if (manager.isDestroyed() || command.canceled) {
       DynamicEnvironmentMapManager._activeComputeCommandCount--;
@@ -638,22 +667,7 @@ function updateSpecularMaps(manager, frameState) {
     texture.destroy();
     manager._specularMapTextures[index] = undefined;
 
-    // All faces for each mipmap level have been copied
-    const length = manager._specularMapTextures.length;
-    if (facesCopied >= length) {
-      manager._irradianceCommandDirty = true;
-      radianceCubeMap.sampler = new Sampler({
-        minificationFilter: TextureMinificationFilter.LINEAR_MIPMAP_LINEAR,
-      });
-
-      manager._shouldRegenerateShaders = true;
-
-      // Cleanup shared resources
-      manager._va.destroy();
-      manager._va = undefined;
-      manager._convolveSP.destroy();
-      manager._convolveSP = undefined;
-    }
+    checkComplete();
   };
 
   let index = 0;
@@ -721,6 +735,7 @@ function updateSpecularMaps(manager, frameState) {
     width /= 2;
     height /= 2;
   }
+  checkComplete();
 }
 
 const irradianceTextureDimensions = new Cartesian2(3, 3); // 9 coefficients
@@ -839,9 +854,9 @@ function updateSphericalHarmonicCoefficients(manager, frameState) {
 DynamicEnvironmentMapManager.prototype.update = function (frameState) {
   const mode = frameState.mode;
   const isSupported =
-    // A FrameState type works here because the function only references the context parameter.
-    // @ts-ignore
-    DynamicEnvironmentMapManager.isDynamicUpdateSupported(frameState);
+    // @ts-expect-error A FrameState type works here because the function only references the context parameter.
+    DynamicEnvironmentMapManager.isDynamicUpdateSupported(frameState) &&
+    this._mipmapLevels >= 1;
 
   if (
     !isSupported ||

package/Source/Scene/EquirectangularPanorama.js

@@ -0,0 +1,264 @@
+import Frozen from "../Core/Frozen.js";
+import defined from "../Core/defined.js";
+import DeveloperError from "../Core/DeveloperError.js";
+import Credit from "../Core/Credit.js";
+import Matrix4 from "../Core/Matrix4.js";
+import Cartesian2 from "../Core/Cartesian2.js";
+import SphereGeometry from "../Core/SphereGeometry.js";
+import GeometryInstance from "../Core/GeometryInstance.js";
+import Material from "./Material.js";
+import MaterialAppearance from "./MaterialAppearance.js";
+import Primitive from "./Primitive.js";
+import VertexFormat from "../Core/VertexFormat.js";
+import destroyObject from "../Core/destroyObject.js";
+
+const DEFAULT_RADIUS = 100000.0;
+
+/**
+ * @typedef {object} EquirectangularPanorama.ConstructorOptions
+ *
+ * Initialization options for the EquirectangularPanorama constructor
+ *
+ * @property {Matrix4} options.transform A 4x4 transformation matrix that defines the panorama’s position and orientation
+ * (for example, derived from a position and heading-pitch-roll).
+ * @property {string|HTMLImageElement|HTMLCanvasElement|ImageBitmap} options.image A URL to an image resource, or a preloaded image object.
+ * @property {number} [options.radius=100000.0] The radius of the panorama in meters.
+ * @property {number} [options.repeatHorizontal=1.0] The number of times to repeat the texture horizontally.
+ * @property {number} [options.repeatVertical=1.0] The number of times to repeat the texture vertically.
+ * @property {Credit|string} [options.credit] A credit for the panorama, which is displayed on the canvas.
+ */
+
+/**
+ * A {@link Panorama} that displays imagery in equirectangular format in a scene.
+ *
+ * @alias EquirectangularPanorama
+ * @constructor
+ *
+ * @param {EquirectangularPanorama.ConstructorOptions} options Object describing initialization options
+ *
+ * @example
+ * const position = Cesium.Cartesian3.fromDegrees(
+ *   -75.1699,  // longitude
+ *   39.9522,   // latitude
+ *   100.0      // height in meters
+ * );
+ *
+ * const heading = Cesium.Math.toRadians(45.0); // rotation about up axis
+ * const pitch = Cesium.Math.toRadians(-30.0);   // pitch (negative looks down)
+ * const roll = Cesium.Math.toRadians(10.0);    // roll about forward axis
+ *
+ * const hpr = new Cesium.HeadingPitchRoll(
+ *   heading,
+ *   pitch,
+ *   roll
+ * );
+ *
+ * const modelMatrix = Cesium.Transforms.headingPitchRollToFixedFrame(
+ *   position,
+ *   hpr,
+ *   Cesium.Ellipsoid.WGS84,
+ *   Cesium.Transforms.eastNorthUpToFixedFrame
+ * );
+ *
+ * scene.primitives.add(new Cesium.EquirectangularPanorama({
+ *   transform: modelMatrix,
+ *   image: 'path/to/image',
+ * }));
+ *
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=panorama|Cesium Sandcastle Panorama}
+ */
+function EquirectangularPanorama(options) {
+  options = options ?? Frozen.EMPTY_OBJECT;
+
+  //>>includeStart('debug', pragmas.debug);
+  if (!defined(options.image)) {
+    throw new DeveloperError("options.image is required.");
+  }
+
+  if (defined(options.transform) && !(options.transform instanceof Matrix4)) {
+    throw new DeveloperError("options.transform must be a Matrix4.");
+  }
+  //>>includeEnd('debug');
+
+  // Credit specified by the user.
+  let credit = options.credit;
+  if (typeof credit === "string") {
+    credit = new Credit(credit);
+  }
+  this._credit = credit;
+
+  this._radius = defined(options.radius) ? options.radius : DEFAULT_RADIUS;
+  this._image = options.image;
+  this._transform = defined(options.transform)
+    ? options.transform
+    : Matrix4.IDENTITY;
+  this._repeatHorizontal = defined(options.repeatHorizontal)
+    ? options.repeatHorizontal
+    : 1.0;
+  this._repeatVertical = defined(options.repeatVertical)
+    ? options.repeatVertical
+    : 1.0;
+
+  const geometry = new SphereGeometry({
+    radius: this._radius,
+    vertexFormat: VertexFormat.ALL,
+  });
+
+  const geometryInstance = new GeometryInstance({
+    geometry: geometry,
+    modelMatrix: this._transform,
+  });
+
+  const equirectangularMaterial = new Material({
+    fabric: {
+      type: "Image",
+      uniforms: {
+        image: this._image, // 2:1 360 degrees equirectangular image path
+        repeat: new Cartesian2(-this._repeatHorizontal, this._repeatVertical), // flip horizontally by default to match expected orientation of images inside a sphere, but allow user to override
+      },
+    },
+  });
+
+  // Create the primitive with the material
+  this._primitive = new Primitive({
+    geometryInstances: geometryInstance,
+    appearance: new MaterialAppearance({
+      material: equirectangularMaterial,
+      closed: true,
+      faceForward: false,
+      translucent: false,
+      renderState: {
+        cull: {
+          enabled: false, // show inside of sphere
+        },
+      },
+    }),
+    credit: this._credit,
+  });
+
+  return this;
+}
+
+Object.defineProperties(EquirectangularPanorama.prototype, {
+  /**
+   * Gets the radius of the panorama.
+   * @memberof EquirectangularPanorama.prototype
+   * @type {number}
+   * @readonly
+   */
+  radius: {
+    get: function () {
+      return this._radius;
+    },
+  },
+
+  /**
+   * Gets the source image of the panorama.
+   * @memberof EquirectangularPanorama.prototype
+   * @type {string|HTMLImageElement|HTMLCanvasElement|ImageBitmap}
+   * @readonly
+   */
+  image: {
+    get: function () {
+      return this._image;
+    },
+  },
+
+  /**
+   * Gets the transform of the panorama.
+   * @memberof EquirectangularPanorama.prototype
+   * @type {Matrix4}
+   * @readonly
+   */
+  transform: {
+    get: function () {
+      return this._transform;
+    },
+  },
+
+  /**
+   * Gets the credits of the panorama.
+   * @memberof EquirectangularPanorama.prototype
+   * @type {Credit}
+   * @readonly
+   */
+  credit: {
+    get: function () {
+      return defined(this._credit) ? this._credit : undefined;
+    },
+  },
+
+  /**
+   * Determines if the equirectangular panorama will be shown.
+   * @memberof EquirectangularPanorama.prototype
+   * @type {boolean}
+   */
+  show: {
+    get: function () {
+      return defined(this._primitive) ? this._primitive.show : undefined;
+    },
+    set: function (value) {
+      if (defined(this._primitive)) {
+        this._primitive.show = value;
+      }
+    },
+  },
+});
+
+// Proxy update/destroy/etc to the primitive
+
+/**
+ * Called when {@link Viewer} or {@link CesiumWidget} render the scene to
+ * get the draw commands needed to render this primitive.
+ * <p>
+ * Do not call this function directly.  This is documented just to
+ * list the exceptions that may be propagated when the scene is rendered:
+ * </p>
+ *
+ */
+EquirectangularPanorama.prototype.update = function (frameState) {
+  if (defined(this._credit)) {
+    frameState.creditDisplay.addCreditToNextFrame(this._credit);
+  }
+
+  return this._primitive.update(frameState);
+};
+
+/**
+ * Destroys the WebGL resources held by this object.  Destroying an object allows for deterministic
+ * release of WebGL resources, instead of relying on the garbage collector to destroy this object.
+ * <br /><br />
+ * Once an object is destroyed, it should not be used; calling any function other than
+ * <code>isDestroyed</code> will result in a {@link DeveloperError} exception.  Therefore,
+ * assign the return value (<code>undefined</code>) to the object as done in the example.
+ *
+ * @exception {DeveloperError} This object was destroyed, i.e., destroy() was called.
+ *
+ *
+ * @example
+ * equirectangularPanorama = equirectangularPanorama && equirectangularPanorama.destroy();
+ *
+ * @see EquirectangularPanorama#isDestroyed
+ */
+EquirectangularPanorama.prototype.destroy = function () {
+  this._primitive = this._primitive && this._primitive.destroy();
+  return destroyObject(this);
+};
+
+/**
+ * Returns true if this object was destroyed; otherwise, false.
+ * <br /><br />
+ * If this object was destroyed, it should not be used; calling any function other than
+ * <code>isDestroyed</code> will result in a {@link DeveloperError} exception.
+ *
+ * @returns {boolean} <code>true</code> if this object was destroyed; otherwise, <code>false</code>.
+ *
+ * @see EquirectangularPanorama#destroy
+ */
+
+EquirectangularPanorama.prototype.isDestroyed = function () {
+  return this._primitive.isDestroyed();
+};
+
+// Exposed for tests
+export default EquirectangularPanorama;

package/Source/Scene/Fog.js

@@ -8,7 +8,7 @@ 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}
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=fog|Cesium Sandcastle Fog Demo}
  *
  * @alias Fog
  * @constructor

package/Source/Scene/FrameState.js

@@ -28,6 +28,13 @@ function FrameState(context, creditDisplay, jobScheduler) {
    */
   this.commandList = [];
 
+  /**
+   * An array of panorama rendering commands.
+   *
+   * @type {DrawCommand[]}
+   */
+  this.panoramaCommandList = [];
+
   /**
    * An array of shadow maps.
    * @type {ShadowMap[]}