@deck.gl/extensions 8.9.0-alpha.4 → 8.9.0-beta.1

package/src/mask/mask.ts

@@ -1,10 +1,11 @@
-import {COORDINATE_SYSTEM, LayerExtension, log} from '@deck.gl/core';
+import {COORDINATE_SYSTEM, Layer, LayerExtension, log} from '@deck.gl/core';
 import mask from './shader-module';
-
-import type {Layer} from '@deck.gl/core';
+import MaskEffect from './mask-effect';
 
 const defaultProps = {
-  maskId: ''
+  maskId: '',
+  maskByInstance: undefined,
+  maskInverted: false
 };
 
 export type MaskExtensionProps = {
@@ -18,6 +19,10 @@ export type MaskExtensionProps = {
    * If not specified, it is automatically deduced from the layer.
    */
   maskByInstance?: boolean;
+  /**
+   * Inverts the masking operation
+   */
+  maskInverted?: boolean;
 };
 
 /** Allows layers to show/hide objects by a geofence. */
@@ -25,11 +30,15 @@ export default class MaskExtension extends LayerExtension {
   static defaultProps = defaultProps;
   static extensionName = 'MaskExtension';
 
+  initializeState(this: Layer<MaskExtensionProps>) {
+    this.context.deck?._addDefaultEffect(new MaskEffect());
+  }
+
   getShaders(this: Layer<MaskExtensionProps>): any {
     // Infer by geometry if 'maskByInstance' prop isn't explictly set
     let maskByInstance = 'instancePositions' in this.getAttributeManager()!.attributes;
     // Users can override by setting the `maskByInstance` prop
-    if ('maskByInstance' in this.props) {
+    if (this.props.maskByInstance !== undefined) {
       maskByInstance = Boolean(this.props.maskByInstance);
     }
     this.state.maskByInstance = maskByInstance;
@@ -40,9 +49,9 @@ export default class MaskExtension extends LayerExtension {
   }
 
   /* eslint-disable camelcase */
-  draw(this: Layer<MaskExtensionProps>, {uniforms, context, moduleParameters}: any) {
+  draw(this: Layer<Required<MaskExtensionProps>>, {uniforms, context, moduleParameters}: any) {
     uniforms.mask_maskByInstance = this.state.maskByInstance;
-    const {maskId = ''} = this.props;
+    const {maskId, maskInverted} = this.props;
     const {maskChannels} = moduleParameters;
     const {viewport} = context;
     if (maskChannels && maskChannels[maskId]) {
@@ -50,6 +59,7 @@ export default class MaskExtension extends LayerExtension {
       let {coordinateSystem: fromCoordinateSystem} = maskChannels[maskId];
       uniforms.mask_enabled = true;
       uniforms.mask_channel = index;
+      uniforms.mask_inverted = maskInverted;
 
       if (fromCoordinateSystem === COORDINATE_SYSTEM.DEFAULT) {
         fromCoordinateSystem = viewport.isGeospatial

package/src/mask/shader-module.ts

@@ -14,6 +14,7 @@ const fs = `
 uniform sampler2D mask_texture;
 uniform int mask_channel;
 uniform bool mask_enabled;
+uniform bool mask_inverted;
 bool mask_isInBounds(vec2 texCoords) {
   if (!mask_enabled) {
     return true;
@@ -29,7 +30,12 @@ bool mask_isInBounds(vec2 texCoords) {
   } else if (mask_channel == 3) {
     maskValue = maskColor.a;
   }
-  return maskValue < 0.5;
+
+  if (mask_inverted) {
+    return maskValue >= 0.5;
+  } else {
+    return maskValue < 0.5;
+  }
 }
 `;
 

package/src/mask/utils.ts

@@ -0,0 +1,148 @@
+import {OrthographicView, WebMercatorViewport, log, Layer, Viewport} from '@deck.gl/core';
+import {fitBounds} from '@math.gl/web-mercator';
+
+export type MaskBounds = [number, number, number, number];
+
+/*
+ * Compute the bounds of the mask in world space, such that it covers an
+ * area currently visible (extended by a buffer) or the area of the masking
+ * data, whichever is smaller
+ */
+export function getMaskBounds({
+  layers,
+  viewport
+}: {
+  layers: Layer[];
+  viewport: Viewport;
+}): MaskBounds {
+  // Join the bounds of layer data
+  let bounds: MaskBounds | null = null;
+  for (const layer of layers) {
+    const subLayerBounds = layer.getBounds();
+    if (subLayerBounds) {
+      if (bounds) {
+        bounds[0] = Math.min(bounds[0], subLayerBounds[0][0]);
+        bounds[1] = Math.min(bounds[1], subLayerBounds[0][1]);
+        bounds[2] = Math.max(bounds[2], subLayerBounds[1][0]);
+        bounds[3] = Math.max(bounds[3], subLayerBounds[1][1]);
+      } else {
+        bounds = [
+          subLayerBounds[0][0],
+          subLayerBounds[0][1],
+          subLayerBounds[1][0],
+          subLayerBounds[1][1]
+        ];
+      }
+    }
+  }
+  const viewportBounds = viewport.getBounds();
+  if (!bounds) {
+    return viewportBounds;
+  }
+
+  // Expand viewport bounds by 2X. Heurestically chosen to avoid masking
+  // errors when mask is partially out of view
+  const paddedBounds = _doubleBounds(viewportBounds);
+
+  // When bounds of the mask are smaller than the viewport bounds simply use
+  // mask bounds, so as to maximize resolution & avoid mask rerenders
+  if (
+    bounds[2] - bounds[0] < paddedBounds[2] - paddedBounds[0] ||
+    bounds[3] - bounds[1] < paddedBounds[3] - paddedBounds[1]
+  ) {
+    return bounds;
+  }
+
+  // As viewport shrinks, to avoid pixelation along mask edges
+  // we need to reduce the bounds and only render the visible portion
+  // of the mask.
+  // We pad the viewport bounds to capture the section
+  // of the mask just outside the viewport to correctly maskByInstance.
+  // Intersect mask & padded viewport bounds
+  bounds[0] = Math.max(bounds[0], paddedBounds[0]);
+  bounds[1] = Math.max(bounds[1], paddedBounds[1]);
+  bounds[2] = Math.min(bounds[2], paddedBounds[2]);
+  bounds[3] = Math.min(bounds[3], paddedBounds[3]);
+  return bounds;
+}
+
+/*
+ * Compute viewport to render the mask into, covering the given bounds
+ */
+export function getMaskViewport({
+  bounds,
+  viewport,
+  width,
+  height
+}: {
+  bounds: MaskBounds;
+  viewport: Viewport;
+  width: number;
+  height: number;
+}): Viewport | null {
+  if (bounds[2] <= bounds[0] || bounds[3] <= bounds[1]) {
+    return null;
+  }
+
+  if (viewport.resolution !== undefined) {
+    log.warn('MaskExtension is not supported in GlobeView')();
+    return null;
+  }
+
+  // Single pixel border to prevent mask bleeding at edge of texture
+  const padding = 1;
+  width -= padding * 2;
+  height -= padding * 2;
+
+  if (viewport.isGeospatial) {
+    const {longitude, latitude, zoom} = fitBounds({
+      width,
+      height,
+      bounds: [
+        [bounds[0], bounds[1]],
+        [bounds[2], bounds[3]]
+      ],
+      maxZoom: 20
+    });
+    return new WebMercatorViewport({
+      longitude,
+      latitude,
+      zoom,
+      x: padding,
+      y: padding,
+      width,
+      height
+    });
+  }
+
+  const center = [(bounds[0] + bounds[2]) / 2, (bounds[1] + bounds[3]) / 2, 0];
+  const scale = Math.min(
+    1048576, // maxZoom of 20: Math.pow(2, 20) = 1048576
+    width / (bounds[2] - bounds[0]),
+    height / (bounds[3] - bounds[1])
+  );
+
+  return new OrthographicView({
+    x: padding,
+    y: padding
+  }).makeViewport({
+    width,
+    height,
+    viewState: {
+      target: center,
+      zoom: Math.log2(scale)
+    }
+  });
+}
+
+function _doubleBounds(bounds: MaskBounds): MaskBounds {
+  const size = {
+    x: bounds[2] - bounds[0],
+    y: bounds[3] - bounds[1]
+  };
+  const center = {
+    x: bounds[0] + 0.5 * size.x,
+    y: bounds[1] + 0.5 * size.y
+  };
+  return [center.x - size.x, center.y - size.y, center.x + size.x, center.y + size.y];
+}

package/src/terrain/height-map-builder.ts

@@ -0,0 +1,120 @@
+import {Framebuffer} from '@luma.gl/core';
+import {joinLayerBounds, getRenderBounds, makeViewport, Bounds} from '../common/projection-utils';
+import {createRenderTarget} from './utils';
+
+import type {Viewport, Layer} from '@deck.gl/core';
+
+const MAP_MAX_SIZE = 2048;
+
+/**
+ * Manages the lifecycle of the height map (a framebuffer that encodes elevation).
+ * One instance of height map is is shared across all layers. It is updated when the viewport changes
+ * or when some terrain source layer's data changes.
+ * During the draw call of any terrainFittingMode:offset layers,
+ * the vertex shader reads from this framebuffer to retrieve its z offset.
+ */
+export class HeightMapBuilder {
+  /** Viewport used to draw into the texture */
+  renderViewport: Viewport | null = null;
+  /** Bounds of the height map texture, in cartesian space */
+  bounds: Bounds | null = null;
+
+  protected fbo?: Framebuffer;
+  protected gl: WebGLRenderingContext;
+  /** Last rendered layers */
+  private layers: Layer[] = [];
+  /** Last layer.getBounds() */
+  private layersBounds: ([number[], number[]] | null)[] = [];
+  /** The union of layersBounds in cartesian space */
+  private layersBoundsCommon: Bounds | null = null;
+  private lastViewport: Viewport | null = null;
+
+  static isSupported(gl: WebGLRenderingContext): boolean {
+    return Framebuffer.isSupported(gl, {colorBufferFloat: true});
+  }
+
+  constructor(gl: WebGLRenderingContext) {
+    this.gl = gl;
+  }
+
+  /** Returns the height map framebuffer for read/write access.
+   * Returns null when the texture is invalid.
+   */
+  getRenderFramebuffer(): Framebuffer | null {
+    if (!this.renderViewport) {
+      return null;
+    }
+    if (!this.fbo) {
+      this.fbo = createRenderTarget(this.gl, {id: 'height-map', float: true});
+    }
+    return this.fbo;
+  }
+
+  /** Called every render cycle to check if the framebuffer needs update */
+  shouldUpdate({layers, viewport}: {layers: Layer[]; viewport: Viewport}): boolean {
+    const layersChanged =
+      layers.length !== this.layers.length ||
+      layers.some(
+        (layer, i) =>
+          // Layer instance is updated
+          // Layer props might have changed
+          // Undetermined props could have an effect on the output geometry of a terrain source,
+          // for example getElevation+updateTriggers, elevationScale, modelMatrix
+          layer !== this.layers[i] ||
+          // Some prop is in transition
+          layer.props.transitions ||
+          // Layer's geometry bounds have changed
+          layer.getBounds() !== this.layersBounds[i]
+      );
+
+    if (layersChanged) {
+      // Recalculate cached bounds
+      this.layers = layers;
+      this.layersBounds = layers.map(layer => layer.getBounds());
+      this.layersBoundsCommon = joinLayerBounds(layers, viewport);
+    }
+
+    const viewportChanged = !this.lastViewport || !viewport.equals(this.lastViewport);
+
+    if (!this.layersBoundsCommon) {
+      this.renderViewport = null;
+    } else if (layersChanged || viewportChanged) {
+      const bounds = getRenderBounds(this.layersBoundsCommon, viewport);
+      this.bounds = bounds;
+      this.lastViewport = viewport;
+
+      const scale = viewport.scale;
+      const pixelWidth = (bounds[2] - bounds[0]) * scale;
+      const pixelHeight = (bounds[3] - bounds[1]) * scale;
+
+      this.renderViewport =
+        pixelWidth > 0 || pixelHeight > 0
+          ? makeViewport({
+              // It's not important whether the geometry is visible in this viewport, because
+              // vertices will not use the standard project_to_clipspace in the DRAW_TO_HEIGHT_MAP shader
+              // However the viewport must have the same center and zoom as the screen viewport
+              // So that projection uniforms used for calculating z are the same
+              bounds: [
+                viewport.center[0] - 1,
+                viewport.center[1] - 1,
+                viewport.center[0] + 1,
+                viewport.center[1] + 1
+              ],
+              zoom: viewport.zoom,
+              width: Math.min(pixelWidth, MAP_MAX_SIZE),
+              height: Math.min(pixelHeight, MAP_MAX_SIZE),
+              viewport
+            })
+          : null;
+      return true;
+    }
+    return false;
+  }
+
+  delete() {
+    if (this.fbo) {
+      this.fbo.color.delete();
+      this.fbo.delete();
+    }
+  }
+}

package/src/terrain/shader-module.ts

@@ -0,0 +1,161 @@
+import {project} from '@deck.gl/core';
+import type {_ShaderModule as ShaderModule} from '@deck.gl/core';
+
+import type {Texture2D} from '@luma.gl/core';
+import type {Bounds} from '../common/projection-utils';
+import type {TerrainCover} from './terrain-cover';
+
+/** Module parameters expected by the terrain shader module */
+export type TerrainModuleSettings = {
+  pickingActive?: boolean;
+  heightMap: Texture2D | null;
+  heightMapBounds?: Bounds | null;
+  dummyHeightMap: Texture2D;
+  terrainCover?: TerrainCover | null;
+  drawToTerrainHeightMap?: boolean;
+  useTerrainHeightMap?: boolean;
+  terrainSkipRender?: boolean;
+};
+
+/** A model can have one of the following modes */
+export const TERRAIN_MODE = {
+  NONE: 0,
+  /** A terrain layer rendering encoded ground elevation into the height map */
+  WRITE_HEIGHT_MAP: 1,
+  /** An offset layer reading encoded ground elevation from the height map */
+  USE_HEIGHT_MAP: 2,
+  /** A terrain layer rendering to screen, using the cover fbo overlaid with its own texture */
+  USE_COVER: 3,
+  /** A terrain layer rendering to screen, using the cover fbo as texture */
+  USE_COVER_ONLY: 4,
+  /** Draped layer is rendered into a texture, and never to screen */
+  SKIP: 5
+};
+
+const TERRAIN_MODE_CONSTANTS = Object.keys(TERRAIN_MODE)
+  .map(key => `const float TERRAIN_MODE_${key} = ${TERRAIN_MODE[key]}.0;`)
+  .join('\n');
+
+export const terrainModule = {
+  name: 'terrain',
+  dependencies: [project],
+  inject: {
+    'vs:#decl': `
+uniform float terrain_mode;
+uniform sampler2D terrain_map;
+uniform vec4 terrain_bounds;
+varying vec3 commonPos;
+${TERRAIN_MODE_CONSTANTS}
+    `,
+    'vs:#main-start': `
+if (terrain_mode == TERRAIN_MODE_SKIP) {
+  gl_Position = vec4(0.0);
+  return;
+}
+`,
+    'vs:DECKGL_FILTER_GL_POSITION': `
+commonPos = geometry.position.xyz;
+if (terrain_mode == TERRAIN_MODE_WRITE_HEIGHT_MAP) {
+  vec2 texCoords = (commonPos.xy - terrain_bounds.xy) / terrain_bounds.zw;
+  position = vec4(texCoords * 2.0 - 1.0, 0.0, 1.0);
+}
+if (terrain_mode == TERRAIN_MODE_USE_HEIGHT_MAP) {
+  vec3 anchor = geometry.worldPosition;
+  anchor.z = 0.0;
+  vec3 anchorCommon = project_position(anchor);
+  vec2 texCoords = (anchorCommon.xy - terrain_bounds.xy) / terrain_bounds.zw;
+  if (texCoords.x >= 0.0 && texCoords.y >= 0.0 && texCoords.x <= 1.0 && texCoords.y <= 1.0) {
+    float terrainZ = texture2D(terrain_map, texCoords).r;
+    geometry.position.z += terrainZ;
+    position = project_common_position_to_clipspace(geometry.position);
+  }
+}
+    `,
+    'fs:#decl': `
+uniform float terrain_mode;
+uniform sampler2D terrain_map;
+uniform vec4 terrain_bounds;
+varying vec3 commonPos;
+${TERRAIN_MODE_CONSTANTS}
+    `,
+    'fs:#main-start': `
+if (terrain_mode == TERRAIN_MODE_WRITE_HEIGHT_MAP) {
+  gl_FragColor = vec4(commonPos.z, 0.0, 0.0, 1.0);
+  return;
+}
+    `,
+    'fs:DECKGL_FILTER_COLOR': `
+if ((terrain_mode == TERRAIN_MODE_USE_COVER) || (terrain_mode == TERRAIN_MODE_USE_COVER_ONLY)) {
+  vec2 texCoords = (commonPos.xy - terrain_bounds.xy) / terrain_bounds.zw;
+  vec4 pixel = texture2D(terrain_map, texCoords);
+  if (terrain_mode == TERRAIN_MODE_USE_COVER_ONLY) {
+    color = pixel;
+  } else {
+    // pixel is premultiplied
+    color = pixel + color * (1.0 - pixel.a);
+  }
+  return;
+}
+    `
+  },
+  getUniforms: (opts = {}, uniforms) => {
+    if ('dummyHeightMap' in opts) {
+      const {
+        drawToTerrainHeightMap,
+        heightMap,
+        heightMapBounds,
+        dummyHeightMap,
+        terrainCover,
+        useTerrainHeightMap,
+        terrainSkipRender
+      } = opts;
+      const {project_uCommonOrigin} = uniforms;
+
+      let mode: number = terrainSkipRender ? TERRAIN_MODE.SKIP : TERRAIN_MODE.NONE;
+      // height map if case USE_HEIGHT_MAP, terrain cover if USE_COVER, otherwise empty
+      let sampler: Texture2D = dummyHeightMap;
+      // height map bounds if case USE_HEIGHT_MAP, terrain cover bounds if USE_COVER, otherwise null
+      let bounds: number[] | null = null;
+      if (drawToTerrainHeightMap) {
+        mode = TERRAIN_MODE.WRITE_HEIGHT_MAP;
+        bounds = heightMapBounds!;
+      } else if (useTerrainHeightMap && heightMap) {
+        mode = TERRAIN_MODE.USE_HEIGHT_MAP;
+        sampler = heightMap;
+        bounds = heightMapBounds!;
+      } else if (terrainCover) {
+        // This is a terrain layer
+        const isPicking = opts.pickingActive;
+        sampler = isPicking
+          ? terrainCover.getPickingFramebuffer()
+          : terrainCover.getRenderFramebuffer();
+        if (isPicking) {
+          // Never render the layer itself in picking pass
+          mode = TERRAIN_MODE.SKIP;
+        }
+        if (sampler) {
+          mode = mode === TERRAIN_MODE.SKIP ? TERRAIN_MODE.USE_COVER_ONLY : TERRAIN_MODE.USE_COVER;
+          bounds = terrainCover.bounds;
+        } else {
+          sampler = dummyHeightMap;
+        }
+      }
+
+      /* eslint-disable camelcase */
+      return {
+        terrain_mode: mode,
+        terrain_map: sampler,
+        // Convert bounds to the common space, as [minX, minY, width, height]
+        terrain_bounds: bounds
+          ? [
+              bounds[0] - project_uCommonOrigin[0],
+              bounds[1] - project_uCommonOrigin[1],
+              bounds[2] - bounds[0],
+              bounds[3] - bounds[1]
+            ]
+          : [0, 0, 0, 0]
+      };
+    }
+    return null;
+  }
+} as ShaderModule<TerrainModuleSettings>;