diff options
Diffstat (limited to 'include')
-rw-r--r-- | include/mbgl/map/camera.hpp | 46 | ||||
-rw-r--r-- | include/mbgl/map/map.hpp | 8 | ||||
-rw-r--r-- | include/mbgl/util/geo.hpp | 5 |
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 |