[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.

4 files changed, 27 insertions, 14 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;
 
diff --git a/platform/ios/src/MGLMapView.mm b/platform/ios/src/MGLMapView.mm
index 98df29fdd4..23c027b2a1 100644
--- a/platform/ios/src/MGLMapView.mm
+++ b/platform/ios/src/MGLMapView.mm
@@ -1813,14 +1813,14 @@ std::chrono::steady_clock::duration MGLDurationInSeconds(float duration)
 
 - (void)flyToCamera:(MGLMapCamera *)camera completionHandler:(nullable void (^)(void))completion
 {
-    [self flyToCamera:camera withDuration:0 completionHandler:completion];
+    [self flyToCamera:camera withDuration:-1 completionHandler:completion];
 }
 
 - (void)flyToCamera:(MGLMapCamera *)camera withDuration:(NSTimeInterval)duration completionHandler:(nullable void (^)(void))completion
 {
     _mbglMap->cancelTransitions();
     mbgl::CameraOptions options = [self cameraOptionsObjectForAnimatingToCamera:camera];
-    if (duration > 0)
+    if (duration >= 0)
     {
         options.duration = MGLDurationInSeconds(duration);
     }
diff --git a/platform/osx/src/MGLMapView.mm b/platform/osx/src/MGLMapView.mm
index 8767c3041f..e4b86f36db 100644
--- a/platform/osx/src/MGLMapView.mm
+++ b/platform/osx/src/MGLMapView.mm
@@ -1009,14 +1009,14 @@ public:
 }
 
 - (void)flyToCamera:(MGLMapCamera *)camera completionHandler:(nullable void (^)(void))completion {
-    [self flyToCamera:camera withDuration:0 completionHandler:completion];
+    [self flyToCamera:camera withDuration:-1 completionHandler:completion];
 }
 
 - (void)flyToCamera:(MGLMapCamera *)camera withDuration:(NSTimeInterval)duration completionHandler:(nullable void (^)(void))completion {
     _mbglMap->cancelTransitions();
     
     mbgl::CameraOptions options = [self cameraOptionsObjectForAnimatingToCamera:camera];
-    if (duration > 0) {
+    if (duration >= 0) {
         options.duration = MGLDurationInSeconds(duration);
     }
     if (completion) {