[ios] Add removeStyleImage to MGLMapView (#14769)

* [ios] Add shoulRremoveStyleImage to MGLMapViewDelegate.

* [ios] Changelog update.

* [ios, macos] Update shouldRemoveStyle method documentation.

platform/ios/CHANGELOG.md

@@ -18,6 +18,10 @@ Mapbox welcomes participation and contributions from everyone. Please read [CONT
 
 * Removed previously deprecated methods and properties that had been marked `unavailable`. ([#15000](https://github.com/mapbox/mapbox-gl-native/pull/15000))
 
+### Styles and rendering
+
+* Added the `-[MGLMapViewDelegate mapView:shouldRemoveStyleImage:]` method for optimizing style image caching. ([#14769](https://github.com/mapbox/mapbox-gl-native/pull/14769))
+
 ### Other changes
 
 * Added variants of several animated `MGLMapView` methods that accept completion handlers ([#14381](https://github.com/mapbox/mapbox-gl-native/pull/14381)):

platform/ios/src/MGLMapView+Impl.h

@@ -69,6 +69,7 @@ public:
     void onSourceChanged(mbgl::style::Source& source) override;
     void onDidBecomeIdle() override;
     void onStyleImageMissing(const std::string& imageIdentifier) override;
+    bool onCanRemoveUnusedStyleImage(const std::string& imageIdentifier) override;
 
 protected:
     /// Cocoa map view that this adapter bridges to.

platform/ios/src/MGLMapView+Impl.mm

@@ -100,3 +100,8 @@ void MGLMapViewImpl::onStyleImageMissing(const std::string& imageIdentifier) {
     NSString *imageName = [NSString stringWithUTF8String:imageIdentifier.c_str()];
     [mapView didFailToLoadImage:imageName];
 }
+
+bool MGLMapViewImpl::onCanRemoveUnusedStyleImage(const std::string &imageIdentifier) {
+    NSString *imageName = [NSString stringWithUTF8String:imageIdentifier.c_str()];
+    return [mapView shouldRemoveStyleImage:imageName];
+}

platform/ios/src/MGLMapView.mm

@@ -6234,6 +6234,14 @@ public:
     }
 }
 
+- (BOOL)shouldRemoveStyleImage:(NSString *)imageName {
+    if ([self.delegate respondsToSelector:@selector(mapView:shouldRemoveStyleImage:)]) {
+        return [self.delegate mapView:self shouldRemoveStyleImage:imageName];
+    }
+    
+    return YES;
+}
+
 - (void)updateUserLocationAnnotationView
 {
     [self updateUserLocationAnnotationViewAnimatedWithDuration:0];

platform/ios/src/MGLMapViewDelegate.h

@@ -277,6 +277,20 @@ NS_ASSUME_NONNULL_BEGIN
 
 - (nullable UIImage *)mapView:(MGLMapView *)mapView didFailToLoadImage:(NSString *)imageName;
 
+/**
+ Asks the delegate whether the map view should evict cached images.
+ 
+ This method is called in two scenarios: when the cumulative size of unused images
+ exceeds the cache size or when the last tile that includes the image is removed from
+ memory.
+ 
+ @param mapView The map view that is evicting the image.
+ @param imageName The image name that is going to be removed.
+ @return A Boolean value indicating whether the map view should evict
+ the cached image.
+ */
+- (BOOL)mapView:(MGLMapView *)mapView shouldRemoveStyleImage:(NSString *)imageName;
+
 #pragma mark Tracking User Location
 
 /**

platform/ios/src/MGLMapView_Private.h

@@ -41,6 +41,7 @@ FOUNDATION_EXTERN MGL_EXPORT MGLExceptionName const _Nonnull MGLUnderlyingMapUna
 - (void)mapViewDidFinishLoadingStyle;
 - (void)sourceDidChange:(nonnull MGLSource *)source;
 - (void)didFailToLoadImage:(nonnull NSString *)imageName;
+- (BOOL)shouldRemoveStyleImage:(nonnull NSString *)imageName;
 
 /** Triggers another render pass even when it is not necessary. */
 - (void)setNeedsRerender;

platform/ios/test/MGLMapViewDelegateIntegrationTests.swift

@@ -98,4 +98,6 @@ extension MGLMapViewDelegateIntegrationTests: MGLMapViewDelegate {
     func mapViewUserLocationAnchorPoint(_ mapView: MGLMapView) -> CGPoint { return CGPoint(x: 100, y: 100) }
     
     func mapView(_ mapView: MGLMapView, didFailToLoadImage imageName: String) -> UIImage? { return nil }
+    
+    func mapView(_ mapView: MGLMapView, shouldRemoveStyleImage imageName: String) -> Bool { return false }
 }

platform/macos/CHANGELOG.md

@@ -8,6 +8,7 @@
 ### Styles and rendering
 
 * Setting `MGLMapView.contentInset` now moves the map’s focal point to the center of the content frame after insetting. ([#14664](https://github.com/mapbox/mapbox-gl-native/pull/14664))
+* Added the `-[MGLMapViewDelegate mapView:shouldRemoveStyleImage:]` method for optimizing style image caching. ([#14769](https://github.com/mapbox/mapbox-gl-native/pull/14769))
 
 ### Other changes
 

platform/macos/src/MGLMapView+Impl.h

@@ -36,6 +36,7 @@ public:
     void onDidFinishLoadingStyle() override;
     void onSourceChanged(mbgl::style::Source& source) override;
     void onDidBecomeIdle() override;
+    bool onCanRemoveUnusedStyleImage(const std::string& imageIdentifier) override;
 
 protected:
     /// Cocoa map view that this adapter bridges to.

platform/macos/src/MGLMapView+Impl.mm

@@ -94,3 +94,8 @@ void MGLMapViewImpl::onSourceChanged(mbgl::style::Source& source) {
     MGLSource * nativeSource = [mapView.style sourceWithIdentifier:identifier];
     [mapView sourceDidChange:nativeSource];
 }
+
+bool MGLMapViewImpl::onCanRemoveUnusedStyleImage(const std::string &imageIdentifier) {
+    NSString *imageName = [NSString stringWithUTF8String:imageIdentifier.c_str()];
+    return [mapView shouldRemoveStyleImage:imageName];
+}

platform/macos/src/MGLMapView.mm

@@ -978,6 +978,14 @@ public:
     self.needsDisplay = YES;
 }
 
+- (BOOL)shouldRemoveStyleImage:(NSString *)imageName {
+    if ([self.delegate respondsToSelector:@selector(mapView:shouldRemoveStyleImage:)]) {
+        return [self.delegate mapView:self shouldRemoveStyleImage:imageName];
+    }
+    
+    return YES;
+}
+
 #pragma mark Printing
 
 - (void)print:(__unused id)sender {

platform/macos/src/MGLMapViewDelegate.h

@@ -183,6 +183,20 @@ NS_ASSUME_NONNULL_BEGIN
 
 - (nullable NSImage *)mapView:(MGLMapView *)mapView didFailToLoadImage:(NSString *)imageName;
 
+/**
+ Asks the delegate whether the map view should evict cached images.
+ 
+ This method is called in two scenarios: when the cumulative size of unused images
+ exceeds the cache size or when the last tile that includes the image is removed from
+ memory.
+ 
+ @param mapView The map view that is evicting the image.
+ @param imageName The image name that is going to be removed.
+ @return A Boolean value indicating whether the map view should evict
+ the cached image.
+ */
+- (BOOL)mapView:(MGLMapView *)mapView shouldRemoveStyleImage:(NSString *)imageName;
+
 #pragma mark Managing the Appearance of Annotations
 
 /**

platform/macos/src/MGLMapView_Private.h

@@ -45,6 +45,7 @@ namespace mbgl {
 - (void)mapViewDidBecomeIdle;
 - (void)mapViewDidFinishLoadingStyle;
 - (void)sourceDidChange:(nonnull MGLSource *)source;
+- (BOOL)shouldRemoveStyleImage:(nonnull NSString *)imageName;
 
 /// Asynchronously render a frame of the map.
 - (void)setNeedsRerender;

platform/macos/test/MGLMapViewDelegateIntegrationTests.swift

@@ -59,4 +59,5 @@ extension MGLMapViewDelegateIntegrationTests: MGLMapViewDelegate {
 
     func mapView(_ mapView: MGLMapView, calloutViewControllerFor annotation: MGLAnnotation) -> NSViewController? { return nil }
 
+    func mapView(_ mapView: MGLMapView, shouldRemoveStyleImage imageName: String) -> Bool { return false }
 }