[core][android] Provide API to control eviction of cached images

include/mbgl/map/map_observer.hpp

@@ -48,6 +48,9 @@ class MapObserver {
     virtual void onSourceChanged(style::Source&) {}
     virtual void onDidBecomeIdle() {}
     virtual void onStyleImageMissing(const std::string&) {}
+    // This method should return true if unused image can be removed,
+    // false otherwise. By default, unused image will be removed.
+    virtual bool onCanRemoveUnusedStyleImage(const std::string&) { return true; }
 };
 
 } // namespace mbgl

include/mbgl/renderer/renderer_observer.hpp

@@ -35,6 +35,7 @@ class RendererObserver {
     // Style is missing an image
     using StyleImageMissingCallback = std::function<void()>;
     virtual void onStyleImageMissing(const std::string&, StyleImageMissingCallback done) { done(); }
+    virtual void onRemoveUnusedStyleImages(const std::vector<std::string>&) {}
 };
 
 } // namespace mbgl

include/mbgl/util/constants.hpp

@@ -48,6 +48,10 @@ constexpr uint8_t DEFAULT_PREFETCH_ZOOM_DELTA = 4;
 
 constexpr uint64_t DEFAULT_MAX_CACHE_SIZE = 50 * 1024 * 1024;
 
+// Default ImageManager's cache size for images added via onStyleImageMissing API.
+// Average sprite size with 1.0 pixel ratio is ~2kB, 8kB for pixel ratio of 2.0.
+constexpr std::size_t DEFAULT_ON_DEMAND_IMAGES_CACHE_SIZE = 100 * 8192;
+
 constexpr Duration DEFAULT_TRANSITION_DURATION = Milliseconds(300);
 constexpr Seconds CLOCK_SKEW_RETRY_TIMEOUT { 30 };
 

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapChangeReceiver.java

@@ -33,6 +33,8 @@ class MapChangeReceiver implements NativeMapView.StateCallback {
   private final List<MapView.OnSourceChangedListener> onSourceChangedListenerList = new CopyOnWriteArrayList<>();
   private final List<MapView.OnStyleImageMissingListener> onStyleImageMissingListenerList
     = new CopyOnWriteArrayList<>();
+  private final List<MapView.OnCanRemoveUnusedStyleImageListener> onCanRemoveUnusedStyleImageListenerList
+    = new CopyOnWriteArrayList<>();
 
   @Override
   public void onCameraWillChange(boolean animated) {
@@ -230,6 +232,29 @@ public void onStyleImageMissing(String imageId) {
     }
   }
 
+  @Override
+  public boolean onCanRemoveUnusedStyleImage(String imageId) {
+    if (onCanRemoveUnusedStyleImageListenerList.isEmpty()) {
+      return true;
+    }
+
+    try {
+      if (!onCanRemoveUnusedStyleImageListenerList.isEmpty()) {
+        boolean canRemove = true;
+        for (MapView.OnCanRemoveUnusedStyleImageListener listener : onCanRemoveUnusedStyleImageListenerList) {
+          canRemove &= listener.onCanRemoveUnusedStyleImage(imageId);
+        }
+
+        return canRemove;
+      }
+    } catch (Throwable err) {
+      Logger.e(TAG, "Exception in onCanRemoveUnusedStyleImage", err);
+      throw err;
+    }
+
+    return true;
+  }
+
   void addOnCameraWillChangeListener(MapView.OnCameraWillChangeListener listener) {
     onCameraWillChangeListenerList.add(listener);
   }
@@ -342,6 +367,14 @@ void removeOnStyleImageMissingListener(MapView.OnStyleImageMissingListener liste
     onStyleImageMissingListenerList.remove(listener);
   }
 
+  void addOnCanRemoveUnusedStyleImageListener(MapView.OnCanRemoveUnusedStyleImageListener listener) {
+    onCanRemoveUnusedStyleImageListenerList.add(listener);
+  }
+
+  void removeOnCanRemoveUnusedStyleImageListener(MapView.OnCanRemoveUnusedStyleImageListener listener) {
+    onCanRemoveUnusedStyleImageListenerList.remove(listener);
+  }
+
   void clear() {
     onCameraWillChangeListenerList.clear();
     onCameraIsChangingListenerList.clear();
@@ -357,5 +390,6 @@ void clear() {
     onDidFinishLoadingStyleListenerList.clear();
     onSourceChangedListenerList.clear();
     onStyleImageMissingListenerList.clear();
+    onCanRemoveUnusedStyleImageListenerList.clear();
   }
 }

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/MapView.java

@@ -797,6 +797,33 @@ public void removeOnStyleImageMissingListener(@NonNull OnStyleImageMissingListen
     mapChangeReceiver.removeOnStyleImageMissingListener(listener);
   }
 
+  /**
+   * Set a callback that's invoked when map needs to release unused image resources.
+   *
+   * A callback will be called only for unused images that were provided by the client via
+   * {@link OnStyleImageMissingListener#onStyleImageMissing(String)} listener interface.
+   *
+   * By default, platform will remove unused images from the style. By adding listener, default
+   * behavior can be overridden and client can control whether to release unused resources.
+   *
+   * @param listener The callback that's invoked when map needs to release unused image resources
+   */
+  public void addOnCanRemoveUnusedStyleImageListener(@NonNull OnCanRemoveUnusedStyleImageListener listener) {
+    mapChangeReceiver.addOnCanRemoveUnusedStyleImageListener(listener);
+  }
+
+  /**
+   * Removes a callback that's invoked when map needs to release unused image resources.
+   *
+   * When all listeners are removed, platform will fallback to default behavior, which is to remove
+   * unused images from the style.
+   *
+   * @param listener The callback that's invoked when map needs to release unused image resources
+   */
+  public void removeOnCanRemoveUnusedStyleImageListener(@NonNull OnCanRemoveUnusedStyleImageListener listener) {
+    mapChangeReceiver.removeOnCanRemoveUnusedStyleImageListener(listener);
+  }
+
   /**
    * Interface definition for a callback to be invoked when the camera will change.
    * <p>
@@ -994,6 +1021,22 @@ public interface OnStyleImageMissingListener {
     void onStyleImageMissing(@NonNull String id);
   }
 
+  /**
+   * Interface definition for a callback to be invoked with an unused image identifier.
+   * <p>
+   * {@link MapView#addOnCanRemoveUnusedStyleImageListener(OnCanRemoveUnusedStyleImageListener)}
+   * </p>
+   */
+  public interface OnCanRemoveUnusedStyleImageListener {
+    /**
+     * Called when the map needs to release unused image resources.
+     *
+     * @param id of an image that is not used by the map and can be removed from the style.
+     * @return true if image can be removed, false otherwise.
+     */
+    boolean onCanRemoveUnusedStyleImage(@NonNull String id);
+  }
+
   /**
    * Sets a callback object which will be triggered when the {@link MapboxMap} instance is ready to be used.
    *

platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/maps/NativeMapView.java

@@ -1050,6 +1050,15 @@ private void onStyleImageMissing(String imageId) {
     }
   }
 
+  @Keep
+  private boolean onCanRemoveUnusedStyleImage(String imageId) {
+    if (stateCallback != null) {
+      return stateCallback.onCanRemoveUnusedStyleImage(imageId);
+    }
+
+    return true;
+  }
+
   @Keep
   protected void onSnapshotReady(@Nullable Bitmap mapContent) {
     if (checkState("OnSnapshotReady")) {
@@ -1463,5 +1472,7 @@ interface StateCallback extends StyleCallback {
     void onSourceChanged(String sourceId);
 
     void onStyleImageMissing(String imageId);
+
+    boolean onCanRemoveUnusedStyleImage(String imageId);
   }
 }

platform/android/MapboxGLAndroidSDKTestApp/src/androidTest/java/com/mapbox/mapboxsdk/testapp/maps/RemoveUnusedImagesTest.kt

@@ -0,0 +1,162 @@
+package com.mapbox.mapboxsdk.testapp.maps
+
+import android.graphics.Bitmap
+import android.support.test.rule.ActivityTestRule
+import android.support.test.runner.AndroidJUnit4
+import com.mapbox.mapboxsdk.camera.CameraUpdateFactory
+import com.mapbox.mapboxsdk.geometry.LatLng
+import com.mapbox.mapboxsdk.maps.MapView
+import com.mapbox.mapboxsdk.maps.MapboxMap
+import com.mapbox.mapboxsdk.maps.Style
+import com.mapbox.mapboxsdk.testapp.R
+import com.mapbox.mapboxsdk.testapp.activity.espresso.EspressoTestActivity
+import org.junit.Assert.*
+import org.junit.Before
+import org.junit.Rule
+import org.junit.Test
+import org.junit.runner.RunWith
+import java.util.concurrent.CountDownLatch
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.TimeoutException
+
+@RunWith(AndroidJUnit4::class)
+class RemoveUnusedImagesTest {
+
+  @Rule
+  @JvmField
+  var rule = ActivityTestRule(EspressoTestActivity::class.java)
+
+  private lateinit var mapView: MapView
+  private lateinit var mapboxMap: MapboxMap
+  private val latch = CountDownLatch(1)
+
+  @Before
+  fun setup() {
+    rule.runOnUiThread {
+      mapView = rule.activity.findViewById(R.id.mapView)
+      mapView.getMapAsync {
+        mapboxMap = it;
+        mapboxMap.setStyle(Style.Builder().fromJson(styleJson))
+      }
+    }
+  }
+
+  @Test
+  fun testRemoveUnusedImagesUserProvidedListener() {
+    var callbackLatch = CountDownLatch(2)
+    rule.runOnUiThread {
+      mapView.addOnStyleImageMissingListener {
+        mapboxMap.style!!.addImage(it, Bitmap.createBitmap(512, 512,  Bitmap.Config.ARGB_8888))
+      }
+
+      // Remove layer and source, so that rendered tiles are no longer used, therefore, map must
+      // notify client about unused images.
+      mapView.addOnDidBecomeIdleListener {
+        mapboxMap.style!!.removeLayer("icon")
+        mapboxMap.style!!.removeSource("geojson")
+      }
+
+      mapView.addOnCanRemoveUnusedStyleImageListener {
+        callbackLatch.countDown()
+        mapboxMap.moveCamera(CameraUpdateFactory.newLatLngZoom(LatLng(0.0, 120.0), 8.0))
+        mapView.addOnDidFinishRenderingFrameListener {
+          assertNotNull(mapboxMap.style!!.getImage("small"))
+          assertNotNull(mapboxMap.style!!.getImage("large"))
+          latch.countDown()
+        }
+        return@addOnCanRemoveUnusedStyleImageListener false
+      }
+    }
+
+    if(!latch.await(5, TimeUnit.SECONDS) && !callbackLatch.await(5, TimeUnit.SECONDS)){
+      throw TimeoutException()
+    }
+  }
+
+  @Test
+  fun testRemoveUnusedImagesDefaultListener() {
+    rule.runOnUiThread {
+      mapView.addOnStyleImageMissingListener {
+        mapboxMap.style!!.addImage(it, Bitmap.createBitmap(512, 512,  Bitmap.Config.ARGB_8888))
+      }
+
+      // Remove layer and source, so that rendered tiles are no longer used, thus
+      // map must request removal of unused images.
+      mapView.addOnDidBecomeIdleListener {
+        mapboxMap.style!!.removeLayer("icon")
+        mapboxMap.style!!.removeSource("geojson")
+        mapboxMap.moveCamera(CameraUpdateFactory.newLatLngZoom(LatLng(0.0, 120.0), 8.0))
+
+        // Wait for the next frame and check that images were removed from the style.
+        mapView.addOnDidFinishRenderingFrameListener {
+          if (mapboxMap.style!!.getImage("small") == null && mapboxMap.style!!.getImage("large") == null) {
+            latch.countDown()
+          }
+        }
+      }
+    }
+
+    if(!latch.await(5, TimeUnit.SECONDS)){
+      throw TimeoutException()
+    }
+  }
+
+  companion object {
+    private const val styleJson = """
+    {
+      "version": 8,
+      "name": "Mapbox Streets",
+      "sources": {
+        "geojson": {
+          "type": "geojson",
+          "data": {
+            "type": "FeatureCollection",
+            "features": [
+              {
+                "type": "Feature",
+                "properties": {
+                  "image": "small"
+                },
+                "geometry": {
+                  "type": "Point",
+                  "coordinates": [
+                    0,
+                    0
+                  ]
+                }
+              },
+              {
+                "type": "Feature",
+                "properties": {
+                  "image": "large"
+                },
+                "geometry": {
+                  "type": "Point",
+                  "coordinates": [
+                    1,
+                    1
+                  ]
+                }
+              }
+            ]
+          }
+        }
+      },
+      "layers": [{
+        "id": "bg",
+        "type": "background",
+        "paint": {
+          "background-color": "#f00"
+        }
+      },{
+        "id": "icon",
+        "type": "symbol",
+        "source": "geojson",
+        "layout": {
+          "icon-image": ["get", "image"]
+        }
+      }]
+    }
+    """
+  }
+}

platform/android/src/android_renderer_frontend.cpp

@@ -54,6 +54,10 @@ class ForwardingRendererObserver : public RendererObserver {
         delegate.invoke(&RendererObserver::onStyleImageMissing, id, done);
     }
 
+    void onRemoveUnusedStyleImages(const std::vector<std::string>& ids) override {
+        delegate.invoke(&RendererObserver::onRemoveUnusedStyleImages, ids);
+    }
+
 private:
     std::shared_ptr<Mailbox> mailbox;
     ActorRef<RendererObserver> delegate;

platform/android/src/native_map_view.cpp

@@ -271,6 +271,20 @@ void NativeMapView::onStyleImageMissing(const std::string& imageId) {
     }
 }
 
+bool NativeMapView::onCanRemoveUnusedStyleImage(const std::string& imageId) {
+    assert(vm != nullptr);
+
+    android::UniqueEnv _env = android::AttachEnv();
+    static auto& javaClass = jni::Class<NativeMapView>::Singleton(*_env);
+    static auto onCanRemoveUnusedStyleImage = javaClass.GetMethod<jboolean (jni::String)>(*_env, "onCanRemoveUnusedStyleImage");
+    auto weakReference = javaPeer.get(*_env);
+    if (weakReference) {
+        return weakReference.Call(*_env, onCanRemoveUnusedStyleImage, jni::Make<jni::String>(*_env, imageId));
+    }
+
+    return true;
+}
+
 // JNI Methods //
 
 void NativeMapView::resizeView(jni::JNIEnv&, int w, int h) {

platform/android/src/native_map_view.hpp

@@ -69,6 +69,7 @@ class NativeMapView : public MapObserver {
     void onDidFinishLoadingStyle() override;
     void onSourceChanged(mbgl::style::Source&) override;
     void onStyleImageMissing(const std::string&) override;
+    bool onCanRemoveUnusedStyleImage(const std::string&) override;
 
     // JNI //
 

src/mbgl/map/map_impl.cpp

@@ -179,4 +179,12 @@ void Map::Impl::onStyleImageMissing(const std::string& id, std::function<void()>
     onUpdate();
 }
 
+void Map::Impl::onRemoveUnusedStyleImages(const std::vector<std::string>& unusedImageIDs) {
+    for (const auto& unusedImageID : unusedImageIDs) {
+        if (observer.onCanRemoveUnusedStyleImage(unusedImageID)) {
+            style->removeImage(unusedImageID);
+        }
+    }
+}
+
 } // namespace mbgl

src/mbgl/map/map_impl.hpp

@@ -46,6 +46,7 @@ class Map::Impl : public style::Observer, public RendererObserver {
     void onWillStartRenderingMap() final;
     void onDidFinishRenderingMap() final;
     void onStyleImageMissing(const std::string&, std::function<void()>) final;
+    void onRemoveUnusedStyleImages(const std::vector<std::string>&) final;
 
     // Map
     void jumpTo(const CameraOptions&);