[android] Expose pre-fetching zoom delta. (#15769)

* [android] Expose pre-fetching zoom delta.

* [android] Fix Clang format.

* [android] Add MapboxMap unit test.

* [android] Add prefetching zoom delta into MapboxMapOptions.

* [android] Deprecate setPrefetchesTiles to migrate to setPrefetchZoomDelta.

* [android] Deprecate getPrefetchesTiles() and migrate to setPrefetchZoomDelta().

* [android] Add unit test to NativeMapViewTest.

* [android] Add IntRange annotation to getPrefetchZoomDelta.

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

@@ -6,6 +6,7 @@ import android.graphics.PointF;
 import android.graphics.RectF;
 import android.os.Bundle;
 import android.support.annotation.FloatRange;
+import android.support.annotation.IntRange;
 import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
 import android.support.annotation.Size;
@@ -246,12 +247,16 @@ public final class MapboxMap {
   // Style
 
   /**
-   * Sets tile pre-fetching from MapboxOptions.
+   * Sets tile pre-fetching zoom delta from MapboxOptions.
    *
    * @param options the options object
    */
   private void setPrefetchesTiles(@NonNull MapboxMapOptions options) {
-    setPrefetchesTiles(options.getPrefetchesTiles());
+    if (!options.getPrefetchesTiles()) {
+      setPrefetchZoomDelta(0);
+    } else {
+      setPrefetchZoomDelta(options.getPrefetchZoomDelta());
+    }
   }
 
   /**
@@ -259,7 +264,9 @@ public final class MapboxMap {
    * tile is rendered as soon as possible at the expense of a little bandwidth.
    *
    * @param enable true to enable
+   * @deprecated Use {@link #setPrefetchZoomDelta(int)} instead.
    */
+  @Deprecated
   public void setPrefetchesTiles(boolean enable) {
     nativeMapView.setPrefetchTiles(enable);
   }
@@ -269,11 +276,38 @@ public final class MapboxMap {
    *
    * @return true if enabled
    * @see MapboxMap#setPrefetchesTiles(boolean)
+   * @deprecated Use {@link #getPrefetchZoomDelta()} instead.
    */
+  @Deprecated
   public boolean getPrefetchesTiles() {
     return nativeMapView.getPrefetchTiles();
   }
 
+  /**
+   * Set the tile pre-fetching zoom delta. Pre-fetching makes sure that a low-resolution
+   * tile at the (current_zoom_level - delta) is rendered as soon as possible at the
+   * expense of a little bandwidth.
+   * Note: This operation will override the MapboxMapOptions#setPrefetchesTiles(boolean)
+   *       Setting zoom delta to 0 will disable pre-fetching.
+   * Default zoom delta is 4.
+   *
+   * @param delta zoom delta
+   */
+  public void setPrefetchZoomDelta(@IntRange(from = 0) int delta) {
+    nativeMapView.setPrefetchZoomDelta(delta);
+  }
+
+  /**
+   * Check current pre-fetching zoom delta.
+   *
+   * @return current zoom delta.
+   * @see MapboxMap#setPrefetchZoomDelta(int)
+   */
+  @IntRange(from = 0)
+  public int getPrefetchZoomDelta() {
+    return nativeMapView.getPrefetchZoomDelta();
+  }
+
   //
   // MinZoom
   //

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

@@ -8,6 +8,7 @@ import android.graphics.drawable.Drawable;
 import android.os.Parcel;
 import android.os.Parcelable;
 import android.support.annotation.ColorInt;
+import android.support.annotation.IntRange;
 import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
 import android.support.annotation.VisibleForTesting;
@@ -70,6 +71,7 @@ public class MapboxMapOptions implements Parcelable {
   private boolean quickZoomGesturesEnabled = true;
 
   private boolean prefetchesTiles = true;
+  private int prefetchZoomDelta = 4;
   private boolean zMediaOverlay = false;
 
   private boolean localIdeographFontFamilyEnabled = true;
@@ -134,6 +136,7 @@ public class MapboxMapOptions implements Parcelable {
     textureMode = in.readByte() != 0;
     translucentTextureSurface = in.readByte() != 0;
     prefetchesTiles = in.readByte() != 0;
+    prefetchZoomDelta = in.readInt();
     zMediaOverlay = in.readByte() != 0;
     localIdeographFontFamilyEnabled = in.readByte() != 0;
     localIdeographFontFamily = in.readString();
@@ -257,6 +260,8 @@ public class MapboxMapOptions implements Parcelable {
         typedArray.getBoolean(R.styleable.mapbox_MapView_mapbox_renderTextureTranslucentSurface, false));
       mapboxMapOptions.setPrefetchesTiles(
         typedArray.getBoolean(R.styleable.mapbox_MapView_mapbox_enableTilePrefetch, true));
+      mapboxMapOptions.setPrefetchZoomDelta(
+              typedArray.getInt(R.styleable.mapbox_MapView_mapbox_prefetchZoomDelta, 4));
       mapboxMapOptions.renderSurfaceOnTop(
         typedArray.getBoolean(R.styleable.mapbox_MapView_mapbox_enableZMediaOverlay, false));
 
@@ -633,13 +638,32 @@ public class MapboxMapOptions implements Parcelable {
    *
    * @param enable true to enable
    * @return This
+   * @deprecated Use {@link #setPrefetchZoomDelta(int)} instead.
    */
+  @Deprecated
   @NonNull
   public MapboxMapOptions setPrefetchesTiles(boolean enable) {
     this.prefetchesTiles = enable;
     return this;
   }
 
+  /**
+   * Set the tile pre-fetching zoom delta. Pre-fetching makes sure that a low-resolution
+   * tile at the (current_zoom_level - delta) is rendered as soon as possible at the
+   * expense of a little bandwidth.
+   * Note: This operation will override the MapboxMapOptions#setPrefetchesTiles(boolean)
+   *       Setting zoom delta to 0 will disable pre-fetching.
+   * Default zoom delta is 4.
+   *
+   * @param delta zoom delta
+   * @return This
+   */
+  @NonNull
+  public MapboxMapOptions setPrefetchZoomDelta(@IntRange(from = 0) int delta) {
+    this.prefetchZoomDelta = delta;
+    return this;
+  }
+
   /**
    * Enable cross-source symbol collision detection, defaults to true.
    * <p>
@@ -721,11 +745,23 @@ public class MapboxMapOptions implements Parcelable {
    * Check whether tile pre-fetching is enabled.
    *
    * @return true if enabled
+   * @deprecated Use {@link #getPrefetchZoomDelta()} instead.
    */
+  @Deprecated
   public boolean getPrefetchesTiles() {
     return prefetchesTiles;
   }
 
+  /**
+   * Check current pre-fetching zoom delta.
+   *
+   * @return current zoom delta.
+   */
+  @IntRange(from = 0)
+  public int getPrefetchZoomDelta() {
+    return prefetchZoomDelta;
+  }
+
   /**
    * Check whether cross-source symbol collision detection is enabled.
    *
@@ -1081,6 +1117,7 @@ public class MapboxMapOptions implements Parcelable {
     dest.writeByte((byte) (textureMode ? 1 : 0));
     dest.writeByte((byte) (translucentTextureSurface ? 1 : 0));
     dest.writeByte((byte) (prefetchesTiles ? 1 : 0));
+    dest.writeInt(prefetchZoomDelta);
     dest.writeByte((byte) (zMediaOverlay ? 1 : 0));
     dest.writeByte((byte) (localIdeographFontFamilyEnabled ? 1 : 0));
     dest.writeString(localIdeographFontFamily);
@@ -1175,6 +1212,9 @@ public class MapboxMapOptions implements Parcelable {
     if (prefetchesTiles != options.prefetchesTiles) {
       return false;
     }
+    if (prefetchZoomDelta != options.prefetchZoomDelta) {
+      return false;
+    }
     if (zMediaOverlay != options.zMediaOverlay) {
       return false;
     }
@@ -1231,6 +1271,7 @@ public class MapboxMapOptions implements Parcelable {
     result = 31 * result + (textureMode ? 1 : 0);
     result = 31 * result + (translucentTextureSurface ? 1 : 0);
     result = 31 * result + (prefetchesTiles ? 1 : 0);
+    result = 31 * result + prefetchZoomDelta;
     result = 31 * result + (zMediaOverlay ? 1 : 0);
     result = 31 * result + (localIdeographFontFamilyEnabled ? 1 : 0);
     result = 31 * result + (localIdeographFontFamily != null ? localIdeographFontFamily.hashCode() : 0);

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

@@ -6,6 +6,7 @@ import android.graphics.RectF;
 import android.support.annotation.IntRange;
 import android.support.annotation.NonNull;
 import android.support.annotation.Nullable;
+
 import com.mapbox.geojson.Feature;
 import com.mapbox.geojson.Geometry;
 import com.mapbox.mapboxsdk.annotations.Marker;
@@ -214,6 +215,11 @@ interface NativeMap {
 
   boolean getPrefetchTiles();
 
+  void setPrefetchZoomDelta(@IntRange(from = 0) int delta);
+
+  @IntRange(from = 0)
+  int getPrefetchZoomDelta();
+
   void setGestureInProgress(boolean inProgress);
 
   float getPixelRatio();

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

@@ -724,6 +724,23 @@ final class NativeMapView implements NativeMap {
     return nativeGetPrefetchTiles();
   }
 
+  @Override
+  public void setPrefetchZoomDelta(@IntRange(from = 0) int delta) {
+    if (checkState("nativeSetPrefetchZoomDelta")) {
+      return;
+    }
+    nativeSetPrefetchZoomDelta(delta);
+  }
+
+  @Override
+  @IntRange(from = 0)
+  public int getPrefetchZoomDelta() {
+    if (checkState("nativeGetPrefetchZoomDelta")) {
+      return 0;
+    }
+    return nativeGetPrefetchZoomDelta();
+  }
+
   // Runtime style Api
 
   @Override
@@ -1383,6 +1400,12 @@ final class NativeMapView implements NativeMap {
   @Keep
   private native boolean nativeGetPrefetchTiles();
 
+  @Keep
+  private native void nativeSetPrefetchZoomDelta(int delta);
+
+  @Keep
+  private native int nativeGetPrefetchZoomDelta();
+
   @Override
   public long getNativePtr() {
     return nativePtr;

platform/android/MapboxGLAndroidSDK/src/main/res-public/values/public.xml

@@ -69,6 +69,7 @@
     <public name="mapbox_foregroundLoadColor" type="attr" />
 
     <public name="mapbox_enableTilePrefetch" type="attr" />
+    <public name="mapbox_prefetchZoomDelta" type="attr"/>
     <public name="mapbox_enableZMediaOverlay" type="attr" />
 
     <!-- Exposed content descriptions -->

platform/android/MapboxGLAndroidSDK/src/main/res/values/attrs.xml

@@ -109,6 +109,7 @@
         <attr name="mapbox_foregroundLoadColor" format="color"/>
 
         <attr name="mapbox_enableTilePrefetch" format="boolean"/>
+        <attr name="mapbox_prefetchZoomDelta" format="integer"/>
         <attr name="mapbox_enableZMediaOverlay" format="boolean"/>
         <attr name="mapbox_pixelRatio" format="float"/>
 

platform/android/MapboxGLAndroidSDK/src/test/java/com/mapbox/mapboxsdk/maps/MapboxMapOptionsTest.java

@@ -167,6 +167,16 @@ public class MapboxMapOptionsTest {
     assertFalse(new MapboxMapOptions().setPrefetchesTiles(false).getPrefetchesTiles());
   }
 
+  @Test
+  public void testPrefetchZoomDelta() {
+    // Default value
+    assertEquals(4, new MapboxMapOptions().getPrefetchZoomDelta());
+
+    // Check mutations
+    assertEquals(5, new MapboxMapOptions().setPrefetchZoomDelta(5).getPrefetchZoomDelta());
+  }
+
+
   @Test
   public void testCrossSourceCollisions() {
     // Default value

platform/android/MapboxGLAndroidSDK/src/test/java/com/mapbox/mapboxsdk/maps/MapboxMapTest.kt

@@ -126,6 +126,18 @@ class MapboxMapTest {
     verify { nativeMapView.prefetchTiles = true }
   }
 
+  @Test
+  fun testGetPrefetchZoomDelta() {
+    every { nativeMapView.prefetchZoomDelta } answers { 3 }
+    assertEquals(3, mapboxMap.prefetchZoomDelta)
+  }
+
+  @Test
+  fun testSetPrefetchZoomDelta() {
+    mapboxMap.prefetchZoomDelta = 2
+    verify { nativeMapView.prefetchZoomDelta = 2 }
+  }
+
   @Test
   fun testCameraForLatLngBounds() {
     val bounds = LatLngBounds.Builder().include(LatLng()).include(LatLng(1.0, 1.0)).build()