NavigationCamera

class NavigationCamera(    mapboxMap: MapboxMap,     cameraPlugin: CameraAnimationsPlugin,     viewportDataSource: ViewportDataSource,     stateTransition: NavigationCameraStateTransition = MapboxNavigationCameraStateTransition(mapboxMap, cameraPlugin))

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:

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

Link copied to clipboard
fun NavigationCamera(    mapboxMap: MapboxMap,     cameraPlugin: CameraAnimationsPlugin,     viewportDataSource: ViewportDataSource,     stateTransition: NavigationCameraStateTransition = MapboxNavigationCameraStateTransition(mapboxMap, cameraPlugin))

Types

Link copied to clipboard
object Companion

Functions

fun registerNavigationCameraStateChangeObserver(navigationCameraStateChangedObserver: NavigationCameraStateChangedObserver)
Link copied to clipboard
fun requestNavigationCameraToFollowing(    stateTransitionOptions: NavigationCameraTransitionOptions = DEFAULT_STATE_TRANSITION_OPT,     frameTransitionOptions: NavigationCameraTransitionOptions = DEFAULT_FRAME_TRANSITION_OPT,     transitionEndListener: TransitionEndListener? = null)
fun requestNavigationCameraToFollowing(    stateTransitionOptionsBlock: NavigationCameraTransitionOptions.Builder.() -> Unit,     frameTransitionOptionsBlock: NavigationCameraTransitionOptions.Builder.() -> Unit,     transitionEndListener: TransitionEndListener? = null)

Executes a transition to FOLLOWING state. When started, goes to TRANSITION_TO_FOLLOWING and to the final FOLLOWING when ended.

Link copied to clipboard
fun requestNavigationCameraToIdle()

Immediately goes to IDLE state canceling all ongoing transitions.

Link copied to clipboard
fun requestNavigationCameraToOverview(    stateTransitionOptions: NavigationCameraTransitionOptions = DEFAULT_STATE_TRANSITION_OPT,     frameTransitionOptions: NavigationCameraTransitionOptions = DEFAULT_FRAME_TRANSITION_OPT,     transitionEndListener: TransitionEndListener? = null)
fun requestNavigationCameraToOverview(    stateTransitionOptionsBlock: NavigationCameraTransitionOptions.Builder.() -> Unit,     frameTransitionOptionsBlock: NavigationCameraTransitionOptions.Builder.() -> Unit,     transitionEndListener: TransitionEndListener? = null)

Executes a transition to OVERVIEW state. When started, goes to TRANSITION_TO_OVERVIEW and to the final OVERVIEW when ended.

Link copied to clipboard
fun resetFrame()

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.

fun unregisterNavigationCameraStateChangeObserver(navigationCameraStateChangedObserver: NavigationCameraStateChangedObserver)

Properties

Link copied to clipboard
Link copied to clipboard
val state: NavigationCameraState

Returns current NavigationCameraState.