fix(core): add shader-based globe occlusion for IconLayer, TextLayer, and ArcLayer

Fixes #9777 and #9592.

The previous approach of setting cullMode: 'back' globally for globe projections
had two issues:
1. Billboard geometry (IconLayer, TextLayer) doesn't have proper back faces,
   causing icons and text to be incorrectly culled and disappear
2. The coordinate system handedness could cause culling to work in unexpected ways

This change implements shader-based globe occlusion that works for all geometry types:
- Added project_globe_get_occlusion() and project_globe_is_occluded() functions to
  the projection shader module (both GLSL and WGSL)
- IconLayer, TextLayer (via MultiIconLayer), and ArcLayer now automatically hide
  geometry that is on the back side of the globe
- Removed the global cullMode: 'back' parameter from getDefaultParameters() in
  deck-utils.ts
- Updated examples to remove manual cullMode: 'none' workarounds

The solution is transparent to users - no API changes or special configuration needed.

https://claude.ai/code/session_01P6canyQPTd6nckN66pauLK

Author: claude

examples/basemap-browser/src/config/layers.ts

@@ -39,9 +39,6 @@ export function buildLayers(options: LayerBuildOptions): Layer[] {
 
   const interleavedProps = getInterleavedProps(basemap, interleaved);
 
-  // Arc layer needs cullMode: 'none' for globe projection
-  const arcParameters = globe ? {cullMode: 'none' as const} : undefined;
-
   // Sample city data for IconLayer and TextLayer
   const cities = [
     {name: 'London', coordinates: [-0.1276, 51.5074]},
@@ -74,7 +71,6 @@ export function buildLayers(options: LayerBuildOptions): Layer[] {
       getSourceColor: [0, 128, 200],
       getTargetColor: [200, 0, 80],
       getWidth: 1,
-      parameters: arcParameters,
       ...interleavedProps
     }),
     new IconLayer({
@@ -150,9 +146,7 @@ export function buildLayers(options: LayerBuildOptions): Layer[] {
       getAlignmentBaseline: 'center',
       background: true,
       getBackgroundColor: [0, 0, 0, 200],
-      backgroundPadding: [6, 3],
-      // Disable culling for globe projection
-      parameters: {cullMode: 'none'}
+      backgroundPadding: [6, 3]
     })
   ];
 }

examples/get-started/pure-js/maplibre-globe/app.js

@@ -41,9 +41,6 @@ const deckOverlay = new DeckOverlay({
     new ArcLayer({
       id: 'arcs',
       data: AIR_PORTS,
-      parameters: {
-        cullMode: 'none'
-      },
       dataTransform: d => d.features.filter(f => f.properties.scalerank < 4),
       // Styles
       getSourcePosition: f => [-0.4531566, 51.4709959], // London

examples/website/maplibre/app.tsx

@@ -92,7 +92,6 @@ export default function App({
           timeRange,
           getSourceColor: [63, 81, 181],
           getTargetColor: [63, 181, 173],
-          parameters: {cullMode: 'none'},
           ...(interleaveLabels ? {beforeId: 'watername_ocean'} : {})
         })
     );

modules/core/src/shaderlib/project/project.glsl.ts

@@ -277,4 +277,29 @@ float project_pixel_size(float pixels) {
 vec2 project_pixel_size(vec2 pixels) {
   return pixels / project.scale;
 }
+
+//
+// Globe occlusion - returns a value indicating whether a position is occluded by the globe.
+// Returns 0.0 if the position is visible, 1.0 if fully occluded.
+// Can be used to discard fragments or fade out geometry on the back of the globe.
+//
+float project_globe_get_occlusion(vec3 commonPosition) {
+  if (project.projectionMode == PROJECTION_MODE_GLOBE) {
+    // In globe projection, positions are on a sphere centered at origin.
+    // A point is visible if it faces the camera.
+    // The surface normal at any point is the normalized position vector.
+    // The point is visible if dot(normal, viewDirection) > 0
+    vec3 normal = normalize(commonPosition);
+    vec3 viewDir = normalize(project.cameraPosition - commonPosition);
+    float visibility = dot(normal, viewDir);
+    // Return 0.0 if visible (visibility > 0), 1.0 if occluded (visibility <= 0)
+    return visibility > 0.0 ? 0.0 : 1.0;
+  }
+  return 0.0;
+}
+
+// Helper function to check if position is on the back of the globe
+bool project_globe_is_occluded(vec3 commonPosition) {
+  return project_globe_get_occlusion(commonPosition) > 0.5;
+}
 `;

modules/core/src/shaderlib/project/project.wgsl.ts

@@ -302,4 +302,29 @@ fn project_pixel_size_float(pixels: f32) -> f32 {
 fn project_pixel_size_vec2(pixels: vec2<f32>) -> vec2<f32> {
   return pixels / project.scale;
 }
+
+//
+// Globe occlusion - returns a value indicating whether a position is occluded by the globe.
+// Returns 0.0 if the position is visible, 1.0 if fully occluded.
+// Can be used to discard fragments or fade out geometry on the back of the globe.
+//
+fn project_globe_get_occlusion(commonPosition: vec3<f32>) -> f32 {
+  if (project.projectionMode == PROJECTION_MODE_GLOBE) {
+    // In globe projection, positions are on a sphere centered at origin.
+    // A point is visible if it faces the camera.
+    // The surface normal at any point is the normalized position vector.
+    // The point is visible if dot(normal, viewDirection) > 0
+    let normal = normalize(commonPosition);
+    let viewDir = normalize(project.cameraPosition - commonPosition);
+    let visibility = dot(normal, viewDir);
+    // Return 0.0 if visible (visibility > 0), 1.0 if occluded (visibility <= 0)
+    return select(1.0, 0.0, visibility > 0.0);
+  }
+  return 0.0;
+}
+
+// Helper function to check if position is on the back of the globe
+fn project_globe_is_occluded(commonPosition: vec3<f32>) -> bool {
+  return project_globe_get_occlusion(commonPosition) > 0.5;
+}
 `;

modules/layers/src/arc-layer/arc-layer-vertex.glsl.ts

@@ -232,6 +232,12 @@ void main(void) {
   DECKGL_FILTER_GL_POSITION(curr, geometry);
   gl_Position = curr + vec4(project_pixel_size_to_clipspace(offset.xy), 0.0, 0.0);
 
+  // Hide arc segments that are occluded by the globe (on the back side)
+  if (project_globe_is_occluded(geometry.position.xyz)) {
+    // Move to clip space position that will be clipped
+    gl_Position = vec4(0.0, 0.0, 2.0, 1.0);
+  }
+
   vec4 color = mix(instanceSourceColors, instanceTargetColors, segmentRatio);
   vColor = vec4(color.rgb, color.a * layer.opacity);
   DECKGL_FILTER_COLOR(vColor, geometry);

modules/layers/src/icon-layer/icon-layer-vertex.glsl.ts

@@ -66,10 +66,16 @@ void main(void) {
   } else {
     vec3 offset_common = vec3(project_pixel_size(pixelOffset), 0.0);
     DECKGL_FILTER_SIZE(offset_common, geometry);
-    gl_Position = project_position_to_clipspace(instancePositions, instancePositions64Low, offset_common, geometry.position); 
+    gl_Position = project_position_to_clipspace(instancePositions, instancePositions64Low, offset_common, geometry.position);
     DECKGL_FILTER_GL_POSITION(gl_Position, geometry);
   }
 
+  // Hide icons/text that are occluded by the globe (on the back side)
+  if (project_globe_is_occluded(geometry.position.xyz)) {
+    // Move to clip space position that will be clipped
+    gl_Position = vec4(0.0, 0.0, 2.0, 1.0);
+  }
+
   vTextureCoords = mix(
     instanceIconFrames.xy,
     instanceIconFrames.xy + iconSize,

modules/layers/src/icon-layer/icon-layer.wgsl.ts

@@ -78,6 +78,9 @@ fn vertexMain(inp: Attributes) -> Varyings {
   pixelOffset = pixelOffset + inp.instancePixelOffset;
   pixelOffset.y = pixelOffset.y * -1.0;
 
+  // Calculate common position for globe occlusion check
+  let commonPosition = project_position_vec3_f64(inp.instancePositions, inp.instancePositions64Low);
+
   if (icon.billboard != 0) {
     var pos = project_position_to_clipspace(inp.instancePositions, inp.instancePositions64Low, vec3<f32>(0.0)); // TODO, &geometry.position);
     // DECKGL_FILTER_GL_POSITION(pos, geometry);
@@ -95,6 +98,12 @@ fn vertexMain(inp: Attributes) -> Varyings {
     outp.position = pos;
   }
 
+  // Hide icons/text that are occluded by the globe (on the back side)
+  if (project_globe_is_occluded(commonPosition)) {
+    // Move to clip space position that will be clipped
+    outp.position = vec4<f32>(0.0, 0.0, 2.0, 1.0);
+  }
+
   let uvMix = (inp.positions.xy + vec2<f32>(1.0, 1.0)) * 0.5;
   outp.vTextureCoords = mix(inp.instanceIconFrames.xy, inp.instanceIconFrames.xy + iconSize, uvMix) / icon.iconsTextureDim;
 

modules/mapbox/src/deck-utils.ts

@@ -111,9 +111,10 @@ export function getDefaultParameters(map: Map, interleaved: boolean): Parameters
         blendAlphaOperation: 'add'
       }
     : {};
-  if (getProjection(map) === 'globe') {
-    result.cullMode = 'back';
-  }
+  // Note: Globe occlusion (hiding geometry on the back of the globe) is handled
+  // in the shader via project_globe_get_occlusion() rather than GPU back-face culling.
+  // Back-face culling doesn't work correctly for billboard geometry (IconLayer, TextLayer)
+  // which always faces the camera.
   return result;
 }
 

test/apps/projection/app.tsx

@@ -144,7 +144,6 @@ function App() {
     <>
       <DeckGL
         controller
-        parameters={{cullMode: 'back'}}
         views={opts.view}
         initialViewState={opts.viewState}
         layers={layers}