Add FreeCameraOptions to the Map class

3 files changed, 57 insertions, 2 deletions

diff --git a/include/mbgl/map/camera.hpp b/include/mbgl/map/camera.hpp
index 726c009231..5f723db1cc 100644
--- a/include/mbgl/map/camera.hpp
+++ b/include/mbgl/map/camera.hpp
@@ -1,9 +1,10 @@
 #pragma once
 
-#include <mbgl/util/geo.hpp>
 #include <mbgl/util/chrono.hpp>
-#include <mbgl/util/unitbezier.hpp>
+#include <mbgl/util/geo.hpp>
 #include <mbgl/util/optional.hpp>
+#include <mbgl/util/unitbezier.hpp>
+#include <mbgl/util/vectors.hpp>
 
 #include <functional>
 
@@ -96,4 +97,45 @@ struct AnimationOptions {
         : duration(d) {}
 };
 
+/** Various options for accessing physical properties of the underlying camera entity.
+    A direct access to these properties allows more flexible and precise controlling of the camera
+    while also being fully compatible and interchangeable with CameraOptions. All fields are optional. */
+struct FreeCameraOptions {
+    /** Position of the camera in slightly modified web mercator coordinates
+        - The size of 1 unit is the width of the projected world instead of the "mercator meter".
+          Coordinate [0, 0, 0] is the north-west corner and [1, 1, 0] is the south-east corner.
+        - Z coordinate is conformal and must respect minimum and maximum zoom values.
+        - Zoom is automatically computed from the altitude (z)
+    */
+    optional<vec3> position = nullopt;
+
+    /** Orientation of the camera represented as a unit quaternion [x, y, z, w].
+        The default pose of the camera is such that the forward vector is looking up the -Z axis and
+        the up vector is aligned with north orientation of the map:
+          forward: [0, 0, -1]
+          up:      [0, -1, 0]
+          right    [1, 0, 0]
+
+        Orientation can be set freely but certain constraints still apply
+         - Orientation must be representable with only pitch and bearing.
+         - Pitch has an upper limit */
+    optional<vec4> orientation = nullopt;
+
+    /** Helper function for setting the mercator position as Lat&Lng and altitude in meters */
+    void setLocation(const LatLngAltitude& location);
+
+    /** Helper function for converting mercator position into Lat&Lng and altitude in meters.
+        This function fails to return a value if `position` is invalid or is not set */
+    optional<LatLngAltitude> getLocation() const;
+
+    /** Helper function for setting orientation of the camera by defining a focus point
+        on the map. Up vector is required in certain scenarios where bearing can't be deduced
+        from the viewing direction */
+    void lookAtPoint(const LatLng& location, const optional<vec3>& upVector = nullopt);
+
+    /** Helper function for setting the orientation of the camera as a pitch and a bearing.
+        Both values are in degrees */
+    void setPitchBearing(double pitch, double bearing);
+};
+
 } // namespace mbgl
diff --git a/include/mbgl/map/map.hpp b/include/mbgl/map/map.hpp
index 9aa0cb165e..3c61140eb8 100644
--- a/include/mbgl/map/map.hpp
+++ b/include/mbgl/map/map.hpp
@@ -135,6 +135,14 @@ public:
     bool isFullyLoaded() const;
     void dumpDebugLogs() const;
 
+    // FreeCameraOptions provides more direct access to the underlying camera entity.
+    // For backwards compatibility the state set using this API must be representable with
+    // `CameraOptions` as well. Parameters are clamped to a valid range or discarded as invalid
+    // if the conversion to the pitch and bearing presentation is ambiguous. For example orientation
+    // can be invalid if it leads to the camera being upside down or the quaternion has zero length.
+    void setFreeCameraOptions(const FreeCameraOptions& camera);
+    FreeCameraOptions getFreeCameraOptions() const;
+
 protected:
     class Impl;
     const std::unique_ptr<Impl> impl;
diff --git a/include/mbgl/util/geo.hpp b/include/mbgl/util/geo.hpp
index a653d053f5..ae6c1550fa 100644
--- a/include/mbgl/util/geo.hpp
+++ b/include/mbgl/util/geo.hpp
@@ -241,4 +241,9 @@ public:
     }
 };
 
+struct LatLngAltitude {
+    LatLng location = {0.0, 0.0};
+    double altitude = 0.0;
+};
+
 } // namespace mbgl