feat: moved environmentMapOptions to Entity

Author: jfayot

.vscode/cspell.json

@@ -95,6 +95,7 @@
     "unregisters",
     "unrenderable",
     "voxel",
+    "VVLH",
     "WEBG",
     "xdescribe"
   ]

CHANGES.md

@@ -6,7 +6,7 @@
 
 ##### Fixes :wrench:
 
-- Added `enableEnvironmentMap` to `ModelGraphics` constructor options to allow long distance `Entity` movements without performance drop. [#12358](https://github.com/CesiumGS/cesium/pull/12358)
+- Added `environmentMapOptions` to `Entity`'s constructor options with EnvironmentMap disabled by default to allow long distance `Entity` jumps without performance drop. If EnvironmentMap needs to be enabled, ensure to provide a `maximumPositionEpsilon` threshold value large enough with your entity movements use case. [#12358](https://github.com/CesiumGS/cesium/pull/12358)
 
 ### 1.124 - 2024-12-02
 

packages/engine/Source/DataSources/Cesium3DTilesetVisualizer.js

@@ -243,7 +243,9 @@ async function createTileset(resource, tilesetHash, entity, primitives) {
   };
 
   try {
-    const tileset = await Cesium3DTileset.fromUrl(resource);
+    const tileset = await Cesium3DTileset.fromUrl(resource, {
+      environmentMapOptions: entity._environmentMapOptions,
+    });
     tileset.id = entity;
     primitives.add(tileset);
 

packages/engine/Source/DataSources/Entity.js

@@ -98,6 +98,7 @@ function createPropertyTypeDescriptor(name, Type) {
  * @property {PolylineVolumeGraphics | PolylineVolumeGraphics.ConstructorOptions} [polylineVolume] A polylineVolume to associate with this entity.
  * @property {RectangleGraphics | RectangleGraphics.ConstructorOptions} [rectangle] A rectangle to associate with this entity.
  * @property {WallGraphics | WallGraphics.ConstructorOptions} [wall] A wall to associate with this entity.
+ * @property {DynamicEnvironmentMapManager.ConstructorOptions} [environmentMapOptions={enabled: false}] The properties for managing dynamic environment maps on this entity.
  */
 
 /**
@@ -122,6 +123,9 @@ function Entity(options) {
   this._availability = undefined;
   this._id = id;
   this._definitionChanged = new Event();
+  this._environmentMapOptions = defaultValue(options.environmentMapOptions, {
+    enabled: false,
+  });
   this._name = options.name;
   this._show = defaultValue(options.show, true);
   this._trackingReferenceFrame = defaultValue(

packages/engine/Source/DataSources/ModelGraphics.js

@@ -46,7 +46,6 @@ function createArticulationStagePropertyBag(value) {
  * @property {PropertyBag | Object<string, number>} [articulations] An object, where keys are composed of an articulation name, a single space, and a stage name, and the values are numeric properties.
  * @property {Property | ClippingPlaneCollection} [clippingPlanes] A property specifying the {@link ClippingPlaneCollection} used to selectively disable rendering the model.
  * @property {Property | CustomShader} [customShader] A property specifying the {@link CustomShader} to apply to this model.
- * @property {Property | boolean} [enableEnvironmentMap=true] A boolean Property specifying if the model has {@link DynamicEnvironmentMapManager} enabled.
  */
 
 /**
@@ -114,8 +113,6 @@ function ModelGraphics(options) {
   this._clippingPlanesSubscription = undefined;
   this._customShader = undefined;
   this._customShaderSubscription = undefined;
-  this._enableEnvironmentMap = undefined;
-  this._enableEnvironmentMapSubscription = undefined;
 
   this.merge(defaultValue(options, defaultValue.EMPTY_OBJECT));
 }
@@ -336,14 +333,6 @@ Object.defineProperties(ModelGraphics.prototype, {
    * @type {Property|undefined}
    */
   customShader: createPropertyDescriptor("customShader"),
-
-  /**
-   * Gets or sets the boolean Property specifying if the model has {@link DynamicEnvironmentMapManager} enabled.
-   * @memberof ModelGraphics.prototype
-   * @type {Property|undefined}
-   * @default true
-   */
-  enableEnvironmentMap: createPropertyDescriptor("enableEnvironmentMap"),
 });
 
 /**
@@ -378,7 +367,6 @@ ModelGraphics.prototype.clone = function (result) {
   result.articulations = this.articulations;
   result.clippingPlanes = this.clippingPlanes;
   result.customShader = this.customShader;
-  result.enableEnvironmentMap = this.enableEnvironmentMap;
   return result;
 };
 
@@ -453,10 +441,6 @@ ModelGraphics.prototype.merge = function (source) {
     source.clippingPlanes,
   );
   this.customShader = defaultValue(this.customShader, source.customShader);
-  this.enableEnvironmentMap = defaultValue(
-    this.enableEnvironmentMap,
-    source.enableEnvironmentMap,
-  );
 
   const sourceNodeTransformations = source.nodeTransformations;
   if (defined(sourceNodeTransformations)) {

packages/engine/Source/DataSources/ModelVisualizer.js

@@ -35,7 +35,6 @@ const defaultColor = Color.WHITE;
 const defaultColorBlendMode = ColorBlendMode.HIGHLIGHT;
 const defaultColorBlendAmount = 0.5;
 const defaultImageBasedLightingFactor = new Cartesian2(1.0, 1.0);
-const defaultEnableEnvironmentMap = true;
 
 const modelMatrixScratch = new Matrix4();
 const nodeMatrixScratch = new Matrix4();
@@ -86,6 +85,7 @@ async function createModelPrimitive(
       url: resource,
       incrementallyLoadTextures: incrementallyLoadTextures,
       scene: visualizer._scene,
+      environmentMapOptions: entity._environmentMapOptions,
     });
 
     if (visualizer.isDestroyed() || !defined(modelHash[entity.id])) {
@@ -290,12 +290,6 @@ ModelVisualizer.prototype.update = function (time) {
       time,
     );
 
-    model.environmentMapManager.enabled = Property.getValueOrDefault(
-      modelGraphics._enableEnvironmentMap,
-      time,
-      defaultEnableEnvironmentMap,
-    );
-
     // It's possible for getBoundingSphere to run before
     // model becomes ready and these properties are updated
     modelHash[entity.id].modelUpdated = true;

packages/engine/Source/Scene/Cesium3DTileset.js

@@ -105,7 +105,7 @@ import DynamicEnvironmentMapManager from "./DynamicEnvironmentMapManager.js";
  * @property {object} [pointCloudShading] Options for constructing a {@link PointCloudShading} object to control point attenuation based on geometric error and lighting.
  * @property {Cartesian3} [lightColor] The light color when shading models. When <code>undefined</code> the scene's light color is used instead.
  * @property {ImageBasedLighting} [imageBasedLighting] The properties for managing image-based lighting for this tileset.
- * @param {DynamicEnvironmentMapManager.ConstructorOptions} [options.environmentMapOptions] The properties for managing dynamic environment maps on this model.
+ * @property {DynamicEnvironmentMapManager.ConstructorOptions} [environmentMapOptions] The properties for managing dynamic environment maps on this tileset.
  * @property {boolean} [backFaceCulling=true] Whether to cull back-facing geometry. When true, back face culling is determined by the glTF material's doubleSided property; when false, back face culling is disabled.
  * @property {boolean} [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.
  * @property {boolean} [showOutline=true] Whether to display the outline for models using the {@link https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Vendor/CESIUM_primitive_outline|CESIUM_primitive_outline} extension. When true, outlines are displayed. When false, outlines are not displayed.

packages/engine/Specs/DataSources/Cesium3DTilesetVisualizerSpec.js

@@ -133,6 +133,7 @@ describe(
       visualizer.update(time);
       expect(primitive.show).toEqual(true);
       expect(primitive.maximumScreenSpaceError).toEqual(24.0);
+      expect(primitive.environmentMapManager.enabled).toEqual(false);
     });
 
     it("A Cesium3DTilesetGraphics with a Resource causes a primitive to be created.", async function () {

packages/engine/Specs/DataSources/ModelGraphicsSpec.js

@@ -49,7 +49,6 @@ describe("DataSources/ModelGraphics", function () {
       articulations: {
         "articulation1 stage1": 45,
       },
-      enableEnvironmentMap: false,
     };
 
     const model = new ModelGraphics(options);
@@ -105,9 +104,6 @@ describe("DataSources/ModelGraphics", function () {
     expect(model.lightColor.getValue()).toEqual(options.lightColor);
     expect(model.runAnimations.getValue()).toEqual(options.runAnimations);
     expect(model.clampAnimations.getValue()).toEqual(options.clampAnimations);
-    expect(model.enableEnvironmentMap.getValue()).toEqual(
-      options.enableEnvironmentMap,
-    );
 
     let actualNodeTransformations = model.nodeTransformations.getValue(
       new JulianDate(),
@@ -176,7 +172,6 @@ describe("DataSources/ModelGraphics", function () {
       "a1 s1": 10,
       "a2 s2": 20,
     };
-    source.enableEnvironmentMap = new ConstantProperty(true);
 
     const target = new ModelGraphics();
     target.merge(source);
@@ -209,7 +204,6 @@ describe("DataSources/ModelGraphics", function () {
     expect(target.clampAnimations).toBe(source.clampAnimations);
     expect(target.nodeTransformations).toEqual(source.nodeTransformations);
     expect(target.articulations).toEqual(source.articulations);
-    expect(target.enableEnvironmentMap).toBe(source.enableEnvironmentMap);
   });
 
   it("merge does not assign assigned properties", function () {
@@ -247,7 +241,6 @@ describe("DataSources/ModelGraphics", function () {
       "a1 s1": 10,
       "a2 s2": 20,
     };
-    source.enableEnvironmentMap = new ConstantProperty(true);
 
     const uri = new ConstantProperty("");
     const show = new ConstantProperty(true);
@@ -282,7 +275,6 @@ describe("DataSources/ModelGraphics", function () {
       "a1 s1": 10,
       "a2 s2": 20,
     });
-    const enableEnvironmentMap = new ConstantProperty(true);
 
     const target = new ModelGraphics();
     target.uri = uri;
@@ -307,7 +299,6 @@ describe("DataSources/ModelGraphics", function () {
     target.clampAnimations = clampAnimations;
     target.nodeTransformations = nodeTransformations;
     target.articulations = articulations;
-    target.enableEnvironmentMap = enableEnvironmentMap;
 
     target.merge(source);
 
@@ -333,7 +324,6 @@ describe("DataSources/ModelGraphics", function () {
     expect(target.clampAnimations).toBe(clampAnimations);
     expect(target.nodeTransformations).toBe(nodeTransformations);
     expect(target.articulations).toBe(articulations);
-    expect(target.enableEnvironmentMap).toBe(enableEnvironmentMap);
   });
 
   it("clone works", function () {
@@ -372,7 +362,6 @@ describe("DataSources/ModelGraphics", function () {
       "a1 s1": 10,
       "a2 s2": 20,
     };
-    source.enableEnvironmentMap = new ConstantProperty(true);
 
     const result = source.clone();
     expect(result.uri).toBe(source.uri);
@@ -403,7 +392,6 @@ describe("DataSources/ModelGraphics", function () {
     expect(result.clampAnimations).toBe(source.clampAnimations);
     expect(result.nodeTransformations).toEqual(source.nodeTransformations);
     expect(result.articulations).toEqual(source.articulations);
-    expect(result.enableEnvironmentMap).toEqual(source.enableEnvironmentMap);
   });
 
   it("merge throws if source undefined", function () {

packages/engine/Specs/DataSources/ModelVisualizerSpec.js

@@ -146,7 +146,6 @@ describe(
         new Cartesian2(0.5, 0.5),
       );
       model.lightColor = new ConstantProperty(new Color(1.0, 1.0, 0.0, 1.0));
-      model.enableEnvironmentMap = new ConstantProperty(false);
 
       const testObject = entityCollection.getOrCreateEntity("test");
       testObject.position = new ConstantPositionProperty(