[ios, macos] Migrate MGLCustomStyleLayerAdditions to style layer API (#7250)

* [ios, macos] Replaced custom style layer API with MGLOpenGLStyleLayer

Replaced the custom style layer API on MGLMapView with an equally unsupported MGLOpenGLStyleLayer API that nonetheless is consistent with the broader runtime styling API and is compatible with macOS.

Fixed an unrecognized selector crash when wrapping a layer of unrecognized type coming from mbgl.

* [macos] Added lime green layer demo to macosapp

Reprised the demo removed from iosapp in #5091.

* [ios, macos] Rationalized MGLOpenGLStyleLayer API

MGLStyle now strongly references any MGLOpenGLStyleLayer object that’s added to it, in order to prevent pointers from going stale and make it easy for layer drawing code to get more information about the map view. Replaced the MGLOpenGLStyleLayer callback blocks with overridable instance methods. Added internal documentation for each method. Subclassed MGLOpenGLStyleLayer as LimeGreenStyleLayer inside macosapp.

Consolidated -addToMapView: into -addToMapView:belowLayer: to ensure that MGLRedundantLayerException gets raised even if the layer is being inserted rather than added to the bottom of the stack.

* [core] Clarified that rendering happens on the main thread

* [ios, macos] Fixed removing and re-adding MGLOpenGLStyleLayer

Don’t allow index-based layer removal to circumvent -removeFromMapView:, which MGLOpenGLStyleLayer relies on to synchronize the style’s array of MGLOpenGLStyleLayers. When obtaining an MGLOpenGLStyleLayer, get the instance already added to the style instead of creating a new one to wrap the underlying CustomLayer.

13 files changed, 282 insertions, 60 deletions

diff --git a/platform/darwin/src/MGLBackgroundStyleLayer.mm b/platform/darwin/src/MGLBackgroundStyleLayer.mm
index 253414852a..0ac25c39fe 100644
--- a/platform/darwin/src/MGLBackgroundStyleLayer.mm
+++ b/platform/darwin/src/MGLBackgroundStyleLayer.mm
@@ -33,7 +33,7 @@
 
 #pragma mark -  Adding to and removing from a map view
 
-- (void)addToMapView:(MGLMapView *)mapView
+- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
 {
     if (_pendingLayer == nullptr) {
         [NSException raise:@"MGLRedundantLayerException"
@@ -41,11 +41,6 @@
                     "to the style more than once is invalid.", self, mapView.style];
     }
 
-    [self addToMapView:mapView belowLayer:nil];
-}
-
-- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
-{
     if (otherLayer) {
         const mbgl::optional<std::string> belowLayerId{otherLayer.identifier.UTF8String};
         mapView.mbglMap->addLayer(std::move(_pendingLayer), belowLayerId);
diff --git a/platform/darwin/src/MGLCircleStyleLayer.mm b/platform/darwin/src/MGLCircleStyleLayer.mm
index 91f91a7bcd..90026490a6 100644
--- a/platform/darwin/src/MGLCircleStyleLayer.mm
+++ b/platform/darwin/src/MGLCircleStyleLayer.mm
@@ -73,7 +73,7 @@ namespace mbgl {
 }
 #pragma mark -  Adding to and removing from a map view
 
-- (void)addToMapView:(MGLMapView *)mapView
+- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
 {
     if (_pendingLayer == nullptr) {
         [NSException raise:@"MGLRedundantLayerException"
@@ -81,11 +81,6 @@ namespace mbgl {
                     "to the style more than once is invalid.", self, mapView.style];
     }
 
-    [self addToMapView:mapView belowLayer:nil];
-}
-
-- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
-{
     if (otherLayer) {
         const mbgl::optional<std::string> belowLayerId{otherLayer.identifier.UTF8String};
         mapView.mbglMap->addLayer(std::move(_pendingLayer), belowLayerId);
diff --git a/platform/darwin/src/MGLFillStyleLayer.mm b/platform/darwin/src/MGLFillStyleLayer.mm
index 87a5144c6b..e2808ddc19 100644
--- a/platform/darwin/src/MGLFillStyleLayer.mm
+++ b/platform/darwin/src/MGLFillStyleLayer.mm
@@ -68,7 +68,7 @@ namespace mbgl {
 }
 #pragma mark -  Adding to and removing from a map view
 
-- (void)addToMapView:(MGLMapView *)mapView
+- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
 {
     if (_pendingLayer == nullptr) {
         [NSException raise:@"MGLRedundantLayerException"
@@ -76,11 +76,6 @@ namespace mbgl {
                     "to the style more than once is invalid.", self, mapView.style];
     }
 
-    [self addToMapView:mapView belowLayer:nil];
-}
-
-- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
-{
     if (otherLayer) {
         const mbgl::optional<std::string> belowLayerId{otherLayer.identifier.UTF8String};
         mapView.mbglMap->addLayer(std::move(_pendingLayer), belowLayerId);
diff --git a/platform/darwin/src/MGLLineStyleLayer.mm b/platform/darwin/src/MGLLineStyleLayer.mm
index 55d739245f..2fc9d9e695 100644
--- a/platform/darwin/src/MGLLineStyleLayer.mm
+++ b/platform/darwin/src/MGLLineStyleLayer.mm
@@ -80,7 +80,7 @@ namespace mbgl {
 }
 #pragma mark -  Adding to and removing from a map view
 
-- (void)addToMapView:(MGLMapView *)mapView
+- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
 {
     if (_pendingLayer == nullptr) {
         [NSException raise:@"MGLRedundantLayerException"
@@ -88,11 +88,6 @@ namespace mbgl {
                     "to the style more than once is invalid.", self, mapView.style];
     }
 
-    [self addToMapView:mapView belowLayer:nil];
-}
-
-- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
-{
     if (otherLayer) {
         const mbgl::optional<std::string> belowLayerId{otherLayer.identifier.UTF8String};
         mapView.mbglMap->addLayer(std::move(_pendingLayer), belowLayerId);
diff --git a/platform/darwin/src/MGLOpenGLStyleLayer.h b/platform/darwin/src/MGLOpenGLStyleLayer.h
new file mode 100644
index 0000000000..7cb6b147c2
--- /dev/null
+++ b/platform/darwin/src/MGLOpenGLStyleLayer.h
@@ -0,0 +1,34 @@
+#import <Foundation/Foundation.h>
+#import <CoreLocation/CoreLocation.h>
+
+#import "MGLStyleValue.h"
+#import "MGLStyleLayer.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+@class MGLMapView;
+
+typedef struct MGLStyleLayerDrawingContext {
+    CGSize size;
+    CLLocationCoordinate2D centerCoordinate;
+    double zoomLevel;
+    CLLocationDirection direction;
+    CGFloat pitch;
+    CGFloat perspectiveSkew;
+} MGLStyleLayerDrawingContext;
+
+@interface MGLOpenGLStyleLayer : MGLStyleLayer
+
+@property (nonatomic, weak, readonly) MGLMapView *mapView;
+
+- (void)didMoveToMapView:(MGLMapView *)mapView;
+
+- (void)willMoveFromMapView:(MGLMapView *)mapView;
+
+- (void)drawInMapView:(MGLMapView *)mapView withContext:(MGLStyleLayerDrawingContext)context;
+
+- (void)setNeedsDisplay;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/platform/darwin/src/MGLOpenGLStyleLayer.mm b/platform/darwin/src/MGLOpenGLStyleLayer.mm
new file mode 100644
index 0000000000..2e819f0a2b
--- /dev/null
+++ b/platform/darwin/src/MGLOpenGLStyleLayer.mm
@@ -0,0 +1,200 @@
+#import "MGLOpenGLStyleLayer.h"
+
+#import "MGLMapView_Private.h"
+#import "MGLStyle_Private.h"
+
+#include <mbgl/style/layers/custom_layer.hpp>
+#include <mbgl/math/wrap.hpp>
+
+/**
+ Runs the preparation handler block contained in the given context, which is
+ implicitly an instance of `MGLOpenGLStyleLayer`.
+ 
+ @param context An `MGLOpenGLStyleLayer` instance that was provided as context
+    when creating an OpenGL style layer.
+ */
+void MGLPrepareCustomStyleLayer(void *context) {
+    MGLOpenGLStyleLayer *layer = (__bridge MGLOpenGLStyleLayer *)context;
+    [layer didMoveToMapView:layer.mapView];
+}
+
+/**
+ Runs the drawing handler block contained in the given context, which is
+ implicitly an instance of `MGLOpenGLStyleLayer`.
+ 
+ @param context An `MGLOpenGLStyleLayer` instance that was provided as context
+    when creating an OpenGL style layer.
+ */
+void MGLDrawCustomStyleLayer(void *context, const mbgl::style::CustomLayerRenderParameters &params) {
+    MGLOpenGLStyleLayer *layer = (__bridge MGLOpenGLStyleLayer *)context;
+    MGLStyleLayerDrawingContext drawingContext = {
+        .size = CGSizeMake(params.width, params.height),
+        .centerCoordinate = CLLocationCoordinate2DMake(params.latitude, params.longitude),
+        .zoomLevel = params.zoom,
+        .direction = mbgl::util::wrap(params.bearing, 0., 360.),
+        .pitch = params.pitch,
+        .perspectiveSkew = params.altitude,
+    };
+    [layer drawInMapView:layer.mapView withContext:drawingContext];
+}
+
+/**
+ Runs the completion handler block contained in the given context, which is
+ implicitly an instance of `MGLOpenGLStyleLayer`.
+ 
+ @param context An `MGLOpenGLStyleLayer` instance that was provided as context
+    when creating an OpenGL style layer.
+ */
+void MGLFinishCustomStyleLayer(void *context) {
+    MGLOpenGLStyleLayer *layer = (__bridge MGLOpenGLStyleLayer *)context;
+    [layer willMoveFromMapView:layer.mapView];
+}
+
+/**
+ An `MGLOpenGLStyleLayer` is a style layer that is rendered by OpenGL code in
+ Objective-C blocks or Swift closures that you specify. You may initialize a new
+ OpenGL style layer to add to an `MGLStyle` or obtain one from an `MGLMapView`’s
+ current style using the `-[MGLStyle layerWithIdentifier:]` method.
+ 
+ @warning This API is undocumented and therefore unsupported. It may change at
+    any time without notice.
+ */
+@interface MGLOpenGLStyleLayer ()
+
+@property (nonatomic) mbgl::style::CustomLayer *rawLayer;
+
+/**
+ The map view whose style currently contains the layer.
+ 
+ If the layer is not currently part of any map view’s style, this property is
+ set to `nil`.
+ */
+@property (nonatomic, weak, readwrite) MGLMapView *mapView;
+
+@end
+
+@implementation MGLOpenGLStyleLayer {
+    std::unique_ptr<mbgl::style::CustomLayer> _pendingLayer;
+}
+
+/**
+ Returns an OpenGL style layer object initialized with the given identifier.
+ 
+ After initializing and configuring the style layer, add it to a map view’s
+ style using the `-[MGLStyle addLayer:]` or
+ `-[MGLStyle insertLayer:belowLayer:]` method.
+ 
+ @param identifier A string that uniquely identifies the layer in the style to
+    which it is added.
+ @return An initialized OpenGL style layer.
+ */
+- (instancetype)initWithIdentifier:(NSString *)identifier {
+    if (self = [super initWithIdentifier:identifier]) {
+        auto layer = std::make_unique<mbgl::style::CustomLayer>(identifier.UTF8String,
+                                                                MGLPrepareCustomStyleLayer,
+                                                                MGLDrawCustomStyleLayer,
+                                                                MGLFinishCustomStyleLayer,
+                                                                (__bridge void *)self);
+        _pendingLayer = std::move(layer);
+        _rawLayer = _pendingLayer.get();
+    }
+    return self;
+}
+
+#pragma mark - Adding to and removing from a map view
+
+- (void)setMapView:(MGLMapView *)mapView {
+    if (_mapView && mapView) {
+        [NSException raise:@"MGLLayerReuseException"
+                    format:@"%@ cannot be added to more than one MGLStyle at a time.", self];
+    }
+    _mapView.style.openGLLayers[self.identifier] = nil;
+    _mapView = mapView;
+    _mapView.style.openGLLayers[self.identifier] = self;
+}
+
+- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer {
+    self.mapView = mapView;
+    if (otherLayer) {
+        const mbgl::optional<std::string> belowLayerId{ otherLayer.identifier.UTF8String };
+        mapView.mbglMap->addLayer(std::move(_pendingLayer), belowLayerId);
+    } else {
+        mapView.mbglMap->addLayer(std::move(_pendingLayer));
+    }
+}
+
+- (void)removeFromMapView:(MGLMapView *)mapView {
+    auto removedLayer = mapView.mbglMap->removeLayer(self.identifier.UTF8String);
+    self.mapView = nil;
+    if (!removedLayer) {
+        return;
+    }
+    _pendingLayer = std::move(reinterpret_cast<std::unique_ptr<mbgl::style::CustomLayer> &>(removedLayer));
+    _rawLayer = _pendingLayer.get();
+}
+
+/**
+ Called immediately after a layer is added to a map view’s style.
+ 
+ This method is intended to be overridden in a subclass. You can use this method
+ to perform any setup work before the layer is used to draw a frame. For
+ example, you might use this method to compile an OpenGL shader. The default
+ implementation of this method does nothing.
+ 
+ Any resource acquired in this method must be released in
+ `-willMoveFromMapView:`.
+ 
+ @param mapView The map view to whose style the layer has been added.
+ */
+- (void)didMoveToMapView:(MGLMapView *)mapView {
+    
+}
+
+/**
+ Called immediately before a layer is removed from a map view’s style.
+ 
+ This method is intended to be overridden in a subclass. You can use this method
+ to perform any teardown work once the layer has drawn its last frame and is
+ about to be removed from the style. The default implementation of this method
+ does nothing.
+ 
+ This method may be called even if `-didMoveToMapView:` has not been called.
+ 
+ @param mapView The map view from whose style the layer is about to be removed.
+ */
+- (void)willMoveFromMapView:(MGLMapView *)mapView {
+    
+}
+
+/**
+ Called each time the layer needs to draw a new frame in a map view.
+ 
+ This method is intended to be overridden in a subclass. You can use this method
+ to draw the layer’s content. The default implementation of this method does
+ nothing.
+ 
+ Your implementation should not make any assumptions about the OpenGL state,
+ other than that the current OpenGL context is active. It may make changes to
+ the OpenGL state. It is not required to reset values such as the depth mask,
+ stencil mask, or corresponding test flags to their original values.
+ 
+ Be sure to draw your fragments with a <var>z</var> value of 1 to take advantage
+ of the opaque fragment culling, in case the style contains any opaque layers
+ above this layer.
+ 
+ @param mapView The map view to which the layer draws.
+ @param context A context structure with information defining the frame to draw.
+ */
+- (void)drawInMapView:(MGLMapView *)mapView withContext:(MGLStyleLayerDrawingContext)context {
+    
+}
+
+/**
+ Forces the map view associated with this style to redraw the receiving layer,
+ causing its drawing handler to be run.
+ */
+- (void)setNeedsDisplay {
+    [self.mapView setNeedsGLDisplay];
+}
+
+@end
diff --git a/platform/darwin/src/MGLRasterStyleLayer.mm b/platform/darwin/src/MGLRasterStyleLayer.mm
index 3b2c3bd83b..d54f027432 100644
--- a/platform/darwin/src/MGLRasterStyleLayer.mm
+++ b/platform/darwin/src/MGLRasterStyleLayer.mm
@@ -32,7 +32,7 @@
 }
 #pragma mark -  Adding to and removing from a map view
 
-- (void)addToMapView:(MGLMapView *)mapView
+- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
 {
     if (_pendingLayer == nullptr) {
         [NSException raise:@"MGLRedundantLayerException"
@@ -40,11 +40,6 @@
                     "to the style more than once is invalid.", self, mapView.style];
     }
 
-    [self addToMapView:mapView belowLayer:nil];
-}
-
-- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
-{
     if (otherLayer) {
         const mbgl::optional<std::string> belowLayerId{otherLayer.identifier.UTF8String};
         mapView.mbglMap->addLayer(std::move(_pendingLayer), belowLayerId);
diff --git a/platform/darwin/src/MGLStyle.mm b/platform/darwin/src/MGLStyle.mm
index 99d6ca89b6..36c8787bfb 100644
--- a/platform/darwin/src/MGLStyle.mm
+++ b/platform/darwin/src/MGLStyle.mm
@@ -1,4 +1,4 @@
-#import "MGLStyle.h"
+#import "MGLStyle_Private.h"
 
 #import "MGLMapView_Private.h"
 #import "MGLStyleLayer.h"
@@ -8,6 +8,7 @@
 #import "MGLSymbolStyleLayer.h"
 #import "MGLRasterStyleLayer.h"
 #import "MGLBackgroundStyleLayer.h"
+#import "MGLOpenGLStyleLayer.h"
 
 #import "MGLStyle_Private.h"
 #import "MGLStyleLayer_Private.h"
@@ -28,6 +29,7 @@
 #include <mbgl/style/layers/raster_layer.hpp>
 #include <mbgl/style/layers/circle_layer.hpp>
 #include <mbgl/style/layers/background_layer.hpp>
+#include <mbgl/style/layers/custom_layer.hpp>
 #include <mbgl/style/sources/geojson_source.hpp>
 #include <mbgl/style/sources/vector_source.hpp>
 #include <mbgl/style/sources/raster_source.hpp>
@@ -43,6 +45,7 @@
 
 @property (nonatomic, readwrite, weak) MGLMapView *mapView;
 @property (readonly, copy, nullable) NSURL *URL;
+@property (nonatomic, readwrite, strong) NS_MUTABLE_DICTIONARY_OF(NSString *, MGLOpenGLStyleLayer *) *openGLLayers;
 
 @end
 
@@ -105,6 +108,7 @@ static NSURL *MGLStyleURL_emerald;
 - (instancetype)initWithMapView:(MGLMapView *)mapView {
     if (self = [super init]) {
         _mapView = mapView;
+        _openGLLayers = [NSMutableDictionary dictionary];
     }
     return self;
 }
@@ -268,7 +272,7 @@ static NSURL *MGLStyleURL_emerald;
         [NSException raise:NSRangeException
                     format:@"Cannot insert style layer at out-of-bounds index %lu.", (unsigned long)index];
     } else if (index == 0) {
-        [styleLayer addToMapView:self.mapView];
+        [styleLayer addToMapView:self.mapView belowLayer:nil];
     } else {
         MGLStyleLayer *sibling = [self layerFromMBGLLayer:layers.at(layers.size() - index)];
         [styleLayer addToMapView:self.mapView belowLayer:sibling];
@@ -283,7 +287,8 @@ static NSURL *MGLStyleURL_emerald;
                     format:@"Cannot remove style layer at out-of-bounds index %lu.", (unsigned long)index];
     }
     auto layer = layers.at(layers.size() - 1 - index);
-    self.mapView.mbglMap->removeLayer(layer->getID());
+    MGLStyleLayer *styleLayer = [self layerFromMBGLLayer:layer];
+    [styleLayer removeFromMapView:self.mapView];
 }
 
 - (MGLStyleLayer *)layerFromMBGLLayer:(mbgl::style::Layer *)mbglLayer
@@ -307,8 +312,15 @@ static NSURL *MGLStyleURL_emerald;
     } else if (auto circleLayer = mbglLayer->as<mbgl::style::CircleLayer>()) {
         MGLSource *source = [self sourceWithIdentifier:@(circleLayer->getSourceID().c_str())];
         styleLayer = [[MGLCircleStyleLayer alloc] initWithIdentifier:identifier source:source];
-    } else if (mbglLayer->as<mbgl::style::BackgroundLayer>()) {
+    } else if (mbglLayer->is<mbgl::style::BackgroundLayer>()) {
         styleLayer = [[MGLBackgroundStyleLayer alloc] initWithIdentifier:identifier];
+    } else if (auto customLayer = mbglLayer->as<mbgl::style::CustomLayer>()) {
+        styleLayer = self.openGLLayers[identifier];
+        if (styleLayer) {
+            NSAssert(styleLayer.rawLayer == customLayer, @"%@ wraps a CustomLayer that differs from the one associated with the underlying style.", styleLayer);
+            return styleLayer;
+        }
+        styleLayer = [[MGLOpenGLStyleLayer alloc] initWithIdentifier:identifier];
     } else {
         NSAssert(NO, @"Unrecognized layer type");
         return nil;
@@ -347,7 +359,7 @@ static NSURL *MGLStyleURL_emerald;
          layer];
     }
     [self willChangeValueForKey:@"layers"];
-    [layer addToMapView:self.mapView];
+    [layer addToMapView:self.mapView belowLayer:nil];
     [self didChangeValueForKey:@"layers"];
 }
 
@@ -410,7 +422,7 @@ static NSURL *MGLStyleURL_emerald;
          @"Make sure sibling was obtained using -[MGLStyle layerWithIdentifier:].",
          sibling];
     } else if (index + 1 == layers.size()) {
-        [layer addToMapView:self.mapView];
+        [layer addToMapView:self.mapView belowLayer:nil];
     } else {
         MGLStyleLayer *sibling = [self layerFromMBGLLayer:layers.at(index + 1)];
         [layer addToMapView:self.mapView belowLayer:sibling];
diff --git a/platform/darwin/src/MGLStyleLayer.mm b/platform/darwin/src/MGLStyleLayer.mm
index 6d9dabf25e..97f8f86b26 100644
--- a/platform/darwin/src/MGLStyleLayer.mm
+++ b/platform/darwin/src/MGLStyleLayer.mm
@@ -3,6 +3,12 @@
 
 #include <mbgl/style/layer.hpp>
 
+@interface MGLStyleLayer ()
+
+@property (nonatomic) mbgl::style::Layer *rawLayer;
+
+@end
+
 @implementation MGLStyleLayer
 
 - (instancetype)initWithIdentifier:(NSString *)identifier
diff --git a/platform/darwin/src/MGLStyleLayer.mm.ejs b/platform/darwin/src/MGLStyleLayer.mm.ejs
index c89912c1ff..032fbfcc9b 100644
--- a/platform/darwin/src/MGLStyleLayer.mm.ejs
+++ b/platform/darwin/src/MGLStyleLayer.mm.ejs
@@ -110,7 +110,7 @@ namespace mbgl {
 <% } -%>
 #pragma mark -  Adding to and removing from a map view
 
-- (void)addToMapView:(MGLMapView *)mapView
+- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
 {
     if (_pendingLayer == nullptr) {
         [NSException raise:@"MGLRedundantLayerException"
@@ -118,11 +118,6 @@ namespace mbgl {
                     "to the style more than once is invalid.", self, mapView.style];
     }
 
-    [self addToMapView:mapView belowLayer:nil];
-}
-
-- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
-{
     if (otherLayer) {
         const mbgl::optional<std::string> belowLayerId{otherLayer.identifier.UTF8String};
         mapView.mbglMap->addLayer(std::move(_pendingLayer), belowLayerId);
diff --git a/platform/darwin/src/MGLStyleLayer_Private.h b/platform/darwin/src/MGLStyleLayer_Private.h
index e723c8cf1b..077af9a995 100644
--- a/platform/darwin/src/MGLStyleLayer_Private.h
+++ b/platform/darwin/src/MGLStyleLayer_Private.h
@@ -5,6 +5,8 @@
 
 #include <mbgl/style/layer.hpp>
 
+NS_ASSUME_NONNULL_BEGIN
+
 /**
  Assert that the style layer is valid.
 
@@ -40,13 +42,14 @@
 @property (nonatomic) mbgl::style::Layer *rawLayer;
 
 /**
- Adds the mbgl style layer that this object represents to the mbgl map.
- 
+ Adds the mbgl style layer that this object represents to the mbgl map below the
+ specified `otherLayer`.
+
  Once a mbgl style layer is added, ownership of the object is transferred to the
  `mbgl::Map` and this object no longer has an active unique_ptr reference to the
  `mbgl::style::Layer`.
  */
-- (void)addToMapView:(MGLMapView *)mapView;
+- (void)addToMapView:(MGLMapView *)mapView belowLayer:(nullable MGLStyleLayer *)otherLayer;
 
 /**
  Removes the mbgl style layer that this object represents from the mbgl map.
@@ -57,13 +60,6 @@
  */
 - (void)removeFromMapView:(MGLMapView *)mapView;
 
-/**
- Adds the mbgl style layer that this object represents to the mbgl map below the specified `otherLayer`.
-
- Once a mbgl style layer is added, ownership of the object is transferred to the
- `mbgl::Map` and this object no longer has an active unique_ptr reference to the
- `mbgl::style::Layer`.
- */
-- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer;
-
 @end
+
+NS_ASSUME_NONNULL_END
diff --git a/platform/darwin/src/MGLStyle_Private.h b/platform/darwin/src/MGLStyle_Private.h
index b7c2fa4cdb..ee4a30c887 100644
--- a/platform/darwin/src/MGLStyle_Private.h
+++ b/platform/darwin/src/MGLStyle_Private.h
@@ -5,12 +5,21 @@
 #import <mbgl/util/default_styles.hpp>
 #include <mbgl/mbgl.hpp>
 
+NS_ASSUME_NONNULL_BEGIN
+
+@class MGLMapView;
+@class MGLOpenGLStyleLayer;
+
 @interface MGLStyle (Private)
 
 - (instancetype)initWithMapView:(MGLMapView *)mapView;
 
 @property (nonatomic, readonly, weak) MGLMapView *mapView;
 
+@property (nonatomic, readonly, strong) NS_MUTABLE_DICTIONARY_OF(NSString *, MGLOpenGLStyleLayer *) *openGLLayers;
+
 - (void)setStyleClasses:(NS_ARRAY_OF(NSString *) *)appliedClasses transitionDuration:(NSTimeInterval)transitionDuration;
 
 @end
+
+NS_ASSUME_NONNULL_END
diff --git a/platform/darwin/src/MGLSymbolStyleLayer.mm b/platform/darwin/src/MGLSymbolStyleLayer.mm
index 9f4fb27e2b..2561152efc 100644
--- a/platform/darwin/src/MGLSymbolStyleLayer.mm
+++ b/platform/darwin/src/MGLSymbolStyleLayer.mm
@@ -127,7 +127,7 @@ namespace mbgl {
 }
 #pragma mark -  Adding to and removing from a map view
 
-- (void)addToMapView:(MGLMapView *)mapView
+- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
 {
     if (_pendingLayer == nullptr) {
         [NSException raise:@"MGLRedundantLayerException"
@@ -135,11 +135,6 @@ namespace mbgl {
                     "to the style more than once is invalid.", self, mapView.style];
     }
 
-    [self addToMapView:mapView belowLayer:nil];
-}
-
-- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
-{
     if (otherLayer) {
         const mbgl::optional<std::string> belowLayerId{otherLayer.identifier.UTF8String};
         mapView.mbglMap->addLayer(std::move(_pendingLayer), belowLayerId);