feat(core): render the map as a globe when the style sets projection

[johncarmack1984]

Closes #3161.

"projection": {"type": "globe"} renders the map as a globe on Metal, Vulkan, WebGPU and OpenGL, with GL JS's math and GL JS's render tests as the oracle. This PR is the twelve phases of #4525 as 32 commits, one per phase (9 and 10 are one commit per family/backend; 10d is the review's shader-group signature unification). Every commit builds and passes its own tests alone.

The same commits are open as a stack of draft PRs on my fork, chained by base, so each phase can be read as one diff: https://github.com/johncarmack1984/maplibre-native/pulls — #3 to #34, the map is in #3. Rebase-merge would keep the phase commits on main. If you'd rather take phases one at a time, each fork PR can be re-targeted here in order.

Checked: on every commit, the Metal unit tests and the globe render group, plus a Linux OpenGL (Docker) run of the whole render suite, a Bazel build and an MSVC (Windows ARM64) build; the fork's CI on every phase ref, Windows judged against main's own baseline. At the tip: Metal 1362 passed / 79 ignored / 0 failed on the full suite, unit tests 915/915; Linux OpenGL in Docker 1364 passed with the same three environment failures main shows there; Dawn and wgpu 1373 / 86 / 0 on the branch before the instancing merge, and the globe group 59 / 4 / 0 at the tip. @ClayWarren has been running the branch offline in a production Expo/React Native app; the only gap they hit was atmosphere, which is the separate sky property (#4414).

AI Disclosure: Claude Fable 5 was used to orchestrate these changes under John's plan and direction. Claude Opus 4.6 was used to implement, with Fable and John ensuring the changes in every commit were written according to sound CS principles and internal repo conventions. CI has been run on every commit to ensure these changes create no regressions. In my review and testing, I found them to be well-written and to introduce no new issues. Open to feedback and happy to implement any changes deemed necessary. -John

[ClayWarren]

Downstream sky support PR #4534 is now ready for maintainer review. It is intentionally stacked on this globe work because the physical atmosphere depends on its globe camera matrices, depth pass, and projection-transition state, and it has been dogfooded in a production Expo React Native mobile app. Reviewers can isolate the sky work with the sky-only comparison: ClayWarren/maplibre-native@codex/globe-projection-4533...codex/sky-style-spec-4414

Sharing this as dependency and prioritization context; no timeline is implied.

[github-actions]

Bloaty Results 🐋

Compared to main

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +2.2% +3.97Mi  +2.3%  +799Ki    TOTAL

Full report: https://maplibre-native.s3.eu-central-1.amazonaws.com/bloaty-results/pr-4533-compared-to-main.txt

Compared to d387090 (legacy)

    FILE SIZE        VM SIZE    
 --------------  -------------- 
   +59% +68.3Mi  +489% +29.2Mi    TOTAL

Full report: https://maplibre-native.s3.eu-central-1.amazonaws.com/bloaty-results/pr-4533-compared-to-legacy.txt

[github-actions]

Benchmark Results ⚡

Benchmark                                                          Time             CPU      Time Old      Time New       CPU Old       CPU New
-----------------------------------------------------------------------------------------------------------------------------------------------
OVERALL_GEOMEAN                                                 +0.0439         +0.0440             0             0             0             0

Full report: https://maplibre-native.s3.eu-central-1.amazonaws.com/benchmark-results/pr-4533-compared-to-main.txt

[github-actions]

Bloaty Results (iOS) 🐋

Compared to main

    FILE SIZE        VM SIZE    
 --------------  -------------- 
  +1.6%  +250Ki  +1.6%  +256Ki    TOTAL

Full report: https://maplibre-native.s3.eu-central-1.amazonaws.com/bloaty-results-ios/pr-4533-compared-to-main.txt

[johncarmack1984]

First CI run turned up one real failure, on the Device Farm C++ job: TransformState.ProjectionDataMatchesTileMatrix, on both Pixels, every miss at zoom 11.75. The test built its scale as std::pow(2.0, state.getZoom()) and compared matrices bit-for-bit against production's state.scale. That's a pow(2, log2(x)) round trip. glibc and Apple's libm hand 2^11.75 back exactly; Bionic doesn't. Everything else in that run was green.

Fixed in phase 1: the test reads state.getScale() now, same as the code it's checking.

The branch had also fallen behind main, so I rebased; same 32 commits, one line changed. The force-push hides the failing run from the checks tab, so for the record:

• run: https://github.com/maplibre/maplibre-native/actions/runs/33503248756
• failing job: https://github.com/maplibre/maplibre-native/actions/runs/33503248756/job/99841225853
• logcat artifact with the gtest output: https://github.com/maplibre/maplibre-native/actions/runs/33503248756/artifacts/9799339366
• the commit it ran against: https://github.com/maplibre/maplibre-native/commit/6bddd1111f4d41a5d3130d9a78375b97b9e2a35d/checks

[johncarmack1984]

For anyone coming from the newsletter: the 30k lines are mostly fixtures.

lines
17.5k	59 globe render tests under metrics/integration/render-tests/projection/globe/ (one graticule style.json is 7k by itself)
4k	globe.json copied into the iOS and Android example apps
2.8k	shaders, the same globe code once per backend
6k	core

Where the decisions are:

• Phase 1 (fork 3): the seam. ProjectionBase and MercatorProjection behind TransformState, one ProjectionData UBO per drawable through the tweakers, all four backends, Mercator only, pixel-identical to main. Everything after stands on it.
• Phase 4 (fork 6): the globe math. VerticalPerspectiveProjection, ported from GL JS's _calcMatrices and _computeClippingPlane.
• Phase 5 (fork 7): the subdivision port, side by side with GL JS's render/subdivision.ts.
• Phase 6 (fork 8): touch, unproject, ease and constrain.
• Phase 7 (fork 9): tile cover.
• Phase 8 (fork 10): symbol placement and collision.
• Phase 9e (fork 15): the handover to Mercator at high zoom.

6 and 9e are the two questions from #4525.

The rest is that pattern applied again:

• 9a–9d, 9f–9i: the phase 4 shape for each layer family on Metal
• 10a–10c: the Metal shaders again in GLSL, Vulkan GLSL and WGSL; 10d is a signature reorder
• 11a–11c: the example apps
• 12a–12h: fixes from device testing

To try it:

• GLFW: F9
• Android test app: the Globe activity
• iOS app: "MapLibre Basic - Globe"
• any style: "projection": {"type": "globe"}

[acalcutt]

I am wondering if you have tried merged the terrain 3d branch at #4190 into this at all. It seems some of the things left there, like LOD changes, you have already started to tackle as part of this globe PR

I think the LOD changes in terrain might be a cause of at least one of the remaining test failures there. it might be good to reference the TERRAIN.md in that branch in https://github.com/maplibre/maplibre-native/blob/feature/terrain-3d/TERRAIN.md to see how we can combine these

[johncarmack1984]

I'm a little worried about expanding scope too much on an this already gargantuan PR, but will look into both to see how they can be better integrated and planned for in unison

Edit: oh I see you're heavily involved in the feedback on that branch, I'll see what I can do

[johncarmack1984]

@acalcutt Read the LOD section of TERRAIN.md. The second divergence is the one this PR touches, and it goes a step further than the doc says: GL JS puts the Mercator cover on createCalculateTileZoomFunction whenever terrain is set, not only at high pitch (allowVariableZoom is !!options.terrain || pitch > 78.5 - fov/2). Terrain can't match GL JS tile selection until native has that function. Phase 7 ported it, but only inside the globe cover.

Pushed a commit that moves it out to util/tile_lod.hpp (e3e2043): TileZoomFunction, plus elevationForTileCulling with GL JS's centre-elevation and content-elevation terms (both zero on the globe). Unit test against GL JS's function on the same inputs; globe behaviour unchanged. computeMeshCover can call it as is, and the gate is one line. The deltaZoom divergence is terrain-side only.

Merging the branches: not into this PR. Dry-run merge of feature/terrain-3d onto this head:

170	files both branches touch
93	conflicts
66	the position line in vertex shaders: terrain wraps it in apply_drape_transform, globe in projectTile
1	tile_cover.cpp, an include line

GL JS composes that seam with prelude functions, and the globe prelude already defines projectTileWithElevation and projectTileFor3D with GL JS's signatures. That's where the terrain mesh shader and the elevated layers plug in; the drape is orthographic per tile, so it composes after projection. Whichever lands first owns the seam and the second adapts. I'm happy to help with the adapting on the terrain side.

The bigger gap is the cover loop. GL JS runs one coveringTiles with a per-projection details provider, and terrain plugs into the bounding volume for both projections. Phase 7 cloned the loop for the globe instead. Converging is a real refactor; I'd do it as a follow-up rather than reshape this PR mid-review, unless the reviewers want it now.

[acalcutt]

@johncarmack1984 Thanks for looking into my question. I agree that both PRs are huge and should not officially be merged, but testing it in a seperate branch might be helpful to figure out any remaining crossover. From the diagnosis is seems we have quite a few conflicts

Just to note, the AI liked the plan outlined above and used that information to fill in a few gaps. It adds "the extraction is the right shape, and terrain will consume TileZoomFunction and elevationForTileCulling from main once they land — with the note that elevationForTileCulling's centerElevation is already available terrain-side as RenderTerrain::getElevationForLatLn"

[acalcutt]

It had also suggested separating out the LOD changes to their own PR so they could be merged first and used in both our PRs, but I feel like these branches would be highly scrutinized as a whole so I am not sure how feasible that is