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

1 files changed, 25 insertions, 66 deletions

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