1 files changed, 42 insertions, 2 deletions

diff --git a/platform/darwin/src/MGLMapCamera.h b/platform/darwin/src/MGLMapCamera.h
index 7ce5927d1d..f02beb731d 100644
--- a/platform/darwin/src/MGLMapCamera.h
+++ b/platform/darwin/src/MGLMapCamera.h
@@ -49,7 +49,11 @@ MGL_EXPORT
 
 /**
  Returns a new camera with the given distance, pitch, and heading.
-
+ 
+ This method interprets the distance as a straight-line distance from the
+ viewpoint to the center coordinate. To specify the altitude of the viewpoint,
+ use the `-cameraLookingAtCenterCoordinate:altitude:pitch:heading:` method.
+ 
  @param centerCoordinate The geographic coordinate on which the map should be
     centered.
  @param distance The straight-line distance from the viewpoint to the
@@ -63,11 +67,47 @@ MGL_EXPORT
     The value `180` means the top of the map points due south, and so on.
  */
 + (instancetype)cameraLookingAtCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate
-                                   fromDistance:(CLLocationDistance)distance
+                                 acrossDistance:(CLLocationDistance)distance
+                                          pitch:(CGFloat)pitch
+                                        heading:(CLLocationDirection)heading;
+
+/**
+ Returns a new camera with the given altitude, pitch, and heading.
+
+ @param centerCoordinate The geographic coordinate on which the map should be
+    centered.
+ @param altitude The altitude (measured in meters) above the map at which the
+    camera should be situated. The altitude may be less than the distance from
+    the camera’s viewpoint to the camera’s focus point.
+ @param pitch The viewing angle of the camera, measured in degrees. A value of
+    `0` results in a camera pointed straight down at the map. Angles greater
+    than `0` result in a camera angled toward the horizon.
+ @param heading The camera’s heading, measured in degrees clockwise from true
+    north. A value of `0` means that the top edge of the map view corresponds to
+    true north. The value `90` means the top of the map is pointing due east.
+    The value `180` means the top of the map points due south, and so on.
+ */
++ (instancetype)cameraLookingAtCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate
+                                       altitude:(CLLocationDistance)altitude
                                           pitch:(CGFloat)pitch
                                         heading:(CLLocationDirection)heading;
 
 /**
+ @note This initializer incorrectly interprets the `distance` parameter. To
+    specify the straight-line distance from the viewpoint to `centerCoordinate`,
+    use the `-cameraLookingAtCenterCoordinate:acrossDistance:pitch:heading:`
+    method. To specify the altitude of the viewpoint, use the
+    `-cameraLookingAtCenterCoordinate:altitude:pitch:heading:` method, which has
+    the same behavior as this initializer.
+ */
++ (instancetype)cameraLookingAtCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate
+                                   fromDistance:(CLLocationDistance)distance
+                                          pitch:(CGFloat)pitch
+                                        heading:(CLLocationDirection)heading
+__attribute__((deprecated("Use -cameraLookingAtCenterCoordinate:acrossDistance:pitch:heading: "
+                          "or -cameraLookingAtCenterCoordinate:altitude:pitch:heading:.")));
+
+/**
  Returns a Boolean value indicating whether the given camera is functionally
  equivalent to the receiver.