Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MapLibre Native how to list supported features #391

Open
louwers opened this issue Oct 20, 2023 · 9 comments
Open

MapLibre Native how to list supported features #391

louwers opened this issue Oct 20, 2023 · 9 comments
Labels
documentation Improvements or additions to documentation

Comments

@louwers
Copy link
Collaborator

louwers commented Oct 20, 2023

@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
Copy link

@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
Copy link
Collaborator Author

louwers commented Oct 20, 2023

@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
Copy link

@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
Copy link
Collaborator Author

louwers commented Oct 20, 2023

@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
Copy link
Collaborator

HarelM commented Oct 21, 2023

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
Copy link
Contributor

wipfli commented Oct 23, 2023

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
Copy link
Collaborator Author

louwers commented Oct 23, 2023

@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
Copy link
Collaborator

HarelM commented Apr 25, 2024

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 HarelM added the documentation Improvements or additions to documentation label Apr 25, 2024
@HarelM
Copy link
Collaborator

HarelM commented Apr 30, 2024

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...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

4 participants