[android] LocationComponent max fps javadocupstream/lp-animators-battery-optimization

4 files changed, 53 insertions, 6 deletions

diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationComponent.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationComponent.java
index 5dc9172672..f27af0a517 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationComponent.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationComponent.java
@@ -25,6 +25,7 @@ import com.mapbox.mapboxsdk.geometry.LatLng;
 import com.mapbox.mapboxsdk.location.modes.CameraMode;
 import com.mapbox.mapboxsdk.location.modes.RenderMode;
 import com.mapbox.mapboxsdk.log.Logger;
+import com.mapbox.mapboxsdk.maps.MapView;
 import com.mapbox.mapboxsdk.maps.MapboxMap;
 import com.mapbox.mapboxsdk.maps.MapboxMap.OnCameraIdleListener;
 import com.mapbox.mapboxsdk.maps.MapboxMap.OnCameraMoveListener;
@@ -702,6 +703,46 @@ public final class LocationComponent {
     updateLocation(location, false);
   }
 
+  /**
+   * Set max FPS at which location animators can output updates. The throttling will only impact the location puck
+   * and camera tracking smooth animations.
+   * <p>
+   * Setting this <b>will not impact</b> any other animations schedule with {@link MapboxMap}, gesture animations or
+   * {@link #zoomWhileTracking(double)}/{@link #tiltWhileTracking(double)}.
+   * <p>
+   * Use this setting to limit animation rate of the location puck on higher zoom levels to decrease the stress on
+   * the device's CPU which can directly improve battery life, without sacrificing UX.
+   * <p>
+   * Example usage:
+   * <pre>
+   * {@code
+   * mapboxMap.addOnCameraIdleListener(new MapboxMap.OnCameraIdleListener() {
+   *   @Override
+   *   public void onCameraIdle() {
+   *     double zoom = mapboxMap.getCameraPosition().zoom;
+   *     int maxAnimationFps;
+   *     if (zoom < 5) {
+   *       maxAnimationFps = 3;
+   *     } else if (zoom < 10) {
+   *       maxAnimationFps = 5;
+   *     } else if (zoom < 15) {
+   *       maxAnimationFps = 7;
+   *     } else if (zoom < 18) {
+   *       maxAnimationFps = 15;
+   *     } else {
+   *       maxAnimationFps = Integer.MAX_VALUE;
+   *     }
+   *     locationComponent.setMaxAnimationFps(maxAnimationFps);
+   *   }
+   * });
+   * }
+   * </pre>
+   * <p>
+   * If you're looking for a way to throttle the FPS of the whole map, including other animations and gestures, see
+   * {@link MapView#setMaximumFps(int)}.
+   *
+   * @param maxAnimationFps max location animation FPS
+   */
   public void setMaxAnimationFps(int maxAnimationFps) {
     locationAnimatorCoordinator.setMaxAnimationFps(maxAnimationFps);
   }
diff --git a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationLayerController.java b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationLayerController.java
index c726caacfb..1fa36515a7 100644
--- a/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationLayerController.java
+++ b/platform/android/MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationLayerController.java
@@ -447,7 +447,8 @@ final class LocationLayerController {
     if (renderMode == RenderMode.GPS) {
       holders.add(new AnimatorListenerHolder(MapboxAnimator.ANIMATOR_LAYER_GPS_BEARING, gpsBearingValueListener));
     } else if (renderMode == RenderMode.COMPASS) {
-      holders.add(new AnimatorListenerHolder(MapboxAnimator.ANIMATOR_LAYER_COMPASS_BEARING, compassBearingValueListener));
+      holders.add(
+        new AnimatorListenerHolder(MapboxAnimator.ANIMATOR_LAYER_COMPASS_BEARING, compassBearingValueListener));
     }
 
     if (renderMode == RenderMode.COMPASS || renderMode == RenderMode.NORMAL) {
diff --git a/platform/android/MapboxGLAndroidSDK/src/test/java/com/mapbox/mapboxsdk/location/LocationCameraControllerTest.java b/platform/android/MapboxGLAndroidSDK/src/test/java/com/mapbox/mapboxsdk/location/LocationCameraControllerTest.java
index 3be150c3ee..56a8f276a7 100644
--- a/platform/android/MapboxGLAndroidSDK/src/test/java/com/mapbox/mapboxsdk/location/LocationCameraControllerTest.java
+++ b/platform/android/MapboxGLAndroidSDK/src/test/java/com/mapbox/mapboxsdk/location/LocationCameraControllerTest.java
@@ -346,7 +346,8 @@ public class LocationCameraControllerTest {
     camera.setCameraMode(TRACKING_COMPASS);
     float compassBearing = 5f;
 
-    getAnimationListener(ANIMATOR_CAMERA_COMPASS_BEARING, camera.getAnimationListeners()).onNewAnimationValue(compassBearing);
+    getAnimationListener(ANIMATOR_CAMERA_COMPASS_BEARING, camera.getAnimationListeners())
+      .onNewAnimationValue(compassBearing);
 
     verify(mapboxMap).moveCamera(any(CameraUpdate.class));
   }
@@ -359,7 +360,8 @@ public class LocationCameraControllerTest {
     camera.setCameraMode(NONE_COMPASS);
     float compassBearing = 5f;
 
-    getAnimationListener(ANIMATOR_CAMERA_COMPASS_BEARING, camera.getAnimationListeners()).onNewAnimationValue(compassBearing);
+    getAnimationListener(ANIMATOR_CAMERA_COMPASS_BEARING, camera.getAnimationListeners())
+      .onNewAnimationValue(compassBearing);
 
     verify(mapboxMap).moveCamera(any(CameraUpdate.class));
   }
diff --git a/platform/android/MapboxGLAndroidSDK/src/test/java/com/mapbox/mapboxsdk/location/LocationLayerControllerTest.java b/platform/android/MapboxGLAndroidSDK/src/test/java/com/mapbox/mapboxsdk/location/LocationLayerControllerTest.java
index de67f616e2..10553700b3 100644
--- a/platform/android/MapboxGLAndroidSDK/src/test/java/com/mapbox/mapboxsdk/location/LocationLayerControllerTest.java
+++ b/platform/android/MapboxGLAndroidSDK/src/test/java/com/mapbox/mapboxsdk/location/LocationLayerControllerTest.java
@@ -518,7 +518,8 @@ public class LocationLayerControllerTest {
     layer.setRenderMode(RenderMode.COMPASS);
     float compassBearing = 2f;
 
-    getAnimationListener(ANIMATOR_LAYER_COMPASS_BEARING, layer.getAnimationListeners()).onNewAnimationValue(compassBearing);
+    getAnimationListener(ANIMATOR_LAYER_COMPASS_BEARING, layer.getAnimationListeners())
+      .onNewAnimationValue(compassBearing);
 
     verify(locationFeature).addNumberProperty(PROPERTY_COMPASS_BEARING, compassBearing);
   }
@@ -561,7 +562,8 @@ public class LocationLayerControllerTest {
     layer.setRenderMode(RenderMode.NORMAL);
     float accuracyRadiusValue = 2f;
 
-    getAnimationListener(ANIMATOR_LAYER_ACCURACY, layer.getAnimationListeners()).onNewAnimationValue(accuracyRadiusValue);
+    getAnimationListener(ANIMATOR_LAYER_ACCURACY, layer.getAnimationListeners())
+      .onNewAnimationValue(accuracyRadiusValue);
 
     verify(locationFeature).addNumberProperty(PROPERTY_ACCURACY_RADIUS, accuracyRadiusValue);
   }
@@ -584,7 +586,8 @@ public class LocationLayerControllerTest {
     float accuracyRadiusValue = 2f;
 
     assertNull(getAnimationListener(ANIMATOR_LAYER_ACCURACY, layer.getAnimationListeners()));
-    verify(locationFeature, times(0)).addNumberProperty(PROPERTY_ACCURACY_RADIUS, accuracyRadiusValue);
+    verify(locationFeature, times(0))
+      .addNumberProperty(PROPERTY_ACCURACY_RADIUS, accuracyRadiusValue);
   }
 
   private LayerFeatureProvider buildFeatureProvider(@NonNull LocationComponentOptions options) {