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

package/src/terrain/terrain-cover.ts

@@ -0,0 +1,225 @@
+import {Framebuffer} from '@luma.gl/core';
+
+import type {Layer, Viewport} from '@deck.gl/core';
+
+import {createRenderTarget} from './utils';
+import {joinLayerBounds, makeViewport, getRenderBounds, Bounds} from '../common/projection-utils';
+
+// TODO - import from loaders when Tileset2D is split out
+type GeoBoundingBox = {west: number; north: number; east: number; south: number};
+type NonGeoBoundingBox = {left: number; top: number; right: number; bottom: number};
+type Tile2DHeader = {
+  bbox: GeoBoundingBox | NonGeoBoundingBox;
+};
+
+/**
+ * Manages the lifecycle of the terrain cover (draped textures over a terrain mesh).
+ * One terrain cover is created for each unique terrain layer (primitive layer with operation:terrain).
+ * It is updated when the terrain source layer's mesh changes or when any of the terrainFittingMode:drape
+ * layers requires redraw.
+ * During the draw call of a terrain layer, the drape texture is overlaid on top of the layer's own color.
+ */
+export class TerrainCover {
+  isDirty: boolean = true;
+  /** The terrain layer that this instance belongs to */
+  targetLayer: Layer;
+  /** Viewport used to draw into the texture */
+  renderViewport: Viewport | null = null;
+  /** Bounds of the terrain cover texture, in cartesian space */
+  bounds: Bounds | null = null;
+
+  private fbo?: Framebuffer;
+  private pickingFbo?: Framebuffer;
+  private layers: string[] = [];
+  private tile: Tile2DHeader | null;
+  /** Cached version of targetLayer.getBounds() */
+  private targetBounds: [number[], number[]] | null = null;
+  /** targetBounds in cartesian space */
+  private targetBoundsCommon: Bounds | null = null;
+
+  constructor(targetLayer: Layer) {
+    this.targetLayer = targetLayer;
+    this.tile = getTile(targetLayer);
+  }
+
+  get id() {
+    return this.targetLayer.id;
+  }
+
+  /** returns true if the target layer is still in use (i.e. not finalized) */
+  get isActive(): boolean {
+    return Boolean(this.targetLayer.getCurrentLayer());
+  }
+
+  shouldUpdate({
+    targetLayer,
+    viewport,
+    layers,
+    layerNeedsRedraw
+  }: {
+    targetLayer?: Layer;
+    viewport?: Viewport;
+    layers?: Layer[];
+    layerNeedsRedraw?: Record<string, boolean>;
+  }): boolean {
+    if (targetLayer) {
+      this.targetLayer = targetLayer;
+    }
+    const sizeChanged = viewport ? this._updateViewport(viewport) : false;
+
+    let layersChanged = layers ? this._updateLayers(layers) : false;
+
+    if (layerNeedsRedraw) {
+      for (const id of this.layers) {
+        if (layerNeedsRedraw[id]) {
+          layersChanged = true;
+          // console.log('layer needs redraw', id);
+          break;
+        }
+      }
+    }
+
+    return layersChanged || sizeChanged;
+  }
+
+  /** Compare layers with the last version. Only rerender if necessary. */
+  private _updateLayers(layers: Layer[]): boolean {
+    let needsRedraw = false;
+    layers = this.tile ? getIntersectingLayers(this.tile, layers) : layers;
+
+    if (layers.length !== this.layers.length) {
+      needsRedraw = true;
+      // console.log('layers count changed', this.layers.length, '>>', layers.length);
+    } else {
+      for (let i = 0; i < layers.length; i++) {
+        const id = layers[i].id;
+        if (id !== this.layers[i]) {
+          needsRedraw = true;
+          // console.log('layer added/removed', id);
+          break;
+        }
+      }
+    }
+    if (needsRedraw) {
+      this.layers = layers.map(layer => layer.id);
+    }
+    return needsRedraw;
+  }
+
+  /** Compare viewport and terrain bounds with the last version. Only rerender if necesary. */
+  private _updateViewport(viewport: Viewport): boolean {
+    const targetLayer = this.targetLayer;
+    let shouldRedraw = false;
+
+    if (this.targetBounds !== targetLayer.getBounds()) {
+      // console.log('bounds changed', this.bounds, '>>', newBounds);
+      shouldRedraw = true;
+      this.targetBounds = targetLayer.getBounds();
+      this.targetBoundsCommon = joinLayerBounds([targetLayer], viewport);
+    }
+
+    if (!this.targetBoundsCommon) {
+      return false;
+    }
+
+    const newZoom = Math.ceil(viewport.zoom + 0.5);
+    // If the terrain layer is bound to a tile, always render a texture that cover the whole tile.
+    // Otherwise, use the smaller of layer bounds and the viewport bounds.
+    if (this.tile) {
+      this.bounds = this.targetBoundsCommon;
+    } else {
+      const oldZoom = this.renderViewport?.zoom;
+      shouldRedraw = shouldRedraw || newZoom !== oldZoom;
+      const newBounds = getRenderBounds(this.targetBoundsCommon, viewport);
+      const oldBounds = this.bounds;
+      shouldRedraw = shouldRedraw || !oldBounds || newBounds.some((x, i) => x !== oldBounds[i]);
+      this.bounds = newBounds;
+    }
+
+    if (shouldRedraw) {
+      this.renderViewport = makeViewport({
+        bounds: this.bounds,
+        zoom: newZoom,
+        viewport
+      });
+    }
+
+    return shouldRedraw;
+  }
+
+  getRenderFramebuffer(): Framebuffer | null {
+    if (!this.renderViewport || this.layers.length === 0) {
+      return null;
+    }
+    if (!this.fbo) {
+      this.fbo = createRenderTarget(this.targetLayer.context.gl, {id: this.id});
+    }
+    return this.fbo;
+  }
+
+  getPickingFramebuffer(): Framebuffer | null {
+    if (!this.renderViewport || (this.layers.length === 0 && !this.targetLayer.props.pickable)) {
+      return null;
+    }
+    if (!this.pickingFbo) {
+      this.pickingFbo = createRenderTarget(this.targetLayer.context.gl, {id: `${this.id}-picking`});
+    }
+    return this.pickingFbo;
+  }
+
+  filterLayers(layers: Layer[]) {
+    return layers.filter(({id}) => this.layers.includes(id));
+  }
+
+  delete() {
+    const {fbo, pickingFbo} = this;
+    if (fbo) {
+      fbo.texture.delete();
+      fbo.delete();
+    }
+    if (pickingFbo) {
+      pickingFbo.texture.delete();
+      pickingFbo.delete();
+    }
+  }
+}
+
+/**
+ * Remove layers that do not overlap with the current terrain cover.
+ * This implementation only has effect when a TileLayer is overlaid on top of a TileLayer
+ */
+function getIntersectingLayers(sourceTile: Tile2DHeader, layers: Layer[]): Layer[] {
+  return layers.filter(layer => {
+    const tile = getTile(layer);
+    if (tile) {
+      return intersect(sourceTile.bbox, tile.bbox);
+    }
+    return true;
+  });
+}
+
+/** If layer is the descendent of a TileLayer, return the corresponding tile. */
+function getTile(layer: Layer): Tile2DHeader | null {
+  while (layer) {
+    // @ts-expect-error tile may not exist
+    const {tile} = layer.props;
+    if (tile) {
+      return tile;
+    }
+    layer = layer.parent as Layer;
+  }
+  return null;
+}
+
+function intersect(
+  b1: GeoBoundingBox | NonGeoBoundingBox,
+  b2: GeoBoundingBox | NonGeoBoundingBox
+): boolean {
+  if ('west' in b1 && 'west' in b2) {
+    return b1.west < b2.east && b2.west < b1.east && b1.south < b2.north && b2.south < b1.north;
+  }
+  if ('left' in b1 && 'left' in b2) {
+    return b1.left < b2.right && b2.left < b1.right && b1.top < b2.bottom && b2.top < b1.bottom;
+  }
+  return false;
+}

package/src/terrain/terrain-effect.ts

@@ -0,0 +1,223 @@
+import {Texture2D, ProgramManager} from '@luma.gl/core';
+import {log} from '@deck.gl/core';
+
+import {terrainModule, TerrainModuleSettings} from './shader-module';
+import {TerrainCover} from './terrain-cover';
+import {TerrainPass} from './terrain-pass';
+import {TerrainPickingPass, TerrainPickingPassRenderOptions} from './terrain-picking-pass';
+import {HeightMapBuilder} from './height-map-builder';
+
+import type {Effect, PreRenderOptions, Layer, Viewport} from '@deck.gl/core';
+
+/** Class to manage terrain effect */
+export class TerrainEffect implements Effect {
+  id = 'terrain-effect';
+  props = null;
+  useInPicking = true;
+
+  /** true if picking in the current pass */
+  private isPicking: boolean = false;
+  /** true if should use in the current pass */
+  private isDrapingEnabled: boolean = false;
+  /** An empty texture as placeholder */
+  private dummyHeightMap: Texture2D;
+  /** A texture encoding the ground elevation, updated once per redraw. Used by layers with offset mode */
+  private heightMap?: HeightMapBuilder;
+  private terrainPass!: TerrainPass;
+  private terrainPickingPass!: TerrainPickingPass;
+  /** One texture for each primitive terrain layer, into which the draped layers render */
+  private terrainCovers: Map<string, TerrainCover> = new Map();
+
+  initialize(gl: WebGLRenderingContext) {
+    this.dummyHeightMap = new Texture2D(gl, {
+      width: 1,
+      height: 1,
+      data: new Uint8Array([0, 0, 0, 0])
+    });
+    this.terrainPass = new TerrainPass(gl, {id: 'terrain'});
+    this.terrainPickingPass = new TerrainPickingPass(gl, {id: 'terrain-picking'});
+
+    if (HeightMapBuilder.isSupported(gl)) {
+      this.heightMap = new HeightMapBuilder(gl);
+    } else {
+      log.warn('Terrain offset mode is not supported by this browser')();
+    }
+
+    ProgramManager.getDefaultProgramManager(gl).addDefaultModule(terrainModule);
+  }
+
+  preRender(gl: WebGLRenderingContext, opts: PreRenderOptions): void {
+    if (!this.dummyHeightMap) {
+      // First time this effect is in use, initialize resources and register the shader module
+      this.initialize(gl);
+      for (const layer of opts.layers) {
+        // Force the terrain layer (and its descendents) to rebuild their models with the new shader
+        if (layer.props.operation.includes('terrain')) {
+          layer.setChangeFlags({extensionsChanged: true});
+        }
+      }
+    }
+
+    // @ts-expect-error pickZ only defined in picking pass
+    if (opts.pickZ) {
+      // Do not update if picking attributes
+      this.isDrapingEnabled = false;
+      return;
+    }
+
+    const {viewports, pass} = opts;
+    const isPicking = pass.startsWith('picking');
+    this.isPicking = isPicking;
+    this.isDrapingEnabled = true;
+
+    // TODO - support multiple views?
+    const viewport = viewports[0];
+    const layers = (isPicking ? this.terrainPickingPass : this.terrainPass).getRenderableLayers(
+      viewport,
+      opts as TerrainPickingPassRenderOptions
+    );
+
+    const terrainLayers = layers.filter(l => l.props.operation.includes('terrain'));
+    if (terrainLayers.length === 0) {
+      return;
+    }
+
+    if (!isPicking) {
+      const offsetLayers = layers.filter(l => l.state.terrainFittingMode === 'offset');
+      if (offsetLayers.length > 0) {
+        this._updateHeightMap(terrainLayers, viewport, opts);
+      }
+    }
+
+    const drapeLayers = layers.filter(l => l.state.terrainFittingMode === 'drape');
+    this._updateTerrainCovers(terrainLayers, drapeLayers, viewport, opts);
+  }
+
+  getModuleParameters(layer: Layer): TerrainModuleSettings {
+    const {terrainFittingMode} = layer.state;
+
+    return {
+      heightMap: this.heightMap?.getRenderFramebuffer(),
+      heightMapBounds: this.heightMap?.bounds,
+      dummyHeightMap: this.dummyHeightMap,
+      terrainCover: this.isDrapingEnabled ? this.terrainCovers.get(layer.id) : null,
+      useTerrainHeightMap: terrainFittingMode === 'offset',
+      terrainSkipRender: terrainFittingMode === 'drape' || !layer.props.operation.includes('draw')
+    };
+  }
+
+  cleanup(): void {
+    if (this.dummyHeightMap) {
+      this.dummyHeightMap.delete();
+      this.dummyHeightMap = undefined;
+    }
+
+    if (this.heightMap) {
+      this.heightMap.delete();
+      this.heightMap = undefined;
+    }
+
+    for (const terrainCover of this.terrainCovers.values()) {
+      terrainCover.delete();
+    }
+    this.terrainCovers.clear();
+  }
+
+  private _updateHeightMap(terrainLayers: Layer[], viewport: Viewport, opts: PreRenderOptions) {
+    if (!this.heightMap) {
+      // Not supported
+      return;
+    }
+
+    const shouldUpdate = this.heightMap.shouldUpdate({layers: terrainLayers, viewport});
+    if (!shouldUpdate) {
+      return;
+    }
+
+    this.terrainPass.renderHeightMap(this.heightMap, {
+      ...opts,
+      layers: terrainLayers,
+      moduleParameters: {
+        heightMapBounds: this.heightMap.bounds,
+        dummyHeightMap: this.dummyHeightMap,
+        devicePixelRatio: 1,
+        drawToTerrainHeightMap: true
+      }
+    });
+  }
+
+  private _updateTerrainCovers(
+    terrainLayers: Layer[],
+    drapeLayers: Layer[],
+    viewport: Viewport,
+    opts: PreRenderOptions
+  ) {
+    // Mark a terrain cover as dirty if one of the drape layers needs redraw
+    const layerNeedsRedraw: Record<string, boolean> = {};
+    for (const layer of drapeLayers) {
+      if (layer.state.terrainCoverNeedsRedraw) {
+        layerNeedsRedraw[layer.id] = true;
+        layer.state.terrainCoverNeedsRedraw = false;
+      }
+    }
+    for (const terrainCover of this.terrainCovers.values()) {
+      terrainCover.isDirty = terrainCover.isDirty || terrainCover.shouldUpdate({layerNeedsRedraw});
+    }
+
+    for (const layer of terrainLayers) {
+      this._updateTerrainCover(layer, drapeLayers, viewport, opts);
+    }
+
+    if (!this.isPicking) {
+      this._pruneTerrainCovers();
+    }
+  }
+
+  private _updateTerrainCover(
+    terrainLayer: Layer,
+    drapeLayers: Layer[],
+    viewport: Viewport,
+    opts: PreRenderOptions
+  ) {
+    const renderPass = this.isPicking ? this.terrainPickingPass : this.terrainPass;
+    let terrainCover = this.terrainCovers.get(terrainLayer.id);
+    if (!terrainCover) {
+      terrainCover = new TerrainCover(terrainLayer);
+      this.terrainCovers.set(terrainLayer.id, terrainCover);
+    }
+    try {
+      const isDirty = terrainCover.shouldUpdate({
+        targetLayer: terrainLayer,
+        viewport,
+        layers: drapeLayers
+      });
+      if (this.isPicking || terrainCover.isDirty || isDirty) {
+        renderPass.renderTerrainCover(terrainCover, {
+          ...opts,
+          layers: drapeLayers,
+          moduleParameters: {
+            dummyHeightMap: this.dummyHeightMap,
+            terrainSkipRender: false,
+            devicePixelRatio: 1
+          }
+        });
+        terrainCover.isDirty = false;
+      }
+    } catch (err) {
+      terrainLayer.raiseError(err as Error, `Error rendering terrain cover ${terrainCover.id}`);
+    }
+  }
+
+  private _pruneTerrainCovers() {
+    /** Prune the cache, remove textures for layers that have been removed */
+    const idsToRemove: string[] = [];
+    for (const [id, terrainCover] of this.terrainCovers) {
+      if (!terrainCover.isActive) {
+        idsToRemove.push(id);
+      }
+    }
+    for (const id of idsToRemove) {
+      this.terrainCovers.delete(id);
+    }
+  }
+}

package/src/terrain/terrain-pass.ts

@@ -0,0 +1,86 @@
+import {withParameters} from '@luma.gl/core';
+import {Layer, Viewport, _LayersPass as LayersPass, LayersPassRenderOptions} from '@deck.gl/core';
+import type {HeightMapBuilder} from './height-map-builder';
+import type {TerrainCover} from './terrain-cover';
+
+import GL from '@luma.gl/constants';
+
+export type TerrainPassRenderOptions = LayersPassRenderOptions;
+
+/** Renders textures used by the TerrainEffect render pass */
+export class TerrainPass extends LayersPass {
+  getRenderableLayers(viewport: Viewport, opts: TerrainPassRenderOptions): Layer[] {
+    const {layers} = opts;
+    const result: Layer[] = [];
+    const drawParamsByIndex = this._getDrawLayerParams(viewport, opts, true);
+    for (let i = 0; i < layers.length; i++) {
+      const layer = layers[i];
+      if (!layer.isComposite && drawParamsByIndex[i].shouldDrawLayer) {
+        result.push(layer);
+      }
+    }
+
+    return result;
+  }
+
+  renderHeightMap(heightMap: HeightMapBuilder, opts: Partial<TerrainPassRenderOptions>) {
+    // console.log('Updating height map')
+    const target = heightMap.getRenderFramebuffer();
+    const viewport = heightMap.renderViewport;
+
+    if (!target || !viewport) {
+      return;
+    }
+
+    target.resize(viewport);
+
+    withParameters(
+      this.gl,
+      {
+        clearColor: [0, 0, 0, 0],
+        blend: true,
+        blendFunc: [GL.ONE, GL.ONE],
+        blendEquation: GL.MAX,
+        depthTest: false
+      },
+      () =>
+        this.render({
+          ...opts,
+          target,
+          pass: 'terrain-height-map',
+          layers: opts.layers!,
+          viewports: [viewport],
+          effects: []
+        })
+    );
+  }
+
+  renderTerrainCover(terrainCover: TerrainCover, opts: Partial<TerrainPassRenderOptions>) {
+    // console.log('Updating terrain cover ' + terrainCover.id)
+    const target = terrainCover.getRenderFramebuffer();
+    const viewport = terrainCover.renderViewport;
+
+    if (!target || !viewport) {
+      return;
+    }
+
+    const layers = terrainCover.filterLayers(opts.layers!);
+    target.resize(viewport);
+
+    withParameters(
+      this.gl,
+      {
+        depthTest: false
+      },
+      () =>
+        this.render({
+          ...opts,
+          target,
+          pass: `terrain-cover-${terrainCover.id}`,
+          layers,
+          effects: [],
+          viewports: [viewport]
+        })
+    );
+  }
+}

package/src/terrain/terrain-picking-pass.ts

@@ -0,0 +1,87 @@
+import {
+  Layer,
+  Viewport,
+  LayersPassRenderOptions,
+  _PickLayersPass as PickLayersPass
+} from '@deck.gl/core';
+import {withParameters} from '@luma.gl/core';
+import type {TerrainCover} from './terrain-cover';
+
+export type TerrainPickingPassRenderOptions = LayersPassRenderOptions & {
+  pickZ: boolean;
+};
+
+/** Renders textures used by the TerrainEffect picking pass */
+export class TerrainPickingPass extends PickLayersPass {
+  /** Save layer index for use when drawing to terrain cover.
+   * When a terrain cover's picking buffer is rendered,
+   * we need to make sure each layer receives a consistent index (encoded in the alpha channel)
+   * so that a picked color can be decoded back to the correct layer.
+   * Updated in getRenderableLayers which is called in TerrainEffect.preRender
+   */
+  drawParameters: Record<string, any> = {};
+
+  getRenderableLayers(viewport: Viewport, opts: TerrainPickingPassRenderOptions): Layer[] {
+    const {layers} = opts;
+    const result: Layer[] = [];
+    this.drawParameters = {};
+    this._resetColorEncoder(opts.pickZ);
+    const drawParamsByIndex = this._getDrawLayerParams(viewport, opts);
+    for (let i = 0; i < layers.length; i++) {
+      const layer = layers[i];
+      if (!layer.isComposite && drawParamsByIndex[i].shouldDrawLayer) {
+        result.push(layer);
+        this.drawParameters[layer.id] = drawParamsByIndex[i].layerParameters;
+      }
+    }
+
+    return result;
+  }
+
+  renderTerrainCover(terrainCover: TerrainCover, opts: Partial<TerrainPickingPassRenderOptions>) {
+    // console.log('Updating terrain cover for picking ' + terrainCover.id)
+    const target = terrainCover.getPickingFramebuffer();
+    const viewport = terrainCover.renderViewport;
+
+    if (!target || !viewport) {
+      return;
+    }
+
+    const layers = terrainCover.filterLayers(opts.layers!);
+    const terrainLayer = terrainCover.targetLayer;
+    if (terrainLayer.props.pickable) {
+      layers.unshift(terrainLayer);
+    }
+    target.resize(viewport);
+
+    withParameters(
+      this.gl,
+      {
+        depthTest: false
+      },
+      () =>
+        this.render({
+          ...opts,
+          pickingFBO: target,
+          pass: `terrain-cover-picking-${terrainCover.id}`,
+          layers,
+          effects: [],
+          viewports: [viewport],
+          // Disable the default culling because TileLayer would cull sublayers based on the screen viewport,
+          // not the viewport of the terrain cover. Culling is already done by `terrainCover.filterLayers`
+          cullRect: undefined,
+          deviceRect: viewport,
+          pickZ: false
+        })
+    );
+  }
+
+  protected getLayerParameters(layer: Layer, layerIndex: number, viewport: Viewport): any {
+    if (this.drawParameters[layer.id]) {
+      return this.drawParameters[layer.id];
+    }
+    const parameters = super.getLayerParameters(layer, layerIndex, viewport);
+    parameters.blend = true;
+    return parameters;
+  }
+}

package/src/terrain/terrain.ts

@@ -0,0 +1,74 @@
+import {LayerExtension, UpdateParameters} from '@deck.gl/core';
+import {TerrainEffect} from './terrain-effect';
+import {terrainModule} from './shader-module';
+
+import type {Layer} from '@deck.gl/core';
+
+const defaultProps = {
+  terrainFittingMode: undefined
+};
+
+export type TerrainExtensionProps = {
+  /**
+   * controls whether an object is drawn over the terrain surface by its anchor (usually defined by an accessor called `getPosition`, e.g. icon, scatterplot) or by its geometry (e.g. path, polygon).
+   * If not specified, it is automatically deduced from the layer.
+   */
+  terrainFittingMode?: 'offset' | 'drape';
+};
+
+type TerrainExtensionState = {
+  /** Resolved fitting mode */
+  terrainFittingMode: 'offset' | 'drape';
+  /** Set when a layer is flagged as needs redraw */
+  terrainCoverNeedsRedraw: boolean;
+};
+
+/** Allows layers to show/hide objects by a geofence. */
+export default class TerrainExtension extends LayerExtension {
+  static defaultProps = defaultProps;
+  static extensionName = 'TerrainExtension';
+
+  getShaders(this: Layer<TerrainExtensionProps>): any {
+    return {
+      modules: [terrainModule]
+    };
+  }
+
+  initializeState(this: Layer<TerrainExtensionProps>) {
+    this.context.deck?._addDefaultEffect(new TerrainEffect());
+  }
+
+  updateState(
+    this: Layer<TerrainExtensionProps>,
+    params: UpdateParameters<Layer<TerrainExtensionProps>>
+  ) {
+    const {props, oldProps} = params;
+
+    if (
+      this.state.terrainFittingMode &&
+      props.terrainFittingMode === oldProps.terrainFittingMode &&
+      // @ts-ignore `extruded` may not exist in props
+      props.extruded === oldProps.extruded
+    ) {
+      return;
+    }
+
+    let {terrainFittingMode} = props;
+    if (!terrainFittingMode) {
+      // props.extruded is used as an indication that the layer is 2.5D
+      // @ts-ignore `extruded` may not exist in props
+      const is3d = this.props.extruded as boolean;
+      const attributes = this.getAttributeManager()?.attributes;
+      const hasAnchor = attributes && 'instancePositions' in attributes;
+      terrainFittingMode = is3d || hasAnchor ? 'offset' : 'drape';
+    }
+    this.setState({terrainFittingMode});
+  }
+
+  onNeedsRedraw(this: Layer<{}>): void {
+    const state = this.state as TerrainExtensionState;
+    if (state.terrainFittingMode === 'drape') {
+      state.terrainCoverNeedsRedraw = true;
+    }
+  }
+}