@cesium/engine 24.0.0 → 26.0.0

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,
     );
   }
 

package/Source/Scene/Model/Model.js

@@ -20,6 +20,7 @@ import ClippingPlaneCollection from "../ClippingPlaneCollection.js";
 import ClippingPolygonCollection from "../ClippingPolygonCollection.js";
 import DynamicEnvironmentMapManager from "../DynamicEnvironmentMapManager.js";
 import ColorBlendMode from "../ColorBlendMode.js";
+import EdgeDisplayMode from "../EdgeDisplayMode.js";
 import GltfLoader from "../GltfLoader.js";
 import HeightReference, {
   isHeightReferenceRelative,
@@ -75,6 +76,11 @@ import ModelImagery from "./ModelImagery.js";
  *  {@link https://github.com/KhronosGroup/glTF/pull/2514|EXT_mesh_primitive_restart}
  *  </li>
  *  <li>
+ *  {@link https://github.com/KhronosGroup/glTF/pull/2479|EXT_mesh_primitive_edge_visibility}
+ *  (edges are hidden by default; set {@link EdgeDisplayMode} via
+ *  {@link Model#edgeDisplayMode} or {@link Cesium3DTileset#edgeDisplayMode} to display them)
+ *  </li>
+ *  <li>
  *  {@link https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Vendor/EXT_meshopt_compression|EXT_meshopt_compression}
  *  </li>
  *  <li>
@@ -151,6 +157,7 @@ import ModelImagery from "./ModelImagery.js";
  * @privateParam {Color} [options.color] A color that blends with the model's rendered color.
  * @privateParam {ColorBlendMode} [options.colorBlendMode=ColorBlendMode.HIGHLIGHT] Defines how the color blends with the model.
  * @privateParam {number} [options.colorBlendAmount=0.5] Value used to determine the color strength when the <code>colorBlendMode</code> is <code>MIX</code>. A value of 0.0 results in the model's rendered color while a value of 1.0 results in a solid color, with any value in-between resulting in a mix of the two.
+ * @privateParam {EdgeDisplayMode} [options.edgeDisplayMode=EdgeDisplayMode.SURFACES_ONLY] Controls how edges from the {@link https://github.com/KhronosGroup/glTF/pull/2479|EXT_mesh_primitive_edge_visibility} extension are rendered relative to surface geometry.
  * @privateParam {Color} [options.silhouetteColor=Color.RED] The silhouette color. If more than 256 models have silhouettes enabled, there is a small chance that overlapping models will have minor artifacts.
  * @privateParam {number} [options.silhouetteSize=0.0] The size of the silhouette in pixels.
  * @privateParam {boolean} [options.enableShowOutline=true] Whether to enable outlines for models using the {@link https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor/CESIUM_primitive_outline|CESIUM_primitive_outline} extension. This can be set to false to avoid the additional processing of geometry at load time. When false, the showOutlines and outlineColor options are ignored.
@@ -417,6 +424,8 @@ function Model(options) {
   this._enableDebugWireframe = options.enableDebugWireframe ?? false;
   this._enableShowOutline = options.enableShowOutline ?? true;
   this._debugWireframe = options.debugWireframe ?? false;
+  this._edgeDisplayMode =
+    options.edgeDisplayMode ?? EdgeDisplayMode.SURFACES_ONLY;
 
   // Warning for improper setup of debug wireframe
   if (
@@ -1204,6 +1213,29 @@ Object.defineProperties(Model.prototype, {
     },
   },
 
+  /**
+   * Controls how edges from the
+   * {@link https://github.com/KhronosGroup/glTF/pull/2479|EXT_mesh_primitive_edge_visibility}
+   * glTF extension are rendered relative to surface geometry. Primitives that
+   * do not declare the extension are unaffected by this setting.
+   *
+   * @memberof Model.prototype
+   *
+   * @type {EdgeDisplayMode}
+   *
+   * @default EdgeDisplayMode.SURFACES_ONLY
+   *
+   * @experimental This feature is using part of the glTF spec that is not yet final and is subject to change without Cesium's standard deprecation policy.
+   */
+  edgeDisplayMode: {
+    get: function () {
+      return this._edgeDisplayMode;
+    },
+    set: function (value) {
+      this._edgeDisplayMode = value;
+    },
+  },
+
   /**
    * Whether or not to render the model.
    *
@@ -2941,6 +2973,7 @@ Model.prototype.destroyModelResources = function () {
  * @param {Color} [options.color] A color that blends with the model's rendered color.
  * @param {ColorBlendMode} [options.colorBlendMode=ColorBlendMode.HIGHLIGHT] Defines how the color blends with the model.
  * @param {number} [options.colorBlendAmount=0.5] Value used to determine the color strength when the <code>colorBlendMode</code> is <code>MIX</code>. A value of 0.0 results in the model's rendered color while a value of 1.0 results in a solid color, with any value in-between resulting in a mix of the two.
+ * @param {EdgeDisplayMode} [options.edgeDisplayMode=EdgeDisplayMode.SURFACES_ONLY] Controls how edges from the {@link https://github.com/KhronosGroup/glTF/pull/2479|EXT_mesh_primitive_edge_visibility} extension are rendered relative to surface geometry.
  * @param {Color} [options.silhouetteColor=Color.RED] The silhouette color. If more than 256 models have silhouettes enabled, there is a small chance that overlapping models will have minor artifacts.
  * @param {number} [options.silhouetteSize=0.0] The size of the silhouette in pixels.
  * @param {boolean} [options.enableShowOutline=true] Whether to enable outlines for models using the {@link https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor/CESIUM_primitive_outline|CESIUM_primitive_outline} extension. This can be set false to avoid post-processing geometry at load time. When false, the showOutlines and outlineColor options are ignored.
@@ -3307,6 +3340,7 @@ function makeModelOptions(loader, modelType, options) {
     color: options.color,
     colorBlendAmount: options.colorBlendAmount,
     colorBlendMode: options.colorBlendMode,
+    edgeDisplayMode: options.edgeDisplayMode,
     silhouetteColor: options.silhouetteColor,
     silhouetteSize: options.silhouetteSize,
     enableShowOutline: options.enableShowOutline,