@cesium/engine 17.0.0 → 18.0.0

package/Source/Scene/Model/ModelRenderResources.js

@@ -101,6 +101,19 @@ function ModelRenderResources(model) {
    * @private
    */
   this.hasSkipLevelOfDetail = false;
+
+  /**
+   * The NodeRenderResources for the nodes of the scene graph.
+   *
+   * Note that elements of this array may be <code>undefined</code> when
+   * there was no runtime node for a certain node.
+   *
+   * @type {NodeRenderResources[]}
+   * @default []
+   *
+   * @private
+   */
+  this.nodeRenderResources = [];
 }
 
 export default ModelRenderResources;

package/Source/Scene/Model/ModelRuntimePrimitive.js

@@ -12,6 +12,7 @@ import CustomShaderPipelineStage from "./CustomShaderPipelineStage.js";
 import DequantizationPipelineStage from "./DequantizationPipelineStage.js";
 import FeatureIdPipelineStage from "./FeatureIdPipelineStage.js";
 import GeometryPipelineStage from "./GeometryPipelineStage.js";
+import ImageryPipelineStage from "./ImageryPipelineStage.js";
 import LightingPipelineStage from "./LightingPipelineStage.js";
 import MaterialPipelineStage from "./MaterialPipelineStage.js";
 import MetadataPickingPipelineStage from "./MetadataPickingPipelineStage.js";
@@ -27,6 +28,7 @@ import SelectedFeatureIdPipelineStage from "./SelectedFeatureIdPipelineStage.js"
 import SkinningPipelineStage from "./SkinningPipelineStage.js";
 import VerticalExaggerationPipelineStage from "./VerticalExaggerationPipelineStage.js";
 import WireframePipelineStage from "./WireframePipelineStage.js";
+import oneTimeWarning from "../../Core/oneTimeWarning.js";
 
 /**
  * In memory representation of a single primitive, that is, a primitive
@@ -206,6 +208,12 @@ ModelRuntimePrimitive.prototype.configurePipeline = function (frameState) {
   const hasMorphTargets =
     defined(primitive.morphTargets) && primitive.morphTargets.length > 0;
   const hasSkinning = defined(node.skin);
+
+  // Check whether the model is part of a `Model3DTileContent` that
+  // belongs to a tileset that has imagery layers. If this is the
+  // case, then the `ImageryPipelineStage` will be required.
+  const hasImageryLayers = defined(model.imageryLayers);
+
   const hasCustomShader = defined(customShader);
   const hasCustomFragmentShader =
     hasCustomShader && defined(customShader.fragmentShaderText);
@@ -270,6 +278,17 @@ ModelRuntimePrimitive.prototype.configurePipeline = function (frameState) {
     pipelineStages.push(DequantizationPipelineStage);
   }
 
+  if (hasImageryLayers) {
+    if (hasOutlines) {
+      oneTimeWarning(
+        "outlines-and-draping",
+        "Primitive outlines disable imagery draping",
+      );
+    } else {
+      pipelineStages.push(ImageryPipelineStage);
+    }
+  }
+
   if (materialsEnabled) {
     pipelineStages.push(MaterialPipelineStage);
   }

package/Source/Scene/Model/ModelSceneGraph.js

@@ -445,6 +445,7 @@ const scratchModelPositionMin = new Cartesian3();
 const scratchModelPositionMax = new Cartesian3();
 const scratchPrimitivePositionMin = new Cartesian3();
 const scratchPrimitivePositionMax = new Cartesian3();
+
 /**
  * Generates the {@link ModelDrawCommand} for each primitive in the model.
  * If the model is used for classification, a {@link ClassificationModelDrawCommand}
@@ -456,6 +457,30 @@ const scratchPrimitivePositionMax = new Cartesian3();
  * @private
  */
 ModelSceneGraph.prototype.buildDrawCommands = function (frameState) {
+  const modelRenderResources = this.buildRenderResources(frameState);
+  this.computeBoundingVolumes(modelRenderResources);
+  this.createDrawCommands(modelRenderResources, frameState);
+};
+
+/**
+ * Generates the {@link ModelRenderResources} for the model.
+ *
+ * This will traverse the model, nodes and primitives of the scene graph,
+ * and perform the following tasks:
+ *
+ * - configure the pipeline stages by calling `configurePipeline`,
+ *   `runtimeNode.configurePipeline`, and `runtimePrimitive.configurePipeline`
+ * - create the `ModelRenderResources`, `NodeRenderResources`, and
+ *   `PrimitiveRenderResources`
+ * - Process the render resources with the respective pipelines
+ *
+ * @param {FrameState} frameState The current frame state. This is needed to
+ * allocate GPU resources as needed.
+ * @returns {ModelRenderResources} The model render resources
+ *
+ * @private
+ */
+ModelSceneGraph.prototype.buildRenderResources = function (frameState) {
   const model = this._model;
   const modelRenderResources = new ModelRenderResources(model);
 
@@ -465,26 +490,12 @@ ModelSceneGraph.prototype.buildDrawCommands = function (frameState) {
   this.configurePipeline(frameState);
   const modelPipelineStages = this.modelPipelineStages;
 
-  let i, j, k;
-  for (i = 0; i < modelPipelineStages.length; i++) {
+  for (let i = 0; i < modelPipelineStages.length; i++) {
     const modelPipelineStage = modelPipelineStages[i];
     modelPipelineStage.process(modelRenderResources, model, frameState);
   }
 
-  const modelPositionMin = Cartesian3.fromElements(
-    Number.MAX_VALUE,
-    Number.MAX_VALUE,
-    Number.MAX_VALUE,
-    scratchModelPositionMin,
-  );
-  const modelPositionMax = Cartesian3.fromElements(
-    -Number.MAX_VALUE,
-    -Number.MAX_VALUE,
-    -Number.MAX_VALUE,
-    scratchModelPositionMax,
-  );
-
-  for (i = 0; i < this._runtimeNodes.length; i++) {
+  for (let i = 0; i < this._runtimeNodes.length; i++) {
     const runtimeNode = this._runtimeNodes[i];
 
     // If a node in the model was unreachable from the scene graph, there will
@@ -500,8 +511,9 @@ ModelSceneGraph.prototype.buildDrawCommands = function (frameState) {
       modelRenderResources,
       runtimeNode,
     );
+    modelRenderResources.nodeRenderResources[i] = nodeRenderResources;
 
-    for (j = 0; j < nodePipelineStages.length; j++) {
+    for (let j = 0; j < nodePipelineStages.length; j++) {
       const nodePipelineStage = nodePipelineStages[j];
 
       nodePipelineStage.process(
@@ -511,8 +523,7 @@ ModelSceneGraph.prototype.buildDrawCommands = function (frameState) {
       );
     }
 
-    const nodeTransform = runtimeNode.computedTransform;
-    for (j = 0; j < runtimeNode.runtimePrimitives.length; j++) {
+    for (let j = 0; j < runtimeNode.runtimePrimitives.length; j++) {
       const runtimePrimitive = runtimeNode.runtimePrimitives[j];
 
       runtimePrimitive.configurePipeline(frameState);
@@ -522,16 +533,76 @@ ModelSceneGraph.prototype.buildDrawCommands = function (frameState) {
         nodeRenderResources,
         runtimePrimitive,
       );
+      nodeRenderResources.primitiveRenderResources[j] =
+        primitiveRenderResources;
 
-      for (k = 0; k < primitivePipelineStages.length; k++) {
+      for (let k = 0; k < primitivePipelineStages.length; k++) {
         const primitivePipelineStage = primitivePipelineStages[k];
-
         primitivePipelineStage.process(
           primitiveRenderResources,
           runtimePrimitive.primitive,
           frameState,
         );
       }
+    }
+  }
+  return modelRenderResources;
+};
+
+/**
+ * Computes the bounding volumes for the scene graph and the model.
+ *
+ * This will traverse the model, nodes and primitives of the scene graph,
+ * and compute the bounding volumes. Specifically, it will compute
+ *
+ * - this._boundingSphere
+ * - model._boundingSphere
+ *
+ * With the latter being modified as of
+ *
+ * - model._initialRadius = model._boundingSphere.radius;
+ * - model._boundingSphere.radius *= model._clampedScale;
+ *
+ * NOTE: This contains some bugs. See https://github.com/CesiumGS/cesium/issues/12108
+ *
+ * @param {ModelRenderResources} modelRenderResources The model render resources
+ *
+ * @private
+ */
+ModelSceneGraph.prototype.computeBoundingVolumes = function (
+  modelRenderResources,
+) {
+  const model = this._model;
+
+  const modelPositionMin = Cartesian3.fromElements(
+    Number.MAX_VALUE,
+    Number.MAX_VALUE,
+    Number.MAX_VALUE,
+    scratchModelPositionMin,
+  );
+  const modelPositionMax = Cartesian3.fromElements(
+    -Number.MAX_VALUE,
+    -Number.MAX_VALUE,
+    -Number.MAX_VALUE,
+    scratchModelPositionMax,
+  );
+
+  for (let i = 0; i < this._runtimeNodes.length; i++) {
+    const runtimeNode = this._runtimeNodes[i];
+
+    // If a node in the model was unreachable from the scene graph, there will
+    // be no corresponding runtime node and therefore should be skipped.
+    if (!defined(runtimeNode)) {
+      continue;
+    }
+
+    const nodeRenderResources = modelRenderResources.nodeRenderResources[i];
+    const nodeTransform = runtimeNode.computedTransform;
+    for (let j = 0; j < runtimeNode.runtimePrimitives.length; j++) {
+      const runtimePrimitive = runtimeNode.runtimePrimitives[j];
+
+      const primitiveRenderResources =
+        nodeRenderResources.primitiveRenderResources[j];
 
       runtimePrimitive.boundingSphere = BoundingSphere.clone(
         primitiveRenderResources.boundingSphere,
@@ -559,12 +630,6 @@ ModelSceneGraph.prototype.buildDrawCommands = function (frameState) {
         primitivePositionMax,
         modelPositionMax,
       );
-
-      const drawCommand = ModelDrawCommands.buildModelDrawCommand(
-        primitiveRenderResources,
-        frameState,
-      );
-      runtimePrimitive.drawCommand = drawCommand;
     }
   }
 
@@ -596,6 +661,47 @@ ModelSceneGraph.prototype.buildDrawCommands = function (frameState) {
   model._boundingSphere.radius *= model._clampedScale;
 };
 
+/**
+ * Creates the draw commands for the primitives in the scene graph.
+ *
+ * This will traverse the model, nodes and primitives of the scene graph,
+ * and create the respective draw commands for the primitives, storing
+ * them as the `runtimePrimitive.drawCommand`, respectively.
+ *
+ * @param {ModelRenderResources} modelRenderResources The model render resources
+ *
+ * @private
+ */
+ModelSceneGraph.prototype.createDrawCommands = function (
+  modelRenderResources,
+  frameState,
+) {
+  for (let i = 0; i < this._runtimeNodes.length; i++) {
+    const runtimeNode = this._runtimeNodes[i];
+
+    // If a node in the model was unreachable from the scene graph, there will
+    // be no corresponding runtime node and therefore should be skipped.
+    if (!defined(runtimeNode)) {
+      continue;
+    }
+
+    const nodeRenderResources = modelRenderResources.nodeRenderResources[i];
+
+    for (let j = 0; j < runtimeNode.runtimePrimitives.length; j++) {
+      const runtimePrimitive = runtimeNode.runtimePrimitives[j];
+
+      const primitiveRenderResources =
+        nodeRenderResources.primitiveRenderResources[j];
+
+      const drawCommand = ModelDrawCommands.buildModelDrawCommand(
+        primitiveRenderResources,
+        frameState,
+      );
+      runtimePrimitive.drawCommand = drawCommand;
+    }
+  }
+};
+
 /**
  * Configure the model pipeline stages. If the pipeline needs to be re-run, call
  * this method again to ensure the correct sequence of pipeline stages are

package/Source/Scene/Model/NodeRenderResources.js

@@ -155,6 +155,16 @@ function NodeRenderResources(modelRenderResources, runtimeNode) {
    * @private
    */
   this.instanceCount = 0;
+
+  /**
+   * The PrimitiveRenderResources for the primitives of the node.
+   *
+   * @type {PrimitiveRenderResources[]}
+   * @default []
+   *
+   * @private
+   */
+  this.primitiveRenderResources = [];
 }
 
 export default NodeRenderResources;

package/Source/Scene/ModelComponents.js

@@ -620,6 +620,16 @@ function Primitive() {
    * @private
    */
   this.outlineCoordinates = undefined;
+
+  /**
+   * If the model is part of a Model3DTileContent of a Cesium3DTileset that
+   * has 'imageryLayers', then this will represent the information that is
+   * required for draping the imagery over this primitive.
+   *
+   * @type {ModelPrimitiveImagery|undefined}
+   * @private
+   */
+  this.modelPrimitiveImagery = undefined;
 }
 
 /**

package/Source/Scene/VoxelPrimitive.js

@@ -45,6 +45,7 @@ import VoxelMetadataOrder from "./VoxelMetadataOrder.js";
  * @see VoxelProvider
  * @see Cesium3DTilesVoxelProvider
  * @see VoxelShapeType
+ * @see {@link https://github.com/CesiumGS/cesium/tree/main/Documentation/CustomShaderGuide|Custom Shader Guide}
  *
  * @experimental This feature is not final and is subject to change without Cesium's standard deprecation policy.
  */
@@ -339,22 +340,22 @@ function VoxelPrimitive(options) {
   this._transformPositionWorldToUv = new Matrix4();
 
   /**
-   * @type {Matrix4}
+   * @type {Matrix3}
    * @private
    */
-  this._transformPositionUvToWorld = new Matrix4();
+  this._transformDirectionWorldToUv = new Matrix3();
 
   /**
-   * @type {Matrix3}
+   * @type {Matrix4}
    * @private
    */
-  this._transformDirectionWorldToLocal = new Matrix3();
+  this._transformPositionUvToWorld = new Matrix4();
 
   /**
    * @type {Matrix3}
    * @private
    */
-  this._transformNormalLocalToWorld = new Matrix3();
+  this._transformDirectionWorldToLocal = new Matrix3();
 
   // Rendering
   /**
@@ -442,8 +443,8 @@ function VoxelPrimitive(options) {
     transformPositionViewToUv: new Matrix4(),
     transformPositionUvToView: new Matrix4(),
     transformDirectionViewToLocal: new Matrix3(),
-    transformNormalLocalToWorld: new Matrix3(),
     cameraPositionUv: new Cartesian3(),
+    cameraDirectionUv: new Cartesian3(),
     ndcSpaceAxisAlignedBoundingBox: new Cartesian4(),
     clippingPlanesTexture: undefined,
     clippingPlanesMatrix: new Matrix4(),
@@ -1075,6 +1076,7 @@ Object.defineProperties(VoxelPrimitive.prototype, {
    *
    * @memberof VoxelPrimitive.prototype
    * @type {CustomShader}
+   * @see {@link https://github.com/CesiumGS/cesium/tree/main/Documentation/CustomShaderGuide|Custom Shader Guide}
    */
   customShader: {
     get: function () {
@@ -1135,10 +1137,6 @@ Object.defineProperties(VoxelPrimitive.prototype, {
 
 const scratchIntersect = new Cartesian4();
 const scratchNdcAabb = new Cartesian4();
-const scratchScale = new Cartesian3();
-const scratchLocalScale = new Cartesian3();
-const scratchRotation = new Matrix3();
-const scratchRotationAndLocalScale = new Matrix3();
 const scratchTransformPositionWorldToLocal = new Matrix4();
 const scratchTransformPositionLocalToWorld = new Matrix4();
 const scratchTransformPositionLocalToProjection = new Matrix4();
@@ -1306,16 +1304,20 @@ VoxelPrimitive.prototype.update = function (frameState) {
     transformDirectionViewToWorld,
     uniforms.transformDirectionViewToLocal,
   );
-  uniforms.transformNormalLocalToWorld = Matrix3.clone(
-    this._transformNormalLocalToWorld,
-    uniforms.transformNormalLocalToWorld,
-  );
-  const cameraPositionWorld = frameState.camera.positionWC;
   uniforms.cameraPositionUv = Matrix4.multiplyByPoint(
     this._transformPositionWorldToUv,
-    cameraPositionWorld,
+    frameState.camera.positionWC,
     uniforms.cameraPositionUv,
   );
+  uniforms.cameraDirectionUv = Matrix3.multiplyByVector(
+    this._transformDirectionWorldToUv,
+    frameState.camera.directionWC,
+    uniforms.cameraDirectionUv,
+  );
+  uniforms.cameraDirectionUv = Cartesian3.normalize(
+    uniforms.cameraDirectionUv,
+    uniforms.cameraDirectionUv,
+  );
   uniforms.stepSize = this._stepSizeMultiplier;
 
   // Render the primitive
@@ -1606,23 +1608,6 @@ function updateShapeAndTransforms(primitive, shape, provider) {
     transformPositionLocalToWorld,
     scratchTransformPositionWorldToLocal,
   );
-  const rotation = Matrix4.getRotation(
-    transformPositionLocalToWorld,
-    scratchRotation,
-  );
-  // Note that inverse(rotation) is the same as transpose(rotation)
-  const scale = Matrix4.getScale(transformPositionLocalToWorld, scratchScale);
-  const maximumScaleComponent = Cartesian3.maximumComponent(scale);
-  const localScale = Cartesian3.divideByScalar(
-    scale,
-    maximumScaleComponent,
-    scratchLocalScale,
-  );
-  const rotationAndLocalScale = Matrix3.multiplyByScale(
-    rotation,
-    localScale,
-    scratchRotationAndLocalScale,
-  );
 
   // Set member variables when the shape is dirty
   primitive._transformPositionWorldToUv = Matrix4.multiplyTransformation(
@@ -1630,6 +1615,10 @@ function updateShapeAndTransforms(primitive, shape, provider) {
     transformPositionWorldToLocal,
     primitive._transformPositionWorldToUv,
   );
+  primitive._transformDirectionWorldToUv = Matrix4.getMatrix3(
+    primitive._transformPositionWorldToUv,
+    primitive._transformDirectionWorldToUv,
+  );
   primitive._transformPositionUvToWorld = Matrix4.multiplyTransformation(
     transformPositionLocalToWorld,
     transformPositionUvToLocal,
@@ -1639,10 +1628,6 @@ function updateShapeAndTransforms(primitive, shape, provider) {
     transformPositionWorldToLocal,
     primitive._transformDirectionWorldToLocal,
   );
-  primitive._transformNormalLocalToWorld = Matrix3.inverseTranspose(
-    rotationAndLocalScale,
-    primitive._transformNormalLocalToWorld,
-  );
 
   return true;
 }

package/Source/Scene/VoxelRenderResources.js

@@ -140,13 +140,13 @@ function VoxelRenderResources(primitive) {
     }
     shaderBuilder.addFragmentLines([IntersectClippingPlanes]);
   }
+  shaderBuilder.addFragmentLines([IntersectDepth]);
   if (primitive._depthTest) {
     shaderBuilder.addDefine(
       "DEPTH_TEST",
       undefined,
       ShaderDestination.FRAGMENT,
     );
-    shaderBuilder.addFragmentLines([IntersectDepth]);
   }
 
   if (shapeType === "BOX") {