@cesium/engine 26.1.0 → 26.3.0

package/Source/Scene/View.js

@@ -11,6 +11,7 @@ import Pass from "../Renderer/Pass.js";
 import PassState from "../Renderer/PassState.js";
 import Camera from "./Camera.js";
 import EdgeFramebuffer from "./EdgeFramebuffer.js";
+import PlanarFillIdFramebuffer from "./PlanarFillIdFramebuffer.js";
 import FrustumCommands from "./FrustumCommands.js";
 import GlobeDepth from "./GlobeDepth.js";
 import GlobeTranslucencyFramebuffer from "./GlobeTranslucencyFramebuffer.js";
@@ -62,9 +63,11 @@ function View(scene, camera, viewport) {
   this.viewport = viewport;
   this.passState = passState;
   this.pickFramebuffer = new PickFramebuffer(context);
+  this.snapFramebuffer = undefined;
   this.pickDepthFramebuffer = new PickDepthFramebuffer();
   this.sceneFramebuffer = new SceneFramebuffer();
   this.edgeFramebuffer = new EdgeFramebuffer();
+  this.planarFillIdFramebuffer = new PlanarFillIdFramebuffer();
   this.globeDepth = globeDepth;
   this.globeTranslucencyFramebuffer = new GlobeTranslucencyFramebuffer();
   this.oit = oit;
@@ -211,15 +214,11 @@ function updateFrustums(view, scene, near, far) {
       curNear = Math.max(near, Math.pow(farToNearRatio, m) * near);
       curFar = Math.min(far, farToNearRatio * curNear);
     }
-    let frustumCommands = frustumCommandsList[m];
-    if (!defined(frustumCommands)) {
-      frustumCommands = frustumCommandsList[m] = new FrustumCommands(
-        curNear,
-        curFar,
-      );
+    if (!defined(frustumCommandsList[m])) {
+      frustumCommandsList[m] = new FrustumCommands(curNear, curFar);
     } else {
-      frustumCommands.near = curNear;
-      frustumCommands.far = curFar;
+      frustumCommandsList[m].near = curNear;
+      frustumCommandsList[m].far = curFar;
     }
   }
 }
@@ -443,11 +442,14 @@ View.prototype.createPotentiallyVisibleSet = function (scene) {
 
 View.prototype.destroy = function () {
   this.pickFramebuffer = this.pickFramebuffer && this.pickFramebuffer.destroy();
+  this.snapFramebuffer = this.snapFramebuffer && this.snapFramebuffer.destroy();
   this.pickDepthFramebuffer =
     this.pickDepthFramebuffer && this.pickDepthFramebuffer.destroy();
   this.sceneFramebuffer =
     this.sceneFramebuffer && this.sceneFramebuffer.destroy();
   this.edgeFramebuffer = this.edgeFramebuffer && this.edgeFramebuffer.destroy();
+  this.planarFillIdFramebuffer =
+    this.planarFillIdFramebuffer && this.planarFillIdFramebuffer.destroy();
   this.globeDepth = this.globeDepth && this.globeDepth.destroy();
   this.oit = this.oit && this.oit.destroy();
   this.translucentTileClassification =

package/Source/Scene/VoxelTraversal.js

@@ -602,7 +602,7 @@ function updateKeyframeNodes(that, frameState) {
         that._primitive.tileFailed.raiseEvent();
         continue;
       }
-      let addNodeIndex = 0;
+      let addNodeIndex;
       if (megatexture.isFull()) {
         // If the megatexture is full, try removing a discardable node with the lowest priority.
         addNodeIndex = keyframeNodesInMegatextureCount - 1 - destroyedCount;

package/Source/Scene/WebMapServiceImageryProvider.js

@@ -48,7 +48,10 @@ const excludesReverseAxis = [
  * @property {object} [getFeatureInfoParameters=WebMapServiceImageryProvider.GetFeatureInfoDefaultParameters] Additional parameters to pass to the WMS server in the GetFeatureInfo URL.
  * @property {Resource|string} [getFeatureInfoUrl] The getFeatureInfo URL of the WMS service. If the property is not defined then we use the property value of url.
  * @property {GetFeatureInfoFormat[]} [getFeatureInfoFormats=WebMapServiceImageryProvider.DefaultGetFeatureInfoFormats] The formats
- *        in which to try WMS GetFeatureInfo requests.
+ *        in which to try WMS GetFeatureInfo requests. Since feature info responses vary across WMS services,
+ *        you may need to supply a custom format and parsing callback; see the
+ *        {@link https://sandcastle.cesium.com/?id=web-map-tile-service-picking|Sandcastle example} for a complete
+ *        example of writing your own callback.
  * @property {Rectangle} [rectangle=Rectangle.MAX_VALUE] The rectangle of the layer.
  * @property {TilingScheme} [tilingScheme=new GeographicTilingScheme()] The tiling scheme to use to divide the world into tiles.
  * @property {Ellipsoid} [ellipsoid] The ellipsoid.  If the tilingScheme is specified,
@@ -90,6 +93,7 @@ const excludesReverseAxis = [
  *
  * @see {@link https://enterprise.arcgis.com/en/server/latest/publish-services/linux/wms-services.htm|ArcGIS Server WMS Services}
  * @see {@link http://www.w3.org/TR/cors/|Cross-Origin Resource Sharing}
+ * @see {@link https://sandcastle.cesium.com/?id=web-map-tile-service-picking|Custom GetFeatureInfo Sandcastle Example}
  *
  * @example
  * // WMS servers operated by the US government https://apps.nationalmap.gov/services/

package/Source/Scene/WebMapTileServiceImageryProvider.js

@@ -29,7 +29,10 @@ import GetFeatureInfoFormat from "./GetFeatureInfoFormat.js";
  * @property {object} [getFeatureInfoParameters] Additional parameters to include in GetFeatureInfo requests. Keys are lowercased internally.
  * @property {Resource|string} [getFeatureInfoUrl] The GetFeatureInfo URL of the WMTS service. If not specified, the value of <code>url</code> is used.
  * @property {GetFeatureInfoFormat[]} [getFeatureInfoFormats=WebMapTileServiceImageryProvider.DefaultGetFeatureInfoFormats] The formats
- *                          in which to try WMTS GetFeatureInfo requests.
+ *                          in which to try WMTS GetFeatureInfo requests. Since feature info responses vary across WMTS services,
+ *                          you may need to supply a custom format and parsing callback; see the
+ *                          {@link https://sandcastle.cesium.com/?id=web-map-tile-service-picking|Sandcastle example} for a complete
+ *                          example of writing your own callback.
  * @property {Rectangle} [rectangle=Rectangle.MAX_VALUE] The rectangle covered by the layer.
  * @property {TilingScheme} [tilingScheme] The tiling scheme corresponding to the organization of the tiles in the TileMatrixSet.
  * @property {Ellipsoid} [ellipsoid] The ellipsoid.  If not specified, the WGS84 ellipsoid is used.
@@ -176,6 +179,8 @@ import GetFeatureInfoFormat from "./GetFeatureInfoFormat.js";
  * @see TileMapServiceImageryProvider
  * @see WebMapServiceImageryProvider
  * @see UrlTemplateImageryProvider
+ * 
+ * @see {@link https://sandcastle.cesium.com/?id=web-map-tile-service-picking|Custom GetFeatureInfo Sandcastle Example}
  */
 function WebMapTileServiceImageryProvider(options) {
   options = options ?? Frozen.EMPTY_OBJECT;

package/Source/Scene/createElevationBandMaterial.js

@@ -202,7 +202,7 @@ function createLayeredEntries(layers) {
   const layeredEntries = preprocess(layers);
 
   let entriesAccumNext = [];
-  let entriesAccumCurr = [];
+  let entriesAccumCurr;
   let i;
 
   function addEntry(height, color) {

package/Source/Scene/renderBufferPointCollection.js

@@ -306,8 +306,7 @@ function renderBufferPointCollection(collection, frameState, renderContext) {
 
   frameState.commandList.push(command);
 
-  collection._dirtyCount = 0;
-  collection._dirtyOffset = 0;
+  collection._makeClean();
 
   return renderContext;
 }

package/Source/Scene/renderBufferPolygonCollection.js

@@ -332,8 +332,7 @@ function renderBufferPolygonCollection(collection, frameState, renderContext) {
 
   frameState.commandList.push(command);
 
-  collection._dirtyCount = 0;
-  collection._dirtyOffset = 0;
+  collection._makeClean();
 
   return renderContext;
 }

package/Source/Scene/renderBufferPolylineCollection.js

@@ -168,6 +168,8 @@ function renderBufferPolylineCollection(collection, frameState, renderContext) {
   if (collection._dirtyCount > 0) {
     const { _dirtyOffset, _dirtyCount } = collection;
 
+    const widthInMeters = collection.widthUnits === "meters";
+
     const indexArray = renderContext.indexArray;
 
     const {
@@ -200,6 +202,8 @@ function renderBufferPolylineCollection(collection, frameState, renderContext) {
       polyline.getMaterial(material);
       const encodedColor = AttributeCompression.encodeRGB8(material.color);
       const colorAlpha = material.color.alpha;
+      // A negative width marks a width in meters, which the shader converts to pixels.
+      const signedWidth = widthInMeters ? -material.width : material.width;
       Color.fromRgba(polyline._pickId, pickColor);
       const show = polyline.show;
 
@@ -306,7 +310,7 @@ function renderBufferPolylineCollection(collection, frameState, renderContext) {
 
           showColorWidthAndTexCoordArray[vOffset * 4] = show ? 1 : 0;
           showColorWidthAndTexCoordArray[vOffset * 4 + 1] = encodedColor;
-          showColorWidthAndTexCoordArray[vOffset * 4 + 2] = material.width;
+          showColorWidthAndTexCoordArray[vOffset * 4 + 2] = signedWidth;
           showColorWidthAndTexCoordArray[vOffset * 4 + 3] = j / (jl - 1);
 
           alphaArray[vOffset] = colorAlpha * 255.0;
@@ -544,8 +548,7 @@ function renderBufferPolylineCollection(collection, frameState, renderContext) {
 
   frameState.commandList.push(command);
 
-  collection._dirtyCount = 0;
-  collection._dirtyOffset = 0;
+  collection._makeClean();
 
   return renderContext;
 }

package/Source/Shaders/BufferPolylineMaterialVS.glsl

@@ -24,7 +24,7 @@ void main()
 {
     float show = showColorWidthAndTexCoord.x;
     vec4 color = czm_decodeRGB8(showColorWidthAndTexCoord.y);
-    float width = showColorWidthAndTexCoord.z;
+    float signedWidth = showColorWidthAndTexCoord.z;
     float texCoord = showColorWidthAndTexCoord.w;
 
     ///////////////////////////////////////////////////////////////////////////
@@ -37,11 +37,23 @@ void main()
     vec4 positionEC = czm_translateRelativeToEye(positionHigh, positionLow);
     vec4 prevPositionEC = czm_translateRelativeToEye(prevPositionHigh, prevPositionLow);
     vec4 nextPositionEC = czm_translateRelativeToEye(nextPositionHigh, nextPositionLow);
-    vec4 positionWC = getPolylineWindowCoordinates(positionEC, prevPositionEC, nextPositionEC, expandDir, width, usePrevious, polylineAngle);
 #else
     vec4 positionEC = czm_modelView * vec4(position, 1.0);
     vec4 prevPositionEC = czm_modelView * vec4(prevPosition, 1.0);
     vec4 nextPositionEC = czm_modelView * vec4(nextPosition, 1.0);
+#endif
+
+    // A negative width is in meters; see renderBufferPolylineCollection. The quad is
+    // extruded in window coordinates, so convert it at this vertex's depth.
+    float width = abs(signedWidth);
+    if (signedWidth < 0.0)
+    {
+        width /= max(czm_metersPerPixel(positionEC), czm_epsilon7);
+    }
+
+#ifdef USE_FLOAT64
+    vec4 positionWC = getPolylineWindowCoordinates(positionEC, prevPositionEC, nextPositionEC, expandDir, width, usePrevious, polylineAngle);
+#else
     // Positions are already in eye space; use the EC variant to skip the redundant transform.
     vec4 positionWC = getPolylineWindowCoordinatesEC(positionEC, prevPositionEC, nextPositionEC, expandDir, width, usePrevious, polylineAngle);
 #endif

package/Source/Shaders/BufferPolylineMaterialVS.js

@@ -25,7 +25,7 @@ void main()\n\
 {\n\
     float show = showColorWidthAndTexCoord.x;\n\
     vec4 color = czm_decodeRGB8(showColorWidthAndTexCoord.y);\n\
-    float width = showColorWidthAndTexCoord.z;\n\
+    float signedWidth = showColorWidthAndTexCoord.z;\n\
     float texCoord = showColorWidthAndTexCoord.w;\n\
 \n\
     ///////////////////////////////////////////////////////////////////////////\n\
@@ -38,11 +38,23 @@ void main()\n\
     vec4 positionEC = czm_translateRelativeToEye(positionHigh, positionLow);\n\
     vec4 prevPositionEC = czm_translateRelativeToEye(prevPositionHigh, prevPositionLow);\n\
     vec4 nextPositionEC = czm_translateRelativeToEye(nextPositionHigh, nextPositionLow);\n\
-    vec4 positionWC = getPolylineWindowCoordinates(positionEC, prevPositionEC, nextPositionEC, expandDir, width, usePrevious, polylineAngle);\n\
 #else\n\
     vec4 positionEC = czm_modelView * vec4(position, 1.0);\n\
     vec4 prevPositionEC = czm_modelView * vec4(prevPosition, 1.0);\n\
     vec4 nextPositionEC = czm_modelView * vec4(nextPosition, 1.0);\n\
+#endif\n\
+\n\
+    // A negative width is in meters; see renderBufferPolylineCollection. The quad is\n\
+    // extruded in window coordinates, so convert it at this vertex's depth.\n\
+    float width = abs(signedWidth);\n\
+    if (signedWidth < 0.0)\n\
+    {\n\
+        width /= max(czm_metersPerPixel(positionEC), czm_epsilon7);\n\
+    }\n\
+\n\
+#ifdef USE_FLOAT64\n\
+    vec4 positionWC = getPolylineWindowCoordinates(positionEC, prevPositionEC, nextPositionEC, expandDir, width, usePrevious, polylineAngle);\n\
+#else\n\
     // Positions are already in eye space; use the EC variant to skip the redundant transform.\n\
     vec4 positionWC = getPolylineWindowCoordinatesEC(positionEC, prevPositionEC, nextPositionEC, expandDir, width, usePrevious, polylineAngle);\n\
 #endif\n\

package/Source/Shaders/Builtin/Constants/passCesium3DTile.glsl

@@ -6,4 +6,4 @@
  *
  * @see czm_pass
  */
-const float czm_passCesium3DTile = 5.0;
+const float czm_passCesium3DTile = 6.0;

package/Source/Shaders/Builtin/Constants/passCesium3DTile.js

@@ -7,5 +7,5 @@ export default "/**\n\
  *\n\
  * @see czm_pass\n\
  */\n\
-const float czm_passCesium3DTile = 5.0;\n\
+const float czm_passCesium3DTile = 6.0;\n\
 ";

package/Source/Shaders/Builtin/Constants/passCesium3DTileClassification.glsl

@@ -6,4 +6,4 @@
  *
  * @see czm_pass
  */
-const float czm_passCesium3DTileClassification = 6.0;
+const float czm_passCesium3DTileClassification = 7.0;

package/Source/Shaders/Builtin/Constants/passCesium3DTileClassification.js

@@ -7,5 +7,5 @@ export default "/**\n\
  *\n\
  * @see czm_pass\n\
  */\n\
-const float czm_passCesium3DTileClassification = 6.0;\n\
+const float czm_passCesium3DTileClassification = 7.0;\n\
 ";

package/Source/Shaders/Builtin/Constants/passCesium3DTileClassificationIgnoreShow.glsl

@@ -6,4 +6,4 @@
  *
  * @see czm_pass
  */
-const float czm_passCesium3DTileClassificationIgnoreShow = 7.0;
+const float czm_passCesium3DTileClassificationIgnoreShow = 8.0;

package/Source/Shaders/Builtin/Constants/passCesium3DTileClassificationIgnoreShow.js

@@ -7,5 +7,5 @@ export default "/**\n\
  *\n\
  * @see czm_pass\n\
  */\n\
-const float czm_passCesium3DTileClassificationIgnoreShow = 7.0;\n\
+const float czm_passCesium3DTileClassificationIgnoreShow = 8.0;\n\
 ";

package/Source/Shaders/Builtin/Constants/passCesium3DTilePlanarFillId.glsl

@@ -0,0 +1,9 @@
+/**
+ * The automatic GLSL constant for {@link Pass#CESIUM_3D_TILE_PLANAR_FILL_ID}
+ *
+ * @name czm_passCesium3DTilePlanarFillId
+ * @glslConstant
+ *
+ * @see czm_pass
+ */
+const float czm_passCesium3DTilePlanarFillId = 5.0;

package/Source/Shaders/Builtin/Constants/passCesium3DTilePlanarFillId.js

@@ -0,0 +1,11 @@
+//This file is automatically rebuilt by the Cesium build process.
+export default "/**\n\
+ * The automatic GLSL constant for {@link Pass#CESIUM_3D_TILE_PLANAR_FILL_ID}\n\
+ *\n\
+ * @name czm_passCesium3DTilePlanarFillId\n\
+ * @glslConstant\n\
+ *\n\
+ * @see czm_pass\n\
+ */\n\
+const float czm_passCesium3DTilePlanarFillId = 5.0;\n\
+";

package/Source/Shaders/Builtin/Constants/passClassification.glsl

@@ -6,4 +6,4 @@
  *
  * @see czm_pass
  */
-const float czm_passClassification = 7.0;
+const float czm_passClassification = 8.0;

package/Source/Shaders/Builtin/Constants/passClassification.js

@@ -7,5 +7,5 @@ export default "/**\n\
  *\n\
  * @see czm_pass\n\
  */\n\
-const float czm_passClassification = 7.0;\n\
+const float czm_passClassification = 8.0;\n\
 ";

package/Source/Shaders/Builtin/Constants/passGaussianSplats.glsl

@@ -6,4 +6,4 @@
  *
  * @see czm_pass
  */
-const float czm_passGaussianSplats = 11.0;
+const float czm_passGaussianSplats = 12.0;

package/Source/Shaders/Builtin/Constants/passGaussianSplats.js

@@ -7,5 +7,5 @@ export default "/**\n\
  *\n\
  * @see czm_pass\n\
  */\n\
-const float czm_passGaussianSplats = 11.0;\n\
+const float czm_passGaussianSplats = 12.0;\n\
 ";

package/Source/Shaders/Builtin/Constants/passOpaque.glsl

@@ -6,4 +6,4 @@
  *
  * @see czm_pass
  */
-const float czm_passOpaque = 8.0;
+const float czm_passOpaque = 9.0;

package/Source/Shaders/Builtin/Constants/passOpaque.js

@@ -7,5 +7,5 @@ export default "/**\n\
  *\n\
  * @see czm_pass\n\
  */\n\
-const float czm_passOpaque = 8.0;\n\
+const float czm_passOpaque = 9.0;\n\
 ";

package/Source/Shaders/Builtin/Constants/passTranslucent.glsl

@@ -6,4 +6,4 @@
  *
  * @see czm_pass
  */
-const float czm_passTranslucent = 9.0;
+const float czm_passTranslucent = 10.0;

package/Source/Shaders/Builtin/Constants/passTranslucent.js

@@ -7,5 +7,5 @@ export default "/**\n\
  *\n\
  * @see czm_pass\n\
  */\n\
-const float czm_passTranslucent = 9.0;\n\
+const float czm_passTranslucent = 10.0;\n\
 ";

package/Source/Shaders/Builtin/Constants/passVoxels.glsl

@@ -6,4 +6,4 @@
  *
  * @see czm_pass
  */
-const float czm_passVoxels = 10.0;
+const float czm_passVoxels = 11.0;

package/Source/Shaders/Builtin/Constants/passVoxels.js

@@ -7,5 +7,5 @@ export default "/**\n\
  *\n\
  * @see czm_pass\n\
  */\n\
-const float czm_passVoxels = 10.0;\n\
+const float czm_passVoxels = 11.0;\n\
 ";

package/Source/Shaders/Builtin/CzmBuiltins.js

@@ -16,6 +16,7 @@ import czm_passCesium3DTileClassification from './Constants/passCesium3DTileClas
 import czm_passCesium3DTileClassificationIgnoreShow from './Constants/passCesium3DTileClassificationIgnoreShow.js'
 import czm_passCesium3DTileEdges from './Constants/passCesium3DTileEdges.js'
 import czm_passCesium3DTileEdgesDirect from './Constants/passCesium3DTileEdgesDirect.js'
+import czm_passCesium3DTilePlanarFillId from './Constants/passCesium3DTilePlanarFillId.js'
 import czm_passClassification from './Constants/passClassification.js'
 import czm_passCompute from './Constants/passCompute.js'
 import czm_passEnvironment from './Constants/passEnvironment.js'
@@ -66,7 +67,6 @@ import czm_cascadeColor from './Functions/cascadeColor.js'
 import czm_cascadeDistance from './Functions/cascadeDistance.js'
 import czm_cascadeMatrix from './Functions/cascadeMatrix.js'
 import czm_cascadeWeights from './Functions/cascadeWeights.js'
-import czm_clipPolygons from './Functions/clipPolygons.js'
 import czm_columbusViewMorph from './Functions/columbusViewMorph.js'
 import czm_computeAtmosphereColor from './Functions/computeAtmosphereColor.js'
 import czm_computeGroundAtmosphereScattering from './Functions/computeGroundAtmosphereScattering.js'
@@ -82,6 +82,7 @@ import czm_ellipsoidContainsPoint from './Functions/ellipsoidContainsPoint.js'
 import czm_ellipsoidTextureCoordinates from './Functions/ellipsoidTextureCoordinates.js'
 import czm_equalsEpsilon from './Functions/equalsEpsilon.js'
 import czm_eyeOffset from './Functions/eyeOffset.js'
+import czm_eyeToCartographicDelta from './Functions/eyeToCartographicDelta.js'
 import czm_eyeToWindowCoordinates from './Functions/eyeToWindowCoordinates.js'
 import czm_fastApproximateAtan from './Functions/fastApproximateAtan.js'
 import czm_fog from './Functions/fog.js'
@@ -130,7 +131,6 @@ import czm_transformPlane from './Functions/transformPlane.js'
 import czm_translateRelativeToEye from './Functions/translateRelativeToEye.js'
 import czm_translucentPhong from './Functions/translucentPhong.js'
 import czm_transpose from './Functions/transpose.js'
-import czm_unpackClippingExtents from './Functions/unpackClippingExtents.js'
 import czm_unpackDepth from './Functions/unpackDepth.js'
 import czm_unpackFloat from './Functions/unpackFloat.js'
 import czm_unpackTexture from './Functions/unpackTexture.js'
@@ -160,6 +160,7 @@ export default {
     czm_passCesium3DTileClassificationIgnoreShow : czm_passCesium3DTileClassificationIgnoreShow,
     czm_passCesium3DTileEdges : czm_passCesium3DTileEdges,
     czm_passCesium3DTileEdgesDirect : czm_passCesium3DTileEdgesDirect,
+    czm_passCesium3DTilePlanarFillId : czm_passCesium3DTilePlanarFillId,
     czm_passClassification : czm_passClassification,
     czm_passCompute : czm_passCompute,
     czm_passEnvironment : czm_passEnvironment,
@@ -210,7 +211,6 @@ export default {
     czm_cascadeDistance : czm_cascadeDistance,
     czm_cascadeMatrix : czm_cascadeMatrix,
     czm_cascadeWeights : czm_cascadeWeights,
-    czm_clipPolygons : czm_clipPolygons,
     czm_columbusViewMorph : czm_columbusViewMorph,
     czm_computeAtmosphereColor : czm_computeAtmosphereColor,
     czm_computeGroundAtmosphereScattering : czm_computeGroundAtmosphereScattering,
@@ -226,6 +226,7 @@ export default {
     czm_ellipsoidTextureCoordinates : czm_ellipsoidTextureCoordinates,
     czm_equalsEpsilon : czm_equalsEpsilon,
     czm_eyeOffset : czm_eyeOffset,
+    czm_eyeToCartographicDelta : czm_eyeToCartographicDelta,
     czm_eyeToWindowCoordinates : czm_eyeToWindowCoordinates,
     czm_fastApproximateAtan : czm_fastApproximateAtan,
     czm_fog : czm_fog,
@@ -274,7 +275,6 @@ export default {
     czm_translateRelativeToEye : czm_translateRelativeToEye,
     czm_translucentPhong : czm_translucentPhong,
     czm_transpose : czm_transpose,
-    czm_unpackClippingExtents : czm_unpackClippingExtents,
     czm_unpackDepth : czm_unpackDepth,
     czm_unpackFloat : czm_unpackFloat,
     czm_unpackTexture : czm_unpackTexture,

package/Source/Shaders/Builtin/Functions/eyeToCartographicDelta.glsl

@@ -0,0 +1,74 @@
+/**
+ * Computes the geodetic offset (delta longitude, latitude, and height) from a reference cartographic position
+ * to a point given in eye coordinates.
+ *
+ * This is designed to preserve precision. Rather than converting the point's absolute world position to
+ * cartographic -- which is too large to process precisely at 32 bits -- it works entirely with the small
+ * delta between the point and the camera. By projecting the eye-space offset onto the ellipsoid's equatorial
+ * and meridional planes, it derives the change in (longitude, latitude, height) as small, precisely-representable
+ * quantities. The delta gets smaller and more precise as one zooms in.
+ * <br /><br />
+ * This assumes an ellipsoid of revolution (equatorial radii equal, as with WGS84), so that longitude is exact.
+ * The latitude calculation is only first-order accurate, since the meridian is an ellipse rather than a circle.
+ *
+ * @name czm_eyeToCartographicDelta
+ * @glslFunction
+ *
+ * @param {vec3} positionEC The position, in eye coordinates, to measure to.
+ *
+ * @returns {vec3} The geodetic offset from the camera to <code>positionEC</code>, as (delta longitude, delta latitude in radians, delta height in meters).
+ */
+vec3 czm_eyeToCartographicDelta(vec3 positionEC)
+{
+    // A vector representing the camera-to-vertex offset, in an ENU oriented reference frame (centered at the camera)
+    vec3 cameraToVertex = czm_eyeToEnu * positionEC;
+
+    float cosLatitude = cos(czm_eyeCartographic.y);
+    float sinLatitude = sin(czm_eyeCartographic.y);
+
+    // To derive longitude, project the camera and vertex onto the equatorial plane, in a frame such that the camera lies along the +x axis. In this frame,
+    // the vertex's (delta) longitude is simply the atan of its x and y components.
+    float primeVerticalRadius = 1.0 / czm_eyeEllipsoidCurvature.x;
+    vec2 cameraEquatorialPos = vec2((primeVerticalRadius + czm_eyeCartographic.z) * cosLatitude, 0.0);
+    vec2 vertexEquatorialPos = cameraEquatorialPos + vec2(-cameraToVertex.y * sinLatitude + cameraToVertex.z * cosLatitude, cameraToVertex.x);
+    float deltaLongitude = atan(vertexEquatorialPos.y, vertexEquatorialPos.x);
+
+    // Deriving latitude is a bit harder: we can't directly project the vertex onto the camera's meridian — the latitude projection is dependent on the longitude.
+    // Instead we can rotate the vertex (by -deltaLongitude) onto the camera's meridional plane.  (Note: (unlike the exact longitude case) this is only first-order accurate because the meridian is an ellipse rather than a circle)
+    // Using a 2D rotation formula introduces precision issues (subtraction of large-magnitude quantities), so instead we can calculate the vector difference
+    // between the vertex and its rotated version, and apply that offset to the cameraToVertex vector. Then, the cameraToVertex vector accurately
+    // reflects the difference between the camera and the _rotated_ vertex, so we can then project the camera onto the meridional plane and apply this offset - just as we did for deltaLongitude, above.
+    // Best of all, we can do this all with small delta quantities which preserve precision.
+    //
+    // (I suggest drawing this out -- with the vertex and camera vectors projected onto the equatorial plane, with the camera on the +x axis)
+    // Mathematically: if you compare (subtract) vertexEquatorialPos and the same vector rotated onto the camera's meridional plane, you get
+    // |dx| = |vertexEquatorialPos| - vertexEquatorialPos.x = (r - x) = r * (1 - cos(deltaLongitude))
+    // |dy| = cameraToVertex.x (the east component)
+    // (To avoid precision issues, we'll use the identity (1 - cos(x) = 2 * sin^2(x/2)))
+    //
+    // Since these offsets were produced in the equatorial plane, and cameraToVertex is in the camera's ENU frame, we need to deconstruct along the camera's north and up axes. And we only care about
+    // dx, since dy is in the camera's east direction, and that component gets zeroed out when projecting onto the camera's meridional plane.
+    float sinHalfLongitude = sin(deltaLongitude * 0.5);
+    float dx = length(vertexEquatorialPos) * 2.0 * sinHalfLongitude * sinHalfLongitude;
+    vec3 meridionalOffset = vec3(
+        0.0,                                 // east
+        cameraToVertex.y - dx * sinLatitude, // north
+        cameraToVertex.z + dx * cosLatitude  // up
+    );
+
+    // Reframe the camera in a meridional plane, where it lies along the +z axis, and apply the meridionalOffset to get the vertex's position in that plane.
+    // Then, deltaLatitude is simply the atan of its x and y components.
+    float meridionalRadius = 1.0 / czm_eyeEllipsoidCurvature.y;
+    vec2 cameraMeridionalPos = vec2(meridionalRadius + czm_eyeCartographic.z, 0.0);
+    vec2 vertMeridionalPos = cameraMeridionalPos + vec2(meridionalOffset.z, meridionalOffset.y);
+    float deltaLatitude = atan(vertMeridionalPos.y, vertMeridionalPos.x);
+
+    // Finally, derive the change in height above the ellipsoid. This is the meridional-plane analogue of the dx step above:
+    // there we rotated the vertex (in the equatorial plane) to the camera's longitude; here we rotate it (in the meridional plane, by -deltaLatitude)
+    // to the camera's latitude, aligning it with the camera's radial (up) direction.
+    float sinHalfLatitude = sin(deltaLatitude * 0.5);
+    float dz = length(vertMeridionalPos) * 2.0 * sinHalfLatitude * sinHalfLatitude;
+    float deltaHeight = meridionalOffset.z + dz;
+
+    return vec3(deltaLongitude, deltaLatitude, deltaHeight);
+}

package/Source/Shaders/Builtin/Functions/eyeToCartographicDelta.js

@@ -0,0 +1,76 @@
+//This file is automatically rebuilt by the Cesium build process.
+export default "/**\n\
+ * Computes the geodetic offset (delta longitude, latitude, and height) from a reference cartographic position\n\
+ * to a point given in eye coordinates.\n\
+ *\n\
+ * This is designed to preserve precision. Rather than converting the point's absolute world position to\n\
+ * cartographic -- which is too large to process precisely at 32 bits -- it works entirely with the small\n\
+ * delta between the point and the camera. By projecting the eye-space offset onto the ellipsoid's equatorial\n\
+ * and meridional planes, it derives the change in (longitude, latitude, height) as small, precisely-representable\n\
+ * quantities. The delta gets smaller and more precise as one zooms in.\n\
+ * <br /><br />\n\
+ * This assumes an ellipsoid of revolution (equatorial radii equal, as with WGS84), so that longitude is exact.\n\
+ * The latitude calculation is only first-order accurate, since the meridian is an ellipse rather than a circle.\n\
+ *\n\
+ * @name czm_eyeToCartographicDelta\n\
+ * @glslFunction\n\
+ *\n\
+ * @param {vec3} positionEC The position, in eye coordinates, to measure to.\n\
+ *\n\
+ * @returns {vec3} The geodetic offset from the camera to <code>positionEC</code>, as (delta longitude, delta latitude in radians, delta height in meters).\n\
+ */\n\
+vec3 czm_eyeToCartographicDelta(vec3 positionEC)\n\
+{\n\
+    // A vector representing the camera-to-vertex offset, in an ENU oriented reference frame (centered at the camera)\n\
+    vec3 cameraToVertex = czm_eyeToEnu * positionEC;\n\
+\n\
+    float cosLatitude = cos(czm_eyeCartographic.y);\n\
+    float sinLatitude = sin(czm_eyeCartographic.y);\n\
+\n\
+    // To derive longitude, project the camera and vertex onto the equatorial plane, in a frame such that the camera lies along the +x axis. In this frame,\n\
+    // the vertex's (delta) longitude is simply the atan of its x and y components.\n\
+    float primeVerticalRadius = 1.0 / czm_eyeEllipsoidCurvature.x;\n\
+    vec2 cameraEquatorialPos = vec2((primeVerticalRadius + czm_eyeCartographic.z) * cosLatitude, 0.0);\n\
+    vec2 vertexEquatorialPos = cameraEquatorialPos + vec2(-cameraToVertex.y * sinLatitude + cameraToVertex.z * cosLatitude, cameraToVertex.x);\n\
+    float deltaLongitude = atan(vertexEquatorialPos.y, vertexEquatorialPos.x);\n\
+\n\
+    // Deriving latitude is a bit harder: we can't directly project the vertex onto the camera's meridian — the latitude projection is dependent on the longitude.\n\
+    // Instead we can rotate the vertex (by -deltaLongitude) onto the camera's meridional plane.  (Note: (unlike the exact longitude case) this is only first-order accurate because the meridian is an ellipse rather than a circle)\n\
+    // Using a 2D rotation formula introduces precision issues (subtraction of large-magnitude quantities), so instead we can calculate the vector difference\n\
+    // between the vertex and its rotated version, and apply that offset to the cameraToVertex vector. Then, the cameraToVertex vector accurately\n\
+    // reflects the difference between the camera and the _rotated_ vertex, so we can then project the camera onto the meridional plane and apply this offset - just as we did for deltaLongitude, above.\n\
+    // Best of all, we can do this all with small delta quantities which preserve precision.\n\
+    //\n\
+    // (I suggest drawing this out -- with the vertex and camera vectors projected onto the equatorial plane, with the camera on the +x axis)\n\
+    // Mathematically: if you compare (subtract) vertexEquatorialPos and the same vector rotated onto the camera's meridional plane, you get\n\
+    // |dx| = |vertexEquatorialPos| - vertexEquatorialPos.x = (r - x) = r * (1 - cos(deltaLongitude))\n\
+    // |dy| = cameraToVertex.x (the east component)\n\
+    // (To avoid precision issues, we'll use the identity (1 - cos(x) = 2 * sin^2(x/2)))\n\
+    //\n\
+    // Since these offsets were produced in the equatorial plane, and cameraToVertex is in the camera's ENU frame, we need to deconstruct along the camera's north and up axes. And we only care about\n\
+    // dx, since dy is in the camera's east direction, and that component gets zeroed out when projecting onto the camera's meridional plane.\n\
+    float sinHalfLongitude = sin(deltaLongitude * 0.5);\n\
+    float dx = length(vertexEquatorialPos) * 2.0 * sinHalfLongitude * sinHalfLongitude;\n\
+    vec3 meridionalOffset = vec3(\n\
+        0.0,                                 // east\n\
+        cameraToVertex.y - dx * sinLatitude, // north\n\
+        cameraToVertex.z + dx * cosLatitude  // up\n\
+    );\n\
+\n\
+    // Reframe the camera in a meridional plane, where it lies along the +z axis, and apply the meridionalOffset to get the vertex's position in that plane.\n\
+    // Then, deltaLatitude is simply the atan of its x and y components.\n\
+    float meridionalRadius = 1.0 / czm_eyeEllipsoidCurvature.y;\n\
+    vec2 cameraMeridionalPos = vec2(meridionalRadius + czm_eyeCartographic.z, 0.0);\n\
+    vec2 vertMeridionalPos = cameraMeridionalPos + vec2(meridionalOffset.z, meridionalOffset.y);\n\
+    float deltaLatitude = atan(vertMeridionalPos.y, vertMeridionalPos.x);\n\
+\n\
+    // Finally, derive the change in height above the ellipsoid. This is the meridional-plane analogue of the dx step above:\n\
+    // there we rotated the vertex (in the equatorial plane) to the camera's longitude; here we rotate it (in the meridional plane, by -deltaLatitude)\n\
+    // to the camera's latitude, aligning it with the camera's radial (up) direction.\n\
+    float sinHalfLatitude = sin(deltaLatitude * 0.5);\n\
+    float dz = length(vertMeridionalPos) * 2.0 * sinHalfLatitude * sinHalfLatitude;\n\
+    float deltaHeight = meridionalOffset.z + dz;\n\
+\n\
+    return vec3(deltaLongitude, deltaLatitude, deltaHeight);\n\
+}\n\
+";