Reimplement MGLAnnotation atop MGLSource and MGLStyleLayer

[1ec5]

The runtime styling API is in many ways more powerful than the MapKit-inspired annotation API, which consists of MGLAnnotation subclasses and styling methods on MGLMapViewDelegate. However, at least at the SDK level, the annotation API needs to stick around in some form to service annotation views, and having a MapKit-like, highly object-oriented API is desirable where feasible, because it’s more direct, focused, and discoverable than the runtime styling API. But over time, we should allow the runtime styling API to subsume the annotation API. Developers should be able to think of the annotation API as nothing more than a shortcut for runtime styling functionality, rather than an entirely separate code path.

As an alternative to or as part of #1734, we could migrate the SDK’s annotation API to MGLSource and MGLStyleLayer. MGLSource is basically a level of indirection around MGLAnnotation and subclasses. MGLStyleLayer serves essentially the same purpose as MKOverlayRenderer.

Per #5626 (comment) et seq., this work is blocked by:

• Add and modify individual features in a GeoJSON source on the fly (Add and modify individual features in a GeoJSON source on the fly #6177) for point annotations
• Optionally persist layers and sources across styles (Optionally persist layers and sources across styles #6180)
• Feature querying should return existing, untiled annotations (Feature querying should return existing annotations #6178) for hit testing
• GeoJSON sources should keep track of original GeoJSON objects (mbgl::style::GeoJSONSource should have GeoJSON getter #7376)
• Add paint property for icon image URL (Add paint property for icon image URL mapbox-gl-style-spec#485) for MGLAnnotationImage (fixed in [ios, macos] possibility to set custom images to style #6637)
• Convert template images to SDF icons (Convert template images to SDF icons #7291)

This work would be complicated by:

• Removing fill-outline-color (Remove "fill-outline-color" mapbox-gl-js#4088)

/cc @incanus @jfirebaugh @frederoni @boundsj

[1ec5]

In addition to supporting annotation views, another reason the annotation API needs to stick around is for interactivity (annotation selection and callouts). GeoJSON is very much a do-it-yourself approach to markers, where the developer has to manage their own gesture recognizer, perform feature querying, and keep track of selection themselves. That can be a boon for very custom implementations, but it’s way too much work for 99% of developers. (This entire example consists of code the SDK should be responsible for.)

[incanus]

the annotation API needs to stick around is for interactivity (annotation selection and callouts).

Though I'm unfamiliar with the current status, we had this initially pre-views by mapping gestures into query regions in core, sprite-based annotations. I agree views are still necessary if we want to allow developers to use existing UIView-derived stuff wholesale, and the higher-level API is also useful and familiar. I support the idea of merging this into core as much as possible, including again exploring the approach of per-frame syncing of view layer contents into core GL textures (something I'd be glad to again deep dive on).

[1ec5]

Though I'm unfamiliar with the current status, we had this initially pre-views by mapping gestures into query regions in core, sprite-based annotations. I agree views are still necessary if we want to allow developers to use existing UIView-derived stuff wholesale, and the higher-level API is also useful and familiar. I support the idea of merging this into core as much as possible, including again exploring the approach of per-frame syncing of view layer contents into core GL textures (something I'd be glad to again deep dive on).

In #6181 (comment), I wasn’t talking about view-backed annotations at all, but rather about annotations in general. The current balance between SDK-specific code and mbgl support code is a good one, because gesture handling, selection state management, and callouts (all handled by the SDK) are extremely platform-specific, while queryRenderedFeatures (part of mbgl) is platform-agnostic.

Baking annotation views into textures is a large effort orthogonal to whether we keep around an object-oriented interface for working with overlay data. My comment is meant to head off suggestions that we eliminate the annotation API in favor of GeoJSON sources, which would throw interactivity out with the bathwater and be incompatible with the goal of encouraging developers to switch from MapKit or the Google Maps SDK.

[incanus]

Ah, got it. Agree!

[1ec5]

I’ve updated the original comment with a list of major blocking issues (currently #6177, #6180, and #6178). I’m sure there are more, but these should be plenty to tide us over for now.

Additionally, it’s very important that any refactoring we do along these lines not regress performance. We should add a performance unit test that measures the time it takes to add 10,000 annotations (with a reasonable but not significant tolerance) and avoid landing the refactoring until that test passes without modification.

[incanus]

To carry over past work & research from #1125, we may be able to get even annotation views down into GL using an approach like this:

http://stackoverflow.com/a/10259503/977220

I would like to look into this again as part of truly accomplishing the following, mentioned above:

Developers should be able to think of the annotation API as nothing more than a shortcut for runtime styling functionality, rather than an entirely separate code path.

[1ec5]

If it’s a shortcut we’re looking to provide, then #1734 (comment) would get us there with much less code.