@cesium/engine 24.0.0 → 25.0.0

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

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * An enum of storage types for covariance information.
  *
@@ -27,4 +29,6 @@ const StorageType = {
   Indirect: "Indirect",
 };
 
-export default Object.freeze(StorageType);
+Object.freeze(StorageType);
+
+export default StorageType;

package/Source/Scene/Model/GeoJsonLoader.js

@@ -56,7 +56,6 @@ class GeoJsonLoader extends ResourceLoader {
   /**
    * The cache key of the resource.
    *
-   * @memberof GeoJsonLoader.prototype
    *
    * @type {string}
    * @readonly
@@ -69,7 +68,6 @@ class GeoJsonLoader extends ResourceLoader {
   /**
    * The loaded components.
    *
-   * @memberof GeoJsonLoader.prototype
    *
    * @type {ModelComponents.Components}
    * @readonly

package/Source/Scene/Model/I3dmLoader.js

@@ -129,7 +129,6 @@ class I3dmLoader extends ResourceLoader {
   /**
    * true if textures are loaded, useful when incrementallyLoadTextures is true
    *
-   * @memberof  I3dmLoader.prototype
    *
    * @type {boolean}
    * @readonly
@@ -142,7 +141,6 @@ class I3dmLoader extends ResourceLoader {
   /**
    * The cache key of the resource
    *
-   * @memberof I3dmLoader.prototype
    *
    * @type {string}
    * @readonly
@@ -155,7 +153,6 @@ class I3dmLoader extends ResourceLoader {
   /**
    * The loaded components.
    *
-   * @memberof I3dmLoader.prototype
    *
    * @type {ModelComponents.Components}
    * @default {@link Matrix4.IDENTITY}

package/Source/Scene/Model/InstancingPipelineStage.js

@@ -706,7 +706,7 @@ function processTransformAttributes(
   );
 
   // Only use matrices for the transforms if the rotation attribute is defined.
-  if (defined(rotationAttribute)) {
+  if (defined(rotationAttribute) || keepTypedArray) {
     processTransformMatrixAttributes(
       renderResources,
       instances,

package/Source/Scene/Model/LightingModel.js

@@ -1,3 +1,5 @@
+// @ts-check
+
 /**
  * The lighting model to use for lighting a {@link Model}.
  *
@@ -27,4 +29,6 @@ const LightingModel = {
   PBR: 1,
 };
 
-export default Object.freeze(LightingModel);
+Object.freeze(LightingModel);
+
+export default LightingModel;

package/Source/Scene/Model/MaterialPipelineStage.js

@@ -2,9 +2,13 @@ import defined from "../../Core/defined.js";
 import Cartesian3 from "../../Core/Cartesian3.js";
 import Cartesian4 from "../../Core/Cartesian4.js";
 import Matrix3 from "../../Core/Matrix3.js";
+import Matrix4 from "../../Core/Matrix4.js";
+import Transforms from "../../Core/Transforms.js";
 import ShaderDestination from "../../Renderer/ShaderDestination.js";
 import Pass from "../../Renderer/Pass.js";
 import MaterialStageFS from "../../Shaders/Model/MaterialStageFS.js";
+import ConstantLodStageVS from "../../Shaders/Model/ConstantLodStageVS.js";
+import ConstantLodStageFS from "../../Shaders/Model/ConstantLodStageFS.js";
 import AlphaMode from "../AlphaMode.js";
 import ModelComponents from "../ModelComponents.js";
 import VertexAttributeSemantic from "../VertexAttributeSemantic.js";
@@ -61,6 +65,25 @@ MaterialPipelineStage.process = function (
   const material = primitive.material;
   const { model, uniformMap, shaderBuilder } = renderResources;
 
+  if (!defined(uniformMap.u_constantLodDistance)) {
+    uniformMap.u_constantLodDistance = function () {
+      const boundingSphere = model.boundingSphere;
+      const camera = frameState.camera;
+
+      if (defined(boundingSphere) && defined(camera)) {
+        const distance = Cartesian3.distance(
+          camera.positionWC,
+          boundingSphere.center,
+        );
+        // Clamp to a minimum small distance to avoid calling log2(0) in shader
+        return Math.max(distance, 0.1);
+      }
+
+      // Return a fallback distance before camera/bounding sphere are available
+      return 1.0;
+    };
+  }
+
   // Classification models only use position and feature ID attributes,
   // so textures should be disabled to avoid compile errors.
   const hasClassification = defined(model.classificationType);
@@ -78,6 +101,7 @@ MaterialPipelineStage.process = function (
     defaultNormalTexture,
     defaultEmissiveTexture,
     disableTextures,
+    renderResources,
   );
 
   if (defined(material.specularGlossiness)) {
@@ -87,6 +111,7 @@ MaterialPipelineStage.process = function (
       shaderBuilder,
       defaultTexture,
       disableTextures,
+      renderResources,
     );
   } else {
     if (
@@ -131,6 +156,7 @@ MaterialPipelineStage.process = function (
       shaderBuilder,
       defaultTexture,
       disableTextures,
+      renderResources,
     );
   }
 
@@ -206,6 +232,112 @@ MaterialPipelineStage.process = function (
   }
 };
 
+/**
+ * Process constant LOD extension for a texture
+ *
+ * @param {ShaderBuilder} shaderBuilder The shader builder to modify
+ * @param {Object<string, Function>} uniformMap The uniform map to modify.
+ * @param {ModelComponents.TextureReader} textureReader The texture to add to the shader
+ * @param {string} uniformName The name of the sampler uniform
+ * @param {string} defineName The name of the texture for use in the defines
+ * @param {PrimitiveRenderResources|undefined} renderResources The render resources
+ * @private
+ */
+function processConstantLod(
+  shaderBuilder,
+  uniformMap,
+  textureReader,
+  uniformName,
+  defineName,
+  renderResources,
+) {
+  const constantLod = textureReader.constantLod;
+
+  if (!defined(constantLod)) {
+    return;
+  }
+
+  // renderResources is required for constant LOD to transform from ECEF/world coordinates to ENU
+  if (!defined(renderResources)) {
+    return;
+  }
+
+  const constantLodDefine = `HAS_${defineName}_CONSTANT_LOD`;
+  shaderBuilder.addDefine(constantLodDefine, undefined, ShaderDestination.BOTH);
+
+  if (!defined(uniformMap.u_constantLodOffset)) {
+    shaderBuilder.addDefine(
+      "HAS_CONSTANT_LOD",
+      undefined,
+      ShaderDestination.BOTH,
+    );
+
+    shaderBuilder.addVarying("vec3", "v_constantLodUvCustom");
+
+    shaderBuilder.addUniform(
+      "vec2",
+      "u_constantLodOffset",
+      ShaderDestination.VERTEX,
+    );
+
+    shaderBuilder.addUniform(
+      "float",
+      "u_constantLodDistance",
+      ShaderDestination.VERTEX,
+    );
+
+    shaderBuilder.addUniform(
+      "mat4",
+      "u_constantLodWorldToEnu",
+      ShaderDestination.VERTEX,
+    );
+
+    shaderBuilder.addFragmentLines(ConstantLodStageFS);
+
+    const constantLodLines = ConstantLodStageVS.split("\n").filter((line) => {
+      return !line.trim().startsWith("//") || line.includes("#");
+    });
+    shaderBuilder.addFunctionLines("setDynamicVaryingsVS", constantLodLines);
+  }
+
+  const paramsUniformName = `${uniformName}ConstantLodParams`;
+  shaderBuilder.addUniform(
+    "vec3",
+    paramsUniformName,
+    ShaderDestination.FRAGMENT,
+  );
+
+  uniformMap[paramsUniformName] = function () {
+    return new Cartesian3(
+      constantLod.minClampDistance,
+      constantLod.maxClampDistance,
+      constantLod.repetitions,
+    );
+  };
+
+  if (!defined(uniformMap.u_constantLodOffset)) {
+    uniformMap.u_constantLodOffset = function () {
+      return constantLod.offset;
+    };
+
+    const enuMatrixInverse = Matrix4.clone(Matrix4.IDENTITY);
+    let matrixComputed = false;
+
+    uniformMap.u_constantLodWorldToEnu = function () {
+      if (!matrixComputed) {
+        const boundingSphere = renderResources.model.boundingSphere;
+        if (defined(boundingSphere)) {
+          const modelCenter = boundingSphere.center;
+          const enuFrame = Transforms.eastNorthUpToFixedFrame(modelCenter);
+          Matrix4.inverse(enuFrame, enuMatrixInverse);
+          matrixComputed = true;
+        }
+      }
+      return matrixComputed ? enuMatrixInverse : Matrix4.IDENTITY;
+    };
+  }
+}
+
 /**
  * Add uniforms and defines for the BENTLEY_materials_line_style extension.
  *
@@ -426,6 +558,8 @@ function processTextureScale(
  * @param {ModelComponents.TextureReader} textureReader The texture to add to the shader
  * @param {string} uniformName The name of the sampler uniform such as <code>u_baseColorTexture</code>
  * @param {string} defineName The name of the texture for use in the defines, minus any prefix or suffix. For example, "BASE_COLOR" or "EMISSIVE"
+ * @param {Texture} defaultTexture The default texture to use as a fallback if the texture is not yet loaded
+ * @param {PrimitiveRenderResources|undefined} renderResources The render resources
  *
  * @private
  */
@@ -436,6 +570,7 @@ function processTexture(
   uniformName,
   defineName,
   defaultTexture,
+  renderResources,
 ) {
   // Add a uniform for the texture itself
   shaderBuilder.addUniform(
@@ -487,6 +622,16 @@ function processTexture(
       defineName,
     );
   }
+
+  // Process constant LOD extension if present
+  processConstantLod(
+    shaderBuilder,
+    uniformMap,
+    textureReader,
+    uniformName,
+    defineName,
+    renderResources,
+  );
 }
 
 function processMaterialUniforms(
@@ -497,6 +642,7 @@ function processMaterialUniforms(
   defaultNormalTexture,
   defaultEmissiveTexture,
   disableTextures,
+  renderResources,
 ) {
   const { emissiveFactor, emissiveTexture, normalTexture, occlusionTexture } =
     material;
@@ -531,14 +677,43 @@ function processMaterialUniforms(
     }
   }
 
+  // Extract base color constant LOD to apply to normal texture
+  let baseColorConstantLod;
+  if (
+    defined(material.metallicRoughness) &&
+    defined(material.metallicRoughness.baseColorTexture) &&
+    defined(material.metallicRoughness.baseColorTexture.constantLod)
+  ) {
+    baseColorConstantLod =
+      material.metallicRoughness.baseColorTexture.constantLod;
+  } else if (
+    defined(material.specularGlossiness) &&
+    defined(material.specularGlossiness.diffuseTexture) &&
+    defined(material.specularGlossiness.diffuseTexture.constantLod)
+  ) {
+    baseColorConstantLod =
+      material.specularGlossiness.diffuseTexture.constantLod;
+  }
+
   if (defined(normalTexture) && !disableTextures) {
+    // If normal texture AND base color have constant LOD, use base color's constant LOD properties to keep textures in sync
+    let normalTextureToProcess = normalTexture;
+    if (defined(normalTexture.constantLod) && defined(baseColorConstantLod)) {
+      normalTextureToProcess = Object.create(
+        Object.getPrototypeOf(normalTexture),
+      );
+      Object.assign(normalTextureToProcess, normalTexture);
+      normalTextureToProcess.constantLod = baseColorConstantLod;
+    }
+
     processTexture(
       shaderBuilder,
       uniformMap,
-      normalTexture,
+      normalTextureToProcess,
       "u_normalTexture",
       "NORMAL",
       defaultNormalTexture,
+      renderResources,
     );
   }
 
@@ -560,8 +735,9 @@ function processMaterialUniforms(
  * @param {ModelComponents.SpecularGlossiness} specularGlossiness
  * @param {Object<string, Function>} uniformMap The uniform map to modify.
  * @param {ShaderBuilder} shaderBuilder
- * @param {Texture} defaultTexture
+ * @param {Texture} defaultTexture The default texture to use as a fallback if the texture is not yet loaded
  * @param {boolean} disableTextures
+ * @param {PrimitiveRenderResources|undefined} renderResources The render resources for the primitive
  * @private
  */
 function processSpecularGlossinessUniforms(
@@ -570,6 +746,7 @@ function processSpecularGlossinessUniforms(
   shaderBuilder,
   defaultTexture,
   disableTextures,
+  renderResources,
 ) {
   const {
     diffuseTexture,
@@ -593,6 +770,7 @@ function processSpecularGlossinessUniforms(
       "u_diffuseTexture",
       "DIFFUSE",
       defaultTexture,
+      renderResources,
     );
   }
 
@@ -925,8 +1103,9 @@ function processClearcoatUniforms(
  * @param {ModelComponents.MetallicRoughness} metallicRoughness
  * @param {Object<string, Function>} uniformMap The uniform map to modify.
  * @param {ShaderBuilder} shaderBuilder
- * @param {Texture} defaultTexture
+ * @param {Texture} defaultTexture The default texture to use as a fallback if the texture is not yet loaded
  * @param {boolean} disableTextures
+ * @param {PrimitiveRenderResources|undefined} renderResources The render resources for the primitive
  * @private
  */
 function processMetallicRoughnessUniforms(
@@ -935,6 +1114,7 @@ function processMetallicRoughnessUniforms(
   shaderBuilder,
   defaultTexture,
   disableTextures,
+  renderResources,
 ) {
   shaderBuilder.addDefine(
     "USE_METALLIC_ROUGHNESS",
@@ -951,6 +1131,7 @@ function processMetallicRoughnessUniforms(
       "u_baseColorTexture",
       "BASE_COLOR",
       defaultTexture,
+      renderResources,
     );
   }