@tangram.gl/basemap-layers 0.0.0-stage → 0.0.0

package/src/geojson-source.ts

@@ -0,0 +1,318 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {GeoJSONVT, GeoJSONVTOptions} from '@maplibre/geojson-vt';
+import {createTileIndex, cutTile, decodeTile, GEOJSON_TILE_EXTENT} from './geojson-tiler';
+import type {GeoJsonWorkerRequest, GeoJsonWorkerResponse} from './geojson-worker';
+import type {BasemapSource} from './style-resolver';
+
+/** The size of a GeoJSON source's tiles in pixels, fixed in MapLibre GL JS. */
+const GEOJSON_TILE_SIZE = 512;
+
+/** The default `maxzoom` of a GeoJSON source, as in the style specification. */
+const GEOJSON_DEFAULT_MAXZOOM = 18;
+
+/** The highest zoom geojson-vt tiles at. */
+const GEOJSON_VT_MAX_ZOOM = 24;
+
+/** Tile units per pixel of a GeoJSON tile. */
+const TILE_UNITS_PER_PIXEL = GEOJSON_TILE_EXTENT / GEOJSON_TILE_SIZE;
+
+/** Whether a source is a GeoJSON source whose data has been resolved to a GeoJSON object. */
+export function isGeoJsonSource(source: BasemapSource | undefined): boolean {
+  return (
+    source?.type === 'geojson' &&
+    Boolean(source.data) &&
+    typeof source.data === 'object' &&
+    !Array.isArray(source.data)
+  );
+}
+
+/** The deepest zoom a GeoJSON source is tiled at; deeper views overzoom its tiles. */
+export function getGeoJsonMaxZoom(source: BasemapSource): number {
+  const maxzoom = getNumber(source.maxzoom, GEOJSON_DEFAULT_MAXZOOM);
+  return Math.max(0, Math.min(Math.round(maxzoom), GEOJSON_VT_MAX_ZOOM));
+}
+
+/** A finite number, or `fallback`. */
+function getNumber(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+/**
+ * geojson-vt options for a GeoJSON source, as MapLibre GL JS 6 sets them: `buffer` and
+ * `tolerance` are given in pixels of a 512 pixel tile, and the source's `maxzoom` is the deepest
+ * zoom tiled. Clustering is supported without `clusterProperties`.
+ */
+export function getGeoJsonVtOptions(source: BasemapSource): GeoJSONVTOptions {
+  const maxZoom = getGeoJsonMaxZoom(source);
+  const generateId = Boolean(source.generateId);
+  const promoteId = typeof source.promoteId === 'string' ? source.promoteId : undefined;
+  const options: GeoJSONVTOptions = {
+    maxZoom,
+    extent: GEOJSON_TILE_EXTENT,
+    buffer: getNumber(source.buffer, 128) * TILE_UNITS_PER_PIXEL,
+    tolerance: getNumber(source.tolerance, 0.375) * TILE_UNITS_PER_PIXEL,
+    generateId,
+    // geojson-vt rejects `promoteId` together with `generateId`, which then wins, as in MapLibre.
+    promoteId: generateId ? undefined : promoteId
+  };
+  if (source.cluster) {
+    const clusterMaxZoom = getNumber(source.clusterMaxZoom, maxZoom - 1);
+    options.cluster = true;
+    options.clusterOptions = {
+      // The cluster index holds a level per zoom: bounded by the source's tiled zooms, which
+      // MapLibre GL JS only warns about, so that a style value cannot make it build millions.
+      maxZoom: Math.max(0, Math.min(Math.round(clusterMaxZoom), maxZoom)),
+      minPoints: Math.max(2, getNumber(source.clusterMinPoints, 2)),
+      extent: GEOJSON_TILE_EXTENT,
+      radius: getNumber(source.clusterRadius, 50) * TILE_UNITS_PER_PIXEL,
+      log: false,
+      generateId
+    };
+  }
+  return options;
+}
+
+/**
+ * How many coordinate positions of a FeatureCollection go to the worker in one message. Posting
+ * copies the features on the main thread, so a large source goes in batches, with the main thread
+ * free to draw between them.
+ */
+const POSITIONS_PER_BATCH = 100_000;
+
+/** Whether GeoJSON sources are tiled in a worker where workers are available. For tests. */
+let workerEnabled = true;
+
+/**
+ * Whether tiles requested from now on are cut in a worker, where one can start (`true`, the
+ * default), or on the main thread. For tests.
+ */
+export function setGeoJsonWorkerEnabled(enabled: boolean): void {
+  workerEnabled = enabled;
+}
+
+/** A tile request sent to the worker, and how to cut the tile here if the worker fails. */
+type PendingTile = {
+  source: BasemapSource;
+  index: {x: number; y: number; z: number};
+  resolve: (features: Record<string, unknown>[]) => void;
+  reject: (error: unknown) => void;
+};
+
+/**
+ * The worker that indexes GeoJSON sources and cuts their tiles, shared by all of them. If it
+ * cannot start (a bundle that does not emit it, a content security policy without `worker-src`)
+ * or fails, its requests, and every later one, are cut on the main thread instead.
+ */
+class GeoJsonWorker {
+  failed = false;
+  private worker: Worker;
+  private nextId = 0;
+  private sources = new WeakMap<BasemapSource, {id: number; sent: Promise<void>}>();
+  private requests = new Map<number, PendingTile>();
+  private registry = new FinalizationRegistry<number>(id =>
+    this.post({type: 'remove', source: id})
+  );
+
+  constructor(worker: Worker) {
+    this.worker = worker;
+    worker.onmessage = ({data}: MessageEvent<GeoJsonWorkerResponse>) => {
+      const request = this.requests.get(data.request);
+      this.requests.delete(data.request);
+      if (!request) {
+        return;
+      }
+      if ('error' in data) {
+        request.reject(new Error(data.error));
+      } else {
+        request.resolve(decodeTile(data.tile));
+      }
+    };
+    worker.onerror = event => {
+      event.preventDefault?.();
+      this.fail();
+    };
+    worker.onmessageerror = () => this.fail();
+  }
+
+  /** Cuts a tile of `source` in the worker, sending the source's data first if it is new. */
+  async getTileFeatures(
+    source: BasemapSource,
+    index: {x: number; y: number; z: number}
+  ): Promise<Record<string, unknown>[]> {
+    let entry = this.sources.get(source);
+    if (!entry) {
+      const id = this.nextId++;
+      entry = {id, sent: this.sendSource(id, source)};
+      this.sources.set(source, entry);
+      this.registry.register(source, id);
+    }
+    await entry.sent;
+    if (this.failed) {
+      return getMainThreadTileFeatures(source, index);
+    }
+    const request = this.nextId++;
+    return new Promise((resolve, reject) => {
+      this.requests.set(request, {source, index, resolve, reject});
+      this.post({type: 'tile', source: entry.id, request, ...index});
+    });
+  }
+
+  /**
+   * Sends a source's data and options. A FeatureCollection's features go in batches, yielding to
+   * the main thread between them; the worker builds the index when the last one arrives.
+   */
+  private async sendSource(id: number, source: BasemapSource): Promise<void> {
+    const options = getGeoJsonVtOptions(source);
+    const data = source.data as {type?: string; features?: unknown};
+    if (data.type !== 'FeatureCollection' || !Array.isArray(data.features)) {
+      this.post({type: 'index', source: id, data, options});
+      return;
+    }
+    let batch: unknown[] = [];
+    let positions = 0;
+    for (const feature of data.features) {
+      batch.push(feature);
+      positions += countPositions((feature as {geometry?: unknown})?.geometry);
+      if (positions >= POSITIONS_PER_BATCH) {
+        this.post({type: 'features', source: id, features: batch});
+        batch = [];
+        positions = 0;
+        await yieldToMainThread();
+        if (this.failed) {
+          return;
+        }
+      }
+    }
+    this.post({type: 'features', source: id, features: batch});
+    this.post({type: 'index', source: id, options});
+  }
+
+  private post(message: GeoJsonWorkerRequest): void {
+    if (this.failed) {
+      return;
+    }
+    try {
+      this.worker.postMessage(message);
+    } catch {
+      // Data that cannot be cloned (a function in a property, say) is tiled on the main thread.
+      this.fail();
+    }
+  }
+
+  /** Stops using the worker, and cuts the tiles it still owes on the main thread. */
+  private fail(): void {
+    if (this.failed) {
+      return;
+    }
+    this.failed = true;
+    this.worker.terminate();
+    const requests = [...this.requests.values()];
+    this.requests.clear();
+    for (const {source, index, resolve, reject} of requests) {
+      try {
+        resolve(getMainThreadTileFeatures(source, index));
+      } catch (error) {
+        reject(error);
+      }
+    }
+  }
+}
+
+/** The number of positions in a GeoJSON geometry's coordinates, to size the batches sent. */
+function countPositions(geometry: unknown): number {
+  const {type, coordinates, geometries} = (geometry || {}) as {
+    type?: string;
+    coordinates?: unknown;
+    geometries?: unknown[];
+  };
+  if (type === 'GeometryCollection') {
+    return (geometries || []).reduce<number>((sum, child) => sum + countPositions(child), 0);
+  }
+  const count = (value: unknown): number => {
+    if (!Array.isArray(value)) {
+      return 0;
+    }
+    if (typeof value[0] === 'number') {
+      return 1;
+    }
+    let sum = 0;
+    for (const child of value) {
+      sum += count(child);
+    }
+    return sum;
+  };
+  return count(coordinates);
+}
+
+/** Resolves after the browser has had a turn to run other tasks, without timer throttling. */
+function yieldToMainThread(): Promise<void> {
+  return new Promise(resolve => {
+    const channel = new MessageChannel();
+    channel.port1.onmessage = () => {
+      channel.port1.close();
+      resolve();
+    };
+    channel.port2.postMessage(null);
+  });
+}
+
+/** The shared worker, once started; `null` where none can start. */
+let geoJsonWorker: GeoJsonWorker | null | undefined;
+
+/**
+ * The shared worker, or `null` where GeoJSON is tiled on the main thread: where the platform has
+ * no `Worker` (Node), where the worker could not be created or has failed, or when tests turned
+ * workers off.
+ */
+function getGeoJsonWorker(): GeoJsonWorker | null {
+  if (!workerEnabled || typeof Worker === 'undefined') {
+    return null;
+  }
+  if (geoJsonWorker === undefined) {
+    try {
+      // Bundlers (Vite, webpack 5, esbuild with a plugin, Parcel) emit the worker and its imports
+      // from this expression, which must stay literal. The CommonJS build has no `import.meta.url`
+      // and throws here.
+      geoJsonWorker = new GeoJsonWorker(
+        new Worker(new URL('./geojson-worker.js', import.meta.url), {type: 'module'})
+      );
+    } catch {
+      geoJsonWorker = null;
+    }
+  }
+  return geoJsonWorker?.failed ? null : geoJsonWorker;
+}
+
+/** Each source's tile index on the main thread, built when its first tile is requested there. */
+const tileIndexes = new WeakMap<BasemapSource, GeoJSONVT>();
+
+/** Cuts a tile of a GeoJSON source on the main thread, building its index first if needed. */
+function getMainThreadTileFeatures(
+  source: BasemapSource,
+  index: {x: number; y: number; z: number}
+): Record<string, unknown>[] {
+  let tileIndex = tileIndexes.get(source);
+  if (!tileIndex) {
+    tileIndex = createTileIndex(source.data, getGeoJsonVtOptions(source));
+    tileIndexes.set(source, tileIndex);
+  }
+  return decodeTile(cutTile(tileIndex, index.z, index.x, index.y));
+}
+
+/**
+ * The features of one tile of a GeoJSON source, cut by geojson-vt as MapLibre GL JS cuts them, in
+ * the normalized tile-local coordinates of decoded vector tiles: the existing vector tile path
+ * then draws them as it draws vector tiles. The source is indexed, and its tiles cut, in a worker
+ * where one can start, and on the main thread otherwise. Rejects if the source's data is not
+ * valid GeoJSON.
+ */
+export async function getGeoJsonTileFeatures(
+  source: BasemapSource,
+  index: {x: number; y: number; z: number}
+): Promise<Record<string, unknown>[]> {
+  const worker = getGeoJsonWorker();
+  return worker ? worker.getTileFeatures(source, index) : getMainThreadTileFeatures(source, index);
+}

package/src/geojson-tiler.ts

@@ -0,0 +1,185 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/**
+ * Cutting GeoJSON into vector tiles with `@maplibre/geojson-vt`, and the transferable form a
+ * tile's features take between the worker that cuts them and the main thread that draws them.
+ * This module runs in both: it holds no state and imports nothing from the rest of the module.
+ */
+
+import {GeoJSONVT, type GeoJSONVTFeature, type GeoJSONVTOptions} from '@maplibre/geojson-vt';
+
+/** The extent of MapLibre GL JS's tiles, in tile units: GeoJSON is tiled at this precision. */
+export const GEOJSON_TILE_EXTENT = 8192;
+
+/** The geometry types of a tile's features, by how deep their coordinates nest. */
+const GEOMETRY_DEPTHS = {
+  Point: 0,
+  MultiPoint: 1,
+  LineString: 1,
+  MultiLineString: 2,
+  Polygon: 2,
+  MultiPolygon: 3
+} as const;
+
+type GeometryType = keyof typeof GEOMETRY_DEPTHS;
+
+/** One feature of an encoded tile: its coordinates are in the tile's typed arrays. */
+type EncodedFeature = {
+  type: GeometryType;
+  properties: Record<string, unknown>;
+  id?: unknown;
+};
+
+/**
+ * A tile's features in a form whose bulk can be transferred between threads: each feature's
+ * coordinates, in tile units, follow one another in `positions` (x, y pairs), and `lengths` holds,
+ * depth first, the length of each array above a position (the polygons of a multipolygon, the
+ * rings of a polygon, the points of a ring). Tile units are integers: geojson-vt rounds them.
+ */
+export type EncodedTile = {
+  features: EncodedFeature[];
+  positions: Int32Array;
+  lengths: Uint32Array;
+};
+
+/** Builds the tile index of a GeoJSON source's data. Throws if the data is not valid GeoJSON. */
+export function createTileIndex(data: unknown, options: GeoJSONVTOptions): GeoJSONVT {
+  return new GeoJSONVT(data as GeoJSON.GeoJSON, options);
+}
+
+/** A ring's signed area in tile units, as `@mapbox/vector-tile` computes it. */
+function getSignedArea(ring: [number, number][]): number {
+  let sum = 0;
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+    sum += (ring[j][0] - ring[i][0]) * (ring[i][1] + ring[j][1]);
+  }
+  return sum;
+}
+
+/**
+ * Groups a polygon feature's rings into polygons, as MapLibre GL JS does for vector tiles: a ring
+ * wound as the first one starts a polygon, and a ring wound the other way is a hole of the
+ * polygon before it. Rings without area are dropped.
+ */
+function classifyRings(rings: [number, number][][]): [number, number][][][] {
+  const polygons: [number, number][][][] = [];
+  let polygon: [number, number][][] | undefined;
+  let clockwise: boolean | undefined;
+  for (const ring of rings) {
+    const area = getSignedArea(ring);
+    if (area === 0) {
+      continue;
+    }
+    clockwise ??= area < 0;
+    if (clockwise === area < 0) {
+      polygon = [ring];
+      polygons.push(polygon);
+    } else {
+      polygon?.push(ring);
+    }
+  }
+  return polygons;
+}
+
+/** A geojson-vt tile feature's GeoJSON geometry, in tile units; `null` for a polygon without area. */
+function getGeometry(feature: GeoJSONVTFeature): {type: GeometryType; coordinates: unknown} | null {
+  if (feature.type === 1) {
+    const points = feature.geometry;
+    return points.length === 1
+      ? {type: 'Point', coordinates: points[0]}
+      : {type: 'MultiPoint', coordinates: points};
+  }
+  if (feature.type === 2) {
+    const lines = feature.geometry;
+    return lines.length === 1
+      ? {type: 'LineString', coordinates: lines[0]}
+      : {type: 'MultiLineString', coordinates: lines};
+  }
+  const polygons = classifyRings(feature.geometry);
+  if (polygons.length === 0) {
+    return null;
+  }
+  return polygons.length === 1
+    ? {type: 'Polygon', coordinates: polygons[0]}
+    : {type: 'MultiPolygon', coordinates: polygons};
+}
+
+/**
+ * Cuts one tile from a tile index, as MapLibre GL JS cuts it, and encodes its features. Its typed
+ * arrays' buffers can be transferred.
+ */
+export function cutTile(index: GeoJSONVT, z: number, x: number, y: number): EncodedTile {
+  const features: EncodedFeature[] = [];
+  const positions: number[] = [];
+  const lengths: number[] = [];
+
+  const writeCoordinates = (coordinates: any, depth: number) => {
+    if (depth === 0) {
+      positions.push(coordinates[0], coordinates[1]);
+      return;
+    }
+    lengths.push(coordinates.length);
+    for (const child of coordinates) {
+      writeCoordinates(child, depth - 1);
+    }
+  };
+
+  for (const feature of index.getTile(z, x, y)?.features || []) {
+    const geometry = getGeometry(feature);
+    if (!geometry) {
+      continue;
+    }
+    writeCoordinates(geometry.coordinates, GEOMETRY_DEPTHS[geometry.type]);
+    const encoded: EncodedFeature = {type: geometry.type, properties: feature.tags || {}};
+    if (feature.id !== undefined) {
+      encoded.id = feature.id;
+    }
+    features.push(encoded);
+  }
+  return {features, positions: Int32Array.from(positions), lengths: Uint32Array.from(lengths)};
+}
+
+/**
+ * The GeoJSON features of an encoded tile, in the normalized tile-local coordinates of decoded
+ * vector tiles: the vector tile path then draws them as it draws vector tiles.
+ */
+export function decodeTile(tile: EncodedTile): Record<string, unknown>[] {
+  const {positions, lengths} = tile;
+  let position = 0;
+  let length = 0;
+
+  const readCoordinates = (depth: number): unknown => {
+    if (depth === 0) {
+      const point = [
+        positions[position] / GEOJSON_TILE_EXTENT,
+        positions[position + 1] / GEOJSON_TILE_EXTENT
+      ];
+      position += 2;
+      return point;
+    }
+    const count = lengths[length++];
+    const children = new Array(count);
+    for (let i = 0; i < count; i++) {
+      children[i] = readCoordinates(depth - 1);
+    }
+    return children;
+  };
+
+  return tile.features.map(({type, properties, id}) => {
+    const feature: Record<string, unknown> = {
+      type: 'Feature',
+      geometry: {type, coordinates: readCoordinates(GEOMETRY_DEPTHS[type])},
+      properties
+    };
+    if (id !== undefined) {
+      feature.id = id;
+    }
+    return feature;
+  });
+}

package/src/geojson-worker.ts

@@ -0,0 +1,98 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/**
+ * The worker that indexes GeoJSON sources and cuts their tiles, as MapLibre GL JS's
+ * `GeoJSONWorkerSource` does, so that a large source does not hold the main thread. See
+ * `geojson-source.ts` for the other end of each message.
+ */
+
+import type {GeoJSONVT, GeoJSONVTOptions} from '@maplibre/geojson-vt';
+import {createTileIndex, cutTile} from './geojson-tiler';
+
+/** A message from the main thread. Messages of one source arrive in the order they are sent. */
+export type GeoJsonWorkerRequest =
+  /** Features of a FeatureCollection, sent in batches before its `index` message. */
+  | {type: 'features'; source: number; features: unknown[]}
+  /** Builds a source's index from `data`, or from the features sent before it. */
+  | {type: 'index'; source: number; data?: unknown; options: GeoJSONVTOptions}
+  | {type: 'tile'; source: number; request: number; z: number; x: number; y: number}
+  | {type: 'remove'; source: number};
+
+/** The answer to a `tile` request: the encoded tile, or why the source cannot be tiled. */
+export type GeoJsonWorkerResponse = {request: number} & (
+  | {tile: ReturnType<typeof cutTile>}
+  | {error: string}
+);
+
+/** The features of each source whose index is not built yet. */
+const pendingFeatures = new Map<number, unknown[]>();
+
+/** Each source's index, or the error building it threw. */
+const indexes = new Map<number, GeoJSONVT | Error>();
+
+const scope = globalThis as unknown as {
+  onmessage: ((event: MessageEvent<GeoJsonWorkerRequest>) => void) | null;
+  postMessage: (message: GeoJsonWorkerResponse, transfer: Transferable[]) => void;
+};
+
+scope.onmessage = ({data: message}) => {
+  switch (message.type) {
+    case 'features': {
+      const features = pendingFeatures.get(message.source);
+      if (features) {
+        for (const feature of message.features) {
+          features.push(feature);
+        }
+      } else {
+        pendingFeatures.set(message.source, message.features);
+      }
+      break;
+    }
+    case 'index': {
+      const data = message.data ?? {
+        type: 'FeatureCollection',
+        features: pendingFeatures.get(message.source) || []
+      };
+      pendingFeatures.delete(message.source);
+      try {
+        indexes.set(message.source, createTileIndex(data, message.options));
+      } catch (error) {
+        indexes.set(message.source, error instanceof Error ? error : new Error(String(error)));
+      }
+      break;
+    }
+    case 'tile': {
+      const index = indexes.get(message.source);
+      try {
+        if (!index) {
+          throw new Error('GeoJSON source has no index');
+        }
+        if (index instanceof Error) {
+          throw index;
+        }
+        const tile = cutTile(index, message.z, message.x, message.y);
+        scope.postMessage({request: message.request, tile}, [
+          tile.positions.buffer,
+          tile.lengths.buffer
+        ]);
+      } catch (error) {
+        scope.postMessage(
+          {request: message.request, error: error instanceof Error ? error.message : String(error)},
+          []
+        );
+      }
+      break;
+    }
+    case 'remove':
+      pendingFeatures.delete(message.source);
+      indexes.delete(message.source);
+      break;
+    default:
+  }
+};

package/src/globe-horizon-extension.ts

@@ -0,0 +1,64 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {LayerExtension, project} from '@deck.gl/core';
+import type {Layer} from '@deck.gl/core';
+
+/**
+ * Hides every vertex of an instance whose anchor (`geometry.worldPosition`) lies beyond the
+ * globe's horizon. Runs after the collision filter's `DECKGL_FILTER_GL_POSITION` injection
+ * (`order: 1`), so its sort depth cannot move a hidden quad back into clip space.
+ *
+ * In `GlobeView`'s common space the globe is centred at the origin with radius `GLOBE_RADIUS`. As
+ * in MapLibre GL JS, the test uses the point of the surface under the anchor, with unit normal
+ * `n`:
+ * - with a perspective camera at `C`, the point is visible when `dot(n, C) >= GLOBE_RADIUS`, the
+ *   camera's side of the plane through the points where lines from the camera touch the globe;
+ * - with an orthographic camera, whose rays are parallel, it is visible when the normal does not
+ *   point away from the viewer. The fourth row of an orthographic view-projection matrix is
+ *   `(0, 0, 0, 1)`, and its third row is the direction in which depth grows.
+ */
+const globeHorizonModule = {
+  name: 'globeHorizon',
+  dependencies: [project],
+  inject: {
+    'vs:DECKGL_FILTER_GL_POSITION': {
+      order: 1,
+      injection: /* glsl */ `
+  if (project.projectionMode == PROJECTION_MODE_GLOBE) {
+    vec3 globeHorizon_normal = normalize(project_position(geometry.worldPosition));
+    mat4 globeHorizon_m = project.viewProjectionMatrix;
+    vec3 globeHorizon_wRow = vec3(globeHorizon_m[0][3], globeHorizon_m[1][3], globeHorizon_m[2][3]);
+    bool globeHorizon_hidden = dot(globeHorizon_wRow, globeHorizon_wRow) == 0.0
+      ? dot(globeHorizon_normal, vec3(globeHorizon_m[0][2], globeHorizon_m[1][2], globeHorizon_m[2][2])) > 0.0
+      : dot(globeHorizon_normal, project.cameraPosition) < GLOBE_RADIUS;
+    if (globeHorizon_hidden) {
+      // Every vertex of the quad lands beyond the far plane, so it is clipped. In the collision
+      // pass this keeps a hidden label out of the collision map.
+      position = vec4(0.0, 0.0, 2.0, 1.0);
+    }
+  }
+`
+    }
+  }
+} as const;
+
+/**
+ * Hides labels and icons whose anchor is on the far side of the globe in a `GlobeView`, in the
+ * screen pass and in the collision filter's pass. In other views the shader does nothing. WebGL
+ * only: on WebGPU the extension adds no shader code.
+ *
+ * Added to a composite layer such as `TextLayer`, it reaches the character and background
+ * sublayers.
+ */
+export class GlobeHorizonExtension extends LayerExtension {
+  static extensionName = 'GlobeHorizonExtension';
+
+  getShaders(this: Layer) {
+    if (this.context.device.type === 'webgpu') {
+      return {};
+    }
+    return {modules: [globeHorizonModule]};
+  }
+}