maplibre-gl 6.0.0 → 6.2.0

package/src/render/subdivision.bench.ts

@@ -0,0 +1,39 @@
+import {bench} from 'vitest';
+import Point from '@mapbox/point-geometry';
+import {CanonicalTileID} from '../tile/tile_id.ts';
+import {EXTENT} from '../data/extent.ts';
+import {subdividePolygon} from './subdivision.ts';
+
+function generateRing(cx: number, cy: number, radius: number, vertexCount: number): Point[] {
+    const ring = [];
+
+    for (let i = 0; i < vertexCount; i++) {
+        const angle = i / vertexCount * 2.0 * Math.PI;
+        ring.push(new Point(
+            Math.round(cx + Math.cos(angle) * radius),
+            Math.round(cy + Math.sin(angle) * radius)
+        ));
+    }
+
+    return ring;
+}
+
+const vertexCountMultiplier = 11;
+const granularity = 64;
+const tileID = new CanonicalTileID(2, 1, 1);
+
+const polygon: Point[][] = [generateRing(EXTENT / 2, EXTENT / 2, EXTENT * 1.1 / 2, 81 * vertexCountMultiplier)];
+
+function generateHole(cx: number, cy: number, r: number, vertexCount: number) {
+    polygon.push(generateRing(cx * EXTENT, cy * EXTENT, r * EXTENT, vertexCount));
+}
+
+generateHole(0.25, 0.5, 0.15, 16 * vertexCountMultiplier);
+generateHole(0.75, 0.5, 0.15, 2 * vertexCountMultiplier);
+generateHole(0.5, 0.1, 0.05, 4 * vertexCountMultiplier);
+
+bench('subdividePolygon', () => {
+    for (let i = 0; i < 10; i++) {
+        subdividePolygon(polygon, tileID, granularity, true);
+    }
+});

package/src/render/subdivision.test.ts

@@ -224,7 +224,7 @@ describe('Fill subdivision', () => {
                 3, 0
             ]
         ]);
-        checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+        expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
     });
 
     test('Polygon is unchanged when granularity=1, but winding order is corrected.', () => {
@@ -259,7 +259,7 @@ describe('Fill subdivision', () => {
                 3, 0
             ]
         ]);
-        checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+        expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
     });
 
     test('Polygon inside cell is unchanged', () => {
@@ -294,7 +294,7 @@ describe('Fill subdivision', () => {
                 3, 0
             ]
         ]);
-        checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+        expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
     });
 
     test('Subdivide a polygon', () => {
@@ -349,7 +349,6 @@ describe('Fill subdivision', () => {
         //  7:
         //
         //  8:  2
-        console.log(result.indicesTriangles);
         expect(result.indicesTriangles).toEqual([
             3, 0, 6,
             7, 0, 3,
@@ -405,7 +404,7 @@ describe('Fill subdivision', () => {
                 6,   3
             ]
         ]);
-        checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+        expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
     });
 
     describe('Polygon outline line list is correct', () => {
@@ -420,7 +419,7 @@ describe('Fill subdivision', () => {
             expect(hasDuplicateVertices(result.verticesFlattened)).toBe(false);
             testMeshIntegrity(result.indicesTriangles);
             testPolygonOutlineMatches(result.indicesTriangles, result.indicesLineList);
-            checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+            expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
         });
 
         test('Small polygon', () => {
@@ -434,7 +433,7 @@ describe('Fill subdivision', () => {
             expect(hasDuplicateVertices(result.verticesFlattened)).toBe(false);
             testMeshIntegrity(result.indicesTriangles);
             testPolygonOutlineMatches(result.indicesTriangles, result.indicesLineList);
-            checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+            expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
         });
 
         test('Medium polygon', () => {
@@ -448,7 +447,7 @@ describe('Fill subdivision', () => {
             expect(hasDuplicateVertices(result.verticesFlattened)).toBe(false);
             testMeshIntegrity(result.indicesTriangles);
             testPolygonOutlineMatches(result.indicesTriangles, result.indicesLineList);
-            checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+            expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
         });
 
         test('Large polygon', () => {
@@ -462,7 +461,7 @@ describe('Fill subdivision', () => {
             expect(hasDuplicateVertices(result.verticesFlattened)).toBe(false);
             testMeshIntegrity(result.indicesTriangles);
             testPolygonOutlineMatches(result.indicesTriangles, result.indicesLineList);
-            checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+            expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
         });
 
         test('Large polygon with hole', () => {
@@ -481,7 +480,7 @@ describe('Fill subdivision', () => {
             expect(hasDuplicateVertices(result.verticesFlattened)).toBe(false);
             testMeshIntegrity(result.indicesTriangles);
             testPolygonOutlineMatches(result.indicesTriangles, result.indicesLineList);
-            checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+            expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
         });
 
         test('Large polygon with hole, granularity=0', () => {
@@ -500,7 +499,7 @@ describe('Fill subdivision', () => {
             expect(hasDuplicateVertices(result.verticesFlattened)).toBe(false);
             testMeshIntegrity(result.indicesTriangles);
             testPolygonOutlineMatches(result.indicesTriangles, result.indicesLineList);
-            checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+            expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
         });
 
         test('Large polygon with hole, finer granularity', () => {
@@ -518,7 +517,7 @@ describe('Fill subdivision', () => {
             ], canonicalDefault, EXTENT / 8);
 
             expect(hasDuplicateVertices(result.verticesFlattened)).toBe(false);
-            checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+            expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
 
             // This polygon subdivision results in at least one edge that is shared among more than 2 triangles.
             // This is not ideal, but it is also an edge case of a weird triangle getting subdivided by a very fine grid.
@@ -587,7 +586,7 @@ describe('Fill subdivision', () => {
                     5, 3
                 ]
             ]);
-            checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+            expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
         });
 
         test('Polygon with duplicate vertex with hole inside cell', () => {
@@ -641,7 +640,7 @@ describe('Fill subdivision', () => {
                     4, 0
                 ]
             ]);
-            checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+            expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
         });
 
         test('Polygon with duplicate edge inside cell', () => {
@@ -701,7 +700,7 @@ describe('Fill subdivision', () => {
                     3, 0
                 ]
             ]);
-            checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+            expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
         });
     });
 
@@ -778,7 +777,7 @@ describe('Fill subdivision', () => {
                 4, 0
             ]
         ]);
-        checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+        expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
     });
 
     test('Generates pole geometry for north pole only (geometry not bordering other pole)', () => {
@@ -814,7 +813,7 @@ describe('Fill subdivision', () => {
                 2, 3, 3, 0
             ]
         ]);
-        checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+        expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
     });
 
     test('Generates pole geometry for south pole only (geometry not bordering other pole)', () => {
@@ -850,7 +849,7 @@ describe('Fill subdivision', () => {
                 2, 3, 3, 0
             ]
         ]);
-        checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+        expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
     });
 
     test('Generates pole geometry for north pole only (tile not bordering other pole)', () => {
@@ -886,7 +885,7 @@ describe('Fill subdivision', () => {
                 2, 3, 3, 0
             ]
         ]);
-        checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+        expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
     });
 
     test('Generates pole geometry for south pole only (tile not bordering other pole)', () => {
@@ -922,7 +921,7 @@ describe('Fill subdivision', () => {
                 2, 3, 3, 0
             ]
         ]);
-        checkWindingOrder(result.verticesFlattened, result.indicesTriangles);
+        expectWindingOrder(result.verticesFlattened, result.indicesTriangles);
     });
 
     test('Scanline subdivision ring generation case 1', () => {
@@ -952,7 +951,7 @@ describe('Fill subdivision', () => {
         const ring = [0, 1, 2, 3, 4, 5, 6, 7];
         const finalIndices = [];
         scanlineTriangulateVertexRing(vertices, ring, finalIndices);
-        checkWindingOrder(vertices, finalIndices);
+        expectWindingOrder(vertices, finalIndices);
     });
 
     test('Scanline subdivision ring generation case 2', () => {
@@ -961,7 +960,7 @@ describe('Fill subdivision', () => {
         const ring = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
         const finalIndices = [];
         scanlineTriangulateVertexRing(vertices, ring, finalIndices);
-        checkWindingOrder(vertices, finalIndices);
+        expectWindingOrder(vertices, finalIndices);
     });
 });
 
@@ -1076,7 +1075,7 @@ function hasDuplicateVertices(flattened: number[]): boolean {
 /**
  * Passes if all triangles have the correct winding order, otherwise throws.
  */
-function checkWindingOrder(flattened: number[], indices: number[]): void {
+function expectWindingOrder(flattened: number[], indices: number[]): void {
     for (let i = 0; i < indices.length; i += 3) {
         const i0 = indices[i];
         const i1 = indices[i + 1];

package/src/render/subdivision.ts

@@ -612,6 +612,11 @@ class Subdivider {
         // Add pole geometry if needed
         this._handlePoles(subdividedTriangles);
 
+        if (this._granularity >= 2 && this._canonical?.z === 0) {
+            subdividedTriangles = this._removeTrianglesOutsideTileX(subdividedTriangles);
+            subdividedLines = subdividedLines.map(lines => this._removeLinesOutsideTileX(lines));
+        }
+
         return {
             verticesFlattened: this._vertexBuffer,
             indicesTriangles: subdividedTriangles,
@@ -619,6 +624,47 @@ class Subdivider {
         };
     }
 
+    private _vertexOutsideTileX(index: number): boolean {
+        const x = this._vertexBuffer[index * 2];
+        return x < 0 || x > EXTENT;
+    }
+
+    /**
+     * Drops all triangles that reach beyond the tile's X extent.
+     *
+     * On globe the z0 tile's buffer wraps around the planet onto the tile itself, drawing buffered geometry twice.
+     * Only globe uses subdivision (`granularity >= 2`), so mercator is never affected.
+     * @param indices - Triangle indices into `this._vertexBuffer`.
+     * @returns The indices with every triangle that has a vertex outside the tile's X extent removed.
+     */
+    private _removeTrianglesOutsideTileX(indices: number[]): number[] {
+        const filtered: number[] = [];
+        for (let i = 0; i < indices.length; i += 3) {
+            if (this._vertexOutsideTileX(indices[i]) || this._vertexOutsideTileX(indices[i + 1]) || this._vertexOutsideTileX(indices[i + 2])) {
+                continue;
+            }
+            filtered.push(indices[i], indices[i + 1], indices[i + 2]);
+        }
+        return filtered;
+    }
+
+    /**
+     * Drops all outline line segments that reach beyond the tile's X extent,
+     * for the same reason as {@link Subdivider._removeTrianglesOutsideTileX}.
+     * @param indices - Line segment indices into `this._vertexBuffer`.
+     * @returns The indices with every segment that has a vertex outside the tile's X extent removed.
+     */
+    private _removeLinesOutsideTileX(indices: number[]): number[] {
+        const filtered: number[] = [];
+        for (let i = 0; i < indices.length; i += 2) {
+            if (this._vertexOutsideTileX(indices[i]) || this._vertexOutsideTileX(indices[i + 1])) {
+                continue;
+            }
+            filtered.push(indices[i], indices[i + 1]);
+        }
+        return filtered;
+    }
+
     /**
      * Sometimes the supplies vertex and index array has duplicate vertices - same coordinates that are referenced by multiple different indices.
      * That is not allowed for purposes of subdivision, duplicates are removed in `this.initializeVertices`.

package/src/render/terrain.test.ts

@@ -1,6 +1,5 @@
 import {describe, beforeEach, afterEach, test, expect, vi} from 'vitest';
 import Point from '@mapbox/point-geometry';
-import {mat4} from 'gl-matrix';
 import {Terrain} from './terrain.ts';
 import {Context} from '../webgl/context.ts';
 import {RGBAImage} from '../util/image.ts';
@@ -248,31 +247,66 @@ describe('Terrain', () => {
         expect(actualVertexArray).toStrictEqual([0, 0, 0, 2048, 0, 0, 4096, 0, 0, 6144, 0, 0, 8192, 0, 0, 0, 2048, 0, 2048, 2048, 0, 4096, 2048, 0, 6144, 2048, 0, 8192, 2048, 0, 0, 4096, 0, 2048, 4096, 0, 4096, 4096, 0, 6144, 4096, 0, 8192, 4096, 0, 0, 6144, 0, 2048, 6144, 0, 4096, 6144, 0, 6144, 6144, 0, 8192, 6144, 0, 0, 8192, 0, 2048, 8192, 0, 4096, 8192, 0, 6144, 8192, 0, 8192, 8192, 0, 0, 0, 1, 2048, 0, 1, 4096, 0, 1, 6144, 0, 1, 8192, 0, 1, 0, 8192, 1, 2048, 8192, 1, 4096, 8192, 1, 6144, 8192, 1, 8192, 8192, 1, 0, 0, 0, 0, 0, 1, 0, 2048, 0, 0, 2048, 1, 0, 4096, 0, 0, 4096, 1, 0, 6144, 0, 0, 6144, 1, 0, 8192, 0, 0, 8192, 1, 8192, 0, 0, 8192, 0, 1, 8192, 2048, 0, 8192, 2048, 1, 8192, 4096, 0, 8192, 4096, 1, 8192, 6144, 0, 8192, 6144, 1, 8192, 8192, 0, 8192, 8192, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]);
     });
 
-    test('interpolation works', () => {
-        const mockTerrain = {
-            getDEMElevation: Terrain.prototype.getDEMElevation,
-            getTerrainData() {
-                return {
-                    u_terrain_matrix: mat4.create(),
-                    tile: {
-                        dem: {
-                            dim: 1,
-                            sampleBilinear(x: number, y: number) {
-                                return 100 * x + 10 * y;
-                            }
-                        }
-                    }
-                };
+    test('getElevation interpolates and reuses DEM sampling setup until reset', () => {
+        const terrain = new Terrain(null, {_source: {tileSize: 512}} as any, {exaggeration: 2} as any);
+        const tileID = new OverscaledTileID(1, 0, 1, 0, 0);
+        const sourceTile = {
+            tileID,
+            dem: {
+                dim: 1,
+                sampleBilinear: (x: number, y: number) => 100 * x + 10 * y
             }
-        };
-        const tileID = new OverscaledTileID(0, 0, 0, 0, 0);
-        expect(mockTerrain.getDEMElevation(tileID, 0, 0)).toBeCloseTo(0);
-        expect(mockTerrain.getDEMElevation(tileID, 1, 1)).toBeCloseTo(110);
-        expect(mockTerrain.getDEMElevation(tileID, 0, 0.5)).toBeCloseTo(5);
-        expect(mockTerrain.getDEMElevation(tileID, 1, 0.5)).toBeCloseTo(105);
-        expect(mockTerrain.getDEMElevation(tileID, 0.5, 0)).toBeCloseTo(50);
-        expect(mockTerrain.getDEMElevation(tileID, 0.5, 1)).toBeCloseTo(60);
-        expect(mockTerrain.getDEMElevation(tileID, 0.4, 0.2)).toBeCloseTo(42);
+        } as any as Tile;
+        terrain.tileManager.getSourceTile = vi.fn(() => sourceTile);
+        terrain.tileManager.getSource = vi.fn(() => ({minzoom: 0, maxzoom: 22}) as any);
+
+        expect(terrain.getDEMElevation(tileID, EXTENT * 0.4, EXTENT * 0.2)).toBeCloseTo(42);
+        expect(terrain.getElevation(tileID, EXTENT / 2, EXTENT / 2)).toBeCloseTo(110);
+        expect(terrain.getElevation(tileID, EXTENT / 2, EXTENT / 2)).toBeCloseTo(110);
+        expect(terrain.tileManager.getSourceTile).toHaveBeenCalledTimes(1);
+
+        terrain.resetElevationCache();
+        expect(terrain.getElevation(tileID, EXTENT / 2, EXTENT / 2)).toBeCloseTo(110);
+
+        expect(terrain.tileManager.getSourceTile).toHaveBeenCalledTimes(2);
+    });
+
+    test('getDEMElevation samples the correct part of a parent DEM tile', () => {
+        const terrain = new Terrain(null, {_source: {tileSize: 512}} as any, {} as any);
+        const childTileID = new OverscaledTileID(2, 0, 2, 3, 3);
+        const parentTileID = new OverscaledTileID(1, 0, 1, 1, 1);
+        const sampleBilinear = vi.fn(() => 42);
+
+        terrain.tileManager.getSourceTile = vi.fn(() => ({
+            tileID: parentTileID,
+            dem: {dim: 4, sampleBilinear}
+        }) as any as Tile);
+        terrain.tileManager.getSource = vi.fn(() => ({maxzoom: 22}) as any);
+
+        expect(terrain.getDEMElevation(childTileID, EXTENT / 2, EXTENT / 2)).toBe(42);
+        // The center of the bottom-right child is at 75% of both parent axes.
+        expect(sampleBilinear).toHaveBeenCalledWith(3, 3);
+    });
+
+    test('getElevation retries sampling setup when DEM data becomes available', () => {
+        const terrain = new Terrain(null, {_source: {tileSize: 512}} as any, {exaggeration: 1} as any);
+        const tileID = new OverscaledTileID(1, 0, 1, 0, 0);
+        let tileHasDem = false;
+
+        terrain.tileManager.getSourceTile = vi.fn(() => ({
+            tileID,
+            dem: tileHasDem ? {
+                dim: 1,
+                sampleBilinear: (x: number, y: number) => 100 * x + 10 * y
+            } : undefined
+        }) as any as Tile);
+        terrain.tileManager.getSource = vi.fn(() => ({minzoom: 0, maxzoom: 22}) as any);
+
+        expect(terrain.getElevation(tileID, EXTENT / 2, EXTENT / 2)).toBe(0);
+
+        tileHasDem = true;
+        expect(terrain.getElevation(tileID, EXTENT / 2, EXTENT / 2)).toBeCloseTo(55);
+        expect(terrain.tileManager.getSourceTile).toHaveBeenCalledTimes(2);
     });
 
     test('getElevationForLngLat uses covering tiles to get the right zoom', () => {
@@ -323,15 +357,15 @@ describe('Terrain', () => {
 
     test('getDEMElevation normalizes out-of-bounds coordinates to neighbor tile', () => {
         const terrain = new Terrain(null, {_source: {tileSize: 512}} as any, {} as any);
-        const spy = vi.fn().mockReturnValue({tile: null});
-        terrain.getTerrainData = spy;
+        const getSourceTile = vi.fn();
+        terrain.tileManager.getSourceTile = getSourceTile;
 
         // tile (0,0,1) with x beyond EXTENT should normalize to tile (1,0,1)
         const tileID = new OverscaledTileID(1, 0, 1, 0, 0);
         terrain.getDEMElevation(tileID, EXTENT + 100, 50);
 
-        expect(spy).toHaveBeenCalledOnce();
-        const [calledTileID] = spy.mock.calls[0];
+        expect(getSourceTile).toHaveBeenCalledTimes(1);
+        const [calledTileID] = getSourceTile.mock.calls[0];
         expect(calledTileID.canonical.x).toBe(1);
         expect(calledTileID.canonical.y).toBe(0);
         expect(calledTileID.canonical.z).toBe(1);
@@ -339,15 +373,15 @@ describe('Terrain', () => {
 
     test('getDEMElevation returns 0 for coordinates beyond tile grid', () => {
         const terrain = new Terrain(null, {_source: {tileSize: 512}} as any, {} as any);
-        const spy = vi.fn();
-        terrain.getTerrainData = spy;
+        const getSourceTile = vi.fn();
+        terrain.tileManager.getSourceTile = getSourceTile;
 
         // tile (0,0,0) with y beyond EXTENT — no tile exists below at z=0
         const tileID = new OverscaledTileID(0, 0, 0, 0, 0);
         const result = terrain.getDEMElevation(tileID, 100, EXTENT + 100);
 
         expect(result).toBe(0);
-        expect(spy).not.toHaveBeenCalled();
+        expect(getSourceTile).not.toHaveBeenCalled();
     });
 
     describe('getElevationForLngLatZoom returns 0 for out of bounds', () => {
@@ -361,11 +395,11 @@ describe('Terrain', () => {
             expect(terrain.getElevationForLngLatZoom(new LngLat(0, 88), 0)).toBe(0);
         });
 
-        test('zoom', () => {
+        test('zoom below the minimum', () => {
             expect(terrain.getElevationForLngLatZoom(new LngLat(0, 0), MIN_TILE_ZOOM - 1)).toBe(0);
         });
 
-        test('zoom', () => {
+        test('zoom above the maximum', () => {
             expect(terrain.getElevationForLngLatZoom(new LngLat(0, 0), MAX_TILE_ZOOM + 1)).toBe(0);
         });
     });

package/src/render/terrain.ts

@@ -1,4 +1,4 @@
-import {mat4, vec2} from 'gl-matrix';
+import {mat4} from 'gl-matrix';
 import {OverscaledTileID} from '../tile/tile_id.ts';
 import {RGBAImage} from '../util/image.ts';
 import {warnOnce} from '../util/util.ts';
@@ -38,6 +38,8 @@ export type TerrainData = {
     tile: Tile;
 };
 
+type TerrainElevationSampler = (x: number, y: number, extent: number) => number;
+
 /**
  * @internal
  * This is the main class which handles most of the 3D Terrain logic. It has the following topics:
@@ -135,7 +137,13 @@ export class Terrain {
      * as of overzooming of raster-dem tiles in high zoomlevels, this cache contains
      * matrices to transform from vector-tile coords to raster-dem-tile coords.
      */
-    _demMatrixCache: {[_: string]: { matrix: mat4; coord: OverscaledTileID }};
+    _demMatrixCache: Map<string, mat4>;
+    /**
+     * Per-render cache of resolved CPU elevation samplers. It is cleared after
+     * terrain tile selection updates and whenever the terrain source changes.
+     * Missing DEM data is deliberately not cached so a later sample can retry.
+     */
+    _elevationSamplerCache: Map<string, TerrainElevationSampler>;
     /**
      * Controls how terrain skirt length is calculated.
      * @see {@link MapOptions.terrainSkirtLength}
@@ -149,7 +157,8 @@ export class Terrain {
         this._terrainSkirtLength = terrainSkirtLength;
         this.qualityFactor = 2;
         this.meshSize = 128;
-        this._demMatrixCache = {};
+        this._demMatrixCache = new Map();
+        this._elevationSamplerCache = new Map();
         this.coordsIndex = [];
         this._coordsTextureSize = 1024;
     }
@@ -200,13 +209,8 @@ export class Terrain {
         const normalized = tileID.normalizeCoordinates(x, y, extent);
         if (!normalized) return 0;
 
-        const terrain = this.getTerrainData(normalized.tileID);
-        const dem = terrain.tile?.dem;
-        if (!dem) return 0;
-
-        const pos = vec2.transformMat4([], [normalized.x / extent * EXTENT, normalized.y / extent * EXTENT], terrain.u_terrain_matrix);
-        const coord = [pos[0] * dem.dim, pos[1] * dem.dim];
-        return dem.sampleBilinear(coord[0], coord[1]);
+        const sampler = this._getElevationSampler(normalized.tileID);
+        return sampler ? sampler(normalized.x, normalized.y, extent) : 0;
     }
 
     /**
@@ -250,6 +254,59 @@ export class Terrain {
         return this.getDEMElevation(tileID, x, y, extent) * this.exaggeration;
     }
 
+    /**
+     * Clear CPU elevation samplers that may retain a previously selected DEM tile.
+     * @internal
+     */
+    resetElevationCache(): void {
+        this._elevationSamplerCache.clear();
+    }
+
+    _getElevationSampler(tileID: OverscaledTileID): TerrainElevationSampler | null {
+        const key = tileID.key;
+        const cachedSampler = this._elevationSamplerCache.get(key);
+        if (cachedSampler) return cachedSampler;
+
+        const sourceTile = this.tileManager.getSourceTile(tileID, true);
+        const dem = sourceTile?.dem;
+        if (!sourceTile || !dem) return null;
+
+        const matrix = this._getDEMTileMatrix(tileID, sourceTile);
+        // Store the vector-tile to DEM-pixel transform once for the hot sampling loop.
+        const demPixelScaleX = matrix[0] * dem.dim;
+        const demPixelScaleY = matrix[5] * dem.dim;
+        const demPixelOffsetX = matrix[12] * dem.dim;
+        const demPixelOffsetY = matrix[13] * dem.dim;
+        const sampler = (x: number, y: number, extent: number): number => {
+            const extentScale = extent === EXTENT ? 1 : EXTENT / extent;
+            return dem.sampleBilinear(
+                x * extentScale * demPixelScaleX + demPixelOffsetX,
+                y * extentScale * demPixelScaleY + demPixelOffsetY
+            );
+        };
+        this._elevationSamplerCache.set(key, sampler);
+        return sampler;
+    }
+
+    _getDEMTileMatrix(tileID: OverscaledTileID, sourceTile: Tile): mat4 {
+        const matrixKey = `${sourceTile.tileID.key}/${tileID.key}`;
+        const cachedMatrix = this._demMatrixCache.get(matrixKey);
+        if (cachedMatrix) return cachedMatrix;
+
+        const maxzoom = this.tileManager.getSource().maxzoom;
+        let dz = tileID.canonical.z - sourceTile.tileID.canonical.z;
+        if (tileID.overscaledZ > tileID.canonical.z) {
+            if (tileID.canonical.z >= maxzoom) dz =  tileID.canonical.z - maxzoom;
+            else warnOnce('cannot calculate elevation if elevation maxzoom > source.maxzoom');
+        }
+        const dx = tileID.canonical.x - (tileID.canonical.x >> dz << dz);
+        const dy = tileID.canonical.y - (tileID.canonical.y >> dz << dz);
+        const demMatrix = mat4.fromScaling(new Float64Array(16), [1 / (EXTENT << dz), 1 / (EXTENT << dz), 0]);
+        mat4.translate(demMatrix, demMatrix, [dx * EXTENT, dy * EXTENT, 0]);
+        this._demMatrixCache.set(matrixKey, demMatrix);
+        return demMatrix;
+    }
+
     /**
      * returns a Terrain Object for a tile. Unless the tile corresponds to data (e.g. tile is loading), return a flat dem object
      * @param tileID - the tile to get the terrain for
@@ -277,27 +334,13 @@ export class Terrain {
             sourceTile.demTexture.bind(context.gl.NEAREST, context.gl.CLAMP_TO_EDGE);
             sourceTile.needsTerrainPrepare = false;
         }
-        // create matrix for lookup in dem data
-        const matrixKey = sourceTile && sourceTile.toString() + sourceTile.tileID.key + tileID.key;
-        if (matrixKey && !this._demMatrixCache[matrixKey]) {
-            const maxzoom = this.tileManager.getSource().maxzoom;
-            let dz = tileID.canonical.z - sourceTile.tileID.canonical.z;
-            if (tileID.overscaledZ > tileID.canonical.z) {
-                if (tileID.canonical.z >= maxzoom) dz =  tileID.canonical.z - maxzoom;
-                else warnOnce('cannot calculate elevation if elevation maxzoom > source.maxzoom');
-            }
-            const dx = tileID.canonical.x - (tileID.canonical.x >> dz << dz);
-            const dy = tileID.canonical.y - (tileID.canonical.y >> dz << dz);
-            const demMatrix = mat4.fromScaling(new Float64Array(16), [1 / (EXTENT << dz), 1 / (EXTENT << dz), 0]);
-            mat4.translate(demMatrix, demMatrix, [dx * EXTENT, dy * EXTENT, 0]);
-            this._demMatrixCache[matrixKey] = {matrix: demMatrix, coord: tileID};
-        }
+        const terrainMatrix = sourceTile ? this._getDEMTileMatrix(tileID, sourceTile) : this._emptyDemMatrix;
         // return uniform values & textures
         return {
             'u_depth': 2,
             'u_terrain': 3,
             'u_terrain_dim': sourceTile?.dem?.dim || 1,
-            'u_terrain_matrix': matrixKey ? this._demMatrixCache[matrixKey].matrix : this._emptyDemMatrix,
+            'u_terrain_matrix': terrainMatrix,
             'u_terrain_unpack': sourceTile?.dem?.getUnpackVector() || this._emptyDemUnpack,
             'u_terrain_exaggeration': this.exaggeration,
             texture: (sourceTile?.demTexture || this._emptyDemTexture).texture,

package/src/shaders/glsl/_projection_globe.fragment.glsl

@@ -0,0 +1,12 @@
+uniform bool u_projection_clip_antimeridian;
+
+in highp float v_projection_tile_x;
+
+// On globe the z0 tile's buffer wraps around the planet onto the tile itself, drawing geometry near the antimeridian twice.
+// To avoid this, we discard fragments beyond the tile's X extent (0..8192) when enabled for the tile.
+// The range test is half-open so that both sides of the antimeridian tile the seam exactly, without overlap.
+void clipAntimeridian() {
+    if (u_projection_clip_antimeridian && (v_projection_tile_x < 0.0 || v_projection_tile_x >= 8192.0)) {
+        discard;
+    }
+}

package/src/shaders/glsl/_projection_globe.fragment.glsl.g.ts

@@ -0,0 +1,2 @@
+// This file is generated. Edit build/generate-shaders.ts, then run `npm run codegen`.
+export default 'uniform bool u_projection_clip_antimeridian;in highp float v_projection_tile_x;void clipAntimeridian() {if (u_projection_clip_antimeridian && (v_projection_tile_x < 0.0 || v_projection_tile_x >=8192.0)) {discard;}}';