NavigationCamera is a class that tries to simplify management of the Map's camera object in typical navigation scenarios. It's fed camera frames via the ViewportDataSource, generates transitions with NavigationCameraStateTransition and executes them.
NavigationCamera's lifecycle can't exceed the lifecycle of the MapboxMap (or indirectly MapView) that it's attached to without risking reference leaks.
When the camera is transitioning between states, it reports that status with TRANSITION_TO_FOLLOWING and TRANSITION_TO_OVERVIEW helper states. These helper transition states cannot be directly requested.
Change to IDLE state is always instantaneous.
In order to be able to perform state transitions or later frame updates, the
NavigationCamera needs data. This is provided by the ViewportDataSource argument. The source is an observable interface that produces
CameraOptions that frame the camera for both FOLLOWING and OVERVIEW states.
NavigationCamera subscribes to the data source and listens for updates.
MapboxNavigationViewportDataSource is a default implementation of the source that helps to generate camera frames based on the current route’s geometry, road's graph, trip's progress, etc.
NavigationCamera is supplied with data and a state request, it invokes the NavigationCameraStateTransition that generates a set of Map SDK CameraAnimators that perform the transition to the desired camera position created by the data source.
When a state is requested,
NavigationCamera takes the latest computed ViewportData values and passes them to the NavigationCameraStateTransition to create the NavigationCameraStateTransition.transitionToFollowing or NavigationCameraStateTransition.transitionToOverview transitions.
NavigationCamera already is in one of the FOLLOWING or OVERVIEW states, data source updates trigger creation of NavigationCameraStateTransition.updateFrameForFollowing or NavigationCameraStateTransition.updateFrameForOverview transitions.
After generating the transitions,
NavigationCamera handles registering them to Maps SDK, executing, listening for cancellation, adjusting states, etc.
Gestures and other camera interactions
When FOLLOWING or OVERVIEW states are engaged, the
NavigationCamera assumes full ownership of the CameraAnimationsPlugin. This means that if any other camera transition is scheduled outside of the
NavigationCamera’s context, there might be side-effects or glitches. Consequently, if you want to perform other camera transitions, first call requestNavigationCameraToIdle, and only after that perform the desired transition.
Alternatively, you can use one of the default implementations of CameraAnimationsLifecycleListener that automate the response of the
NavigationCamera for gesture interactions and other camera animations:
NavigationScaleGestureHandler behaves as above, but allows for executing various scale gestures to manipulate the camera's zoom level when in NavigationCameraState.FOLLOWING without immediately falling back to NavigationCameraState.IDLE.
If you are using the MapboxNavigationViewportDataSource instance, you can use debugger to provide a MapboxNavigationViewportDataSourceDebugger instance which will draw various info on the screen when the NavigationCamera operates to together with the MapboxNavigationViewportDataSource.
Make sure to also provide the same instance to MapboxNavigationViewportDataSource.debugger.