Various user tracking mode corrections

CHANGELOG.md

@@ -55,6 +55,8 @@ Known issues:
 - MGLMapCamera’s `altitude` values now match those of MKMapCamera. ([#3362](https://github.com/mapbox/mapbox-gl-native/pull/3362))
 - MGLMapView properties like `centerCoordinate` and `camera` now offset the center to account for any translucent top or bottom bar. As a result, when user tracking is enabled and the map view is an immediate child of a view controller, the user dot is centered in the unobscured portion of the map view. To override this offset, modify the `contentInset` property; you may also need to set the containing view controller’s `automaticallyAdjustsScrollViewInsets` property to `NO`. ([#3583](https://github.com/mapbox/mapbox-gl-native/pull/3583))
 - In user tracking mode, the user dot stays in a fixed position within MGLMapView while the map pans smoothly. A new property, `userLocationVerticalAlignment`, determines the user dot’s fixed position. ([#3589](https://github.com/mapbox/mapbox-gl-native/pull/3589))
+- When the user tracking mode is set to `MGLUserTrackingModeFollowWithCourse`, an optional `targetCoordinate` is kept within sight at all times as the user changes location. This property, in conjunction with the `userLocationVerticalAlignment` property, may be useful for displaying the user’s progress toward a waypoint. ([#3680](https://github.com/mapbox/mapbox-gl-native/pull/3680))
+- Heading or course tracking mode can now be enabled as soon as an MGLMapView is initialized. ([#3680](https://github.com/mapbox/mapbox-gl-native/pull/3680))
 - Zooming and rotation gestures no longer disable user tracking mode. ([#3589](https://github.com/mapbox/mapbox-gl-native/pull/3589))
 - User tracking mode starts out at a lower zoom level by default. ([#3589](https://github.com/mapbox/mapbox-gl-native/pull/3589))
 - Fixed an issue with small map views not properly fitting annotations within bounds. (#[3407](https://github.com/mapbox/mapbox-gl-native/pull/3407))

include/mbgl/ios/MGLMapView.h

@@ -224,7 +224,12 @@ IB_DESIGNABLE
 @property (nonatomic, readonly, nullable) MGLUserLocation *userLocation;
 
 /** 
- The mode used to track the user location.
+ The mode used to track the user location. The default value is
+ `MGLUserTrackingModeNone`.
+
+ Changing the value of this property updates the map view with an animated
+ transition. If you don’t want to animate the change, use the
+ `-setUserTrackingMode:animated:` method instead.
  */
 @property (nonatomic, assign) MGLUserTrackingMode userTrackingMode;
 
@@ -243,15 +248,70 @@ IB_DESIGNABLE
 /**
  The vertical alignment of the user location annotation within the receiver. The
  default value is `MGLAnnotationVerticalAlignmentCenter`.
+
+ Changing the value of this property updates the map view with an animated
+ transition. If you don’t want to animate the change, use the
+ `-setUserLocationVerticalAlignment:animated:` method instead.
  */
 @property (nonatomic, assign) MGLAnnotationVerticalAlignment userLocationVerticalAlignment;
 
+/**
+ Sets the vertical alignment of the user location annotation within the
+ receiver, with an optional transition.
+
+ @param alignment The vertical alignment of the user location annotation.
+ @param animated If `YES`, the user location annotation animates to its new
+    position within the map view. If `NO`, the user location annotation
+    instantaneously moves to its new position.
+ */
+- (void)setUserLocationVerticalAlignment:(MGLAnnotationVerticalAlignment)alignment animated:(BOOL)animated;
+
 /**
  Whether the map view should display a heading calibration alert when necessary.
  The default value is `YES`.
  */
 @property (nonatomic, assign) BOOL displayHeadingCalibration;
 
+/**
+ The geographic coordinate that is the subject of observation as the user
+ location is being tracked.
+
+ By default, this property is set to an invalid coordinate, indicating that
+ there is no target. In course tracking mode, the target forms one of two foci
+ in the viewport, the other being the user location annotation. Typically, this
+ property is set to a destination or waypoint in a real-time navigation scene.
+ As the user annotation moves toward the target, the map automatically zooms in
+ to fit both foci optimally within the viewport.
+
+ This property has no effect if the `userTrackingMode` property is set to a
+ value other than `MGLUserTrackingModeFollowWithCourse`.
+
+ Changing the value of this property updates the map view with an animated
+ transition. If you don’t want to animate the change, use the
+ `-setTargetCoordinate:animated:` method instead.
+ */
+@property (nonatomic, assign) CLLocationCoordinate2D targetCoordinate;
+
+/**
+ Sets the geographic coordinate that is the subject of observation as the user
+ location is being tracked, with an optional transition animation.
+
+ By default, the target coordinate is set to an invalid coordinate, indicating
+ that there is no target. In course tracking mode, the target forms one of two
+ foci in the viewport, the other being the user location annotation. Typically,
+ the target is set to a destination or waypoint in a real-time navigation scene.
+ As the user annotation moves toward the target, the map automatically zooms in
+ to fit both foci optimally within the viewport.
+
+ This method has no effect if the `userTrackingMode` property is set to a value
+ other than `MGLUserTrackingModeFollowWithCourse`.
+
+ @param targetCoordinate The target coordinate to fit within the viewport.
+ @param animated If `YES`, the map animates to fit the target within the map
+    view. If `NO`, the map fits the target instantaneously.
+ */
+- (void)setTargetCoordinate:(CLLocationCoordinate2D)targetCoordinate animated:(BOOL)animated;
+
 #pragma mark Configuring How the User Interacts with the Map
 
 /**

include/mbgl/map/map.hpp

@@ -130,6 +130,7 @@ class Map : private util::noncopyable {
 
     // Pitch
     void setPitch(double pitch, const Duration& = Duration::zero());
+    void setPitch(double pitch, const PrecisionPoint&, const Duration& = Duration::zero());
     double getPitch() const;
 
     // North Orientation

platform/android/src/jni.cpp

@@ -680,11 +680,12 @@ jdouble JNICALL nativeGetPitch(JNIEnv *env, jobject obj, jlong nativeMapViewPtr)
     return nativeMapView->getMap().getPitch();
 }
 
-void JNICALL nativeSetPitch(JNIEnv *env, jobject obj, jlong nativeMapViewPtr, jdouble pitch, jlong duration) {
+void JNICALL nativeSetPitch(JNIEnv *env, jobject obj, jlong nativeMapViewPtr, jdouble pitch, jlong milliseconds) {
     mbgl::Log::Debug(mbgl::Event::JNI, "nativeGetPitch");
     assert(nativeMapViewPtr != 0);
     NativeMapView *nativeMapView = reinterpret_cast<NativeMapView *>(nativeMapViewPtr);
-    nativeMapView->getMap().setPitch(pitch, mbgl::Milliseconds(duration));
+    mbgl::Duration duration((mbgl::Milliseconds(milliseconds)));
+    nativeMapView->getMap().setPitch(pitch, duration);
 }
 
 void JNICALL nativeScaleBy(JNIEnv *env, jobject obj, jlong nativeMapViewPtr, jdouble ds, jdouble cx,