[core] Standardize transform origin

All Transform methods that take a PrecisionPoint now assume a “flipped” origin at the upper-left corner of the view. Previously, some methods assumed an origin at the lower-left corner.

3 files changed, 58 insertions, 44 deletions

diff --git a/src/mbgl/map/transform.cpp b/src/mbgl/map/transform.cpp
index da99d64fc2..dc541bc391 100644
--- a/src/mbgl/map/transform.cpp
+++ b/src/mbgl/map/transform.cpp
@@ -153,26 +153,25 @@ double Transform::getScale() const {
     return state.scale;
 }
 
-void Transform::setScale(double scale, const PrecisionPoint& anchor, const Duration& duration) {
+void Transform::setScale(double scale, const PrecisionPoint& flippedAnchor, const Duration& duration) {
     if (std::isnan(scale)) {
         return;
     }
     
-    const double factor = scale / state.scale;
-    PrecisionPoint offset = { 0, 0 };
-    PrecisionPoint center = {
-        state.width / 2.0f,
-        state.height / 2.0f,
-    };
-    if (anchor) {
-        offset = {
-            anchor.x - center.x,
-            center.y - anchor.y,
+    CameraOptions camera;
+    if (flippedAnchor) {
+        const double factor = scale / state.scale;
+        PrecisionPoint center = {
+            state.width / 2.0,
+            state.height / 2.0,
+        };
+        PrecisionPoint anchor = {
+            flippedAnchor.x,
+            state.height - flippedAnchor.y,
         };
+        PrecisionPoint offset = anchor - center;
+        camera.center = state.pointToLatLng(anchor - offset / factor);
     }
-
-    CameraOptions camera;
-    camera.center = state.pointToLatLng(center + offset / factor);
     camera.zoom = state.scaleZoom(scale);
     easeTo(camera, duration);
 }
@@ -203,15 +202,6 @@ void Transform::easeTo(const CameraOptions& camera, const AnimationOptions& anim
         }
     }
     
-    const PrecisionPoint startPoint = {
-        state.lngX(startLatLng.longitude),
-        state.latY(startLatLng.latitude),
-    };
-    const PrecisionPoint endPoint = {
-        state.lngX(latLng.longitude),
-        state.latY(latLng.latitude),
-    };
-    
     Update update = state.getZoom() == zoom ? Update::Repaint : Update::Zoom;
     
     // Constrain camera options.
@@ -255,15 +245,11 @@ void Transform::easeTo(const CameraOptions& camera, const AnimationOptions& anim
                 return ease.solve(t, 0.001);
             },
             [=](double t) {
-                // Calculate the current point and zoom level along the flight path.
-                PrecisionPoint framePoint = util::interpolate(startPoint, endPoint, t);
-                double frameScale = util::interpolate(startScale, scale, t);
-                
-                // Convert to geographic coordinates and set the new viewpoint.
                 LatLng frameLatLng = {
-                    state.yLat(framePoint.y, startWorldSize),
-                    state.xLng(framePoint.x, startWorldSize),
+                    util::interpolate(startLatLng.latitude, latLng.latitude, t),
+                    util::interpolate(startLatLng.longitude, latLng.longitude, t),
                 };
+                double frameScale = util::interpolate(startScale, scale, t);
                 state.setLatLngZoom(frameLatLng, state.scaleZoom(frameScale));
                 
                 if (angle != startAngle) {
@@ -523,24 +509,28 @@ void Transform::setAngle(double angle, const Duration& duration) {
     setAngle(angle, {NAN, NAN}, duration);
 }
 
-void Transform::setAngle(double angle, const PrecisionPoint& center, const Duration& duration) {
+void Transform::setAngle(double angle, const PrecisionPoint& flippedAnchor, const Duration& duration) {
     if (std::isnan(angle)) {
         return;
     }
 
-    LatLng rotationCenter;
+    PrecisionPoint anchor = {
+        flippedAnchor.x,
+        state.height - flippedAnchor.y,
+    };
+    LatLng anchorLatLng;
 
-    if (center) {
-        rotationCenter = state.pointToLatLng(center);
-        setLatLng(rotationCenter);
+    if (flippedAnchor) {
+        anchorLatLng = state.pointToLatLng(anchor);
+        setLatLng(anchorLatLng);
     }
     
     CameraOptions camera;
     camera.angle = angle;
     easeTo(camera, duration);
 
-    if (center) {
-        setLatLng(rotationCenter, center);
+    if (flippedAnchor) {
+        setLatLng(anchorLatLng, anchor);
     }
 }
 
diff --git a/src/mbgl/map/transform.hpp b/src/mbgl/map/transform.hpp
index 52e3b3e627..b8dd808f58 100644
--- a/src/mbgl/map/transform.hpp
+++ b/src/mbgl/map/transform.hpp
@@ -26,28 +26,54 @@ public:
 
     void jumpTo(const CameraOptions&);
     void easeTo(const CameraOptions&, const AnimationOptions& = {});
-    /** Smoothly zoom out, pan, and zoom back into the given camera along a
+    /** Smoothly zooms out, pan, and zoom back into the given camera along a
         great circle, as though the viewer is aboard a supersonic jetcopter. */
     void flyTo(const CameraOptions&, const AnimationOptions& = {});
 
     // Position
-    void moveBy(const PrecisionPoint&, const Duration& = Duration::zero());
+    
+    /** Pans the map by the given amount.
+        @param offset The distance to pan the map by, measured in pixels from
+            top to bottom and from left to right. */
+    void moveBy(const PrecisionPoint& offset, const Duration& = Duration::zero());
     void setLatLng(const LatLng&, const Duration& = Duration::zero());
     void setLatLng(const LatLng&, const PrecisionPoint&, const Duration& = Duration::zero());
     void setLatLngZoom(const LatLng&, double zoom, const Duration& = Duration::zero());
     LatLng getLatLng() const { return state.getLatLng(); }
 
     // Zoom
-    void scaleBy(double ds, const PrecisionPoint& center = {NAN, NAN}, const Duration& = Duration::zero());
-    void setScale(double scale, const PrecisionPoint& center = {NAN, NAN}, const Duration& = Duration::zero());
+
+    /** Scales the map, keeping the given point fixed within the view.
+        @param ds The difference in scale factors to scale the map by.
+        @param anchor A point relative to the top-left corner of the view. */
+    void scaleBy(double ds, const PrecisionPoint& anchor = {NAN, NAN}, const Duration& = Duration::zero());
+    /** Sets the scale factor, keeping the given point fixed within the view.
+        @param scale The new scale factor.
+        @param anchor A point relative to the top-left corner of the view. */
+    void setScale(double scale, const PrecisionPoint& anchor = {NAN, NAN}, const Duration& = Duration::zero());
+    /** Sets the zoom level.
+        @param zoom The new zoom level. */
     void setZoom(double zoom, const Duration& = Duration::zero());
+    /** Returns the zoom level. */
     double getZoom() const;
+    /** Returns the scale factor. */
     double getScale() const;
 
     // Angle
+
     void rotateBy(const PrecisionPoint& first, const PrecisionPoint& second, const Duration& = Duration::zero());
+    /** Sets the angle of rotation.
+        @param angle The new angle of rotation, measured in radians
+            counterclockwise from true north. */
     void setAngle(double angle, const Duration& = Duration::zero());
-    void setAngle(double angle, const PrecisionPoint& center, const Duration& = Duration::zero());
+    /** Sets the angle of rotation, keeping the given point fixed within the view.
+        @param angle The new angle of rotation, measured in radians
+            counterclockwise from true north.
+        @param anchor A point relative to the top-left corner of the view. */
+    void setAngle(double angle, const PrecisionPoint& anchor, const Duration& = Duration::zero());
+    /** Returns the angle of rotation.
+        @return The angle of rotation, measured in radians counterclockwise from
+            true north. */
     double getAngle() const;
 
     // Pitch
diff --git a/src/mbgl/map/transform_state.cpp b/src/mbgl/map/transform_state.cpp
index 376424c74c..9d01657494 100644
--- a/src/mbgl/map/transform_state.cpp
+++ b/src/mbgl/map/transform_state.cpp
@@ -396,5 +396,3 @@ void TransformState::setScalePoint(const double newScale, const PrecisionPoint &
     Bc = worldSize() / 360;
     Cc = worldSize() / util::M2PI;
 }
-
-