@cesium/engine 22.2.0 → 23.0.0

package/Source/Scene/BufferLoader.js

@@ -10,46 +10,40 @@ import ResourceLoaderState from "./ResourceLoaderState.js";
  * Implements the {@link ResourceLoader} interface.
  * </p>
  *
- * @alias BufferLoader
- * @constructor
- * @augments ResourceLoader
- *
- * @param {object} options Object with the following properties:
- * @param {Uint8Array} [options.typedArray] The typed array containing the embedded buffer contents. Mutually exclusive with options.resource.
- * @param {Resource} [options.resource] The {@link Resource} pointing to the external buffer. Mutually exclusive with options.typedArray.
- * @param {string} [options.cacheKey] The cache key of the resource.
- *
- * @exception {DeveloperError} One of options.typedArray and options.resource must be defined.
- *
  * @private
  */
-function BufferLoader(options) {
-  options = options ?? Frozen.EMPTY_OBJECT;
-  const typedArray = options.typedArray;
-  const resource = options.resource;
-  const cacheKey = options.cacheKey;
+class BufferLoader extends ResourceLoader {
+  /**
+   * @param {object} options Object with the following properties:
+   * @param {Uint8Array} [options.typedArray] The typed array containing the embedded buffer contents. Mutually exclusive with options.resource.
+   * @param {Resource} [options.resource] The {@link Resource} pointing to the external buffer. Mutually exclusive with options.typedArray.
+   * @param {string} [options.cacheKey] The cache key of the resource.
+   *
+   * @exception {DeveloperError} One of options.typedArray and options.resource must be defined.
+   */
+  constructor(options) {
+    super();
 
-  //>>includeStart('debug', pragmas.debug);
-  if (defined(typedArray) === defined(resource)) {
-    throw new DeveloperError(
-      "One of options.typedArray and options.resource must be defined.",
-    );
-  }
-  //>>includeEnd('debug');
+    options = options ?? Frozen.EMPTY_OBJECT;
+    const typedArray = options.typedArray;
+    const resource = options.resource;
+    const cacheKey = options.cacheKey;
 
-  this._typedArray = typedArray;
-  this._resource = resource;
-  this._cacheKey = cacheKey;
-  this._state = ResourceLoaderState.UNLOADED;
-  this._promise = undefined;
-}
+    //>>includeStart('debug', pragmas.debug);
+    if (defined(typedArray) === defined(resource)) {
+      throw new DeveloperError(
+        "One of options.typedArray and options.resource must be defined.",
+      );
+    }
+    //>>includeEnd('debug');
 
-if (defined(Object.create)) {
-  BufferLoader.prototype = Object.create(ResourceLoader.prototype);
-  BufferLoader.prototype.constructor = BufferLoader;
-}
+    this._typedArray = typedArray;
+    this._resource = resource;
+    this._cacheKey = cacheKey;
+    this._state = ResourceLoaderState.UNLOADED;
+    this._promise = undefined;
+  }
 
-Object.defineProperties(BufferLoader.prototype, {
   /**
    * The cache key of the resource.
    *
@@ -59,11 +53,10 @@ Object.defineProperties(BufferLoader.prototype, {
    * @readonly
    * @private
    */
-  cacheKey: {
-    get: function () {
-      return this._cacheKey;
-    },
-  },
+  get cacheKey() {
+    return this._cacheKey;
+  }
+
   /**
    * The typed array containing the embedded buffer contents.
    *
@@ -73,31 +66,45 @@ Object.defineProperties(BufferLoader.prototype, {
    * @readonly
    * @private
    */
-  typedArray: {
-    get: function () {
-      return this._typedArray;
-    },
-  },
-});
+  get typedArray() {
+    return this._typedArray;
+  }
 
-/**
- * Loads the resource.
- * @returns {Promise<BufferLoader>} A promise which resolves to the loader when the resource loading is completed.
- * @private
- */
-BufferLoader.prototype.load = async function () {
-  if (defined(this._promise)) {
+  /**
+   * Loads the resource.
+   * @returns {Promise<BufferLoader>} A promise which resolves to the loader when the resource loading is completed.
+   * @private
+   */
+  async load() {
+    if (defined(this._promise)) {
+      return this._promise;
+    }
+
+    if (defined(this._typedArray)) {
+      this._promise = Promise.resolve(this);
+      return this._promise;
+    }
+
+    this._promise = loadExternalBuffer(this);
     return this._promise;
   }
 
-  if (defined(this._typedArray)) {
-    this._promise = Promise.resolve(this);
-    return this._promise;
+  /**
+   * Exposed for testing
+   * @private
+   */
+  static _fetchArrayBuffer(resource) {
+    return resource.fetchArrayBuffer();
   }
 
-  this._promise = loadExternalBuffer(this);
-  return this._promise;
-};
+  /**
+   * Unloads the resource.
+   * @private
+   */
+  unload() {
+    this._typedArray = undefined;
+  }
+}
 
 async function loadExternalBuffer(bufferLoader) {
   const resource = bufferLoader._resource;
@@ -122,20 +129,4 @@ async function loadExternalBuffer(bufferLoader) {
   }
 }
 
-/**
- * Exposed for testing
- * @private
- */
-BufferLoader._fetchArrayBuffer = function (resource) {
-  return resource.fetchArrayBuffer();
-};
-
-/**
- * Unloads the resource.
- * @private
- */
-BufferLoader.prototype.unload = function () {
-  this._typedArray = undefined;
-};
-
 export default BufferLoader;

package/Source/Scene/Camera.js

@@ -63,8 +63,8 @@ import SceneMode from "./SceneMode.js";
  *
  * @param {Scene} scene The scene.
  *
- * @demo {@link https://sandcastle.cesium.com/index.html?src=Camera.html|Cesium Sandcastle Camera Demo}
- * @demo {@link https://sandcastle.cesium.com/index.html?src=Camera%20Tutorial.html|Cesium Sandcastle Camera Tutorial Example}
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=camera|Cesium Sandcastle Camera Demo}
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=camera-tutorial|Cesium Sandcastle Camera Tutorial Example}
  * @demo {@link https://cesium.com/learn/cesiumjs-learn/cesiumjs-camera|Camera Tutorial}
  *
  * @example
@@ -3005,6 +3005,17 @@ function getPickRayOrthographic(camera, windowPosition, result) {
 
   Cartesian3.clone(camera.directionWC, result.direction);
 
+  // Account for wrap-around in 2D infinite scroll mode
+  if (
+    camera._mode === SceneMode.SCENE2D &&
+    camera._scene.mapMode2D === MapMode2D.INFINITE_SCROLL
+  ) {
+    const maxHorizontal = camera._maxCoord.x;
+    origin.y =
+      CesiumMath.mod(origin.y + maxHorizontal, 2.0 * maxHorizontal) -
+      maxHorizontal;
+  }
+
   return result;
 }
 

package/Source/Scene/ClippingPlaneCollection.js

@@ -41,8 +41,8 @@ import ClippingPlane from "./ClippingPlane.js";
  * @param {Color} [options.edgeColor=Color.WHITE] The color applied to highlight the edge along which an object is clipped.
  * @param {number} [options.edgeWidth=0.0] The width, in pixels, of the highlight applied to the edge along which an object is clipped.
  *
- * @demo {@link https://sandcastle.cesium.com/?src=3D%20Tiles%20Clipping%20Planes.html|Clipping 3D Tiles and glTF models.}
- * @demo {@link https://sandcastle.cesium.com/?src=Terrain%20Clipping%20Planes.html|Clipping the Globe.}
+ * @demo {@link https://sandcastle.cesium.com/?id=3d-tiles-clipping-planes|Clipping 3D Tiles and glTF models.}
+ * @demo {@link https://sandcastle.cesium.com/?id=terrain-clipping-planes|Clipping the Globe.}
  *
  * @example
  * // This clipping plane's distance is positive, which means its normal

package/Source/Scene/CloudCollection.js

@@ -86,8 +86,8 @@ const COLOR_INDEX = CumulusCloud.COLOR_INDEX;
  * @see CloudCollection#remove
  * @see CumulusCloud
  *
- * @demo {@link https://sandcastle.cesium.com/index.html?src=Clouds.html|Cesium Sandcastle Clouds Demo}
- * @demo {@link https://sandcastle.cesium.com/index.html?src=Cloud%20Parameters.html|Cesium Sandcastle Cloud Parameters Demo}
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=clouds|Cesium Sandcastle Clouds Demo}
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=cloud-parameters|Cesium Sandcastle Cloud Parameters Demo}
  *
  * @example
  * // Create a cloud collection with two cumulus clouds

package/Source/Scene/CubeMapPanorama.js

@@ -0,0 +1,351 @@
+import BoxGeometry from "../Core/BoxGeometry.js";
+import Cartesian3 from "../Core/Cartesian3.js";
+import Check from "../Core/Check.js";
+import defined from "../Core/defined.js";
+import destroyObject from "../Core/destroyObject.js";
+import DeveloperError from "../Core/DeveloperError.js";
+import GeometryPipeline from "../Core/GeometryPipeline.js";
+import Matrix4 from "../Core/Matrix4.js";
+import VertexFormat from "../Core/VertexFormat.js";
+import BufferUsage from "../Renderer/BufferUsage.js";
+import CubeMap from "../Renderer/CubeMap.js";
+import DrawCommand from "../Renderer/DrawCommand.js";
+import loadCubeMap from "../Renderer/loadCubeMap.js";
+import RenderState from "../Renderer/RenderState.js";
+import ShaderProgram from "../Renderer/ShaderProgram.js";
+import ShaderSource from "../Renderer/ShaderSource.js";
+import VertexArray from "../Renderer/VertexArray.js";
+import SkyBoxFS from "../Shaders/SkyBoxFS.js";
+import SkyBoxVS from "../Shaders/SkyBoxVS.js";
+import CubeMapPanoramaVS from "../Shaders/CubeMapPanoramaVS.js";
+import BlendingState from "./BlendingState.js";
+import SceneMode from "./SceneMode.js";
+import Pass from "../Renderer/Pass.js";
+import Credit from "../Core/Credit.js";
+
+/**
+ * @typedef {object} CubeMapPanorama.ConstructorOptions
+ *
+ * Initialization options for the CubeMapPanorama constructor
+ *
+ * @property {object} [options.sources] The source URL or <code>Image</code> object for each of the six cube map faces.  See the example below.
+ * @property {Matrix4} [options.transform] A 4x4 transformation matrix that defines the panorama’s position and orientation
+ * @property {boolean} [options.show=true] Determines if this primitive will be shown.
+ * @property {Credit|string} [options.credit] A credit for the panorama, which is displayed on the canvas.
+ *
+ */
+
+/**
+ * A {@link Panorama} that displays imagery in cube map format in a scene.
+ * <p>
+ * This is only supported in 3D.  The cube map panorama is faded out when morphing to 2D or Columbus view.  The size of
+ * the cube map panorama must not exceed {@link Scene#maximumSkyBoxSize}.
+ * </p>
+ *
+ * @alias CubeMapPanorama
+ * @constructor
+ *
+ * @param {CubeMapPanorama.ConstructorOptions} options Object describing initialization options
+ *
+ * @example
+ * const modelMatrix = Cesium.Matrix4.getMatrix3(
+ *   Cesium.Transforms.localFrameToFixedFrameGenerator("north", "down")(
+ *     Cesium.Cartesian3.fromDegrees(longitude, latitude, height),
+ *     Cesium.Ellipsoid.default
+ *   ),
+ *   new Cesium.Matrix3()
+ * );
+ *
+ *
+ * scene.primitives.add(new Cesium.CubeMapPanorama({
+ *   sources : {
+ *     positiveX : 'cubemap_px.png',
+ *     negativeX : 'cubemap_nx.png',
+ *     positiveY : 'cubemap_py.png',
+ *     negativeY : 'cubemap_ny.png',
+ *     positiveZ : 'cubemap_pz.png',
+ *     negativeZ : 'cubemap_nz.png'
+ *   }
+ *   transform: modelMatrix,
+ * }));
+ *
+ * @see SkyBox
+ *
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=panorama|Cesium Sandcastle Panorama}
+ */
+function CubeMapPanorama(options) {
+  /**
+   * The sources used to create the cube map faces: an object
+   * with <code>positiveX</code>, <code>negativeX</code>, <code>positiveY</code>,
+   * <code>negativeY</code>, <code>positiveZ</code>, and <code>negativeZ</code> properties.
+   * These can be either URLs or <code>Image</code> objects.
+   *
+   * @type {object}
+   * @default undefined
+   */
+  this.sources = options.sources;
+  this._sources = undefined;
+
+  this._transform = options.transform ?? undefined;
+
+  /**
+   * Determines if the cube map panorama will be shown.
+   *
+   * @type {boolean}
+   * @default true
+   */
+  this.show = options.show ?? true;
+
+  this._returnCommand = options.returnCommand ?? false;
+  this._addToPanoramaCommandList = !this._returnCommand;
+
+  this._command = new DrawCommand({
+    modelMatrix: Matrix4.clone(Matrix4.IDENTITY),
+    owner: this,
+    // render before everything else
+    pass: Pass.ENVIRONMENT,
+  });
+  this._cubeMap = undefined;
+
+  this._attributeLocations = undefined;
+  this._useHdr = undefined;
+  this._hasError = false;
+  this._error = undefined;
+
+  // Credit specified by the user.
+  let credit = options.credit;
+  if (typeof credit === "string") {
+    credit = new Credit(credit);
+  }
+  this._credit = credit;
+}
+
+Object.defineProperties(CubeMapPanorama.prototype, {
+  /**
+   * Gets the transform of the panorama.
+   * @memberof CubeMapPanorama.prototype
+   * @type {Matrix4}
+   * @readonly
+   */
+  transform: {
+    get: function () {
+      return this._transform;
+    },
+  },
+
+  /**
+   * Gets the credits of the panorama.
+   * @memberof CubeMapPanorama.prototype
+   * @type {Credit}
+   * @readonly
+   */
+  credit: {
+    get: function () {
+      return defined(this._credit) ? this._credit : undefined;
+    },
+  },
+});
+
+/**
+ * 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>
+ *
+ * @exception {DeveloperError} this.sources is required and must have positiveX, negativeX, positiveY, negativeY, positiveZ, and negativeZ properties.
+ * @exception {DeveloperError} this.sources properties must all be the same type.
+ */
+CubeMapPanorama.prototype.update = function (frameState, useHdr) {
+  const that = this;
+  const { mode, passes, context, panoramaCommandList } = frameState;
+
+  if (!this.show) {
+    return undefined;
+  }
+
+  if (mode !== SceneMode.SCENE3D && mode !== SceneMode.MORPHING) {
+    return undefined;
+  }
+
+  // The cube map panorama is only rendered during the render pass; it is not pickable, it doesn't cast shadows, etc.
+  if (!passes.render) {
+    return undefined;
+  }
+
+  // Throw any errors that had previously occurred asynchronously so they aren't
+  // ignored when running.  See https://github.com/CesiumGS/cesium/pull/12307
+  if (this._hasError) {
+    const error = this._error;
+    this._hasError = false;
+    this._error = undefined;
+    throw error;
+  }
+
+  if (this._sources !== this.sources) {
+    this._sources = this.sources;
+    const sources = this.sources;
+
+    //>>includeStart('debug', pragmas.debug);
+    Check.defined("this.sources", sources);
+    if (
+      Object.values(CubeMap.FaceName).some(
+        (faceName) => !defined(sources[faceName]),
+      )
+    ) {
+      throw new DeveloperError(
+        "this.sources must have positiveX, negativeX, positiveY, negativeY, positiveZ, and negativeZ properties.",
+      );
+    }
+
+    const sourceType = typeof sources.positiveX;
+    if (
+      Object.values(CubeMap.FaceName).some(
+        (faceName) => typeof sources[faceName] !== sourceType,
+      )
+    ) {
+      throw new DeveloperError(
+        "this.sources properties must all be the same type.",
+      );
+    }
+    //>>includeEnd('debug');
+
+    if (typeof sources.positiveX === "string") {
+      // Given urls for cube-map images.  Load them.
+      loadCubeMap(context, this._sources)
+        .then(function (cubeMap) {
+          that._cubeMap = that._cubeMap && that._cubeMap.destroy();
+          that._cubeMap = cubeMap;
+        })
+        .catch((error) => {
+          // Defer throwing the error until the next call to update to prevent
+          // test from failing in `afterAll` if this is rejected after the test
+          // using the Skybox ends.  See https://github.com/CesiumGS/cesium/pull/12307
+          this._hasError = true;
+          this._error = error;
+        });
+    } else {
+      this._cubeMap = this._cubeMap && this._cubeMap.destroy();
+      this._cubeMap = new CubeMap({
+        context: context,
+        source: sources,
+      });
+    }
+    this._addToPanoramaCommandList = true;
+  }
+
+  const command = this._command;
+
+  if (!defined(command.vertexArray)) {
+    command.uniformMap = {
+      u_cubeMap: function () {
+        return that._cubeMap;
+      },
+      u_cubeMapPanoramaTransform: function () {
+        return that._transform;
+      },
+    };
+
+    const geometry = BoxGeometry.createGeometry(
+      BoxGeometry.fromDimensions({
+        dimensions: new Cartesian3(2.0, 2.0, 2.0),
+        vertexFormat: VertexFormat.POSITION_ONLY,
+      }),
+    );
+    const attributeLocations = (this._attributeLocations =
+      GeometryPipeline.createAttributeLocations(geometry));
+
+    command.vertexArray = VertexArray.fromGeometry({
+      context: context,
+      geometry: geometry,
+      attributeLocations: attributeLocations,
+      bufferUsage: BufferUsage.STATIC_DRAW,
+    });
+
+    // no depth test/write
+    command.renderState = RenderState.fromCache({
+      depthTest: { enabled: false },
+      depthMask: false,
+      blending: BlendingState.ALPHA_BLEND,
+    });
+    this._addToPanoramaCommandList = true;
+  }
+
+  if (!defined(command.shaderProgram) || this._useHdr !== useHdr) {
+    const fs = new ShaderSource({
+      defines: [useHdr ? "HDR" : ""],
+      sources: [SkyBoxFS],
+    });
+    command.shaderProgram = ShaderProgram.fromCache({
+      context: context,
+      //vertexShaderSource: SkyBoxVS,
+      vertexShaderSource: defined(this._transform)
+        ? CubeMapPanoramaVS
+        : SkyBoxVS,
+      fragmentShaderSource: fs,
+      attributeLocations: this._attributeLocations,
+    });
+    this._useHdr = useHdr;
+    this._addToPanoramaCommandList = true;
+  }
+
+  if (!defined(this._cubeMap)) {
+    return undefined;
+  }
+
+  if (this.show && defined(this._credit) && !this._returnCommand) {
+    const creditDisplay = frameState.creditDisplay;
+    creditDisplay.addCreditToNextFrame(this._credit);
+  }
+
+  if (this._returnCommand) {
+    return command;
+  }
+
+  if (this._addToPanoramaCommandList) {
+    panoramaCommandList.push(command);
+    this._addToPanoramaCommandList = false;
+  }
+};
+
+/**
+ * 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 CubeMapPanorama#destroy
+ */
+CubeMapPanorama.prototype.isDestroyed = function () {
+  return false;
+};
+
+/**
+ * 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
+ * cubeMapPanorama = cubeMapPanorama && cubeMapPanorama.destroy();
+ *
+ * @see CubeMapPanorama#isDestroyed
+ */
+CubeMapPanorama.prototype.destroy = function () {
+  const command = this._command;
+  command.vertexArray = command.vertexArray && command.vertexArray.destroy();
+  command.shaderProgram =
+    command.shaderProgram && command.shaderProgram.destroy();
+  this._cubeMap = this._cubeMap && this._cubeMap.destroy();
+  return destroyObject(this);
+};
+
+export default CubeMapPanorama;

package/Source/Scene/CumulusCloud.js

@@ -31,7 +31,7 @@ import defined from "../Core/defined.js";
  * @internalConstructor
  * @class
  *
- * @demo {@link https://sandcastle.cesium.com/index.html?src=Cloud%20Parameters.html|Cesium Sandcastle Cloud Parameters Demo}
+ * @demo {@link https://sandcastle.cesium.com/index.html?id=cloud-parameters|Cesium Sandcastle Cloud Parameters Demo}
  */
 function CumulusCloud(options, cloudCollection) {
   options = options ?? Frozen.EMPTY_OBJECT;

package/Source/Scene/DerivedCommand.js

@@ -264,13 +264,13 @@ function getPickShaderProgram(context, shaderProgram, pickId) {
 
   const hasFragData = sources.some((source) => source.includes("out_FragData"));
   const outputColorVariable = hasFragData ? "out_FragData_0" : "out_FragColor";
-  const newMain = `void main () 
-{ 
-    czm_non_pick_main(); 
-    if (${outputColorVariable}.a == 0.0) { 
-        discard; 
-    } 
-    ${outputColorVariable} = ${pickId}; 
+  const newMain = `void main ()
+{
+    czm_non_pick_main();
+    if (${outputColorVariable}.a == 0.0) {
+        discard;
+    }
+    ${outputColorVariable} = ${pickId};
 } `;
 
   const length = sources.length;
@@ -394,29 +394,6 @@ function getComponentCount(classProperty) {
   return classProperty.arrayLength;
 }
 
-/**
- * Returns the type that the given class property has in a GLSL shader.
- *
- * It returns the same string as `PropertyTextureProperty.prototype.getGlslType`
- * for a property texture property with the given class property
- *
- * @param {MetadataClassProperty} classProperty The class property
- * @returns {string} The GLSL shader type string for the property
- */
-function getGlslType(classProperty) {
-  const componentCount = getComponentCount(classProperty);
-  if (classProperty.normalized) {
-    if (componentCount === 1) {
-      return "float";
-    }
-    return `vec${componentCount}`;
-  }
-  if (componentCount === 1) {
-    return "int";
-  }
-  return `ivec${componentCount}`;
-}
-
 /**
  * Returns a shader statement that applies the inverse of the
  * value transform to the given value, based on the given offset
@@ -547,7 +524,7 @@ function getPickMetadataShaderProgram(
 
   const metadataProperty = pickedMetadataInfo.metadataProperty;
   const classProperty = pickedMetadataInfo.classProperty;
-  const glslType = getGlslType(classProperty);
+  const glslType = classProperty.getGlslType();
 
   // Define the components that will go into the output `metadataValues`.
   // This will be the 'color' that is written into the frame buffer,