feat(extensions): TerrainExtension GlobeView support

docs/api-reference/extensions/terrain-extension.md

@@ -9,6 +9,8 @@ To use this extension, first define a terrain source with the prop `operation: '
 
 For each layer that should be fitted to the terrain surface, add the `TerrainExtension` to its `extensions` prop.
 
+The extension works on both `MapView` and `GlobeView`. Terrain cover and height-map FBOs are computed in absolute Mercator common space so the same draw target can be sampled from either projection without re-rendering when the user toggles between them. When pairing with a `TerrainLayer` source on `GlobeView`, set the source's `tesselator: 'grid'` so its mesh is valid on both projections.
+
 <div style={{position:'relative',height:450}}></div>
 <div style={{position:'absolute',transform:'translateY(-450px)',paddingLeft:'inherit',paddingRight:'inherit',left:0,right:0}}>
   <iframe height="450" style={{width: '100%'}} scrolling="no" title="deck.gl TerrainExtension" src="https://codepen.io/vis-gl/embed/VwGLLeR?height=450&theme-id=light&default-tab=result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">

examples/website/terrain-extension/app.tsx

@@ -5,6 +5,7 @@
 import React, {useState, useEffect, useMemo} from 'react';
 import {createRoot} from 'react-dom/client';
 import {DeckGL} from '@deck.gl/react';
+import {_GlobeView as GlobeView, MapView} from '@deck.gl/core';
 import {TerrainLayer} from '@deck.gl/geo-layers';
 import {GeoJsonLayer, IconLayer, TextLayer} from '@deck.gl/layers';
 import {_TerrainExtension as TerrainExtension} from '@deck.gl/extensions';
@@ -25,7 +26,7 @@ const INITIAL_VIEW_STATE: MapViewState = {
   longitude: -0.6194,
   zoom: 10,
   pitch: 55,
-  maxZoom: 13.5,
+  maxZoom: 23.5,
   bearing: 0,
   maxPitch: 89
 };
@@ -84,6 +85,8 @@ export default function App({
   initialViewState?: MapViewState;
 }) {
   const [routes, setRoutes] = useState<FeatureCollection<LineString, RouteProperties>>();
+  const [useGlobe, setUseGlobe] = useState(false);
+  const [viewState, setViewState] = useState<MapViewState>(initialViewState);
 
   useEffect(() => {
     // eslint-disable-next-line @typescript-eslint/no-floating-promises
@@ -111,8 +114,7 @@ export default function App({
       elevationDecoder: ELEVATION_DECODER,
       elevationData: TERRAIN_IMAGE,
       texture: SURFACE_IMAGE,
-      wireframe: false,
-      color: [255, 255, 255],
+      material: false,
       operation: 'terrain+draw'
     }),
     new GeoJsonLayer<RouteProperties>({
@@ -132,7 +134,8 @@ export default function App({
       getPosition: d => d.coordinates,
       getIcon: d => (d.type === 'start' ? 'green' : 'checker'),
       getSize: 32,
-      extensions: [new TerrainExtension()]
+      extensions: [new TerrainExtension()],
+      terrainDrawMode: 'offset'
     }),
     new TextLayer<Stage>({
       id: 'stage-label',
@@ -151,14 +154,37 @@ export default function App({
     })
   ];
 
+  const view = useGlobe ? new GlobeView() : new MapView();
+
   return (
-    <DeckGL
-      initialViewState={initialViewState}
-      controller={true}
-      layers={layers}
-      pickingRadius={5}
-      getTooltip={getTooltip}
-    />
+    <>
+      <DeckGL
+        views={view}
+        viewState={viewState}
+        onViewStateChange={e => setViewState(e.viewState as MapViewState)}
+        controller={true}
+        layers={layers}
+        pickingRadius={5}
+        getTooltip={getTooltip}
+      />
+      <button
+        onClick={() => setUseGlobe(v => !v)}
+        style={{
+          position: 'absolute',
+          top: 12,
+          right: 12,
+          zIndex: 10,
+          padding: '6px 10px',
+          font: '12px ui-monospace, monospace',
+          background: 'rgba(0,0,0,0.65)',
+          color: '#fff',
+          border: '1px solid #888',
+          cursor: 'pointer'
+        }}
+      >
+        {useGlobe ? 'MapView' : 'GlobeView'}
+      </button>
+    </>
   );
 }
 

modules/extensions/src/terrain/height-map-builder.ts

@@ -3,7 +3,14 @@
 // Copyright (c) vis.gl contributors
 
 import {Device, Framebuffer} from '@luma.gl/core';
-import {joinLayerBounds, getRenderBounds, makeViewport, Bounds} from '../utils/projection-utils';
+import {
+  joinLayerBounds,
+  getRenderBounds,
+  makeViewport,
+  getMercatorReferenceViewport,
+  lngLatToMercatorCommon,
+  Bounds
+} from '../utils/projection-utils';
 import {createRenderTarget} from './utils';
 
 import type {Viewport, Layer} from '@deck.gl/core';
@@ -72,18 +79,22 @@ export class HeightMapBuilder {
       );
 
     if (layersChanged) {
-      // Recalculate cached bounds
+      // Recalculate cached bounds in absolute Mercator common space
       this.layers = layers;
       this.layersBounds = layers.map(layer => layer.getBounds());
-      this.layersBoundsCommon = joinLayerBounds(layers, viewport);
+      this.layersBoundsCommon = joinLayerBounds(layers, getMercatorReferenceViewport(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);
+      // On GlobeView, viewport bounds are sphere cartesian — skip intersection
+      const isGlobe = Boolean(viewport.resolution && viewport.resolution > 0);
+      const bounds = isGlobe
+        ? this.layersBoundsCommon
+        : getRenderBounds(this.layersBoundsCommon, viewport);
       if (bounds[2] <= bounds[0] || bounds[3] <= bounds[1]) {
         this.renderViewport = null;
         return false;
@@ -96,19 +107,19 @@ export class HeightMapBuilder {
       const pixelWidth = (bounds[2] - bounds[0]) * scale;
       const pixelHeight = (bounds[3] - bounds[1]) * scale;
 
+      // Use Mercator center — viewport.center on GlobeView is sphere cartesian
+      const centerMerc = viewport.isGeospatial
+        ? lngLatToMercatorCommon([viewport.longitude ?? 0, viewport.latitude ?? 0])
+        : [viewport.center[0], viewport.center[1]];
+
       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
-              ],
+              bounds: [centerMerc[0] - 1, centerMerc[1] - 1, centerMerc[0] + 1, centerMerc[1] + 1],
               zoom: viewport.zoom,
               width: Math.min(pixelWidth, MAP_MAX_SIZE),
               height: Math.min(pixelHeight, MAP_MAX_SIZE),

modules/extensions/src/terrain/shader-module.ts

@@ -67,10 +67,20 @@ uniform sampler2D terrain_map;
 export const terrainModule = {
   name: 'terrain',
   dependencies: [project],
-  // eslint-disable-next-line prefer-template
-  vs: uniformBlock + /* glsl */ 'out vec3 commonPos;',
-  // eslint-disable-next-line prefer-template
-  fs: uniformBlock + /* glsl */ 'in vec3 commonPos;',
+  vs: `${uniformBlock}
+out vec3 commonPos;
+// In globe mode, absolute Mercator position for terrain FBO UV lookups
+out vec2 terrainMercPos;
+
+vec2 terrain_globe_to_mercator(vec3 globePosition) {
+  float D = length(globePosition);
+  float sinLat = clamp(globePosition.z / D, -0.999998, 0.999998);
+  float x = atan(globePosition.x, -globePosition.y);
+  float y = atanh(sinLat);
+  return (vec2(x, y) + PI) * WORLD_SCALE;
+}
+`,
+  fs: `${uniformBlock}in vec3 commonPos;\nin vec2 terrainMercPos;`,
   inject: {
     'vs:#main-start': /* glsl */ `
 if (terrain.mode == TERRAIN_MODE_SKIP) {
@@ -80,8 +90,13 @@ if (terrain.mode == TERRAIN_MODE_SKIP) {
 `,
     'vs:DECKGL_FILTER_GL_POSITION': /* glsl */ `
 commonPos = geometry.position.xyz;
+if (project.projectionMode == PROJECTION_MODE_GLOBE) {
+  terrainMercPos = terrain_globe_to_mercator(commonPos);
+} else {
+  terrainMercPos = commonPos.xy;
+}
 if (terrain.mode == TERRAIN_MODE_WRITE_HEIGHT_MAP) {
-  vec2 texCoords = (commonPos.xy - terrain.bounds.xy) / terrain.bounds.zw;
+  vec2 texCoords = (terrainMercPos - terrain.bounds.xy) / terrain.bounds.zw;
   position = vec4(texCoords * 2.0 - 1.0, 0.0, 1.0);
   commonPos.z += project.commonOrigin.z;
 }
@@ -105,7 +120,7 @@ if (terrain.mode == TERRAIN_MODE_WRITE_HEIGHT_MAP) {
     `,
     'fs:DECKGL_FILTER_COLOR': /* glsl */ `
 if ((terrain.mode == TERRAIN_MODE_USE_COVER) || (terrain.mode == TERRAIN_MODE_USE_COVER_ONLY)) {
-  vec2 texCoords = (commonPos.xy - terrain.bounds.xy) / terrain.bounds.zw;
+  vec2 texCoords = (terrainMercPos - terrain.bounds.xy) / terrain.bounds.zw;
   vec4 pixel = texture(terrain_map, texCoords);
   if (terrain.mode == TERRAIN_MODE_USE_COVER_ONLY) {
     color = pixel;
@@ -169,7 +184,7 @@ if ((terrain.mode == TERRAIN_MODE_USE_COVER) || (terrain.mode == TERRAIN_MODE_US
       return {
         mode,
         terrain_map: sampler,
-        // Convert bounds to the common space, as [minX, minY, width, height]
+        // Convert bounds to common space, as [minX, minY, width, height]
         bounds: bounds
           ? [
               bounds[0] - commonOrigin[0],

modules/extensions/src/terrain/terrain-cover.ts

@@ -7,7 +7,14 @@ import {Framebuffer} from '@luma.gl/core';
 import type {Layer, Viewport} from '@deck.gl/core';
 
 import {createRenderTarget} from './utils';
-import {joinLayerBounds, makeViewport, getRenderBounds, Bounds} from '../utils/projection-utils';
+import {
+  getMercatorReferenceViewport,
+  joinLayerBounds,
+  lngLatToMercatorCommon,
+  makeViewport,
+  getRenderBounds,
+  Bounds
+} from '../utils/projection-utils';
 
 type TileHeader = {
   boundingBox: [min: number[], max: number[]];
@@ -113,13 +120,14 @@ export class TerrainCover {
     const targetLayer = this.targetLayer;
     let shouldRedraw = false;
 
+    // Bounds in absolute Mercator common space (matches terrain cover FBO viewport)
     if (this.tile && 'boundingBox' in this.tile) {
       if (!this.targetBounds) {
         shouldRedraw = true;
         this.targetBounds = this.tile.boundingBox;
 
-        const bottomLeftCommon = viewport.projectPosition(this.targetBounds[0]);
-        const topRightCommon = viewport.projectPosition(this.targetBounds[1]);
+        const bottomLeftCommon = lngLatToMercatorCommon(this.targetBounds[0]);
+        const topRightCommon = lngLatToMercatorCommon(this.targetBounds[1]);
         this.targetBoundsCommon = [
           bottomLeftCommon[0],
           bottomLeftCommon[1],
@@ -131,7 +139,10 @@ export class TerrainCover {
       // console.log('bounds changed', this.bounds, '>>', newBounds);
       shouldRedraw = true;
       this.targetBounds = targetLayer.getBounds();
-      this.targetBoundsCommon = joinLayerBounds([targetLayer], viewport);
+      this.targetBoundsCommon = joinLayerBounds(
+        [targetLayer],
+        getMercatorReferenceViewport(viewport)
+      );
     }
 
     if (!this.targetBoundsCommon) {
@@ -146,7 +157,11 @@ export class TerrainCover {
     } else {
       const oldZoom = this.renderViewport?.zoom;
       shouldRedraw = shouldRedraw || newZoom !== oldZoom;
-      const newBounds = getRenderBounds(this.targetBoundsCommon, viewport);
+      // On GlobeView, viewport bounds are sphere cartesian — skip intersection
+      const isGlobe = Boolean(viewport.resolution && viewport.resolution > 0);
+      const newBounds = isGlobe
+        ? this.targetBoundsCommon
+        : getRenderBounds(this.targetBoundsCommon, viewport);
       const oldBounds = this.bounds;
       shouldRedraw = shouldRedraw || !oldBounds || newBounds.some((x, i) => x !== oldBounds[i]);
       this.bounds = newBounds;

modules/extensions/src/utils/projection-utils.ts

@@ -8,6 +8,26 @@ import type {Layer, Viewport} from '@deck.gl/core';
 /** Bounds in CARTESIAN coordinates */
 export type Bounds = [minX: number, minY: number, maxX: number, maxY: number];
 
+/** Fixed Mercator viewport for projection-independent coordinate conversion */
+const MERCATOR_REFERENCE_VIEWPORT = new WebMercatorViewport({
+  width: 1,
+  height: 1,
+  longitude: 0,
+  latitude: 0,
+  zoom: 0
+});
+
+/** Project lng/lat to absolute Mercator common space. */
+export function lngLatToMercatorCommon(lngLat: number[]): [number, number] {
+  const [x, y] = MERCATOR_REFERENCE_VIEWPORT.projectPosition(lngLat);
+  return [x, y];
+}
+
+/** Returns a Mercator viewport for bounds computation, bypassing GlobeView. */
+export function getMercatorReferenceViewport(viewport: Viewport): Viewport {
+  return viewport.isGeospatial ? MERCATOR_REFERENCE_VIEWPORT : viewport;
+}
+
 /*
  * Compute the union of bounds from multiple layers
  * Returns bounds in CARTESIAN coordinates
@@ -63,11 +83,14 @@ export function makeViewport(opts: {
     return null;
   }
 
-  const centerWorld = viewport.unprojectPosition([
-    (bounds[0] + bounds[2]) / 2,
-    (bounds[1] + bounds[3]) / 2,
-    0
-  ]);
+  // Unproject through Mercator reference (GlobeView would give sphere coords)
+  const centerWorld = isGeospatial
+    ? MERCATOR_REFERENCE_VIEWPORT.unprojectPosition([
+        (bounds[0] + bounds[2]) / 2,
+        (bounds[1] + bounds[3]) / 2,
+        0
+      ])
+    : viewport.unprojectPosition([(bounds[0] + bounds[2]) / 2, (bounds[1] + bounds[3]) / 2, 0]);
 
   let {width, height, zoom} = opts;
   if (zoom === undefined) {

modules/geo-layers/src/terrain-layer/terrain-layer.ts

@@ -237,12 +237,24 @@ export default class TerrainLayer<ExtraPropsT extends {} = {}> extends Composite
 
     const [mesh, texture] = data;
 
+    const {viewport} = this.context;
+    const isGlobe = Boolean(viewport.resolution && viewport.resolution > 0);
+    const bounds = (mesh as {header?: {boundingBox?: [number[], number[]]}}).header?.boundingBox;
+    const hasLngLatBounds = Boolean(
+      bounds &&
+        Math.abs(bounds[0][0]) <= 180 &&
+        Math.abs(bounds[1][0]) <= 180 &&
+        Math.abs(bounds[0][1]) <= 90 &&
+        Math.abs(bounds[1][1]) <= 90
+    );
+
     return new SubLayerClass(props, {
       data: DUMMY_DATA,
       mesh,
       texture,
       _instanced: false,
-      coordinateSystem: COORDINATE_SYSTEM.CARTESIAN,
+      coordinateSystem:
+        isGlobe && hasLngLatBounds ? COORDINATE_SYSTEM.LNGLAT : COORDINATE_SYSTEM.CARTESIAN,
       getPosition: d => [0, 0, 0],
       getColor: color,
       wireframe,
@@ -299,6 +311,8 @@ export default class TerrainLayer<ExtraPropsT extends {} = {}> extends Composite
     } = this.props;
 
     if (this.state.isTiled) {
+      const projectionMode = this.context.viewport.projectionMode;
+
       return new TileLayer<MeshAndTexture>(
         this.getSubLayerProps({
           id: 'tiles'
@@ -311,7 +325,8 @@ export default class TerrainLayer<ExtraPropsT extends {} = {}> extends Composite
               elevationData: urlTemplateToUpdateTrigger(elevationData),
               texture: urlTemplateToUpdateTrigger(texture),
               meshMaxError,
-              elevationDecoder
+              elevationDecoder,
+              projectionMode
             }
           },
           onViewportLoad: this.onViewportLoad.bind(this),