@hztxi/cesium-engine 25.0.6 → 25.0.7

package/Source/Scene/GroundPolylinePrimitive.js

@@ -182,7 +182,7 @@ function GroundPolylinePrimitive(options) {
 
   this._retainedGeometryInstances = undefined;
 
-  /** @private Root {@link GroundPolylineGeometry} ref from the last inner {@link Primitive} build. */
+  /** Root {@link GroundPolylineGeometry} ref from the last inner {@link Primitive} build. @private */
   this._lastGroundPolylineRootGeometry = undefined;
 
   this._ready = false;
@@ -816,6 +816,7 @@ GroundPolylinePrimitive.prototype.update = function (frameState) {
       GroundPolylineGeometry.setProjectionAndEllipsoid(
         geometryInstance.geometry,
         frameState.mapProjection,
+        frameState.columbusRepeatWorlds,
       );
       geometryInstance.geometry._verticalExaggeration =
         frameState.verticalExaggeration;

package/Source/Scene/Polyline.js

@@ -34,6 +34,20 @@ import Material from "./Material.js";
  * @see PolylineCollection
  *
  */
+function makePolylineSegments(polyline, modelMatrix, columbusRepeatWorlds) {
+  if (columbusRepeatWorlds) {
+    // Columbus repeat worlds: keep the polyline continuous through the
+    // ±180° meridian instead of splitting it at the IDL.
+    // PolylineCollection's getSegments lifts the projected positions onto
+    // adjacent world copies so the line draws through the seam.
+    return {
+      positions: polyline._actualPositions,
+      lengths: [polyline._actualPositions.length],
+    };
+  }
+  return PolylinePipeline.wrapLongitude(polyline._actualPositions, modelMatrix);
+}
+
 function Polyline(options, polylineCollection) {
   options = options ?? Frozen.EMPTY_OBJECT;
 
@@ -76,9 +90,13 @@ function Polyline(options, polylineCollection) {
   }
 
   this._modelMatrix = modelMatrix;
-  this._segments = PolylinePipeline.wrapLongitude(
-    this._actualPositions,
+  this._columbusRepeatWorlds =
+    defined(polylineCollection) &&
+    polylineCollection._columbusRepeatWorlds === true;
+  this._segments = makePolylineSegments(
+    this,
     modelMatrix,
+    this._columbusRepeatWorlds,
   );
 
   this._actualLength = undefined;
@@ -371,10 +389,19 @@ Polyline.prototype.update = function () {
   const positionsChanged =
     this._propertiesChanged[POSITION_INDEX] > 0 ||
     this._propertiesChanged[POSITION_SIZE_INDEX] > 0;
-  if (!Matrix4.equals(modelMatrix, this._modelMatrix) || positionsChanged) {
-    this._segments = PolylinePipeline.wrapLongitude(
-      this._actualPositions,
+  const columbusRepeatWorlds =
+    defined(this._polylineCollection) &&
+    this._polylineCollection._columbusRepeatWorlds === true;
+  if (
+    !Matrix4.equals(modelMatrix, this._modelMatrix) ||
+    positionsChanged ||
+    columbusRepeatWorlds !== this._columbusRepeatWorlds
+  ) {
+    this._columbusRepeatWorlds = columbusRepeatWorlds;
+    this._segments = makePolylineSegments(
+      this,
       modelMatrix,
+      columbusRepeatWorlds,
     );
     this._boundingVolumeWC = BoundingSphere.transform(
       this._boundingVolume,

package/Source/Scene/PolylineCollection.js

@@ -32,6 +32,7 @@ import PolylineFS from "../Shaders/PolylineFS.js";
 import PolylineVS from "../Shaders/PolylineVS.js";
 import BatchTable from "./BatchTable.js";
 import BlendingState from "./BlendingState.js";
+import ColumbusWorlds from "./ColumbusWorlds.js";
 import Material from "./Material.js";
 import Polyline from "./Polyline.js";
 import SceneMode from "./SceneMode.js";
@@ -168,6 +169,11 @@ function PolylineCollection(options) {
 
   this._mode = undefined;
 
+  // Whether Columbus repeat worlds are enabled; when true, polylines are
+  // kept continuous through the ±180° meridian instead of being split at the
+  // IDL. Set each update() from the frame state.
+  this._columbusRepeatWorlds = false;
+
   this._polylinesToUpdate = [];
   this._vertexArrays = [];
   this._positionBuffer = undefined;
@@ -423,6 +429,16 @@ PolylineCollection.prototype.update = function (frameState) {
 
   updateMode(this, frameState);
 
+  const columbusRepeatWorlds =
+    frameState.columbusRepeatWorlds === true &&
+    frameState.mode === SceneMode.COLUMBUS_VIEW;
+  if (this._columbusRepeatWorlds !== columbusRepeatWorlds) {
+    // Toggling repeat worlds changes whether polylines are split at the IDL,
+    // which changes vertex buffer sizes; rebuild the vertex arrays.
+    this._columbusRepeatWorlds = columbusRepeatWorlds;
+    this._createVertexArray = true;
+  }
+
   const context = frameState.context;
   const projection = frameState.mapProjection;
   let polyline;
@@ -1784,6 +1800,27 @@ PolylineBucket.prototype.getSegments = function (polyline, projection) {
     );
   }
 
+  if (
+    newPositions.length > 0 &&
+    this.mode === SceneMode.COLUMBUS_VIEW &&
+    polyline._polylineCollection._columbusRepeatWorlds === true
+  ) {
+    // Columbus repeat worlds: the IDL split is disabled in this mode, so lift
+    // consecutive projected u values onto the same world copy. The line stays
+    // in the primary world; the scene renders the visible world copies by
+    // shifting the camera, so a line crossing the seam needs no per-copy
+    // placement of its own.
+    const worldWidth = ColumbusWorlds.getWorldWidth(projection);
+    for (let n = 1; n < newPositions.length; ++n) {
+      const du = newPositions[n].x - newPositions[n - 1].x;
+      if (du > worldWidth * 0.5) {
+        newPositions[n].x -= worldWidth;
+      } else if (du < -worldWidth * 0.5) {
+        newPositions[n].x += worldWidth;
+      }
+    }
+  }
+
   if (newPositions.length > 0) {
     polyline._boundingVolume2D = BoundingSphere.fromPoints(
       newPositions,

package/Source/Scene/Primitive.js

@@ -683,18 +683,20 @@ function createBatchTable(primitive, context) {
   primitive._batchTableOffsetAttribute2DIndex = offset2DIndex;
 }
 
-function cloneAttribute(attribute) {
-  let clonedValues;
-  if (Array.isArray(attribute.values)) {
-    clonedValues = attribute.values.slice(0);
-  } else {
-    clonedValues = new attribute.values.constructor(attribute.values);
+function cloneValues(values) {
+  if (Array.isArray(values)) {
+    return values.slice(0);
   }
+  const ValuesConstructor = values.constructor;
+  return new ValuesConstructor(values);
+}
+
+function cloneAttribute(attribute) {
   return new GeometryAttribute({
     componentDatatype: attribute.componentDatatype,
     componentsPerAttribute: attribute.componentsPerAttribute,
     normalize: attribute.normalize,
-    values: clonedValues,
+    values: cloneValues(attribute.values),
   });
 }
 
@@ -709,12 +711,7 @@ function cloneGeometry(geometry) {
 
   let indices;
   if (defined(geometry.indices)) {
-    const sourceValues = geometry.indices;
-    if (Array.isArray(sourceValues)) {
-      indices = sourceValues.slice(0);
-    } else {
-      indices = new sourceValues.constructor(sourceValues);
-    }
+    indices = cloneValues(geometry.indices);
   }
 
   return new Geometry({
@@ -1278,6 +1275,7 @@ function loadAsynchronous(primitive, frameState) {
           projection: projection,
           elementIndexUintSupported: frameState.context.elementIndexUint,
           scene3DOnly: scene3DOnly,
+          columbusRepeatWorlds: frameState.columbusRepeatWorlds === true,
           vertexCacheOptimize: primitive.vertexCacheOptimize,
           compressVertices: primitive.compressVertices,
           modelMatrix: primitive.modelMatrix,
@@ -1360,6 +1358,7 @@ function loadSynchronous(primitive, frameState) {
     projection: projection,
     elementIndexUintSupported: frameState.context.elementIndexUint,
     scene3DOnly: scene3DOnly,
+    columbusRepeatWorlds: frameState.columbusRepeatWorlds === true,
     vertexCacheOptimize: primitive.vertexCacheOptimize,
     compressVertices: primitive.compressVertices,
     modelMatrix: primitive.modelMatrix,

package/Source/Scene/PrimitivePipeline.js

@@ -12,6 +12,7 @@ import IndexDatatype from "../Core/IndexDatatype.js";
 import Matrix4 from "../Core/Matrix4.js";
 import OffsetGeometryInstanceAttribute from "../Core/OffsetGeometryInstanceAttribute.js";
 import WebMercatorProjection from "../Core/WebMercatorProjection.js";
+import ColumbusWorlds from "./ColumbusWorlds.js";
 
 function transformToWorldCoordinates(
   instances,
@@ -84,11 +85,120 @@ function addBatchIds(instances) {
   }
 }
 
+/**
+ * Keeps a polyline's projected 2D attributes on one contiguous world copy in
+ * Columbus repeat-worlds mode. PolylineGeometry subdivides along the arc and
+ * projects every vertex independently, so a line crossing the ±180° meridian
+ * ends up with consecutive vertices on opposite sides of the primary world,
+ * connected by an edge drawn across the whole map. Consecutive vertices whose
+ * projected u jumps by roughly a full world width are seam crossings: lift
+ * them onto the adjacent copy (the same rule PolylineCollection.getSegments
+ * applies). The per-vertex lift is computed from `position2D` and applied
+ * identically to `prevPosition2D` and `nextPosition2D` so each vertex's
+ * extrusion references stay on the copy the vertex itself was lifted to.
+ *
+ * Other primitive types (no prev/next position attributes) keep the stock
+ * per-side projection; their own IDL splitting still applies.
+ *
+ * @private
+ */
+function liftPolyline2DToWorldCopy(geometry, projection) {
+  const attributes = geometry.attributes;
+  const position2D = attributes.position2D;
+  const prevPosition2D = attributes.prevPosition2D;
+  const nextPosition2D = attributes.nextPosition2D;
+  if (
+    !defined(position2D) ||
+    !defined(prevPosition2D) ||
+    !defined(nextPosition2D)
+  ) {
+    return;
+  }
+
+  const worldWidth = ColumbusWorlds.getWorldWidth(projection);
+  const halfWorldWidth = worldWidth * 0.5;
+  const positions = position2D.values;
+  const vertexCount = positions.length / 3;
+  const lifts = new Float64Array(vertexCount);
+
+  let lift = 0.0;
+  let lifted = false;
+  for (let i = 1; i < vertexCount; ++i) {
+    const du = positions[i * 3] - (positions[(i - 1) * 3] + lift);
+    if (du > halfWorldWidth) {
+      lift -= worldWidth;
+      lifted = true;
+    } else if (du < -halfWorldWidth) {
+      lift += worldWidth;
+      lifted = true;
+    }
+    lifts[i] = lift;
+  }
+  if (!lifted) {
+    return;
+  }
+
+  const prevPositions = prevPosition2D.values;
+  const nextPositions = nextPosition2D.values;
+  for (let i = 0; i < vertexCount; ++i) {
+    const vertexLift = lifts[i];
+    if (vertexLift !== 0.0) {
+      positions[i * 3] += vertexLift;
+      prevPositions[i * 3] += vertexLift;
+      nextPositions[i * 3] += vertexLift;
+    }
+  }
+}
+
+/**
+ * Replays the world-copy shift that {@link GroundPolylineGeometry} baked into
+ * its 2D shadow-volume attributes onto the projected volume positions. The
+ * volume positions are projected here, after the geometry was built, so a
+ * ground polyline crossing the antimeridian would otherwise keep one half on
+ * the neighbouring world copy while its plane tests sit on the other, and the
+ * shifted half is discarded by the fragment shader.
+ *
+ * @private
+ */
+function liftGroundPolyline2DToWorldCopy(geometry, projection) {
+  const attributes = geometry.attributes;
+  const startHiLo2D = attributes.startHiLo2D;
+  const position2D = attributes.position2D;
+  if (!defined(startHiLo2D) || !defined(position2D)) {
+    return;
+  }
+
+  const worldWidth = ColumbusWorlds.getWorldWidth(projection);
+  const halfWorldWidth = worldWidth * 0.5;
+  if (!(halfWorldWidth > 0.0)) {
+    return;
+  }
+
+  const starts = startHiLo2D.values;
+  const positions = position2D.values;
+  const count = Math.min(starts.length / 4, positions.length / 3);
+  for (let i = 0; i < count; ++i) {
+    // startHiLo2D holds the segment start in the unwrapped projection space
+    // (GroundPolylineGeometry nudges and lifts the 2D attributes so a line
+    // crossing the antimeridian stays on one copy), while the volume position
+    // is projected from the ECEF position and therefore wraps. Snap the
+    // position onto the world copy of its own segment: the two can only
+    // differ by whole worlds.
+    const startU = starts[i * 4] + starts[i * 4 + 2];
+    const u = positions[i * 3];
+    const delta = startU - u;
+    if (delta > halfWorldWidth || delta < -halfWorldWidth) {
+      positions[i * 3] = u + Math.round(delta / worldWidth) * worldWidth;
+    }
+  }
+}
+
 function geometryPipeline(parameters) {
   const instances = parameters.instances;
   const projection = parameters.projection;
   const uintIndexSupport = parameters.elementIndexUintSupported;
   const scene3DOnly = parameters.scene3DOnly;
+  const columbusRepeatWorlds = parameters.columbusRepeatWorlds === true;
   const vertexCacheOptimize = parameters.vertexCacheOptimize;
   const compressVertices = parameters.compressVertices;
   const modelMatrix = parameters.modelMatrix;
@@ -170,41 +280,59 @@ function geometryPipeline(parameters) {
     // Split positions for GPU RTE
     const attributes = geometry.attributes;
     if (!scene3DOnly) {
+      // Collect DOUBLE attribute names up front: projectTo2D renames the
+      // attributes it touches, so projecting while iterating them risks
+      // reprocessing the freshly added *3D attributes.
+      const doubleAttributeNames = [];
       for (const name in attributes) {
         if (
           attributes.hasOwnProperty(name) &&
           attributes[name].componentDatatype === ComponentDatatype.DOUBLE
         ) {
-          const name3D = `${name}3D`;
-          const name2D = `${name}2D`;
+          doubleAttributeNames.push(name);
+        }
+      }
 
-          // Compute 2D positions
-          GeometryPipeline.projectTo2D(
-            geometry,
-            name,
-            name3D,
-            name2D,
-            projection,
-          );
-          if (defined(geometry.boundingSphere) && name === "position") {
-            geometry.boundingSphereCV = BoundingSphere.fromVertices(
-              geometry.attributes.position2D.values,
-            );
-          }
+      for (let a = 0; a < doubleAttributeNames.length; ++a) {
+        const name = doubleAttributeNames[a];
+        GeometryPipeline.projectTo2D(
+          geometry,
+          name,
+          `${name}3D`,
+          `${name}2D`,
+          projection,
+        );
+      }
 
-          GeometryPipeline.encodeAttribute(
-            geometry,
-            name3D,
-            `${name3D}High`,
-            `${name3D}Low`,
-          );
-          GeometryPipeline.encodeAttribute(
-            geometry,
-            name2D,
-            `${name2D}High`,
-            `${name2D}Low`,
-          );
-        }
+      if (columbusRepeatWorlds) {
+        liftPolyline2DToWorldCopy(geometry, projection);
+        liftGroundPolyline2DToWorldCopy(geometry, projection);
+      }
+
+      // Compute the Columbus-view bounding sphere before encodeAttribute
+      // renames position2D into position2DHigh/Low.
+      if (defined(geometry.boundingSphere) && defined(attributes.position2D)) {
+        geometry.boundingSphereCV = BoundingSphere.fromVertices(
+          attributes.position2D.values,
+        );
+      }
+
+      for (let a = 0; a < doubleAttributeNames.length; ++a) {
+        const name3D = `${doubleAttributeNames[a]}3D`;
+        const name2D = `${doubleAttributeNames[a]}2D`;
+
+        GeometryPipeline.encodeAttribute(
+          geometry,
+          name3D,
+          `${name3D}High`,
+          `${name3D}Low`,
+        );
+        GeometryPipeline.encodeAttribute(
+          geometry,
+          name2D,
+          `${name2D}High`,
+          `${name2D}Low`,
+        );
       }
     } else {
       for (const name in attributes) {
@@ -715,6 +843,7 @@ PrimitivePipeline.packCombineGeometryParameters = function (
     isGeographic: parameters.projection instanceof GeographicProjection,
     elementIndexUintSupported: parameters.elementIndexUintSupported,
     scene3DOnly: parameters.scene3DOnly,
+    columbusRepeatWorlds: parameters.columbusRepeatWorlds === true,
     vertexCacheOptimize: parameters.vertexCacheOptimize,
     compressVertices: parameters.compressVertices,
     modelMatrix: parameters.modelMatrix,
@@ -761,6 +890,7 @@ PrimitivePipeline.unpackCombineGeometryParameters = function (
     projection: projection,
     elementIndexUintSupported: packedParameters.elementIndexUintSupported,
     scene3DOnly: packedParameters.scene3DOnly,
+    columbusRepeatWorlds: packedParameters.columbusRepeatWorlds === true,
     vertexCacheOptimize: packedParameters.vertexCacheOptimize,
     compressVertices: packedParameters.compressVertices,
     modelMatrix: Matrix4.clone(packedParameters.modelMatrix),