Tangram 0.8.0-RC2

[sarahsnow1]

Overview

Upgrades SDK to use the latest Tangram release candidate. This has breaking API changes to MapzenMap as queueSceneUpdate and applySceneUpdates have been removed. This deprecates queueSceneUpdate and applySceneUpdates. The new updateSceneAsync method has been left out of the public interface for now because the primary use cases for the Android SDK should ensure that users don't need to access this method directly. If they want to use it, they still can via MapzenMap#getMapController#updateSceneAsync.

Proposed Changes

Uses new SceneLoadListener callback to create and return a new MapzenMap via the SDK onMapReady callback. Updates the code to ensure that this method is only invoked once. These changes also improve test coverage.

Future work will add marker restoration support

Closes #393

[tallytalwar]

Not part of this PR, but does it make sense to provide a isBuildingExtrude option to mapStateManager. Our house style offers options to control this.

[sarahsnow1]

I'm glad you brought this up and think it would be nice to provide more global options like this. Created tickets in the iOS and Android SDKs for future work to complete this
#431
mapzen/ios#355

[tallytalwar]

Probably make sense to use sceneId and sceneError here in MapReadyInitializer.

SceneID could be used to check if any subsequent load scene/scene update has not being called and for what sceneID the OnMapReadyCallback should be called.

[sarahsnow1]

Because of the way our APIs are setup I don't think this is needed.

The flow the user goes through is either:

1. MapView#getMapAsync(OnMapReadyCallback) or MapFragment#getMapAsync(OnMapReadyCallback)
2. other calls to the map after receiving it in OnMapReadyCallback

We wrap all calls to MapController so it is only after receiving this callback that the user has a MapzenMap and can make additional calls to MapController. This means that the first call we get to onSceneReady is guaranteed to be the one we care about because it is in response to the only call we have made to MapController (unless the user has accessed MapController directly and made calls to it. But this case can lead to breaking other parts of our API that we don't support).

[tallytalwar]

To clarify this controller is only used to load the scene file and the mapController here: https://github.com/mapzen/android/pull/428/files#diff-2b60561f78b9f2ec09d1ebdfd13cd10cR28, will be set for MapzenMap`?

But this mapController in MapReadyInitializer sets a null for the SceneLoadListener so this does not specify any SceneReadyListener for SceneUpdates. Can you clarify where does this listener gets set for a sceneUpdateAsync?

[sarahsnow1]

The reason I set the mapController's SceneLoadListener to null is because:

1. After the initial scene loads, the SDK considers the map "ready" and doesn't want to invoke the OnMapReadyCallback for other calls to change the scene etc (looking at your comment below, I could also update this to check the sceneId)
2. The SDK provides type safety around scene updates (https://github.com/mapzen/android/blob/master/core/src/main/java/com/mapzen/android/graphics/SceneUpdateManager.java) and is tested to ensure the calls to sceneUpdateAsync don't produce errors. I know there has been talk about supporting external scenes but at the moment, the SDK doesn't have first class support for this case. If developers care about errors we expect them to access the MapController directly and set a SceneLoadListener on this object. There will be future discussion around this expansion of the SDK though.

Does this reasoning make sense, are there things I'm not considering properly?

On a related note, I was planning on setting a SceneLoadListener as part of the marker restoration work here though (#348).