@hztxi/cesium-engine 25.0.6 → 26.2.1

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

package/Source/Scene/QuadtreePrimitive.js

@@ -1781,11 +1781,12 @@ function updateHeights(primitive, frameState) {
           );
 
           if (defined(position)) {
-            // Store the computed position in the cache for future reuse
+            // `pick` wrote into the module-level `scratchPosition`, so `position`
+            // aliases it — clone before caching or the next pick mutates every entry.
             tile.setPositionCacheEntry(
               data.positionCartographic,
               primitive.maximumScreenSpaceError,
-              position,
+              Cartesian3.clone(position),
             );
           }
         }

package/Source/Scene/ResourceCache.js

@@ -419,7 +419,7 @@ ResourceCache.getSpzLoader = function (options) {
 
   const cacheKey = ResourceCacheKey.getSpzCacheKey({
     gltf: gltf,
-    primitive: primitive,
+    spz: spz,
     gltfResource: gltfResource,
     baseResource: baseResource,
   });
@@ -453,13 +453,14 @@ ResourceCache.getSpzLoader = function (options) {
  * @param {number} [options.bufferViewId] The bufferView ID corresponding to the vertex buffer.
  * @param {object} [options.primitive] The primitive containing the Draco extension.
  * @param {object} [options.draco] The Draco extension object.
+ * @param {object} [options.spz] The SPZ extension object.
  * @param {string} [options.attributeSemantic] The attribute semantic, e.g. POSITION or NORMAL.
  * @param {number} [options.accessorId] The accessor ID.
  * @param {boolean} [options.asynchronous=true] Determines if WebGL resource creation will be spread out over several frames or block until all WebGL resources are created.
  * @param {boolean} [options.dequantize=false] Determines whether or not the vertex buffer will be dequantized on the CPU.
  * @param {boolean} [options.loadBuffer=false] Load vertex buffer as a GPU vertex buffer.
  * @param {boolean} [options.loadTypedArray=false] Load vertex buffer as a typed array.
- * @exception {DeveloperError} One of options.bufferViewId and options.draco must be defined.
+ * @exception {DeveloperError} Exactly one vertex buffer source must be effective: options.bufferViewId, options.spz, or options.draco for options.attributeSemantic.
  * @exception {DeveloperError} When options.draco is defined options.attributeSemantic must also be defined.
  * @exception {DeveloperError} When options.draco is defined options.accessorId must also be defined.
  *
@@ -503,9 +504,11 @@ ResourceCache.getVertexBufferLoader = function (options) {
   const hasAccessorId = defined(accessorId);
   const hasSpz = defined(spz);
 
-  if (hasBufferViewId === (hasDraco !== hasSpz)) {
+  const sourceCount =
+    Number(hasBufferViewId) + Number(hasDraco) + Number(hasSpz);
+  if (sourceCount !== 1) {
     throw new DeveloperError(
-      "One of options.bufferViewId, options.draco, or options.spz must be defined.",
+      "Exactly one vertex buffer source must be effective: options.bufferViewId, options.spz, or options.draco for options.attributeSemantic.",
     );
   }
 

package/Source/Scene/ResourceCacheKey.js

@@ -3,8 +3,8 @@ import Frozen from "../Core/Frozen.js";
 import defined from "../Core/defined.js";
 import DeveloperError from "../Core/DeveloperError.js";
 import getAbsoluteUri from "../Core/getAbsoluteUri.js";
+import findMeshoptExtension from "./findMeshoptExtension.js";
 import GltfLoaderUtil from "./GltfLoaderUtil.js";
-import hasExtension from "./hasExtension.js";
 
 /**
  * Compute cache keys for resources in {@link ResourceCache}.
@@ -22,8 +22,8 @@ function getExternalResourceCacheKey(resource) {
 function getBufferViewCacheKey(bufferView) {
   let { byteOffset, byteLength } = bufferView;
 
-  if (hasExtension(bufferView, "EXT_meshopt_compression")) {
-    const meshopt = bufferView.extensions.EXT_meshopt_compression;
+  const meshopt = findMeshoptExtension(bufferView);
+  if (defined(meshopt)) {
     byteOffset = meshopt.byteOffset ?? 0;
     byteLength = meshopt.byteLength;
   }
@@ -71,8 +71,8 @@ function getDracoCacheKey(gltf, draco, gltfResource, baseResource) {
   return `${bufferCacheKey}-range-${bufferViewCacheKey}`;
 }
 
-function getSpzCacheKey(gltf, primitive, gltfResource, baseResource) {
-  const bufferViewId = 0;
+function getSpzCacheKey(gltf, spz, gltfResource, baseResource) {
+  const bufferViewId = spz.bufferView;
   const bufferView = gltf.bufferViews[bufferViewId];
   const bufferId = bufferView.buffer;
   const buffer = gltf.buffers[bufferId];
@@ -247,8 +247,8 @@ ResourceCacheKey.getBufferViewCacheKey = function (options) {
   const bufferView = gltf.bufferViews[bufferViewId];
   let bufferId = bufferView.buffer;
   const buffer = gltf.buffers[bufferId];
-  if (hasExtension(bufferView, "EXT_meshopt_compression")) {
-    const meshopt = bufferView.extensions.EXT_meshopt_compression;
+  const meshopt = findMeshoptExtension(bufferView);
+  if (defined(meshopt)) {
     bufferId = meshopt.buffer;
   }
 
@@ -292,16 +292,16 @@ ResourceCacheKey.getDracoCacheKey = function (options) {
 
 ResourceCacheKey.getSpzCacheKey = function (options) {
   options = options ?? Frozen.EMPTY_OBJECT;
-  const { gltf, primitive, gltfResource, baseResource } = options;
+  const { gltf, spz, gltfResource, baseResource } = options;
 
   //>>includeStart('debug', pragmas.debug);
   Check.typeOf.object("options.gltf", gltf);
-  Check.typeOf.object("options.primitive", primitive);
+  Check.typeOf.object("options.spz", spz);
   Check.typeOf.object("options.gltfResource", gltfResource);
   Check.typeOf.object("options.baseResource", baseResource);
   //>>includeEnd('debug');
 
-  return `spz:${getSpzCacheKey(gltf, primitive, gltfResource, baseResource)}`;
+  return `spz:${getSpzCacheKey(gltf, spz, gltfResource, baseResource)}`;
 };
 /**
  * Gets the vertex buffer cache key.
@@ -313,11 +313,12 @@ ResourceCacheKey.getSpzCacheKey = function (options) {
  * @param {FrameState} options.frameState The frame state.
  * @param {number} [options.bufferViewId] The bufferView ID corresponding to the vertex buffer.
  * @param {object} [options.draco] The Draco extension object.
+ * @param {object} [options.spz] The SPZ extension object.
  * @param {string} [options.attributeSemantic] The attribute semantic, e.g. POSITION or NORMAL.
  * @param {boolean} [options.dequantize=false] Determines whether or not the vertex buffer will be dequantized on the CPU.
  * @param {boolean} [options.loadBuffer=false] Load vertex buffer as a GPU vertex buffer.
  * @param {boolean} [options.loadTypedArray=false] Load vertex buffer as a typed array.
- * @exception {DeveloperError} One of options.bufferViewId and options.draco must be defined.
+ * @exception {DeveloperError} Exactly one vertex buffer source must be effective: options.bufferViewId, options.spz, or options.draco for options.attributeSemantic.
  * @exception {DeveloperError} When options.draco is defined options.attributeSemantic must also be defined.
  *
  * @returns {string} The vertex buffer cache key.
@@ -350,9 +351,11 @@ ResourceCacheKey.getVertexBufferCacheKey = function (options) {
   const hasAttributeSemantic = defined(attributeSemantic);
   const hasSpz = defined(spz);
 
-  if (hasBufferViewId === (hasDraco !== hasSpz)) {
+  const sourceCount =
+    Number(hasBufferViewId) + Number(hasDraco) + Number(hasSpz);
+  if (sourceCount !== 1) {
     throw new DeveloperError(
-      "One of options.bufferViewId and options.draco must be defined.",
+      "Exactly one vertex buffer source must be effective: options.bufferViewId, options.spz, or options.draco for options.attributeSemantic.",
     );
   }
 
@@ -388,6 +391,11 @@ ResourceCacheKey.getVertexBufferCacheKey = function (options) {
     cacheKeySuffix += "-typed-array";
   }
 
+  if (defined(spz)) {
+    const spzCacheKey = getSpzCacheKey(gltf, spz, gltfResource, baseResource);
+    return `vertex-buffer:${spzCacheKey}-spz-${attributeSemantic}${cacheKeySuffix}`;
+  }
+
   if (defined(draco)) {
     const dracoCacheKey = getDracoCacheKey(
       gltf,
@@ -398,11 +406,6 @@ ResourceCacheKey.getVertexBufferCacheKey = function (options) {
     return `vertex-buffer:${dracoCacheKey}-draco-${attributeSemantic}${cacheKeySuffix}`;
   }
 
-  if (spz) {
-    const spzCacheKey = getSpzCacheKey(gltf, spz, gltfResource, baseResource);
-    return `vertex-buffer:${spzCacheKey}-spz-${attributeSemantic}${cacheKeySuffix}`;
-  }
-
   const bufferView = gltf.bufferViews[bufferViewId];
   const bufferId = bufferView.buffer;
   const buffer = gltf.buffers[bufferId];