MapLibre Native how to list supported features

[louwers]

@jechterhoff mentioned that he had to find out with trail and error if icon-overlap is not supported with Node.js

In the style spec docs, only versions for Android, iOS and macOS are listed. But MapLibre Native also has Linux, Windows, Qt and Node.js. What does 'supported' mean? index-of and slice are now part of the core, but we don't have an SDK wrapper for them on iOS. Still, you can use them through a style sheet directly with the next release or the current pre-release.

Instead of a version number, I would like to show a boolean value for most options.

So it will show:

MapLibre Native
✅

When something is supported, or:

MapLibre Native
❌

When it is not.

Plus, optionally a link to a PR where something is implemented (so users can easily find who did the implementation, what discussion was there, maybe ask some follow-up questions) or a link to an open issue when something has not yet been implemented.

I could only find a single property which has differing support on platforms (fill-extrusion-vertical-gradient), and I'm not even sure if this is correct. But in this case we could use:

MapLibre Native
✅ ❌ Android

Or in the example case of slice which I mentioned above, I might document that as:

MapLibre Native
✅ #1113 - No SDK wrapper for Android (see issue #xxx)

But only if there was someone that asked for this to be implemented and there was an issue for it.

Why no version number?

• In principle if you want new features, you should use the newest release available for each platform.
• If a feature is implemented but not released, you should make some noise that you would like to see a release. Making a release should be trivial.
• The style sheet is provided as a JSON document, and although there are SDK wrappers for modifying or interacting with it, a property should already be considered as supported if you can use it with JSON only.
• The support matrix can be updated as soon as a feature is merged, not when support lands for a particular platform, so this reduces the burden placed on maintainers when making a release. This is especialy benificial for platforms that do not have a full-time maintainer.
• The core does not have versioned releases at the moment.

Please let me know if you agree or disagree with my proposal.

cc @HarelM @ntadej

[jechterhoff]

@louwers Thank you for creating this issue.

Two concerns:

• I'm not sure if this proposal allows determining if a particular version of a MapLibre platform that is used in a third-party software supports a given style element or not. For a third-party software, it may not be so easy to switch to the newest release of the MapLibre platform. If one is stuck with a certain version of MapLibre native (core + platform), how can the supported features then be identified?
• Wouldn't requests for creating a new release of a certain MapLibre platform - especially if it is not in the Core Tier - place some burden on MapLibre maintainers? In my example use case, MapLibre Node.js is used, version 5.2.0, released March this year (if I'm not mistaken). So without version information - 1) about the MapLibre native core that is used by MapLibre Node.js 5.2.0, and 2) about the style elements supported for that version of MapLibre native core - a MapLibre user would have to request a new release for a particular platform, in order to ensure that what the Style Spec shows as supported is actually what can be used with that new release. Then again, that information may soon be outdated (when the next version of the Style Spec is published, with changes in MapLibre native core).

With my rudimentary understanding of the overall architecture, it seems like versioning of MapLibre native core is necessary. The style spec could then document from which version a certain feature is supported. In addition, some metadata for MapLibre platform releases would be needed - defining which version of native core is included in that release.

Hope this makes sense.

[louwers]

@jechterhoff That's a great idea!

We can have a versioned core, and let each platform (release) document which version of the core it is based on instead.

[jechterhoff]

@louwers Great! The Style Spec would then document each feature with an indication regarding the core version(s) that support it? Like MapLibre Native Core >= x.y.z.

[louwers]

@jechterhoff Right that sounds sensible. But let's see if others agree and I think we'll also this during the monthly meeting on the 8th of November.

[HarelM]

As said @jechterhoff said, version is very important to know what feature I've can use given a version of maplibre, where you can't upgrade to latest version.
If core gives the most information great, let's have that in the table, if there's a need to add ios and android, then sure let's have those, but having every combination will make this table unreadable, so I would focus on what would give the most accurate and summarized info, but allow to explore more data as needed.
Specifying which version of core each platform is linked with is the best approach from my point of view and should be documented in the documentation of each platform, much like how each version of ngx-maplibre-gl (the angular wrapper) is specifying which version of maplibre-gl-jsb it supports.

[wipfli]

Is the Metal rendering backend part of the MapLibre Native core or part of the iOS platform binding? Because if it is part of the core, then we have actually 2 cores: an OpenGL ES3 and a Metal one, right? Also, there is an OpenGL ES2 branch I think which @ntadej maintains I think...

[louwers]

@wipfli The 'platform bindings' are generally thought of as the glue code that enables using MapLibre Native on a particular platform as well as any auxiliary code that makes doing so more ergonomic.

From this definition it's unhelpful to think of the Metal rendering backend as a platform binding. It can be used with any platform where Metal can run, so Node.js (on macOS), Qt, macOS (AppKit), iOS (UIKit, SwiftUI), GLFW, maybe even visionOS in the future.

The core consists of interfaces and source code shared by multiple platforms. The rendering pipeline is a part of the core. This part was made modular and now has implementations for more than one graphics backend. It is similar to how some core interfaces have platform-specific implementations (e.g. for making HTTP requests), but now the rendering part of the core has more than one implementation (without a default implementation). So from my perspective, there is one core still, but one part of it you can swap out.

[HarelM]

I'm rewriting the docs now.
If this is something someone would like to push forward, now is the time.
BTW, a simple solution would be to add to the readme of the relevant binding and repo the supported features.
This way every repo (besides the code projects) is maintaining it individually.

[HarelM]

Is this something we are planning to push forward, or can we close this issue? I would like to do some housekeeping in the issues in this repo...