@cesium/engine 12.0.1 → 13.0.0

package/Source/Scene/MetadataPicking.js

@@ -6,6 +6,7 @@ import Matrix2 from "../Core/Matrix2.js";
 import Matrix3 from "../Core/Matrix3.js";
 import Matrix4 from "../Core/Matrix4.js";
 import RuntimeError from "../Core/RuntimeError.js";
+import MetadataClassProperty from "./MetadataClassProperty.js";
 import MetadataComponentType from "./MetadataComponentType.js";
 import MetadataType from "./MetadataType.js";
 
@@ -29,6 +30,10 @@ const MetadataPicking = {};
  * @param {DataView} dataView The data view
  * @param {number} index The index (byte offset)
  * @returns {number|bigint|undefined} The value
+ * @throws RuntimeError If the given component type is not a valid
+ * `MetadataComponentType`
+ * @throws RangeError If reading the data from the given data view would
+ * cause an out-of-bounds access
  *
  * @private
  */
@@ -43,21 +48,21 @@ MetadataPicking.decodeRawMetadataValue = function (
     case MetadataComponentType.UINT8:
       return dataView.getUint8(index);
     case MetadataComponentType.INT16:
-      return dataView.getInt16(index);
+      return dataView.getInt16(index, true);
     case MetadataComponentType.UINT16:
-      return dataView.getUint16(index);
+      return dataView.getUint16(index, true);
     case MetadataComponentType.INT32:
-      return dataView.getInt32(index);
+      return dataView.getInt32(index, true);
     case MetadataComponentType.UINT32:
-      return dataView.getUint32(index);
+      return dataView.getUint32(index, true);
     case MetadataComponentType.INT64:
-      return dataView.getBigInt64(index);
+      return dataView.getBigInt64(index, true);
     case MetadataComponentType.UINT64:
-      return dataView.getBigUint64(index);
+      return dataView.getBigUint64(index, true);
     case MetadataComponentType.FLOAT32:
-      return dataView.getFloat32(index);
+      return dataView.getFloat32(index, true);
     case MetadataComponentType.FLOAT64:
-      return dataView.getFloat64(index);
+      return dataView.getFloat64(index, true);
   }
   throw new RuntimeError(`Invalid component type: ${componentType}`);
 };
@@ -77,6 +82,10 @@ MetadataPicking.decodeRawMetadataValue = function (
  * @param {number} dataViewOffset The byte offset within the data view from
  * which the component should be read
  * @returns {number|bigint|undefined} The metadata value component
+ * @throws RuntimeError If the component of the given property is not
+ * a valid `MetadataComponentType`
+ * @throws RangeError If reading the data from the given data view would
+ * cause an out-of-bounds access
  */
 MetadataPicking.decodeRawMetadataValueComponent = function (
   classProperty,
@@ -114,6 +123,11 @@ MetadataPicking.decodeRawMetadataValueComponent = function (
  * @param {number} elementIndex The index of the element. This is the index
  * inside the array for array-typed properties, and 0 for non-array types.
  * @returns {number|number[]|bigint|bigint[]|undefined} The decoded metadata value element
+ * @throws RuntimeError If the component of the given property is not
+ * a valid `MetadataComponentType`
+ * @throws RangeError If reading the data from the given data view would
+ * cause an out-of-bounds access
+ *
  */
 MetadataPicking.decodeRawMetadataValueElement = function (
   classProperty,
@@ -183,6 +197,7 @@ MetadataPicking.decodeRawMetadataValueElement = function (
  * @param {MetadataClassProperty} classProperty The `MetadataClassProperty`
  * @param {Uint8Array} rawPixelValues The raw values
  * @returns {number|bigint|number[]|bigint[]|undefined} The value
+ * @throws RuntimeError If the class property has an invalid component type
  *
  * @private
  */
@@ -229,7 +244,8 @@ MetadataPicking.decodeRawMetadataValues = function (
  *
  * @param {string} type The `ClassProperty` type
  * @param {number|bigint|number[]|bigint[]|undefined} value The input value
- * @returns {any} The object representation
+ * @returns {undefined|number|bigint|string|boolean|Cartesian2|Cartesian3|Cartesian4|Matrix2|Matrix3|Matrix4} The object representation
+ * @throws RuntimeError If the type is not a valid `MetadataType`
  */
 MetadataPicking.convertToObjectType = function (type, value) {
   if (!defined(value)) {
@@ -250,7 +266,7 @@ MetadataPicking.convertToObjectType = function (type, value) {
     case MetadataType.VEC3:
       return Cartesian3.unpack(numbers, 0, new Cartesian3());
     case MetadataType.VEC4:
-      return Cartesian4.unpack(numbers, 0, new Cartesian3());
+      return Cartesian4.unpack(numbers, 0, new Cartesian4());
     case MetadataType.MAT2:
       return Matrix2.unpack(numbers, 0, new Matrix2());
     case MetadataType.MAT3:
@@ -259,29 +275,104 @@ MetadataPicking.convertToObjectType = function (type, value) {
       return Matrix4.unpack(numbers, 0, new Matrix4());
   }
   // Should never happen:
-  return value;
+  throw new RuntimeError(`Invalid metadata object type: ${type}`);
+};
+
+/**
+ * Converts the given type into a raw value or array representation.
+ *
+ * For `VECn/MATn` types, the given value is converted into an array.
+ * For other types, the value is returned directly
+ *
+ * @param {string} type The `ClassProperty` type
+ * @param {undefined|number|bigint|string|boolean|Cartesian2|Cartesian3|Cartesian4|Matrix2|Matrix3|Matrix4} value The input value
+ * @returns {undefined|number|bigint|string|boolean|number[]} The array representation
+ * @throws RuntimeError If the type is not a valid `MetadataType`
+ */
+MetadataPicking.convertFromObjectType = function (type, value) {
+  if (!defined(value)) {
+    return value;
+  }
+  if (
+    type === MetadataType.SCALAR ||
+    type === MetadataType.STRING ||
+    type === MetadataType.BOOLEAN ||
+    type === MetadataType.ENUM
+  ) {
+    return value;
+  }
+  switch (type) {
+    case MetadataType.VEC2:
+      return Cartesian2.pack(value, Array(2));
+    case MetadataType.VEC3:
+      return Cartesian3.pack(value, Array(3));
+    case MetadataType.VEC4:
+      return Cartesian4.pack(value, Array(4));
+    case MetadataType.MAT2:
+      return Matrix2.pack(value, Array(4));
+    case MetadataType.MAT3:
+      return Matrix3.pack(value, Array(9));
+    case MetadataType.MAT4:
+      return Matrix4.pack(value, Array(16));
+  }
+  // Should never happen:
+  throw new RuntimeError(`Invalid metadata object type: ${type}`);
 };
 
 /**
  * Decode the given raw values into a metadata property value.
  *
- * This just converts the result of `decodeRawMetadataValues`
- * from array-based types into object types like `CartesianN`.
+ * This applies the value transform (offset/scale) to the result
+ * of `decodeRawMetadataValues`, and converts this from array-based
+ * types into object types like `CartesianN`.
  *
  * @param {MetadataClassProperty} classProperty The `MetadataClassProperty`
+ * @param {object} metadataProperty The
+ * `PropertyTextureProperty` or `PropertyAttributeProperty`
  * @param {Uint8Array} rawPixelValues The raw values
- * @returns {any} The value
+ * @returns {MetadataValue} The value
+ * @throws RuntimeError If the class property has an invalid type
+ * or component type
+ * @throws RangeError If the given pixel values do not have sufficient
+ * size to contain the expected value type
  *
  * @private
  */
 MetadataPicking.decodeMetadataValues = function (
   classProperty,
+  metadataProperty,
   rawPixelValues,
 ) {
-  const arrayBasedResult = MetadataPicking.decodeRawMetadataValues(
+  let arrayBasedResult = MetadataPicking.decodeRawMetadataValues(
     classProperty,
     rawPixelValues,
   );
+
+  if (metadataProperty.hasValueTransform) {
+    // In the MetadataClassProperty, these offset/scale are always in
+    // their array-based form (e.g. a number[3] for `VEC3`). But for
+    // the PropertyTextureProperty and PropertyAttributeProperty,
+    // the type of the offset/scale is defined to be
+    // number|Cartesian2|Cartesian3|Cartesian4|Matrix2|Matrix3|Matrix4
+    // So these types are converted into their array-based form here, before
+    // applying them with `MetadataClassProperty.valueTransformInPlace`
+
+    const offset = MetadataPicking.convertFromObjectType(
+      classProperty.type,
+      metadataProperty.offset,
+    );
+    const scale = MetadataPicking.convertFromObjectType(
+      classProperty.type,
+      metadataProperty.scale,
+    );
+    arrayBasedResult = MetadataClassProperty.valueTransformInPlace(
+      arrayBasedResult,
+      offset,
+      scale,
+      MetadataComponentType.applyValueTransform,
+    );
+  }
+
   if (classProperty.isArray) {
     const arrayLength = classProperty.arrayLength;
     const result = Array(arrayLength);
@@ -295,11 +386,11 @@ MetadataPicking.decodeMetadataValues = function (
     }
     return result;
   }
-  const result = MetadataPicking.convertToObjectType(
+  const objectResult = MetadataPicking.convertToObjectType(
     classProperty.type,
     arrayBasedResult,
   );
-  return result;
+  return objectResult;
 };
 
 export default Object.freeze(MetadataPicking);

package/Source/Scene/MetadataType.js

@@ -7,6 +7,26 @@ import Matrix2 from "../Core/Matrix2.js";
 import Matrix3 from "../Core/Matrix3.js";
 import Matrix4 from "../Core/Matrix4.js";
 
+/**
+ * An instance of a metadata value.<br>
+ * <br>
+ * This can be one of the following types:
+ * <ul>
+ *   <li><code>number</code> for type <code>SCALAR</code> and numeric component types except for <code>INT64</code> or <code>UINT64</code></li>
+ *   <li><code>bigint</code> for type <code>SCALAR</code> and component type <code>INT64</code> or <code>UINT64</code></li>
+ *   <li><code>string</code> for type <code>STRING</code> or <code>ENUM</code></li>
+ *   <li><code>boolean</code> for type <code>BOOLEAN</code></li>
+ *   <li><code>Cartesian2</code> for type <code>VEC2</code></li>
+ *   <li><code>Cartesian3</code> for type <code>VEC3</code></li>
+ *   <li><code>Cartesian4</code> for type <code>VEC4</code></li>
+ *   <li><code>Matrix2</code> for type <code>MAT2</code></li>
+ *   <li><code>Matrix3</code> for type <code>MAT3</code></li>
+ *   <li><code>Matrix4</code> for type <code>MAT4</code></li>
+ *   <li>Arrays of these types when the metadata value is an array</li>
+ * </ul>
+ * @typedef {(number|bigint|string|boolean|Cartesian2|Cartesian3|Cartesian4|Matrix2|Matrix3|Matrix4|number[]|bigint[]|string[]|boolean[]|Cartesian2[]|Cartesian3[]|Cartesian4[]|Matrix2[]|Matrix3[]|Matrix4[])} MetadataValue
+ */
+
 /**
  * An enum of metadata types. These metadata types are containers containing
  * one or more components of type {@link MetadataComponentType}

package/Source/Scene/Model/Extensions/Gpm/GltfMeshPrimitiveGpmLoader.js

@@ -234,7 +234,7 @@ GltfMeshPrimitiveGpmLoader.ppeTexturesMetadataSchemaCache = new Map();
  * Create the JSON description of a metadata class that treats
  * the given PPE texture as a property texture property.
  *
- * @param {any} ppeTexture - The PPE texture
+ * @param {PpeTexture} ppeTexture - The PPE texture
  * @param {number} index - The index of the texture in the extension
  * @returns The class JSON
  */
@@ -268,9 +268,9 @@ GltfMeshPrimitiveGpmLoader._createPpeTextureClassJson = function (
   // property values when they are `normalized`, the values will be
   // declared as `normalized` here.
   // The normalization factor will later have to be cancelled out,
-  // when integrating the `scale` into the actual property texture
-  // property. In the property texture property, the `scale` has to
-  // be multiplied by 255.
+  // with the `scale` being multiplied by 255.
+  const offset = ppeTexture.offset ?? 0.0;
+  const scale = (ppeTexture.scale ?? 1.0) * 255.0;
   const classJson = {
     name: `PPE texture class ${index}`,
     properties: {
@@ -279,6 +279,8 @@ GltfMeshPrimitiveGpmLoader._createPpeTextureClassJson = function (
         type: "SCALAR",
         componentType: "UINT8",
         normalized: true,
+        offset: offset,
+        scale: scale,
         min: traits.min,
         max: traits.max,
       },
@@ -406,19 +408,12 @@ GltfMeshPrimitiveGpmLoader._convertToStructuralMetadata = function (
     const ppePropertyName = traits.source;
     const metadataClass = ppeTexturesMetadataSchema.classes[classId];
 
-    // The class property has been declared as `normalized`, so
-    // that `offset` and `scale` can be applied. The normalization
-    // factor has to be cancelled out here, by multiplying the
-    // `scale` with 255.
-    const scale = (ppeTexture.scale ?? 1.0) * 255.0;
     const ppeTextureAsPropertyTexture = {
       class: classId,
       properties: {
         [ppePropertyName]: {
           index: ppeTexture.index,
           texCoord: ppeTexture.texCoord,
-          offset: ppeTexture.offset,
-          scale: scale,
         },
       },
     };

package/Source/Scene/Model/Model3DTileContent.js

@@ -152,12 +152,34 @@ Object.defineProperties(Model3DTileContent.prototype, {
   },
 });
 
+/**
+ * Returns an array containing the `texture.id` values for all textures
+ * that are part of this content.
+ *
+ * @returns {string[]} The texture IDs
+ */
+Model3DTileContent.prototype.getTextureIds = function () {
+  return this._model.statistics.getTextureIds();
+};
+
+/**
+ * Returns the length, in bytes, of the texture data for the texture with
+ * the given ID that is part of this content, or `undefined` if this
+ * content does not contain the texture with the given ID.
+ *
+ * @param {string} textureId The texture ID
+ * @returns {number|undefined} The texture byte length
+ */
+Model3DTileContent.prototype.getTextureByteLengthById = function (textureId) {
+  return this._model.statistics.getTextureByteLengthById(textureId);
+};
+
 /**
  * Returns the object that was created for the given extension.
  *
  * The given name may be the name of a glTF extension, like `"EXT_example_extension"`.
  * If the specified extension was present in the root of the underlying glTF asset,
- * and a loder for the specified extension has processed the extension data, then
+ * and a loader for the specified extension has processed the extension data, then
  * this will return the model representation of the extension.
  *
  * @param {string} extensionName The name of the extension

package/Source/Scene/Model/ModelStatistics.js

@@ -61,7 +61,15 @@ function ModelStatistics() {
   // Sets of buffers and textures that have already been counted.
   // This is to prevent double-counting cached assets.
   this._bufferIdSet = {};
-  this._textureIdSet = {};
+
+  /**
+   * The mapping from `texture.id` strings to the byte length of the
+   * respective texture
+   *
+   * @type {object}
+   * @private
+   */
+  this._textureIdByteLengths = {};
 
   // Associated array of batch textures that have already been counted.
   // This allows for quick look-up to check if a texture has been counted,
@@ -111,7 +119,7 @@ ModelStatistics.prototype.clear = function () {
   this.propertyTablesByteLength = 0;
 
   this._bufferIdSet = {};
-  this._textureIdSet = {};
+  this._textureIdByteLengths = {};
   this._batchTextureIdMap.removeAll();
 };
 
@@ -160,12 +168,32 @@ ModelStatistics.prototype.addTexture = function (texture) {
   Check.typeOf.object("texture", texture);
   //>>includeEnd('debug');
 
-  if (!this._textureIdSet.hasOwnProperty(texture._id)) {
+  if (!this._textureIdByteLengths.hasOwnProperty(texture._id)) {
     this.texturesByteLength += texture.sizeInBytes;
+    this._textureIdByteLengths[texture._id] = texture.sizeInBytes;
   }
+};
 
-  // Simulate set insertion.
-  this._textureIdSet[texture._id] = true;
+/**
+ * Returns an array containing the `texture.id` values for all textures
+ * that are part of the model.
+ *
+ * @returns {string[]} The texture IDs
+ */
+ModelStatistics.prototype.getTextureIds = function () {
+  return Object.keys(this._textureIdByteLengths);
+};
+
+/**
+ * Returns the length, in bytes, of the texture data for the texture with
+ * the given ID that is part of the model, or `undefined` if the model
+ * does not contain the texture with the given ID.
+ *
+ * @param {string} textureId The texture ID
+ * @returns {number|undefined} The texture byte length
+ */
+ModelStatistics.prototype.getTextureByteLengthById = function (textureId) {
+  return this._textureIdByteLengths[textureId];
 };
 
 /**

package/Source/Scene/Model/PointCloudStylingPipelineStage.js

@@ -333,9 +333,10 @@ function addShaderFunctionsAndDefines(shaderBuilder, shaderFunctionInfo) {
     shaderBuilder.addDefine(
       "HAS_POINT_CLOUD_SHOW_STYLE",
       undefined,
-      ShaderDestination.VERTEX,
+      ShaderDestination.BOTH,
     );
     shaderBuilder.addVertexLines(showStyleFunction);
+    shaderBuilder.addVarying("float", "v_pointCloudShow");
   }
 
   const pointSizeStyleFunction = shaderFunctionInfo.pointSizeStyleFunction;

package/Source/Scene/PickedMetadataInfo.js

@@ -6,11 +6,17 @@
  * the metadata values of an object into the picking frame buffer. The
  * raw values are read from that buffer, and are then translated back into
  * proper metadata values in `Picking.pickMetadata`, using the structural
- * information about the metadata `classProperty` that is stored here.
+ * information about the metadata that is stored here.
  *
  * @private
  */
-function PickedMetadataInfo(schemaId, className, propertyName, classProperty) {
+function PickedMetadataInfo(
+  schemaId,
+  className,
+  propertyName,
+  classProperty,
+  metadataProperty,
+) {
   /**
    * The optional ID of the metadata schema
    *
@@ -29,11 +35,23 @@ function PickedMetadataInfo(schemaId, className, propertyName, classProperty) {
    * @type {string}
    */
   this.propertyName = propertyName;
+
   /**
-   * The optional ID of the metadata schema
+   * The the `MetadataClassProperty` that is described by this
+   * structure, as obtained from the `MetadataSchema`
    *
    * @type {MetadataClassProperty}
    */
   this.classProperty = classProperty;
+
+  /**
+   * The `PropertyTextureProperty` or `PropertyAttributeProperty` that
+   * is described by this structure, as obtained from the property texture
+   * or property attribute of the `StructuralMetadata` that matches the
+   * class name and property name.
+   *
+   * @type {object}
+   */
+  this.metadataProperty = metadataProperty;
 }
 export default PickedMetadataInfo;

package/Source/Scene/Picking.js

@@ -426,9 +426,14 @@ Picking.prototype.pickVoxelCoordinate = function (
  * - For `VEC3`, the return type will be a `Cartesian3`
  * - For `VEC4`, the return type will be a `Cartesian4`
  *
+ * Future implementations may additionally return `string`- or
+ * `boolean` types, and `MATn` values as `MatrixN` objects,
+ * and arrays of the respective types.
+ *
  * @param {Cartesian2} windowPosition Window coordinates to perform picking on.
  * @param {PickedMetadataInfo} pickedMetadataInfo Information about the picked metadata.
- * @returns {any} The metadata values
+ * @returns {MetadataValue|undefined} The metadata value, or `undefined`
+ * when no matching metadata value could be picked at the given position
  *
  * @private
  */
@@ -517,6 +522,7 @@ Picking.prototype.pickMetadata = function (
 
   const metadataValue = MetadataPicking.decodeMetadataValues(
     pickedMetadataInfo.classProperty,
+    pickedMetadataInfo.metadataProperty,
     rawMetadataPixel,
   );
 

package/Source/Scene/PostProcessStage.js

@@ -94,9 +94,16 @@ import PostProcessStageSampleMode from "./PostProcessStageSampleMode.js";
 function PostProcessStage(options) {
   options = defaultValue(options, defaultValue.EMPTY_OBJECT);
   const {
+    name = createGuid(),
     fragmentShader,
+    uniforms,
     textureScale = 1.0,
+    forcePowerOfTwo = false,
+    sampleMode = PostProcessStageSampleMode.NEAREST,
     pixelFormat = PixelFormat.RGBA,
+    pixelDatatype = PixelDatatype.UNSIGNED_BYTE,
+    clearColor = Color.BLACK,
+    scissorRectangle,
   } = options;
 
   //>>includeStart('debug', pragmas.debug);
@@ -113,19 +120,13 @@ function PostProcessStage(options) {
   //>>includeEnd('debug');
 
   this._fragmentShader = fragmentShader;
-  this._uniforms = options.uniforms;
+  this._uniforms = uniforms;
   this._textureScale = textureScale;
-  this._forcePowerOfTwo = defaultValue(options.forcePowerOfTwo, false);
-  this._sampleMode = defaultValue(
-    options.sampleMode,
-    PostProcessStageSampleMode.NEAREST,
-  );
+  this._forcePowerOfTwo = forcePowerOfTwo;
+  this._sampleMode = sampleMode;
   this._pixelFormat = pixelFormat;
-  this._pixelDatatype = defaultValue(
-    options.pixelDatatype,
-    PixelDatatype.UNSIGNED_BYTE,
-  );
-  this._clearColor = defaultValue(options.clearColor, Color.BLACK);
+  this._pixelDatatype = pixelDatatype;
+  this._clearColor = clearColor;
 
   this._uniformMap = undefined;
   this._command = undefined;
@@ -143,18 +144,14 @@ function PostProcessStage(options) {
   const passState = new PassState();
   passState.scissorTest = {
     enabled: true,
-    rectangle: defined(options.scissorRectangle)
-      ? BoundingRectangle.clone(options.scissorRectangle)
+    rectangle: defined(scissorRectangle)
+      ? BoundingRectangle.clone(scissorRectangle)
       : new BoundingRectangle(),
   };
   this._passState = passState;
 
   this._ready = false;
 
-  let name = options.name;
-  if (!defined(name)) {
-    name = createGuid();
-  }
   this._name = name;
 
   this._logDepthChanged = undefined;

package/Source/Scene/PostProcessStageCollection.js

@@ -155,32 +155,20 @@ Object.defineProperties(PostProcessStageCollection.prototype, {
    * surface receives light and regardless of the light's position.
    * </p>
    * <p>
-   * The uniforms have the following properties: <code>intensity</code>, <code>bias</code>, <code>lengthCap</code>,
-   * <code>stepSize</code>, <code>frustumLength</code>, <code>ambientOcclusionOnly</code>,
-   * <code>delta</code>, <code>sigma</code>, and <code>blurStepSize</code>.
-   * </p>
+   * The uniforms have the following properties:
    * <ul>
    * <li><code>intensity</code> is a scalar value used to lighten or darken the shadows exponentially. Higher values make the shadows darker. The default value is <code>3.0</code>.</li>
-   *
    * <li><code>bias</code> is a scalar value representing an angle in radians. If the dot product between the normal of the sample and the vector to the camera is less than this value,
    * sampling stops in the current direction. This is used to remove shadows from near planar edges. The default value is <code>0.1</code>.</li>
-   *
    * <li><code>lengthCap</code> is a scalar value representing a length in meters. If the distance from the current sample to first sample is greater than this value,
    * sampling stops in the current direction. The default value is <code>0.26</code>.</li>
-   *
-   * <li><code>stepSize</code> is a scalar value indicating the distance to the next texel sample in the current direction. The default value is <code>1.95</code>.</li>
-   *
-   * <li><code>frustumLength</code> is a scalar value in meters. If the current fragment has a distance from the camera greater than this value, ambient occlusion is not computed for the fragment.
-   * The default value is <code>1000.0</code>.</li>
-   *
+   * <li><code>directionCount</code> is the number of directions along which the ray marching will search for occluders. The default value is <code>8</code>.</li>
+   * <li><code>stepCount</code> is the number of steps the ray marching will take along each direction. The default value is <code>32</code>.</li>
+   * <li><code>randomTexture</code> is a texture where the red channel is a random value in [0.0, 1.0]. The default value is <code>undefined</code>. This texture needs to be set.</li>
    * <li><code>ambientOcclusionOnly</code> is a boolean value. When <code>true</code>, only the shadows generated are written to the output. When <code>false</code>, the input texture is modulated
    * with the ambient occlusion. This is a useful debug option for seeing the effects of changing the uniform values. The default value is <code>false</code>.</li>
    * </ul>
    * <p>
-   * <code>delta</code>, <code>sigma</code>, and <code>blurStepSize</code> are the same properties as {@link PostProcessStageLibrary#createBlurStage}.
-   * The blur is applied to the shadows generated from the image to make them smoother.
-   * </p>
-   * <p>
    * When enabled, this stage will execute before all others.
    * </p>
    *