sprint-plan.md

Sprint Planning

Background & Questions

• Understand paint classes, updatePaintTransitions, Style#_recalculate/StyleLayer#recalculate
• Read through Camera
• jfirebaugh proposed adding camera state as top-level property of style; add to style spec? If yes, how about map z and lnglat constraints as well?

Get it working: integrate style diff with existing API

Goal: make map.setStyle({ layers: [ ..., { one layout property different from map's current style } ] }) as good as map.setLayoutProperty() (modulo a pretty cheap diff)

This seems pretty immediately doable and quick (unless maybe updating unit tests requires a lot of reworking).

• Add mapbox-gl-style-spec's diff implementation as Style#setState.
• Change Map#setStyle to delegate to Style#setState (instead of constructing a new Style instance).
• Mod setStyle to accept partial state (are undefined properties treated as meaningful falsy values?)
• Add a React example to validate and demonstrate the setStyle API

Refactor

Goal: Further separate concerns of state management and user-facing map-manipulation API (Map#setXxxYyy()). Also start moving in the direction of jfirebaugh's proposal mapbox/mapbox-gl-js#1989 (comment)

Before diving in on this and possibly even before "Get it working," I should post up a more detailed proposal for the resulting architecture & API for discussion.

• Change style-mutating Map methods to use Style#setState and make the corresponding Style methods private.
  • Methods: Map#{add,move,remove}Layer, Map#{add,remove}Source, Map#set{Layout,Paint}Property, Map#setFilter, Map#setLayerZoomRange, Map#setLight
  • This should bring Style's internally-public API down to { setState: (partialState: obj) => void, update: (options: obj) => void }, where setState queues a state change and update applies all queued state changes.
  • What happens to Map#getLayer?
• Defer the actual work of diffing/applying changes to Style#update, as it need only be performed once per batch.
  • Remove batching stuff from addLayer, setLayoutProperty, etc. -- these should now just be helpers that directly/immediately mutate Style's internal state
  • By the way: if this only happens once per batch, I wonder whether requiring the input to setState to be immutable is going to add much, perf-wise; worth checking out before taking on a dependency like Immutable.js.
• Pull the style-controlling API into a separate mixin rather than keeping them on Map
• Remove 'paint classes' (How invasive is this? And is it okay to break, or should it be deprecated?)
• Consolidate camera/transform state into Style. This may be out of scope (need to read through Camera to know better)
  • Accept camera/transform state as top-level setState property (includes zoom, center, pitch, bearing, minzoom, maxzoom, lngRange, latRange)
  • Move transform-mutating stuff from Camera to Style
  • Refactor Camera methods to use Style#setState
    • tricky thing here is transitions; can Camera's multi-frame easing code be reworked to use setState efficiently?

Other / Tangential

• Propose addition of Source#update to the Source interface
• Propose decoupling style-update batching from render (TODO: describe relevant observations from WaPo perf work)