@cesium/engine 20.0.2-ion.0 → 21.0.0

package/Source/Scene/Material.js

@@ -327,12 +327,58 @@ function Material(options) {
 
   this._defaultTexture = undefined;
 
+  /**
+   * Any and all promises that are created when initializing the material.
+   * Examples: loading images and cubemaps.
+   *
+   * @type {Promise[]}
+   * @private
+   */
+  this._initializationPromises = [];
+
+  /**
+   * An error that occurred in async operations during material initialization.
+   * Only one error is stored.
+   *
+   * @type {Error|undefined}
+   * @private
+   */
+  this._initializationError = undefined;
+
   initializeMaterial(options, this);
   Object.defineProperties(this, {
     type: {
       value: this.type,
       writable: false,
     },
+
+    /**
+     * The {@link TextureMinificationFilter} to apply to this material's textures.
+     * @type {TextureMinificationFilter}
+     * @default TextureMinificationFilter.LINEAR
+     */
+    minificationFilter: {
+      get: function () {
+        return this._minificationFilter;
+      },
+      set: function (value) {
+        this._minificationFilter = value;
+      },
+    },
+
+    /**
+     * The {@link TextureMagnificationFilter} to apply to this material's textures.
+     * @type {TextureMagnificationFilter}
+     * @default TextureMagnificationFilter.LINEAR
+     */
+    magnificationFilter: {
+      get: function () {
+        return this._magnificationFilter;
+      },
+      set: function (value) {
+        this._magnificationFilter = value;
+      },
+    },
   });
 
   if (!defined(Material._uniformList[this.type])) {
@@ -384,6 +430,68 @@ Material.fromType = function (type, uniforms) {
   return material;
 };
 
+/**
+ * Creates a new material using an existing material type and returns a promise that resolves when
+ * all of the material's resources have been loaded.
+ *
+ * @param {string} type The base material type.
+ * @param {object} [uniforms] Overrides for the default uniforms.
+ * @returns {Promise<Material>} A promise that resolves to a new material object when all resources are loaded.
+ *
+ * @exception {DeveloperError} material with that type does not exist.
+ *
+ * @example
+ * const material = await Cesium.Material.fromTypeAsync('Image', {
+ *    image: '../Images/Cesium_Logo_overlay.png'
+ * });
+ */
+Material.fromTypeAsync = async function (type, uniforms) {
+  //>>includeStart('debug', pragmas.debug);
+  if (!defined(Material._materialCache.getMaterial(type))) {
+    throw new DeveloperError(`material with type '${type}' does not exist.`);
+  }
+  //>>includeEnd('debug');
+
+  const initializationPromises = [];
+  // Unlike Material.fromType, we need to specify the uniforms in the Material constructor up front,
+  // or else anything that needs to be async loaded won't be kicked off until the next Update call.
+  const material = new Material({
+    fabric: {
+      type: type,
+      uniforms: uniforms,
+    },
+  });
+
+  // Recursively collect initialization promises for this material and its submaterials.
+  getInitializationPromises(material, initializationPromises);
+  await Promise.all(initializationPromises);
+  initializationPromises.length = 0;
+
+  if (defined(material._initializationError)) {
+    throw material._initializationError;
+  }
+
+  return material;
+};
+
+/**
+ * Recursively traverses the material and its submaterials to collect all initialization promises.
+ * @param {Material} material The material to traverse.
+ * @param {Promise[]} initializationPromises The array to collect promises into.
+ *
+ * @private
+ */
+function getInitializationPromises(material, initializationPromises) {
+  initializationPromises.push(...material._initializationPromises);
+  const submaterials = material.materials;
+  for (const name in submaterials) {
+    if (submaterials.hasOwnProperty(name)) {
+      const submaterial = submaterials[name];
+      getInitializationPromises(submaterial, initializationPromises);
+    }
+  }
+}
+
 /**
  * Gets whether or not this material is translucent.
  * @returns {boolean} <code>true</code> if this material is translucent, <code>false</code> otherwise.
@@ -586,6 +694,7 @@ function initializeMaterial(options, result) {
   result._strict = options.strict ?? false;
   result._count = options.count ?? 0;
   result._template = clone(options.fabric ?? Frozen.EMPTY_OBJECT);
+  result.fabric = clone(options.fabric ?? Frozen.EMPTY_OBJECT);
   result._template.uniforms = clone(
     result._template.uniforms ?? Frozen.EMPTY_OBJECT,
   );
@@ -616,15 +725,15 @@ function initializeMaterial(options, result) {
   // Make sure the template has no obvious errors. More error checking happens later.
   checkForTemplateErrors(result);
 
+  createMethodDefinition(result);
+  createUniforms(result);
+  createSubMaterials(result);
+
   // If the material has a new type, add it to the cache.
   if (!defined(cachedMaterial)) {
     Material._materialCache.addMaterial(result.type, result);
   }
 
-  createMethodDefinition(result);
-  createUniforms(result);
-  createSubMaterials(result);
-
   const defaultTranslucent =
     result._translucentFunctions.length === 0 ? true : undefined;
   translucent = translucent ?? defaultTranslucent;
@@ -858,10 +967,10 @@ function createTexture2DUpdateFunction(uniformId) {
         texture.destroy();
       }
       texture = undefined;
+      material._texturePaths[uniformId] = undefined;
     }
 
     if (!defined(texture)) {
-      material._texturePaths[uniformId] = undefined;
       texture = material._textures[uniformId] = material._defaultTexture;
 
       uniformDimensionsName = `${uniformId}Dimensions`;
@@ -876,59 +985,90 @@ function createTexture2DUpdateFunction(uniformId) {
       return;
     }
 
-    // When using the entity layer, the Resource objects get recreated on getValue because
-    //  they are clonable. That's why we check the url property for Resources
-    //  because the instances aren't the same and we keep trying to load the same
-    //  image if it fails to load.
-    const isResource = uniformValue instanceof Resource;
     if (
-      !defined(material._texturePaths[uniformId]) ||
-      (isResource &&
-        uniformValue.url !== material._texturePaths[uniformId].url) ||
-      (!isResource && uniformValue !== material._texturePaths[uniformId])
-    ) {
-      if (typeof uniformValue === "string" || isResource) {
-        const resource = isResource
-          ? uniformValue
-          : Resource.createIfNeeded(uniformValue);
-
-        let promise;
-        if (ktx2Regex.test(resource.url)) {
-          promise = loadKTX2(resource.url);
-        } else {
-          promise = resource.fetchImage();
-        }
-
-        Promise.resolve(promise)
-          .then(function (image) {
-            material._loadedImages.push({
-              id: uniformId,
-              image: image,
-            });
-          })
-          .catch(function () {
-            if (defined(texture) && texture !== material._defaultTexture) {
-              texture.destroy();
-            }
-            material._textures[uniformId] = material._defaultTexture;
-          });
-      } else if (
-        uniformValue instanceof HTMLCanvasElement ||
+      (uniformValue instanceof HTMLCanvasElement ||
         uniformValue instanceof HTMLImageElement ||
         uniformValue instanceof ImageBitmap ||
-        uniformValue instanceof OffscreenCanvas
-      ) {
-        material._loadedImages.push({
-          id: uniformId,
-          image: uniformValue,
-        });
-      }
-
+        uniformValue instanceof OffscreenCanvas) &&
+      uniformValue !== material._texturePaths[uniformId]
+    ) {
+      material._loadedImages.push({
+        id: uniformId,
+        image: uniformValue,
+      });
       material._texturePaths[uniformId] = uniformValue;
+      return;
     }
+
+    // If we get to this point, the image should be a string URL or Resource.
+    // Don't wait on the promise to resolve, just start loading the image and poll status from the update loop.
+    loadTexture2DImageForUniform(material, uniformId);
   };
 }
 
+/**
+ * For a given uniform ID, potentially loads a texture image for the material, if the uniform value is a Resource or string URL,
+ * and has changed since the last time this was called (either on construction or update).
+ *
+ * @param {Material} material The material to load the texture for.
+ * @param {string} uniformId The ID of the uniform of the image.
+ * @returns A promise that resolves when the image is loaded, or a resolved promise if image loading is not necessary.
+ *
+ * @private
+ */
+function loadTexture2DImageForUniform(material, uniformId) {
+  const uniforms = material.uniforms;
+  const uniformValue = uniforms[uniformId];
+  if (uniformValue === Material.DefaultImageId) {
+    return Promise.resolve();
+  }
+
+  // Attempt to make a resource from the uniform value. If it's not already a resource or string, this returns the original object.
+  const resource = Resource.createIfNeeded(uniformValue);
+  if (!(resource instanceof Resource)) {
+    return Promise.resolve();
+  }
+
+  // When using the entity layer, the Resource objects get recreated on getValue because
+  // they are clonable. That's why we check the url property for Resources
+  // because the instances aren't the same and we keep trying to load the same
+  // image if it fails to load.
+  const oldResource = Resource.createIfNeeded(
+    material._texturePaths[uniformId],
+  );
+  const uniformHasChanged =
+    !defined(oldResource) || oldResource.url !== resource.url;
+  if (!uniformHasChanged) {
+    return Promise.resolve();
+  }
+
+  let promise;
+  if (ktx2Regex.test(resource.url)) {
+    promise = loadKTX2(resource.url);
+  } else {
+    promise = resource.fetchImage();
+  }
+
+  Promise.resolve(promise)
+    .then(function (image) {
+      material._loadedImages.push({
+        id: uniformId,
+        image: image,
+      });
+    })
+    .catch(function (error) {
+      material._initializationError = error;
+      const texture = material._textures[uniformId];
+      if (defined(texture) && texture !== material._defaultTexture) {
+        texture.destroy();
+      }
+      material._textures[uniformId] = material._defaultTexture;
+    });
+
+  material._texturePaths[uniformId] = uniformValue;
+  return promise;
+}
+
 function createCubeMapUpdateFunction(uniformId) {
   return function (material, context) {
     const uniformValue = material.uniforms[uniformId];
@@ -944,42 +1084,64 @@ function createCubeMapUpdateFunction(uniformId) {
     }
 
     if (!defined(material._textures[uniformId])) {
-      material._texturePaths[uniformId] = undefined;
       material._textures[uniformId] = context.defaultCubeMap;
     }
 
-    if (uniformValue === Material.DefaultCubeMapId) {
-      return;
-    }
+    loadCubeMapImagesForUniform(material, uniformId);
+  };
+}
 
-    const path =
-      uniformValue.positiveX +
-      uniformValue.negativeX +
-      uniformValue.positiveY +
-      uniformValue.negativeY +
-      uniformValue.positiveZ +
-      uniformValue.negativeZ;
-
-    if (path !== material._texturePaths[uniformId]) {
-      const promises = [
-        Resource.createIfNeeded(uniformValue.positiveX).fetchImage(),
-        Resource.createIfNeeded(uniformValue.negativeX).fetchImage(),
-        Resource.createIfNeeded(uniformValue.positiveY).fetchImage(),
-        Resource.createIfNeeded(uniformValue.negativeY).fetchImage(),
-        Resource.createIfNeeded(uniformValue.positiveZ).fetchImage(),
-        Resource.createIfNeeded(uniformValue.negativeZ).fetchImage(),
-      ];
-
-      Promise.all(promises).then(function (images) {
-        material._loadedCubeMaps.push({
-          id: uniformId,
-          images: images,
-        });
+/**
+ * Loads the images for a cubemap uniform, if it has changed since the last time this was called.
+ *
+ * @param {Material} material The material to load the cubemap images for.
+ * @param {string} uniformId The ID of the uniform that corresponds to the cubemap images.
+ * @returns A promise that resolves when the images are loaded, or a resolved promise if image loading is not necessary.
+ */
+function loadCubeMapImagesForUniform(material, uniformId) {
+  const uniforms = material.uniforms;
+  const uniformValue = uniforms[uniformId];
+  if (uniformValue === Material.DefaultCubeMapId) {
+    return Promise.resolve();
+  }
+
+  const path =
+    uniformValue.positiveX +
+    uniformValue.negativeX +
+    uniformValue.positiveY +
+    uniformValue.negativeY +
+    uniformValue.positiveZ +
+    uniformValue.negativeZ;
+
+  // The uniform value is unchanged, no update / image load necessary.
+  if (path === material._texturePaths[uniformId]) {
+    return Promise.resolve();
+  }
+
+  const promises = [
+    Resource.createIfNeeded(uniformValue.positiveX).fetchImage(),
+    Resource.createIfNeeded(uniformValue.negativeX).fetchImage(),
+    Resource.createIfNeeded(uniformValue.positiveY).fetchImage(),
+    Resource.createIfNeeded(uniformValue.negativeY).fetchImage(),
+    Resource.createIfNeeded(uniformValue.positiveZ).fetchImage(),
+    Resource.createIfNeeded(uniformValue.negativeZ).fetchImage(),
+  ];
+
+  const allPromise = Promise.all(promises);
+  allPromise
+    .then(function (images) {
+      material._loadedCubeMaps.push({
+        id: uniformId,
+        images: images,
       });
+    })
+    .catch(function (error) {
+      material._initializationError = error;
+    });
 
-      material._texturePaths[uniformId] = path;
-    }
-  };
+  material._texturePaths[uniformId] = path;
+
+  return allPromise;
 }
 
 function createUniforms(material) {
@@ -1059,11 +1221,17 @@ function createUniform(material, uniformId) {
         return material._textures[uniformId];
       };
       material._updateFunctions.push(createTexture2DUpdateFunction(uniformId));
+      material._initializationPromises.push(
+        loadTexture2DImageForUniform(material, uniformId),
+      );
     } else if (uniformType === "samplerCube") {
       material._uniforms[newUniformId] = function () {
         return material._textures[uniformId];
       };
       material._updateFunctions.push(createCubeMapUpdateFunction(uniformId));
+      material._initializationPromises.push(
+        loadCubeMapImagesForUniform(material, uniformId),
+      );
     } else if (uniformType.indexOf("mat") !== -1) {
       const scratchMatrix = new matrixMap[uniformType]();
       material._uniforms[newUniformId] = function () {

package/Source/Scene/Primitive.js

@@ -2489,10 +2489,16 @@ Primitive.prototype.destroy = function () {
 function setReady(primitive, frameState, state, error) {
   primitive._error = error;
   primitive._state = state;
+
   frameState.afterRender.push(function () {
     primitive._ready =
       primitive._state === PrimitiveState.COMPLETE ||
       primitive._state === PrimitiveState.FAILED;
+
+    // Returning 'true' here will ensure that another rendering pass is
+    // triggered after the primitive actually became ready, to make sure
+    // that it is in fact rendered even in "request render mode"
+    return true;
   });
 }
 export default Primitive;

package/Source/Scene/PrimitiveState.js

@@ -1,13 +1,136 @@
 /**
+ * The states that describe the lifecycle of a <code>Primitive</code>, as
+ * represented by the <code>primitive._state</code>.
+ *
+ * The state transitions are triggered by calls to the <code>update</code>
+ * function, but the actual state changes may happen asynchronously if the
+ * <code>asynchronous</code> flag of the primitive was set to
+ * <code>true</code>.
+ *
  * @private
  */
 const PrimitiveState = {
+  /**
+   * The initial state of a primitive.
+   *
+   * Note that this does NOT mean that the primitive is "ready", as indicated
+   * by the <code>_ready</code> property. It means the opposite: Nothing was
+   * done with the primitive at all.
+   *
+   * For primitives that are created with the <code>asynchronous:true</code>
+   * setting and that are in this state, the <code>update</code> call starts
+   * the creation of the geometry using web workers, and the primitive goes
+   * into the <code>CREATING</code> state.
+   *
+   * For synchronously created primitives, this state never matters. They will
+   * go into the COMBINED (or FAILED) state directly due to a call to the
+   * <code>update</code> function, if they are not yet FAILED, COMBINED,
+   * or COMPLETE.
+   */
   READY: 0,
+
+  /**
+   * The process of creating the primitive geometry is ongoing.
+   *
+   * A primitive can only ever be in this state when it was created
+   * with the <code>asynchronous:true</code> setting.
+   *
+   * It means that web workers are currently creating the geometry
+   * of the primitive.
+   *
+   * When the geometry creation succeeds, then the primitive will go
+   * into the CREATED state. Otherwise, it will go into the FAILED
+   * state. Both will happen asynchronously.
+   *
+   * The <code>update</code> function has to be called regularly
+   * until either of these states is reached.
+   */
   CREATING: 1,
+
+  /**
+   * The geometry for the primitive has been created.
+   *
+   * A primitive can only ever be in this state when it was created
+   * with the <code>asynchronous:true</code> setting.
+   *
+   * It means that web workers have (asynchronously) finished the
+   * creation of the geometry, but further (asynchronous) processing
+   * is necessary: If a primitive is determined to be in this state
+   * during a call to <code>update</code>, an asynchronous process
+   * is triggered to "combine" the geometry, meaning that the primitive
+   * will go into the COMBINING state.
+   */
   CREATED: 2,
+
+  /**
+   * The asynchronous creation of the geometry has been finished, but the
+   * asynchronous process of combining the geometry has not finished yet.
+   *
+   * A primitive can only ever be in this state when it was created
+   * with the <code>asynchronous:true</code> setting.
+   *
+   * It means that whatever is done with
+   * <code>PrimitivePipeline.packCombineGeometryParameters</code> has
+   * not finished yet. When combining the geometry succeeds, the
+   * primitive will go into the COMBINED state. Otherwise, it will
+   * go into the FAILED state.
+   */
   COMBINING: 3,
+
+  /**
+   * The geometry data is in a form that can be uploaded to the GPU.
+   *
+   * For <i>synchronous</i> primitives, this means that the geometry
+   * has been created (synchronously) due to the first call to the
+   * <code>update</code> function.
+   *
+   * For <i>asynchronous</i> primitives, this means that the asynchronous
+   * creation of the geometry and the asynchronous combination of the
+   * geometry have both finished.
+   *
+   * The <code>update</code> function has to be called regularly until
+   * this state is reached. When it is reached, the <code>update</code>
+   * call will cause the transition into the COMPLETE state.
+   */
   COMBINED: 4,
+
+  /**
+   * The geometry has been created and uploaded to the GPU.
+   *
+   * When this state is reached, it eventually causes the <code>_ready</code>
+   * flag of the primitive to become <code>true</code>.
+   *
+   * Note: Setting the <code>ready</code> flag does NOT happen in the
+   * <code>update</code> call: It only happens after rendering the next
+   * frame!
+   *
+   * Note: This state does not mean that nothing has to be done
+   * anymore (so the work is not "complete"). When the primitive is in
+   * this state, the <code>update</code> function still has to be
+   * called regularly.
+   */
   COMPLETE: 5,
+
+  /**
+   * The creation of the primitive failed.
+   *
+   * When this state is reached, it eventually causes the <code>_ready</code>
+   * flag of the primitive to become <code>true</code>.
+   *
+   * Note: Setting the <code>ready</code> flag does NOT happen in the
+   * <code>update</code> call: It only happens after rendering the next
+   * frame!
+   *
+   * This state can be reached when the (synchronous or asynchronous)
+   * creation of the geometry, or the (asynchronous) combination of
+   * the geometry caused any form of error.
+   *
+   * It may or may not imply the presence of the <code>_error</code> property.
+   * When the <code>_error</code> property is present on a FAILED primitive,
+   * this error will be thrown during the <code>update</code> call. When it
+   * is not present for a FAILED primitive, then the <code>update</code> call
+   * will do nothing.
+   */
   FAILED: 6,
 };
 export default Object.freeze(PrimitiveState);

package/Source/Scene/Scene.js

@@ -100,8 +100,8 @@ const requestRenderAfterFrame = function (scene) {
  * @param {object} options Object with the following properties:
  * @param {HTMLCanvasElement} options.canvas The HTML canvas element to create the scene for.
  * @param {ContextOptions} [options.contextOptions] Context and WebGL creation properties.
- * @param {Element} [options.creditContainer] The HTML element in which the credits will be displayed.
- * @param {Element} [options.creditViewport] The HTML element in which to display the credit popup.  If not specified, the viewport will be a added as a sibling of the canvas.
+ * @param {Element} [options.creditContainer] The HTML element in which the credits will be displayed. If not specified, a credit container will be created and added as a sibling of the canvas.
+ * @param {Element} [options.creditViewport] The HTML element in which to display the credit popup.  If not specified, the viewport will be added as a sibling of the canvas.
  * @param {Ellipsoid} [options.ellipsoid=Ellipsoid.default] The default ellipsoid. If not specified, the default ellipsoid is used.
  * @param {MapProjection} [options.mapProjection=new GeographicProjection(options.ellipsoid)] The map projection to use in 2D and Columbus View modes.
  * @param {boolean} [options.orderIndependentTranslucency=true] If true and the configuration supports it, use order independent translucency.