@cesium/engine 9.0.0 → 9.2.0

package/Source/Scene/Globe.js

@@ -449,6 +449,20 @@ Object.defineProperties(Globe.prototype, {
       this._surface.tileProvider.clippingPlanes = value;
     },
   },
+  /**
+   * A property specifying a {@link ClippingPolygonCollection} used to selectively disable rendering inside or outside a list of polygons.
+   *
+   * @memberof Globe.prototype
+   * @type {ClippingPolygonCollection}
+   */
+  clippingPolygons: {
+    get: function () {
+      return this._surface.tileProvider.clippingPolygons;
+    },
+    set: function (value) {
+      this._surface.tileProvider.clippingPolygons = value;
+    },
+  },
   /**
    * A property specifying a {@link Rectangle} used to limit globe rendering to a cartographic area.
    * Defaults to the maximum extent of cartographic coordinates.

package/Source/Scene/GlobeSurfaceShaderSet.js

@@ -10,13 +10,15 @@ function GlobeSurfaceShader(
   flags,
   material,
   shaderProgram,
-  clippingShaderState
+  clippingShaderState,
+  clippingPolygonShaderState
 ) {
   this.numberOfDayTextures = numberOfDayTextures;
   this.flags = flags;
   this.material = material;
   this.shaderProgram = shaderProgram;
   this.clippingShaderState = clippingShaderState;
+  this.clippingPolygonShaderState = clippingPolygonShaderState;
 }
 
 /**
@@ -60,6 +62,31 @@ function getPositionMode(sceneMode) {
   return positionMode;
 }
 
+function getPolygonClippingFunction(context) {
+  // return a noop for webgl1
+  if (!context.webgl2) {
+    return `void clipPolygons(highp sampler2D clippingDistance, int regionsLength, vec2 clippingPosition, int regionIndex) {
+    }`;
+  }
+
+  return `void clipPolygons(highp sampler2D clippingDistance, int regionsLength, vec2 clippingPosition, int regionIndex) {
+    czm_clipPolygons(clippingDistance, regionsLength, clippingPosition, regionIndex);
+  }`;
+}
+
+function getUnpackClippingFunction(context) {
+  // return a noop for webgl1
+  if (!context.webgl2) {
+    return `vec4 unpackClippingExtents(highp sampler2D extentsTexture, int index) {
+      return vec4();
+    }`;
+  }
+
+  return `vec4 unpackClippingExtents(highp sampler2D extentsTexture, int index) {
+    return czm_unpackClippingExtents(extentsTexture, index);
+  }`;
+}
+
 function get2DYPositionFraction(useWebMercatorProjection) {
   const get2DYPositionFractionGeographicProjection =
     "float get2DYPositionFraction(vec2 textureCoordinates) { return get2DGeographicYPositionFraction(textureCoordinates); }";
@@ -95,6 +122,8 @@ GlobeSurfaceShaderSet.prototype.getShaderProgram = function (options) {
   const enableFog = options.enableFog;
   const enableClippingPlanes = options.enableClippingPlanes;
   const clippingPlanes = options.clippingPlanes;
+  const enableClippingPolygons = options.enableClippingPolygons;
+  const clippingPolygons = options.clippingPolygons;
   const clippedByBoundaries = options.clippedByBoundaries;
   const hasImageryLayerCutout = options.hasImageryLayerCutout;
   const colorCorrect = options.colorCorrect;
@@ -152,16 +181,17 @@ GlobeSurfaceShaderSet.prototype.getShaderProgram = function (options) {
     (quantization << 18) |
     (applySplit << 19) |
     (enableClippingPlanes << 20) |
-    (cartographicLimitRectangleFlag << 21) |
-    (imageryCutoutFlag << 22) |
-    (colorCorrect << 23) |
-    (highlightFillTile << 24) |
-    (colorToAlpha << 25) |
-    (hasGeodeticSurfaceNormals << 26) |
-    (hasExaggeration << 27) |
-    (showUndergroundColor << 28) |
-    (translucent << 29) |
-    (applyDayNightAlpha << 30);
+    (enableClippingPolygons << 21) |
+    (cartographicLimitRectangleFlag << 22) |
+    (imageryCutoutFlag << 23) |
+    (colorCorrect << 24) |
+    (highlightFillTile << 25) |
+    (colorToAlpha << 26) |
+    (hasGeodeticSurfaceNormals << 27) |
+    (hasExaggeration << 28) |
+    (showUndergroundColor << 29) |
+    (translucent << 30) |
+    (applyDayNightAlpha << 31);
 
   let currentClippingShaderState = 0;
   if (defined(clippingPlanes) && clippingPlanes.length > 0) {
@@ -169,13 +199,23 @@ GlobeSurfaceShaderSet.prototype.getShaderProgram = function (options) {
       ? clippingPlanes.clippingPlanesState
       : 0;
   }
+
+  let currentClippingPolygonsShaderState = 0;
+  if (defined(clippingPolygons) && clippingPolygons.length > 0) {
+    currentClippingPolygonsShaderState = enableClippingPolygons
+      ? clippingPolygons.clippingPolygonsState
+      : 0;
+  }
+
   let surfaceShader = surfaceTile.surfaceShader;
   if (
     defined(surfaceShader) &&
     surfaceShader.numberOfDayTextures === numberOfDayTextures &&
     surfaceShader.flags === flags &&
     surfaceShader.material === this.material &&
-    surfaceShader.clippingShaderState === currentClippingShaderState
+    surfaceShader.clippingShaderState === currentClippingShaderState &&
+    surfaceShader.clippingPolygonShaderState ===
+      currentClippingPolygonsShaderState
   ) {
     return surfaceShader.shaderProgram;
   }
@@ -190,16 +230,25 @@ GlobeSurfaceShaderSet.prototype.getShaderProgram = function (options) {
   if (
     !defined(surfaceShader) ||
     surfaceShader.material !== this.material ||
-    surfaceShader.clippingShaderState !== currentClippingShaderState
+    surfaceShader.clippingShaderState !== currentClippingShaderState ||
+    surfaceShader.clippingPolygonShaderState !==
+      currentClippingPolygonsShaderState
   ) {
     // Cache miss - we've never seen this combination of numberOfDayTextures and flags before.
     const vs = this.baseVertexShaderSource.clone();
     const fs = this.baseFragmentShaderSource.clone();
 
+    // Need to go before GlobeFS
     if (currentClippingShaderState !== 0) {
       fs.sources.unshift(
         getClippingFunction(clippingPlanes, frameState.context)
-      ); // Need to go before GlobeFS
+      );
+    }
+
+    // Need to go before GlobeFS
+    if (currentClippingPolygonsShaderState !== 0) {
+      fs.sources.unshift(getPolygonClippingFunction(frameState.context));
+      vs.sources.unshift(getUnpackClippingFunction(frameState.context));
     }
 
     vs.defines.push(quantizationDefine);
@@ -292,6 +341,22 @@ GlobeSurfaceShaderSet.prototype.getShaderProgram = function (options) {
       fs.defines.push("ENABLE_CLIPPING_PLANES");
     }
 
+    if (enableClippingPolygons) {
+      fs.defines.push("ENABLE_CLIPPING_POLYGONS");
+      vs.defines.push("ENABLE_CLIPPING_POLYGONS");
+
+      if (clippingPolygons.inverse) {
+        fs.defines.push("CLIPPING_INVERSE");
+      }
+
+      fs.defines.push(
+        `CLIPPING_POLYGON_REGIONS_LENGTH ${clippingPolygons.extentsCount}`
+      );
+      vs.defines.push(
+        `CLIPPING_POLYGON_REGIONS_LENGTH ${clippingPolygons.extentsCount}`
+      );
+    }
+
     if (colorCorrect) {
       fs.defines.push("COLOR_CORRECT");
     }
@@ -377,7 +442,8 @@ GlobeSurfaceShaderSet.prototype.getShaderProgram = function (options) {
       flags,
       this.material,
       shader,
-      currentClippingShaderState
+      currentClippingShaderState,
+      currentClippingPolygonsShaderState
     );
   }
 

package/Source/Scene/GlobeSurfaceTileProvider.js

@@ -38,6 +38,7 @@ import RenderState from "../Renderer/RenderState.js";
 import VertexArray from "../Renderer/VertexArray.js";
 import BlendingState from "./BlendingState.js";
 import ClippingPlaneCollection from "./ClippingPlaneCollection.js";
+import ClippingPolygonCollection from "./ClippingPolygonCollection.js";
 import DepthFunction from "./DepthFunction.js";
 import GlobeSurfaceTile from "./GlobeSurfaceTile.js";
 import ImageryLayer from "./ImageryLayer.js";
@@ -170,6 +171,13 @@ function GlobeSurfaceTileProvider(options) {
    */
   this._clippingPlanes = undefined;
 
+  /**
+   * A property specifying a {@link ClippingPolygonCollection} used to selectively disable rendering inside or outside a list of polygons.
+   * @type {ClippingPolygonCollection}
+   * @private
+   */
+  this._clippingPolygons = undefined;
+
   /**
    * A property specifying a {@link Rectangle} used to selectively limit terrain and imagery rendering.
    * @type {Rectangle}
@@ -290,7 +298,7 @@ Object.defineProperties(GlobeSurfaceTileProvider.prototype, {
     },
   },
   /**
-   * The {@link ClippingPlaneCollection} used to selectively disable rendering the tileset.
+   * The {@link ClippingPlaneCollection} used to selectively disable rendering.
    *
    * @type {ClippingPlaneCollection}
    *
@@ -304,6 +312,22 @@ Object.defineProperties(GlobeSurfaceTileProvider.prototype, {
       ClippingPlaneCollection.setOwner(value, this, "_clippingPlanes");
     },
   },
+
+  /**
+   * The {@link ClippingPolygonCollection} used to selectively disable rendering inside or outside a list of polygons.
+   *
+   * @type {ClippingPolygonCollection}
+   *
+   * @private
+   */
+  clippingPolygons: {
+    get: function () {
+      return this._clippingPolygons;
+    },
+    set: function (value) {
+      ClippingPolygonCollection.setOwner(value, this, "_clippingPolygons");
+    },
+  },
 });
 
 function sortTileImageryByLayerIndex(a, b) {
@@ -391,6 +415,14 @@ GlobeSurfaceTileProvider.prototype.beginUpdate = function (frameState) {
   if (defined(clippingPlanes) && clippingPlanes.enabled) {
     clippingPlanes.update(frameState);
   }
+
+  // update clipping polygons
+  const clippingPolygons = this._clippingPolygons;
+  if (defined(clippingPolygons) && clippingPolygons.enabled) {
+    clippingPolygons.update(frameState);
+    clippingPolygons.queueCommands(frameState);
+  }
+
   this._usedDrawCommands = 0;
 
   this._hasLoadedTilesThisFrame = false;
@@ -657,6 +689,11 @@ function isUndergroundVisible(tileProvider, frameState) {
     return true;
   }
 
+  const clippingPolygons = tileProvider._clippingPolygons;
+  if (defined(clippingPolygons) && clippingPolygons.enabled) {
+    return true;
+  }
+
   if (
     !Rectangle.equals(
       tileProvider.cartographicLimitRectangle,
@@ -775,6 +812,16 @@ GlobeSurfaceTileProvider.prototype.computeTileVisibility = function (
     }
   }
 
+  const clippingPolygons = this._clippingPolygons;
+  if (defined(clippingPolygons) && clippingPolygons.enabled) {
+    const polygonIntersection = clippingPolygons.computeIntersectionWithBoundingVolume(
+      tileBoundingRegion
+    );
+    tile.isClipped = polygonIntersection !== Intersect.OUTSIDE;
+    // Polygon clipping intersections are determined by outer rectangles, therefore we cannot
+    // preemptively determine if a tile is completely clipped or not here.
+  }
+
   let visibility;
   const intersection = cullingVolume.computeVisibility(boundingVolume);
 
@@ -1364,6 +1411,8 @@ GlobeSurfaceTileProvider.prototype.isDestroyed = function () {
 GlobeSurfaceTileProvider.prototype.destroy = function () {
   this._tileProvider = this._tileProvider && this._tileProvider.destroy();
   this._clippingPlanes = this._clippingPlanes && this._clippingPlanes.destroy();
+  this._clippingPolygons =
+    this._clippingPolygons && this._clippingPolygons.destroy();
   this._removeLayerAddedListener =
     this._removeLayerAddedListener && this._removeLayerAddedListener();
   this._removeLayerRemovedListener =
@@ -1755,6 +1804,21 @@ function createTileUniformMap(frameState, globeSurfaceTileProvider) {
       style.alpha = this.properties.clippingPlanesEdgeWidth;
       return style;
     },
+    u_clippingDistance: function () {
+      const texture =
+        globeSurfaceTileProvider._clippingPolygons.clippingTexture;
+      if (defined(texture)) {
+        return texture;
+      }
+      return frameState.context.defaultTexture;
+    },
+    u_clippingExtents: function () {
+      const texture = globeSurfaceTileProvider._clippingPolygons.extentsTexture;
+      if (defined(texture)) {
+        return texture;
+      }
+      return frameState.context.defaultTexture;
+    },
     u_minimumBrightness: function () {
       return frameState.fog.minimumBrightness;
     },
@@ -2039,6 +2103,8 @@ const surfaceShaderSetOptionsScratch = {
   enableFog: undefined,
   enableClippingPlanes: undefined,
   clippingPlanes: undefined,
+  enableClippingPolygons: undefined,
+  clippingPolygons: undefined,
   clippedByBoundaries: undefined,
   hasImageryLayerCutout: undefined,
   colorCorrect: undefined,
@@ -2166,6 +2232,13 @@ function addDrawCommandsForTile(tileProvider, tile, frameState) {
   ) {
     --maxTextures;
   }
+  if (
+    defined(tileProvider.clippingPolygons) &&
+    tileProvider.clippingPolygons.enabled
+  ) {
+    --maxTextures;
+    --maxTextures;
+  }
 
   maxTextures -= globeTranslucencyState.numberOfTextureUniforms;
 
@@ -2726,6 +2799,11 @@ function addDrawCommandsForTile(tileProvider, tile, frameState) {
       uniformMapProperties.clippingPlanesEdgeWidth = clippingPlanes.edgeWidth;
     }
 
+    // update clipping polygons
+    const clippingPolygons = tileProvider._clippingPolygons;
+    const clippingPolygonsEnabled =
+      defined(clippingPolygons) && clippingPolygons.enabled && tile.isClipped;
+
     surfaceShaderSetOptions.numberOfDayTextures = numberOfDayTextures;
     surfaceShaderSetOptions.applyBrightness = applyBrightness;
     surfaceShaderSetOptions.applyContrast = applyContrast;
@@ -2738,6 +2816,8 @@ function addDrawCommandsForTile(tileProvider, tile, frameState) {
     surfaceShaderSetOptions.enableFog = applyFog;
     surfaceShaderSetOptions.enableClippingPlanes = clippingPlanesEnabled;
     surfaceShaderSetOptions.clippingPlanes = clippingPlanes;
+    surfaceShaderSetOptions.enableClippingPolygons = clippingPolygonsEnabled;
+    surfaceShaderSetOptions.clippingPolygons = clippingPolygons;
     surfaceShaderSetOptions.hasImageryLayerCutout = applyCutout;
     surfaceShaderSetOptions.colorCorrect = colorCorrect;
     surfaceShaderSetOptions.highlightFillTile = highlightFillTile;