NavigationCamera
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.
States
The NavigationCamera
is an entity that offers to maintain 3 distinct NavigationCameraStates: IDLE, FOLLOWING, and OVERVIEW. States can be requested at any point in runtime.
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.
Data
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.
On creation, 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.
Transitions
When 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.
When 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
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:
NavigationBasicGesturesHandler transitions
NavigationCamera
to NavigationCameraState.IDLE when any camera transitions outside of theNavigationCamera
context is started.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.
Debugging
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.
Constructors
Types
Functions
Registers NavigationCameraStateChangedObserver.
Executes a transition to FOLLOWING state. When started, goes to TRANSITION_TO_FOLLOWING and to the final FOLLOWING when ended.
Immediately goes to IDLE state canceling all ongoing transitions.
Executes a transition to OVERVIEW state. When started, goes to TRANSITION_TO_OVERVIEW and to the final OVERVIEW when ended.
If the state is FOLLOWING or OVERVIEW, performs an immediate camera transition (a jump, with animation duration equal to 0
) based on the latest data obtained with ViewportDataSource.getViewportData.
Unregisters NavigationCameraStateChangedObserver.