[ios, osx] Allow zero-duration flight

For consistency with -setCamera:…, a duration of 0 jumps instantaneously to the new location, while a negative value uses the distance-dependent default.

Due to the produced curve and applied easing, flyTo() doesn’t model a parabola or ballistic trajectory, but it does simulate powered flight to some extent.

2 files changed, 23 insertions, 10 deletions

diff --git a/include/mbgl/ios/MGLMapView.h b/include/mbgl/ios/MGLMapView.h
index f9c8296221..32d68aa2cd 100644
--- a/include/mbgl/ios/MGLMapView.h
+++ b/include/mbgl/ios/MGLMapView.h
@@ -218,14 +218,20 @@ IB_DESIGNABLE
 *   @param completion The block to execute after the animation finishes. */
 - (void)setCamera:(MGLMapCamera *)camera withDuration:(NSTimeInterval)duration animationTimingFunction:(nullable CAMediaTimingFunction *)function completionHandler:(nullable void (^)(void))completion;
 
-/** Uses a ballistic parabolic motion to "fly" the viewpoint to a different location with respect to the map with a default duration based on the length of the flight path.
+/** Moves the viewpoint to a different location using a transition animation that evokes powered flight and a default duration based on the length of the flight path.
+*
+*   The transition animation seamlessly incorporates zooming and panning to help the user find his or her bearings even after traversing a great distance.
+*
 *   @param camera The new viewpoint.
 *   @param completion The block to execute after the animation finishes. */
 - (void)flyToCamera:(MGLMapCamera *)camera completionHandler:(nullable void (^)(void))completion;
 
-/** Uses a ballistic parabolic motion to "fly" the viewpoint to a different location with respect to the map with an optional transition duration.
+/** Moves the viewpoint to a different location using a transition animation that evokes powered flight and an optional transition duration.
+*
+*   The transition animation seamlessly incorporates zooming and panning to help the user find his or her bearings even after traversing a great distance.
+*
 *   @param camera The new viewpoint.
-*   @param duration The amount of time, measured in seconds, that the transition animation should take. Specify `0` to use the default duration, which is based on the length of the flight path.
+*   @param duration The amount of time, measured in seconds, that the transition animation should take. Specify `0` to jump to the new viewpoint instantaneously. Specify a negative value to use the default duration, which is based on the length of the flight path.
 *   @param completion The block to execute after the animation finishes. */
 - (void)flyToCamera:(MGLMapCamera *)camera withDuration:(NSTimeInterval)duration completionHandler:(nullable void (^)(void))completion;
 
diff --git a/include/mbgl/osx/MGLMapView.h b/include/mbgl/osx/MGLMapView.h
index 40fd2a6bc4..6f46825448 100644
--- a/include/mbgl/osx/MGLMapView.h
+++ b/include/mbgl/osx/MGLMapView.h
@@ -249,21 +249,28 @@ IB_DESIGNABLE
     @param completion The block to execute after the animation finishes. */
 - (void)setCamera:(MGLMapCamera *)camera withDuration:(NSTimeInterval)duration animationTimingFunction:(nullable CAMediaTimingFunction *)function completionHandler:(nullable void (^)(void))completion;
 
-/** Uses a ballistic parabolic motion to “fly” the viewpoint to a different
-    location with respect to the map with a default duration based on the length
-    of the flight path.
+/** Moves the viewpoint to a different location using a transition animation
+    that evokes powered flight and a default duration based on the length of the
+    flight path.
+    
+    The transition animation seamlessly incorporates zooming and panning to help
+    the user find his or her bearings even after traversing a great distance.
     
     @param camera The new viewpoint.
     @param completion The block to execute after the animation finishes. */
 - (void)flyToCamera:(MGLMapCamera *)camera completionHandler:(nullable void (^)(void))completion;
 
-/** Uses a ballistic parabolic motion to “fly” the viewpoint to a different
-    location with respect to the map with an optional transition duration.
+/** Moves the viewpoint to a different location using a transition animation
+    that evokes powered flight and an optional transition duration.
+    
+    The transition animation seamlessly incorporates zooming and panning to help
+    the user find his or her bearings even after traversing a great distance.
     
     @param camera The new viewpoint.
     @param duration The amount of time, measured in seconds, that the transition
-        animation should take. Specify `0` to use the default duration, which is
-        based on the length of the flight path.
+        animation should take. Specify `0` to jump to the new viewpoint
+        instantaneously. Specify a negative value to use the default duration,
+        which is based on the length of the flight path.
     @param completion The block to execute after the animation finishes. */
 - (void)flyToCamera:(MGLMapCamera *)camera withDuration:(NSTimeInterval)duration completionHandler:(nullable void (^)(void))completion;