[core, ios, macos] Add image accessor to MGLStyle (#7096)

* [core] Add interface to get image from sprite atlas

* [tests] Add tests for Map::getImage

* [ios, macos] WIP: get MGLImage for name from style

* [ios, macos] Fixed -imageForName:

Convert from sprite images to platform images using the existing encodePNG() function, which is also used for printing. Allow -imageForName: to return nil without an assertion failure. Added a basic test.

8 files changed, 96 insertions, 3 deletions

diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h
index 54ca267bab..3fe8fb9492 100644
--- a/platform/darwin/src/MGLStyle.h
+++ b/platform/darwin/src/MGLStyle.h
@@ -372,6 +372,23 @@ static const NSInteger MGLStyleDefaultVersion = 9;
 #pragma mark Managing a Style’s Images
 
 /**
+ Returns the image associated with the given name in the style.
+ 
+ @note Names and their associated images are not guaranteed to exist across
+    styles or different versions of the same style. Applications that use this
+    API must first set the style URL to an explicitly versioned style using a
+    convenience method like `+[MGLStyle outdoorsStyleURLWithVersion:]`,
+    `MGLMapView`'s “Style URL” inspectable in Interface Builder, or a manually
+    constructed `NSURL`. This approach also avoids image name changes that will 
+    occur in the default style over time.
+ 
+ @param name The name associated with the image you want to obtain.
+ @return The image associated with the given name, or `nil` if no image is
+    associated with that name.
+ */
+- (nullable MGLImage *)imageForName:(NSString *)name;
+
+/**
  Adds or overrides an image used by the style’s layers.
  
  To use an image in a style layer, give it a unique name using this method, then
diff --git a/platform/darwin/src/MGLStyle.mm b/platform/darwin/src/MGLStyle.mm
index 56dc4ad8f7..99d6ca89b6 100644
--- a/platform/darwin/src/MGLStyle.mm
+++ b/platform/darwin/src/MGLStyle.mm
@@ -482,19 +482,39 @@ static NSURL *MGLStyleURL_emerald;
 
 - (void)setImage:(MGLImage *)image forName:(NSString *)name
 {
-    NSAssert(image, @"image is null");
-    NSAssert(name, @"name is null");
+    if (!image) {
+        [NSException raise:NSInvalidArgumentException
+                    format:@"Cannot assign nil image to “%@”.", name];
+    }
+    if (!name) {
+        [NSException raise:NSInvalidArgumentException
+                    format:@"Cannot assign image %@ to a nil name.", image];
+    }
 
     self.mapView.mbglMap->addImage([name UTF8String], image.mgl_spriteImage);
 }
 
 - (void)removeImageForName:(NSString *)name
 {
-    NSAssert(name, @"name is null");
+    if (!name) {
+        [NSException raise:NSInvalidArgumentException
+                    format:@"Cannot remove image with nil name."];
+    }
 
     self.mapView.mbglMap->removeImage([name UTF8String]);
 }
 
+- (MGLImage *)imageForName:(NSString *)name
+{
+    if (!name) {
+        [NSException raise:NSInvalidArgumentException
+                    format:@"Cannot get image with nil name."];
+    }
+
+    auto spriteImage = self.mapView.mbglMap->getImage([name UTF8String]);
+    return spriteImage ? [[MGLImage alloc] initWithMGLSpriteImage:spriteImage] : nil;
+}
+
 - (NSString *)description
 {
     return [NSString stringWithFormat:@"<%@: %p; name = %@, URL = %@>",
diff --git a/platform/darwin/test/MGLStyleTests.mm b/platform/darwin/test/MGLStyleTests.mm
index 4c0c163b38..8f0d2502fb 100644
--- a/platform/darwin/test/MGLStyleTests.mm
+++ b/platform/darwin/test/MGLStyleTests.mm
@@ -17,6 +17,11 @@
 #import <mbgl/util/default_styles.hpp>
 
 #import <XCTest/XCTest.h>
+#if TARGET_OS_IPHONE
+    #import <UIKit/UIKit.h>
+#else
+    #import <Cocoa/Cocoa.h>
+#endif
 #import <objc/runtime.h>
 
 @interface MGLStyleTests : XCTestCase
@@ -175,4 +180,23 @@
     return styleHeader;
 }
 
+- (void)testImages {
+    NSString *imageName = @"TrackingLocationMask";
+#if TARGET_OS_IPHONE
+    MGLImage *image = [MGLImage imageNamed:imageName
+                                  inBundle:[NSBundle bundleForClass:[self class]]
+             compatibleWithTraitCollection:nil];
+#else
+    MGLImage *image = [[NSBundle bundleForClass:[self class]] imageForResource:imageName];
+#endif
+    XCTAssertNotNil(image);
+    
+    [self.mapView.style setImage:image forName:imageName];
+    MGLImage *styleImage = [self.mapView.style imageForName:imageName];
+    
+    XCTAssertNotNil(styleImage);
+    XCTAssertEqual(image.size.width, styleImage.size.width);
+    XCTAssertEqual(image.size.height, styleImage.size.height);
+}
+
 @end
diff --git a/platform/darwin/test/Media.xcassets/Contents.json b/platform/darwin/test/Media.xcassets/Contents.json
new file mode 100644
index 0000000000..da4a164c91
--- /dev/null
+++ b/platform/darwin/test/Media.xcassets/Contents.json
@@ -0,0 +1,6 @@
+{
+  "info" : {
+    "version" : 1,
+    "author" : "xcode"
+  }
+}
\ No newline at end of file
diff --git a/platform/darwin/test/Media.xcassets/TrackingLocationMask.imageset/Contents.json b/platform/darwin/test/Media.xcassets/TrackingLocationMask.imageset/Contents.json
new file mode 100644
index 0000000000..08cd551fc7
--- /dev/null
+++ b/platform/darwin/test/Media.xcassets/TrackingLocationMask.imageset/Contents.json
@@ -0,0 +1,26 @@
+{
+  "images" : [
+    {
+      "idiom" : "universal",
+      "filename" : "TrackingLocationMask.png",
+      "scale" : "1x"
+    },
+    {
+      "idiom" : "universal",
+      "filename" : "TrackingLocationMask@2x.png",
+      "scale" : "2x"
+    },
+    {
+      "idiom" : "universal",
+      "filename" : "TrackingLocationMask@3x.png",
+      "scale" : "3x"
+    }
+  ],
+  "info" : {
+    "version" : 1,
+    "author" : "xcode"
+  },
+  "properties" : {
+    "template-rendering-intent" : "template"
+  }
+}
\ No newline at end of file
diff --git a/platform/darwin/test/Media.xcassets/TrackingLocationMask.imageset/TrackingLocationMask.png b/platform/darwin/test/Media.xcassets/TrackingLocationMask.imageset/TrackingLocationMask.png
new file mode 100644
index 0000000000..bb7348c482
--- /dev/null
+++ b/platform/darwin/test/Media.xcassets/TrackingLocationMask.imageset/TrackingLocationMask.png
diff --git a/platform/darwin/test/Media.xcassets/TrackingLocationMask.imageset/TrackingLocationMask@2x.png b/platform/darwin/test/Media.xcassets/TrackingLocationMask.imageset/TrackingLocationMask@2x.png
new file mode 100644
index 0000000000..35c5a293ec
--- /dev/null
+++ b/platform/darwin/test/Media.xcassets/TrackingLocationMask.imageset/TrackingLocationMask@2x.png
diff --git a/platform/darwin/test/Media.xcassets/TrackingLocationMask.imageset/TrackingLocationMask@3x.png b/platform/darwin/test/Media.xcassets/TrackingLocationMask.imageset/TrackingLocationMask@3x.png
new file mode 100644
index 0000000000..af523975a5
--- /dev/null
+++ b/platform/darwin/test/Media.xcassets/TrackingLocationMask.imageset/TrackingLocationMask@3x.png