[iOS][macOS] Export `MGLImageSource`, add and update documentation. Use animated ImageSource demo in iOS test app

7 files changed, 85 insertions, 116 deletions

diff --git a/platform/darwin/src/MGLGeometry.h b/platform/darwin/src/MGLGeometry.h
index 003a7638e7..3a3e59fb3e 100644
--- a/platform/darwin/src/MGLGeometry.h
+++ b/platform/darwin/src/MGLGeometry.h
@@ -48,17 +48,18 @@ typedef struct MGLCoordinateBounds {
 /** 
  A quadrilateral area as measured on a two-dimensional map projection.
  `MGLCoordinateQuad` differs from `MGLCoordinateBounds` in that it allows
- representation of non-axis aligned bounds and non-rectangular quadrilaterals
+ representation of non-axis aligned bounds and non-rectangular quadrilaterals.
+ The coordinates are described in counter clockwise order from top left.
  */
 typedef struct MGLCoordinateQuad {
     /** Coordinate at the top left corner. */
     CLLocationCoordinate2D topLeft;
-    /** Coordinate at the top right corner. */
-    CLLocationCoordinate2D topRight;
-    /** Coordinate at the bottom right corner. */
-    CLLocationCoordinate2D bottomRight;
     /** Coordinate at the bottom left corner. */
     CLLocationCoordinate2D bottomLeft;
+    /** Coordinate at the bottom right corner. */
+    CLLocationCoordinate2D bottomRight;
+    /** Coordinate at the top right corner. */
+    CLLocationCoordinate2D topRight;
 } MGLCoordinateQuad;
 
 
@@ -73,6 +74,33 @@ NS_INLINE MGLCoordinateBounds MGLCoordinateBoundsMake(CLLocationCoordinate2D sw,
     return bounds;
 }
 
+/**
+ Creates a new `MGLCoordinateQuad` structure from the given top left,
+  bottom left, bottom right, and top right coordinates.
+ */
+NS_INLINE MGLCoordinateQuad MGLCoordinateQuadMake(CLLocationCoordinate2D topLeft, CLLocationCoordinate2D bottomLeft, CLLocationCoordinate2D bottomRight, CLLocationCoordinate2D topRight) {
+    MGLCoordinateQuad quad;
+    quad.topLeft = topLeft;
+    quad.bottomLeft = bottomLeft;
+    quad.bottomRight = bottomRight;
+    quad.topRight = topRight;
+    return quad;
+}
+
+/**
+ Creates a new `MGLCoordinateQuad` structure from the given `MGLCoordinateBounds`.
+ The returned quad uses the bounds' northeast coordinate as the top right, and the
+  southwest coordinate at the bottom left.
+ */
+NS_INLINE MGLCoordinateQuad MGLCoordinateQuadFromCoordinateBounds(MGLCoordinateBounds bounds) {
+    MGLCoordinateQuad quad;
+    quad.topLeft = CLLocationCoordinate2DMake(bounds.ne.latitude, bounds.sw.longitude);
+    quad.bottomLeft = bounds.sw;
+    quad.bottomRight = CLLocationCoordinate2DMake(bounds.sw.latitude, bounds.ne.longitude);
+    quad.topRight = bounds.ne;
+    return quad;
+}
+
 /** Returns `YES` if the two coordinate bounds are equal to each other. */
 NS_INLINE BOOL MGLCoordinateBoundsEqualToCoordinateBounds(MGLCoordinateBounds bounds1, MGLCoordinateBounds bounds2) {
     return (bounds1.sw.latitude == bounds2.sw.latitude &&
@@ -134,6 +162,15 @@ NS_INLINE NSString *MGLStringFromCoordinateBounds(MGLCoordinateBounds bounds) {
             bounds.ne.latitude, bounds.ne.longitude];
 }
 
+/** Returns a formatted string for the given coordinate quad. */
+NS_INLINE NSString *MGLStringFromCoordinateQuad(MGLCoordinateQuad quad) {
+    return [NSString stringWithFormat:@"{ topleft = {%.1f, %.1f}, bottomleft = {%.1f, %.1f}}, bottomright = {%.1f, %.1f}, topright = {%.1f, %.1f}",
+            quad.topLeft.latitude, quad.topLeft.longitude,
+            quad.bottomLeft.latitude, quad.bottomLeft.longitude,
+            quad.bottomRight.latitude, quad.bottomRight.longitude,
+            quad.topRight.latitude, quad.topRight.longitude];
+}
+
 /** Returns radians, converted from degrees. */
 NS_INLINE CGFloat MGLRadiansFromDegrees(CLLocationDegrees degrees) {
     return (CGFloat)(degrees * M_PI) / 180;
diff --git a/platform/darwin/src/MGLGeometry_Private.h b/platform/darwin/src/MGLGeometry_Private.h
index bdc838667a..88fcf5b576 100644
--- a/platform/darwin/src/MGLGeometry_Private.h
+++ b/platform/darwin/src/MGLGeometry_Private.h
@@ -66,16 +66,9 @@ NS_INLINE std::array<mbgl::LatLng, 4> MGLLatLngArrayFromCoordinateQuad(MGLCoordi
 
 NS_INLINE MGLCoordinateQuad MGLCoordinateQuadFromLatLngArray(std::array<mbgl::LatLng, 4> quad) {
     return { MGLLocationCoordinate2DFromLatLng(quad[0]),
-    MGLLocationCoordinate2DFromLatLng(quad[1]),
+    MGLLocationCoordinate2DFromLatLng(quad[3]),
     MGLLocationCoordinate2DFromLatLng(quad[2]),
-    MGLLocationCoordinate2DFromLatLng(quad[3]) };
-}
-
-NS_INLINE MGLCoordinateQuad MGLCoordinateQuadFromCoordinateBounds(MGLCoordinateBounds bounds) {
-    return { { bounds.ne.latitude, bounds.sw.longitude },
-    bounds.ne,
-    { bounds.sw.latitude, bounds.ne.longitude },
-    bounds.sw };
+    MGLLocationCoordinate2DFromLatLng(quad[1]) };
 }
 
 #if TARGET_OS_IPHONE
diff --git a/platform/darwin/src/MGLImageSource.h b/platform/darwin/src/MGLImageSource.h
index 9ef2c6719a..21487d9739 100644
--- a/platform/darwin/src/MGLImageSource.h
+++ b/platform/darwin/src/MGLImageSource.h
@@ -8,12 +8,17 @@ NS_ASSUME_NONNULL_BEGIN
 
 MGL_EXPORT
 /**
- `MGLImageSource` is a map content source that supplies a georeferenced raster
- image to be shown on the map. The geographic location of the raster image content, 
- supplied with `MGLCoordinateQuad`, can be non-axis aligned.
- `MGLImageSource` supports raster content from `NSURL` or an `MGLImage`.
- Supported image formats are : PNG, TIFF, JPEG, GIF (single frame rendering),
- and BMP.
+ `MGLImageSource` is a content source that is used for a georeferenced raster
+ image to be shown on the map. The georeferenced image scales and rotates as the
+ user zooms and rotates the map. Images may also be used as icons or patterns 
+ in a style layer. To register an image for use as an icon or pattern, 
+ use the `-[MGLStyle setImage:forName:]` method. To configure a point 
+ annotation’s image, use the `MGLAnnotationImage` class.
+ 
+ The geographic location of the raster image content, supplied with 
+ `MGLCoordinateQuad`, can be non-axis aligned.
+ `MGLImageSource` supports raster content from `NSURL`, `NSImage` (macOS), or 
+ `UIImage` (iOS).
  An image source is added to an `MGLStyle` object along with one or more
  `MGLRasterStyleLayer` objects. Use a raster style layer to control the
  appearance of content supplied by the image source.
@@ -28,30 +33,22 @@ MGL_EXPORT
  ### Example
 
  ```swift
- let coordinates: MGLCoordinateQuad = MGLCoordinateQuad(
+ let coordinates = MGLCoordinateQuad(
    topLeft: CLLocationCoordinate2D(latitude: 46.437, longitude: -80.425),
-   topRight: CLLocationCoordinate2D(latitude: 46.437, longitude: -71.516),
+   bottomLeft: CLLocationCoordinate2D(latitude: 37.936, longitude: -80.425),
    bottomRight: CLLocationCoordinate2D(latitude: 37.936, longitude: -71.516),
-   bottomLeft: CLLocationCoordinate2D(latitude: 37.936, longitude: -80.425))
- let source = MGLImageSource(identifier: "images", coordinates: coordinates, imageURL: URL(string: "https://www.mapbox.com/mapbox-gl-js/assets/radar.gif")!)
+   topRight: CLLocationCoordinate2D(latitude: 46.437, longitude: -71.516))
+ let source = MGLImageSource(identifier: "radar", coordinateQuad: coordinates, url: URL(string: "https://www.mapbox.com/mapbox-gl-js/assets/radar.gif")!)
  mapView.style?.addSource(source)
  ```
  */
+MGL_EXPORT
 @interface MGLImageSource : MGLSource
 
 #pragma mark Initializing a Source
 
 /**
- Returns a georeferenced image source with an identifier and coordinates
-
- @param identifier A string that uniquely identifies the source.
- @param coordinateQuad The top left, top right, bottom right, and bottom left coordinates for the image.
- @return An initialized image source.
- */
-- (instancetype)initWithIdentifier:(NSString *)identifier coordinates:(MGLCoordinateQuad)coordinateQuad NS_DESIGNATED_INITIALIZER;
-
-/**
- Returns a georeferenced image source with an identifier, coordinates and a URL
+ Returns a georeferenced image source with an identifier, coordinates and a URL.
 
  @param identifier A string that uniquely identifies the source.
  @param coordinateQuad the top left, top right, bottom right, and bottom left coordinates for the image.
@@ -59,75 +56,37 @@ MGL_EXPORT
     current application’s resource bundle.
  @return An initialized shape source.
  */
-- (instancetype)initWithIdentifier:(NSString *)identifier coordinates:(MGLCoordinateQuad)coordinateQuad imageURL:(NSURL *)url;
+- (instancetype)initWithIdentifier:(NSString *)identifier coordinateQuad:(MGLCoordinateQuad)coordinateQuad URL:(NSURL *)url;
 
 /**
- Returns a georeferenced image source with an identifier, coordinates and an image
+ Returns a georeferenced image source with an identifier, coordinates and an image.
 
  @param identifier A string that uniquely identifies the source.
  @param coordinateQuad The top left, top right, bottom right, and bottom left coordinates for the image.
- @param image The image to display for the sourcde.
+ @param image The image to display for the source.
  @return An initialized shape source.
  */
-- (instancetype)initWithIdentifier:(NSString *)identifier coordinates:(MGLCoordinateQuad)coordinateQuad image:(MGLImage *)image;
-
-/**
- Returns a georeferenced image source with an identifier and coordinates
-
- @param identifier A string that uniquely identifies the source.
- @param bounds The aligned coordinate bounds for the image.
- @return An initialized image source.
- */
-- (instancetype)initWithIdentifier:(NSString *)identifier bounds:(MGLCoordinateBounds)bounds;
-
-/**
- Returns a georeferenced image source with an identifier, coordinates and a URL
-
- @param identifier A string that uniquely identifies the source.
- @param bounds The aligned coordinate bounds for the image.@param url An HTTP(S) URL, absolute file URL, or local file URL relative to the
-    current application’s resource bundle.
- @return An initialized shape source.
- */
-- (instancetype)initWithIdentifier:(NSString *)identifier bounds:(MGLCoordinateBounds)bounds imageURL:(NSURL *)url;
-
-/**
- Returns a georeferenced image source with an identifier, coordinates and an image
-
- @param identifier A string that uniquely identifies the source.
- @param bounds The aligned coordinate bounds for the image.
- @param image The image to display for the sourcde.
- @return An initialized shape source.
- */
-- (instancetype)initWithIdentifier:(NSString *)identifier bounds:(MGLCoordinateBounds)bounds image:(MGLImage *)image;
+- (instancetype)initWithIdentifier:(NSString *)identifier coordinateQuad:(MGLCoordinateQuad)coordinateQuad image:(MGLImage *)image;
 
 #pragma mark Accessing a Source’s Content
 
 /**
  The URL to the source image.
 
- If the receiver was initialized using `-initWithIdentifier:coordinates:` or 
- `-initWithIdentifier:coordinates:image:`, or the `image` property is set,
- this property is set to `nil`.
+ If the receiver was initialized using `-initWithIdentifier:coordinateQuad:image:` or
+ the `image` property is set, this property is set to `nil`.
  */
 @property (nonatomic, copy, nullable)NSURL *URL;
 
 /**
  The source image.
 
- If the receiver was initialized using `-initWithIdentifier:coordinates:` or 
- `-initWithIdentifier:coordinates:imageURL:`, or if the `URL` property is set,
- this property is set to `nil`.
- 
-
+ If the receiver was initialized using `-initWithIdentifier:coordinateQuad:URL:` or if the `URL` property is set, this property is set to `nil`.
  */
 @property (nonatomic, retain, nullable)MGLImage *image;
 
 /**
- The coordinates at which the source image will be placed.
-
- If the receiver was initialized using `-initWithIdentifier:bounds:`,
- `-initWithIdentifier:bounds:image:`, or `initWithIdentifier:bounds:imageURL`,
- the bounds will be converted to an `MGLCoordinateQuad`.
+ The coordinates at which the corners of the source image will be placed.
  */
 @property (nonatomic) MGLCoordinateQuad coordinates;
 @end
diff --git a/platform/darwin/src/MGLImageSource.mm b/platform/darwin/src/MGLImageSource.mm
index 9872a65aff..0a2dc2713f 100644
--- a/platform/darwin/src/MGLImageSource.mm
+++ b/platform/darwin/src/MGLImageSource.mm
@@ -1,4 +1,4 @@
-#import "MGLImageSource_Private.h"
+#import "MGLImageSource.h"
 
 #import "MGLGeometry_Private.h"
 #import "MGLSource_Private.h"
@@ -14,6 +14,7 @@
 #include <mbgl/util/premultiply.hpp>
 
 @interface MGLImageSource ()
+- (instancetype)initWithIdentifier:(NSString *)identifier coordinateQuad:(MGLCoordinateQuad)coordinateQuad NS_DESIGNATED_INITIALIZER;
 
 @property (nonatomic, readonly) mbgl::style::ImageSource *rawSource;
 
@@ -21,7 +22,7 @@
 
 @implementation MGLImageSource
 
-- (instancetype)initWithIdentifier:(NSString *)identifier coordinates:(MGLCoordinateQuad)coordinateQuad {
+- (instancetype)initWithIdentifier:(NSString *)identifier coordinateQuad:(MGLCoordinateQuad)coordinateQuad {
 
     const auto coordsArray = MGLLatLngArrayFromCoordinateQuad(coordinateQuad);
     auto source = std::make_unique<mbgl::style::ImageSource>(identifier.UTF8String, coordsArray);
@@ -29,35 +30,20 @@
 }
 
 
-- (instancetype)initWithIdentifier:(NSString *)identifier coordinates:(MGLCoordinateQuad)coordinateQuad imageURL:(NSURL *)url {
-    self =  [self initWithIdentifier:identifier coordinates: coordinateQuad];
+- (instancetype)initWithIdentifier:(NSString *)identifier coordinateQuad:(MGLCoordinateQuad)coordinateQuad URL:(NSURL *)url {
+    self =  [self initWithIdentifier:identifier coordinateQuad: coordinateQuad];
     self.URL = url;
     return self;
 }
 
 
-- (instancetype)initWithIdentifier:(NSString *)identifier coordinates:(MGLCoordinateQuad)coordinateQuad image:(MGLImage *)image {
-    self =  [self initWithIdentifier:identifier coordinates: coordinateQuad];
+- (instancetype)initWithIdentifier:(NSString *)identifier coordinateQuad:(MGLCoordinateQuad)coordinateQuad image:(MGLImage *)image {
+    self =  [self initWithIdentifier:identifier coordinateQuad: coordinateQuad];
     self.image = image;
 
     return self;
 }
 
-- (instancetype)initWithIdentifier:(NSString *)identifier bounds:(MGLCoordinateBounds)bounds {
-    self = [self initWithIdentifier:identifier coordinates:MGLCoordinateQuadFromCoordinateBounds(bounds)];
-    return self;
-}
-
-- (instancetype)initWithIdentifier:(NSString *)identifier bounds:(MGLCoordinateBounds)bounds imageURL:(NSURL *)url {
-    self = [self initWithIdentifier:identifier coordinates:MGLCoordinateQuadFromCoordinateBounds(bounds) imageURL:url];
-    return self;
-}
-
-- (instancetype)initWithIdentifier:(NSString *)identifier bounds:(MGLCoordinateBounds)bounds image:(MGLImage *)image {
-    self = [self initWithIdentifier:identifier coordinates:MGLCoordinateQuadFromCoordinateBounds(bounds) image:image];
-    return self;
-}
-
 - (NSURL *)URL {
     auto url = self.rawSource->getURL();
     return url ? [NSURL URLWithString:@(url->c_str())] : nil;
@@ -74,8 +60,10 @@
 
 - (void)setImage:(MGLImage *)image {
     if (image != nullptr) {
-        mbgl::UnassociatedImage unassociatedImage = mbgl::util::unpremultiply(image.mgl_PremultipliedImage);
+        mbgl::UnassociatedImage unassociatedImage = mbgl::util::unpremultiply(image.mgl_premultipliedImage);
         self.rawSource->setImage(std::move(unassociatedImage));
+    } else {
+        self.rawSource->setImage(mbgl::UnassociatedImage({0,0}));
     }
     _image = image;
 }
@@ -89,8 +77,8 @@
 }
 
 - (NSString *)description {
-    return [NSString stringWithFormat:@"<%@: %p; identifier = %@; URL = %@; image = %@>",
-            NSStringFromClass([self class]), (void *)self, self.identifier, self.URL, self.image];
+    return [NSString stringWithFormat:@"<%@: %p; identifier = %@; coordinates = %@; URL = %@; image = %@>",
+            NSStringFromClass([self class]), (void *)self, self.identifier, MGLStringFromCoordinateQuad(self.coordinates), self.URL, self.image];
 }
 
 - (mbgl::style::ImageSource *)rawSource {
diff --git a/platform/darwin/src/MGLImageSource_Private.h b/platform/darwin/src/MGLImageSource_Private.h
deleted file mode 100644
index 54f6e00afa..0000000000
--- a/platform/darwin/src/MGLImageSource_Private.h
+++ /dev/null
@@ -1,9 +0,0 @@
-#import "MGLImageSource.h"
-
-NS_ASSUME_NONNULL_BEGIN
-
-@interface MGLImageSource (Private)
-
-@end
-
-NS_ASSUME_NONNULL_END
diff --git a/platform/darwin/src/MGLOfflineStorage.h b/platform/darwin/src/MGLOfflineStorage.h
index 90ba15c84c..b009f893b3 100644
--- a/platform/darwin/src/MGLOfflineStorage.h
+++ b/platform/darwin/src/MGLOfflineStorage.h
@@ -154,7 +154,7 @@ typedef NS_ENUM(NSUInteger, MGLResourceKind) {
     /** JSON part of a sprite sheet. It is constructed of the prefix in
         https://www.mapbox.com/mapbox-gl-js/style-spec/#root-sprite and a JSON file extension. */
     MGLResourceKindSpriteJSON,
-    /** Image **/
+    /** Image data for a georeferenced image source. **/
     MGLResourceKindImage,
 };
 
diff --git a/platform/darwin/src/MGLSource.h b/platform/darwin/src/MGLSource.h
index 8bf48907cc..f990aedd67 100644
--- a/platform/darwin/src/MGLSource.h
+++ b/platform/darwin/src/MGLSource.h
@@ -17,8 +17,9 @@ NS_ASSUME_NONNULL_BEGIN
  `-[MGLStyle addSource:]` and `-[MGLStyle sourceWithIdentifier:]`.
 
  Do not create instances of this class directly, and do not create your own
- subclasses of this class. Instead, create instances of `MGLShapeSource` and the
- concrete subclasses of `MGLTileSource`, `MGLVectorSource` and `MGLRasterSource`.
+ subclasses of this class. Instead, create instances of `MGLShapeSource`, 
+ `MGLImageSource` and the concrete subclasses of `MGLTileSource`,
+ `MGLVectorSource` and `MGLRasterSource`.
  */
 MGL_EXPORT
 @interface MGLSource : NSObject