Runtime styling API

[incanus]

[Updated 20 April 2016 by @jfirebaugh]

The Mapbox GL Style Specification forms the domain model for Mapbox maps. It defines objects such as:

• styles
• sources
• layers
• paint and layout properties

These domain objects are central to rendering and manipulating the map, and they should be exposed by both the core mapbox-gl-native API and by the Android and iOS bindings.

This functionality exists in mapbox-gl-js already, via APIs such as addSource, addLayer, and setPaintProperty. Together, we call this set of APIs the runtime styling API (not to be confused with the Mapbox Styles API, a web API).

To get a sense of what is possible with read and write access to the style and its contents, take a look the mapbox-gl-js examples: the large majority of them use one or more runtime styling APIs.

• Show and hide layers (uses setLayoutProperty)
• Create a timeline animation (uses setFilter)
• Add live realtime data (uses addSource and setData)

Furthermore, the rich functionality provided by mapbox-gl-js plugins like mapbox-gl-directions, mapbox-gl-geocoder, and mapbox-gl-draw are enabled by the runtime styling API.

What we have now

mapbox-gl-native and the mobile SDKs currently have an "Annotations API" which provides some forms of runtime styling, namely adding and removing markers, lines, and polygons, with a limited degree of control over their visual appearance.

Rough compatibility with other mapping SDKs, and familiarity to users porting from them, were higher design priorities for the Annotations API than exposing the full gamut of GL style capabilities. This allowed us to satisfy a number of common and important use cases quickly, but it is limiting in a number of respects, and has led to a impedance mismatch between what users expect to be able to accomplish with the Annotations API versus what can be tractably and efficiently implemented.

The primary problem in this regard is that the Annotations API does not provide any means to group annotations into subsets that share common data sources or rendering properties. This is exactly the problem that style sources and layers were designed to solve, and instead of continuing to try to warp the Annotations API to fit sources and layers, or vice versa, we should expose sources and layers as first class API entities.

Specific runtime styling API related feature requests

• Add "markers" (actually, symbol layers) with full control over style properties (e.g. rotation, sprite image, text, etc.)
• Add lines and polygons with full control over style properties (e.g. dashes, line join, line cap, etc.)
• Dynamically show/hide layers (Show / Hide a layer programmatically #3169)
• Add new layers (CustomLayer usage to add custom tiles as map layer #4210)
• Control layer z-ordering (Z-ordering of MGLAnnotationImages #3992)
• Dynamic modifications of layer filters (Filtering features at runtime #2840)

Timeline

We've been working on internal prerequisites for a runtime styling API for some time now. Most importantly, we:

• Converted the internal representation of layers to a class hierarchy matching the style specification
• Moved ownership of the style and associated data from an auxiliary thread to the main thread, so that it is possible to manipulate it without complex cross-thread communication

Current development on the runtime styling API is focused on adding support to the core C++ API for adding and manipulating layers, including rendering properties. The approach is to use code generators whose input is the style specification itself.

Another major task that remains is to convert the internal representation of sources to a class hierarchy matching the style specification. This is a significant internal refactoring that will be necessary to support runtime creation and manipulation of sources.

The runtime styling API is a high priority, but as always, competes with other high priority items for resources. We currently aim to ship a runtime styling API in some form in late Q2 to early Q3.

[kkaefer]

also see #883 #881

[1ec5]

This would benefit greatly from the approach outlined in mapbox/mapbox-gl-js#1341.

[ljbade]

Putting note from @jfirebaugh that this style API will replace the annotations API style property functions.

I assume we will provide some sort of function that returns the style API object for a given annotation (or make it function on the annotation object itself). And existing style functions will be forwarded to the new API and deprecated.

[jfirebaugh]

@ljbade No, not exactly. What will happen to the existing annotations API hasn't been decided.

I assume we will provide some sort of function that returns the style API object for a given annotation

I don't think we'll do this.

And existing style functions will be forwarded to the new API and deprecated.

We may rewrite the implementation of the existing iOS and Android annotation API in terms of the Style API. But that's probably the extent of the connection between the two APIs.

[ljbade]

@jfirebaugh How will one style an individual annotation? Generate a unique layer per annotation?

[jfirebaugh]

The Style API will not have a concept of "annotations". It will have the concepts of sources, layers, paint properties, and layout properties. And when the style spec supports data-driven styling, so will the Style API.

[jlansing]

Would love a status update on this as well. Being able to texture polylines, polygons and circles would be big for us.

[jfirebaugh]

I've updated the issue description with a much expanded description of what a runtime styling API encompasses and what our plans for it are.

[jfirebaugh]

The key parts of the runtime styling API -- mutable sources and layers -- are now implemented in mbgl core. The remaining core work involves testing these more fully and adding a few miscellaneous APIs such as source data mutation for GeoJSON sources, and layer filter accessors.

Part of my testing strategy involves expanding the style-spec driven code generation such that it generates portions of the node bindings for the runtime styling API. This is proving to work well, and I anticipate that code generation will play a key role for the iOS and Android SDKs as well. @mapbox/mobile -- whenever you have bandwidth to start work on this, let me know and I can give you a walkthrough of how I see this working.

[jfirebaugh]

testing these more fully

Done -- see https://github.com/mapbox/mapbox-gl-test-suite/tree/master/render-tests/runtime-styling

source data mutation for GeoJSON sources

This is pending the integration of the new geometry.hpp-based geojson-vt-cpp.

layer filter accessors

Done in 3459b83

Next up: adding and testing node bindings for addSource and addLayer.

[jfirebaugh]

adding and testing node bindings for addSource and addLayer.

Done in #5462.

[1ec5]

• Qt support for runtime styling landed in [Qt] Implement the runtime style API #5642.
• Android support is being designed in Android - Runtime styling Api #5610 and implemented in [Qt] Implement the runtime style API #5642.
• iOS and macOS support is being designed in Runtime styling API for iOS/macOS #5626 and implemented in Runtime styling API for iOS/macOS #5727.

[yhahn]

\o/