allow for user-provided symbol imagery (aka Sprites)

gyp/platform-ios.gypi

@@ -50,6 +50,8 @@
         '../platform/ios/MGLPolygon.m',
         '../include/mbgl/ios/MGLShape.h',
         '../platform/ios/MGLShape.m',
+        '../include/mbgl/ios/MGLAnnotationImage.h',
+        '../platform/ios/MGLAnnotationImage.m',
         '../platform/ios/NSBundle+MGLAdditions.h',
         '../platform/ios/NSBundle+MGLAdditions.m',
         '../platform/ios/NSException+MGLAdditions.h',

include/mbgl/annotation/sprite_image.hpp

@@ -0,0 +1,40 @@
+#ifndef MBGL_ANNOTATIONS_SPRITE_IMAGE
+#define MBGL_ANNOTATIONS_SPRITE_IMAGE
+
+#include <mbgl/util/noncopyable.hpp>
+#include <mbgl/util/geo.hpp>
+
+#include <string>
+#include <memory>
+#include <cstdint>
+
+namespace mbgl {
+
+class SpriteImage : private util::noncopyable {
+public:
+    SpriteImage(
+        uint16_t width, uint16_t height, float pixelRatio, std::string&& data, bool sdf = false);
+
+    // Logical dimensions of the sprite image.
+    const uint16_t width;
+    const uint16_t height;
+
+    // Pixel ratio of the sprite image.
+    const float pixelRatio;
+
+    // Physical dimensions of the sprite image.
+    const uint16_t pixelWidth;
+    const uint16_t pixelHeight;
+
+    // A string of an RGBA8 representation of the sprite. It must have exactly
+    // (width * ratio) * (height * ratio) * 4 (RGBA) bytes. The scan lines may
+    // not have gaps between them (i.e. stride == 0).
+    const std::string data;
+
+    // Whether this image should be interpreted as a signed distance field icon.
+    const bool sdf;
+};
+
+}
+
+#endif

include/mbgl/ios/MGLAnnotationImage.h

@@ -0,0 +1,16 @@
+#import <UIKit/UIKit.h>
+
+#import "MGLTypes.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface MGLAnnotationImage : NSObject
+
+@property (nonatomic, readonly) UIImage *image;
+@property (nonatomic, readonly) NSString *reuseIdentifier;
+
++ (instancetype)annotationImageWithImage:(UIImage *)image reuseIdentifier:(NSString *)reuseIdentifier;
+
+@end
+
+NS_ASSUME_NONNULL_END

include/mbgl/ios/MGLMapView.h

@@ -5,6 +5,7 @@
 
 NS_ASSUME_NONNULL_BEGIN
 
+@class MGLAnnotationImage;
 @class MGLUserLocation;
 @class MGLPolyline;
 @class MGLPolygon;
@@ -258,6 +259,18 @@ IB_DESIGNABLE
 *   @param annotations The array of annotations to remove. Objects in the array must conform to the MGLAnnotation protocol. */
 - (void)removeAnnotations:(NS_ARRAY_OF(id <MGLAnnotation>) *)annotations;
 
+/** Returns a reusable annotation image object located by its identifier.
+*
+*   For performance reasons, you should generally reuse MGLAnnotationImage objects for annotations in your map views. Dequeueing saves time and memory during performance-critical operations such as scrolling.
+*
+*   @param identifier A string identifying the annotation image to be reused. This string is the same one you specify when initially returning the annotation image object using the mapView:imageForAnnotation: method.
+*   @return An annotation image object with the specified identifier, or `nil` if no such object exists in the reuse queue. */
+- (nullable MGLAnnotationImage *)dequeueReusableAnnotationImageWithIdentifier:(NSString *)identifier;
+
+#pragma mark - Managing Annotation Selections
+
+/** @name Managing Annotation Selections */
+
 /** The annotations that are currently selected.
 *
 *   Assigning a new array to this property selects only the first annotation in the array. */
@@ -336,7 +349,13 @@ IB_DESIGNABLE
 *   @param mapView The map view that requested the annotation symbol name.
 *   @param annotation The object representing the annotation that is about to be displayed. 
 *   @return The marker symbol to display for the specified annotation or `nil` if you want to display the default symbol. */
-- (nullable NSString *)mapView:(MGLMapView *)mapView symbolNameForAnnotation:(id <MGLAnnotation>)annotation;
+- (nullable NSString *)mapView:(MGLMapView *)mapView symbolNameForAnnotation:(id <MGLAnnotation>)annotation __attribute__((unavailable("Use -mapView:imageForAnnotation:.")));
+
+/** Returns an image object to use for the marker for the specified point annotation object.
+*   @param mapView The map view that requested the annotation image.
+*   @param annotation The object representing the annotation that is about to be displayed.
+*   @return The image object to display for the specified annotation or `nil` if you want to display the default marker image. */
+- (nullable MGLAnnotationImage *)mapView:(MGLMapView *)mapView imageForAnnotation:(id <MGLAnnotation>)annotation;
 
 /** Returns the alpha value to use when rendering a shape annotation. Defaults to `1.0`.
 *   @param mapView The map view rendering the shape annotation.

include/mbgl/ios/MapboxGL.h

@@ -1,5 +1,6 @@
 #import "MGLAccountManager.h"
 #import "MGLAnnotation.h"
+#import "MGLAnnotationImage.h"
 #import "MGLGeometry.h"
 #import "MGLMapView.h"
 #import "MGLMultiPoint.h"

include/mbgl/map/map.hpp

@@ -21,6 +21,7 @@ class View;
 class MapData;
 class MapContext;
 class StillImage;
+class SpriteImage;
 class Transform;
 class PointAnnotation;
 class ShapeAnnotation;
@@ -141,6 +142,10 @@ class Map : private util::noncopyable {
     AnnotationIDs getAnnotationsInBounds(const LatLngBounds&, const AnnotationType& = AnnotationType::Any);
     LatLngBounds getBoundsForAnnotations(const AnnotationIDs&);
 
+    // Sprites
+    void setSprite(const std::string&, std::shared_ptr<const SpriteImage>);
+    void removeSprite(const std::string&);
+
     // Memory
     void setSourceTileCacheSize(size_t);
     void onLowMemory();

include/mbgl/platform/default/glfw_view.hpp

@@ -46,14 +46,18 @@ class GLFWView : public mbgl::View {
 
 private:
     mbgl::LatLng makeRandomPoint() const;
+    static std::shared_ptr<const mbgl::SpriteImage>
+    makeSpriteImage(int width, int height, float pixelRatio);
 
     void addRandomPointAnnotations(int count);
     void addRandomShapeAnnotations(int count);
+    void addRandomCustomPointAnnotations(int count);
 
     void clearAnnotations();
     void popAnnotation();
 
     mbgl::AnnotationIDs annotationIDs;
+    std::vector<std::string> spriteIDs;
 
 private:
     bool fullscreen = false;

include/mbgl/util/exception.hpp

@@ -11,6 +11,11 @@ struct Exception : std::runtime_error {
     inline Exception(const std::string &msg) : std::runtime_error(msg) {}
 };
 
+struct SpriteImageException : Exception {
+    inline SpriteImageException(const char *msg) : Exception(msg) {}
+    inline SpriteImageException(const std::string &msg) : Exception(msg) {}
+};
+
 struct GlyphRangeLoadingException : Exception {
     inline GlyphRangeLoadingException(const char *msg) : Exception(msg) {}
     inline GlyphRangeLoadingException(const std::string &msg) : Exception(msg) {}

include/mbgl/util/image.hpp

@@ -7,12 +7,12 @@
 namespace mbgl {
 namespace util {
 
-std::string compress_png(int width, int height, void *rgba);
+std::string compress_png(int width, int height, const void *rgba);
 
 
 class Image {
 public:
-    Image(const std::string &img);
+    explicit Image(const std::string &img);
 
     inline const char *getData() const { return img.get(); }
     inline uint32_t getWidth() const { return width; }

ios/app/MBXViewController.mm

@@ -340,6 +340,45 @@ - (void)dealloc
 
 #pragma mark - MGLMapViewDelegate
 
+- (MGLAnnotationImage *)mapView:(MGLMapView * __nonnull)mapView imageForAnnotation:(id <MGLAnnotation> __nonnull)annotation
+{
+    NSString *title = [(MGLPointAnnotation *)annotation title];
+    NSString *lastTwoCharacters = [title substringFromIndex:title.length - 2];
+
+    MGLAnnotationImage *image = [mapView dequeueReusableAnnotationImageWithIdentifier:lastTwoCharacters];
+
+    if ( ! image)
+    {
+        CGRect rect = CGRectMake(0, 0, 20, 15);
+
+        UIGraphicsBeginImageContextWithOptions(rect.size, NO, [[UIScreen mainScreen] scale]);
+
+        CGContextRef ctx = UIGraphicsGetCurrentContext();
+
+        CGContextSetFillColorWithColor(ctx, [[[UIColor redColor] colorWithAlphaComponent:0.75] CGColor]);
+        CGContextFillRect(ctx, rect);
+
+        CGContextSetStrokeColorWithColor(ctx, [[UIColor blackColor] CGColor]);
+        CGContextStrokeRectWithWidth(ctx, rect, 2);
+
+        NSAttributedString *drawString = [[NSAttributedString alloc] initWithString:lastTwoCharacters attributes:@{
+            NSFontAttributeName: [UIFont fontWithName:@"Arial-BoldMT" size:12],
+            NSForegroundColorAttributeName: [UIColor whiteColor] }];
+        CGSize stringSize = drawString.size;
+        CGRect stringRect = CGRectMake((rect.size.width - stringSize.width) / 2,
+                                       (rect.size.height - stringSize.height) / 2,
+                                       stringSize.width,
+                                       stringSize.height);
+        [drawString drawInRect:stringRect];
+
+        image = [MGLAnnotationImage annotationImageWithImage:UIGraphicsGetImageFromCurrentImageContext() reuseIdentifier:lastTwoCharacters];
+
+        UIGraphicsEndImageContext();
+    }
+
+    return image;
+}
+
 - (BOOL)mapView:(__unused MGLMapView *)mapView annotationCanShowCallout:(__unused id <MGLAnnotation>)annotation
 {
     return YES;

platform/darwin/image.mm

@@ -11,7 +11,7 @@
 namespace mbgl {
 namespace util {
 
-std::string compress_png(int width, int height, void *rgba) {
+std::string compress_png(int width, int height, const void *rgba) {
     CGDataProviderRef provider = CGDataProviderCreateWithData(NULL, rgba, width * height * 4, NULL);
     if (!provider) {
         return "";

platform/default/glfw_view.cpp

@@ -1,5 +1,6 @@
 #include <mbgl/annotation/point_annotation.hpp>
 #include <mbgl/annotation/shape_annotation.hpp>
+#include <mbgl/annotation/sprite_image.hpp>
 #include <mbgl/platform/default/glfw_view.hpp>
 #include <mbgl/platform/gl.hpp>
 #include <mbgl/platform/log.hpp>
@@ -120,6 +121,9 @@ void GLFWView::onKey(GLFWwindow *window, int key, int /*scancode*/, int action,
         case GLFW_KEY_Q:
             view->clearAnnotations();
             break;
+        case GLFW_KEY_P: {
+            view->addRandomCustomPointAnnotations(1);
+        } break;
         }
     }
 
@@ -150,6 +154,49 @@ mbgl::LatLng GLFWView::makeRandomPoint() const {
     return { lat, lon };
 }
 
+std::shared_ptr<const mbgl::SpriteImage>
+GLFWView::makeSpriteImage(int width, int height, float pixelRatio) {
+    const int r = 255 * (double(std::rand()) / RAND_MAX);
+    const int g = 255 * (double(std::rand()) / RAND_MAX);
+    const int b = 255 * (double(std::rand()) / RAND_MAX);
+
+    const int w = std::ceil(pixelRatio * width);
+    const int h = std::ceil(pixelRatio * height);
+
+    std::string pixels(w * h * 4, '\x00');
+    auto data = reinterpret_cast<uint32_t*>(const_cast<char*>(pixels.data()));
+    const int dist = (w / 2) * (w / 2);
+    for (int y = 0; y < h; y++) {
+        for (int x = 0; x < w; x++) {
+            const int dx = x - w / 2;
+            const int dy = y - h / 2;
+            const int diff = dist - (dx * dx + dy * dy);
+            if (diff > 0) {
+                const int a = std::min(0xFF, diff) * 0xFF / dist;
+                // Premultiply the rgb values with alpha
+                data[w * y + x] =
+                    (a << 24) | ((a * r / 0xFF) << 16) | ((a * g / 0xFF) << 8) | (a * b / 0xFF);
+            }
+        }
+    }
+
+    return std::make_shared<mbgl::SpriteImage>(width, height, pixelRatio, std::move(pixels));
+}
+
+void GLFWView::addRandomCustomPointAnnotations(int count) {
+    std::vector<mbgl::PointAnnotation> points;
+
+    for (int i = 0; i < count; i++) {
+        static int spriteID = 1;
+        const auto name = std::string{ "marker-" } + std::to_string(spriteID++);
+        map->setSprite(name, makeSpriteImage(22, 22, 1));
+        spriteIDs.push_back(name);
+        points.emplace_back(makeRandomPoint(), name);
+    }
+
+    auto newIDs = map->addPointAnnotations(points);
+    annotationIDs.insert(annotationIDs.end(), newIDs.begin(), newIDs.end());
+}
 
 void GLFWView::addRandomPointAnnotations(int count) {
     std::vector<mbgl::PointAnnotation> points;

platform/default/image.cpp

@@ -27,7 +27,7 @@ const static bool png_version_check = []() {
 namespace mbgl {
 namespace util {
 
-std::string compress_png(int width, int height, void *rgba) {
+std::string compress_png(int width, int height, const void *rgba) {
     png_voidp error_ptr = 0;
     png_structp png_ptr = png_create_write_struct(PNG_LIBPNG_VER_STRING, error_ptr, NULL, NULL);
     if (!png_ptr) {

platform/ios/MGLAnnotationImage.m

@@ -0,0 +1,30 @@
+#import "MGLAnnotationImage.h"
+
+@interface MGLAnnotationImage ()
+
+@property (nonatomic) UIImage *image;
+@property (nonatomic) NSString *reuseIdentifier;
+
+@end
+
+@implementation MGLAnnotationImage
+
++ (instancetype)annotationImageWithImage:(UIImage *)image reuseIdentifier:(NSString *)reuseIdentifier
+{
+    return [[self alloc] initWithImage:image reuseIdentifier:reuseIdentifier];
+}
+
+- (instancetype)initWithImage:(UIImage *)image reuseIdentifier:(NSString *)reuseIdentifier
+{
+    self = [super init];
+
+    if (self)
+    {
+        _image = image;
+        _reuseIdentifier = [reuseIdentifier copy];
+    }
+
+    return self;
+}
+
+@end