Breaking changes MapLibre GL JS v5

[sbachinin]

This issue is to track breaking changes for MapLibre GL JS v5:

• queryTerrainElevation should return meters above sea level. (Currently it returns a special offset used for positioning of custom 3d objects). - Return above-sea-level elevation from queryTerrainElevation + Pass lowered mercator matrix to custom layer #3854
• getElevationOffset method should be added. It should return the offset that is currently retrieved from queryTerrainElevation - there is elevation definition now as part of the spec.
• "geometry-type" to identify Multi- features maplibre-style-spec#519
• fix: order of normalizeSpriteURL and transformRequest in load sprites #3898
• Expose projection matrix parameters #3136 (comment)
• Fix sky for globe - Sky shouldn't be visible on low zoom in Globe-Mercator projection #4853
• Fix performance issues for globe related to projectAndGetPerspectiveRatio - Globe: symbol and coveringTiles optimizations #4778
• Add projection outside the style for initialization much like zoom/breaking etc. - projection setting on map object (outside style) #4909
• Add more parameters to custom layer to better support globe
• Geojson close to the poles with globe - Will Globe View be developed on MapLibre? #1598 (comment), Globe final PR #3963 (comment) - this is a limitation of mercator coordinates system.
• Return value for on method to allow unsubsribing - Return subscription for on method #5080
• Change how bearing and roll UX on desktop when dragging - Camera Roll #4780 (comment), Improve rotate UX #5074
• Change default font? Remove non-open source fonts #4820, Design Proposal: Allow simple default font change maplibre-style-spec#834, Change default value for text-font to Noto Sans Regular maplibre-style-spec#311
• Globe showstpeer issues (terrain + globe is not a showstopper as one can disable terrain for lower zoom levels when globe is on): showstopper Preventing from releasing a pre-release version as non-pre-release
• Incorporate globe, vertical-perspective and expression for projection - Facilitate for globe transition expression refactoring #5139, Cannot go from vertical-perspective to globe projection #5114 , Projection expression support #5056
• Move webgl initialization configuration into an object to future proof it - Add powerPreference support to MapLibre GL #5135

[sbachinin]

This is likely to produce breaking changes: #3736:

• queryTerrainElevation should return meters above sea level. (Currently it returns a special offset used for positioning of custom 3d objects).
• getElevationOffset method should be added. It should return the offset that is currently retrieved from queryTerrainElevation

[HarelM]

The following issue will also create breaking change to the output of geometry-type:

• Filter can't be applied to type: MultiPolygon #3516

This issue has a part in the style-spec repo as well.

• "geometry-type" to identify Multi- features maplibre-style-spec#519

[wipfli]

I am happy with breaking changes in the API of MapLibre GL JS, but we should not do breaking changes in the style spec, see maplibre/maplibre-style-spec#519 (comment). In my opinion, geometry-type should keep the same behavior as it did so far.

[HarelM]

I respect your opinion, but I don't agree in this specific case, see my comment in the link you sent. TL;DR: more in the area of bug fix and not a style spec change.

[birkskyum]

Depending on when this release is to come out ( looking at our majors, it's statistically likely to be +6 months from now ), it might be relevant to discuss a WebGL1 sunset again. We had some push back in the v3 release May 2023, but there are some indicators that it might be less problematic going forward, especially when looking at Apple ecosystems support.

There are examples of projects in our ecosystem that have moved to WebGL2-only support (looking at you deck.gl), and keeping WebGL1 support going forward will thus both not be compatible with said libraries, and more concerning it will be at the increasing high cost of locking the renderer to a legacy graphics pipeline.

Despite some users relying on it, MapLibre Native already did sunset OpenGL2 (~webgl1) in favor of OpenGL3+ (webgl2) to do the Modularization Refactor, which was crucial for the long-term viability of that renderer, and it would be necessary to do something similar here as well.

[HarelM]

Is there a way you can think of to allow moving the webgl1 code into a plugin somehow leaving the main version using only webgl2 but allowing this plugin to try and "help" in case someone needs webgl1?

[HarelM]

Another candidate for v5 breaking changes:

• fix: order of normalizeSpriteURL and transformRequest in load sprites #3898

[wipfli]

Let's discuss phasing out webgl1 in a separate thread here: #3947

[HarelM]

As part of this issue:

• When simulating a GPS bearing the map zooms in/out with terrain #3878

I found out that freeze elevation is not the default when doing easeTo when terrain is on.

I think it should be, so that it is consistent with pan movement.
This is a breaking change, so I'm writing it here.
The UX is worse if freeze elevation is on by default and the current fix seems to solve the issue well. No need for a breaking change.

[birkskyum]

v5 breaking change:

• CustomRenderMethod should take just an args object Expose projection matrix parameters #3136 (comment)

[birkskyum]

The arial font - I'd love to see it gone from the default, because it's always a problem to source it. Causing headache this moment that it's e.g. not present in openmaptiles/font

Related to:

• Change default value for text-font to Noto Sans Regular maplibre-style-spec#311
• Change default font-face to Noto Sans Regular [#311] maplibre-style-spec#436

[wipfli]

I think we should have a discussion in the next monthly meeting how we want to handle breaking style changes. API changes are something different.

[birkskyum]

Is there a way you can think of to allow moving the webgl1 code into a plugin somehow leaving the main version using only webgl2 but allowing this plugin to try and "help" in case someone needs webgl1?

The only way I see that we can realistically keep webgl1 support is by abstraction:

• Modularize graphics backend #4511

A key difference is how uniforms are made:

	individual uniforms	uniform buffer objects (UBOs)
webgl1	x
webgl2	x	x
webgpu		x

So we'll be going through a transition like this, where webgl2 can be leveraged as a transition technology towards webgpu. In MapLibre Native, the opengl2(webgl1) was simply sunset to allow for this incremental migration, but it seems for GL JS that we'll need to keep webgl1 around, making the abstraction somewhat harder because there seems to be a significantly bigger distance from webgl1 <-> webgpu compared to refactored webgl2 w/ UBOs <-> webgpu. @zhangyiatmicrosoft do you have any idea what the usage numbers are for webgl1 now, compared to the numbers you presented a year ago here?

[HarelM]

It would also be interesting to see if we can both abstract and allow webgl1 to be moved outside the code base, allowing the code to be fully webgl2 or even abstract enough to require another package defining the GL itself - i.e. abstract and also separate to core, webgl1, webgl2, webgpu so that developer can choose which to support/include.

[HarelM]

We are nearing the end of the checklist of breaking changes.
I believe a non pre-release version is soon to come.
If you have any other breaking changes that you think we should consider, now will be the time.