Adding pulsing circle to LocationComponent options

MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/IndicatorLocationLayerRenderer.java

@@ -2,8 +2,6 @@
 
 import android.graphics.Bitmap;
 
-import androidx.annotation.Nullable;
-
 import com.mapbox.mapboxsdk.geometry.LatLng;
 import com.mapbox.mapboxsdk.location.modes.RenderMode;
 import com.mapbox.mapboxsdk.maps.Style;
@@ -12,6 +10,8 @@
 import com.mapbox.mapboxsdk.utils.BitmapUtils;
 import com.mapbox.mapboxsdk.utils.ColorUtils;
 
+import androidx.annotation.Nullable;
+
 import static com.mapbox.mapboxsdk.location.LocationComponentConstants.BACKGROUND_ICON;
 import static com.mapbox.mapboxsdk.location.LocationComponentConstants.BACKGROUND_STALE_ICON;
 import static com.mapbox.mapboxsdk.location.LocationComponentConstants.BEARING_ICON;
@@ -181,6 +181,30 @@ private void setLayerBearing(double bearing) {
     lastBearing = bearing;
   }
 
+  /**
+   * Adjust the visibility of the pulsing LocationComponent circle.
+   */
+  @Override
+  public void adjustPulsingCircleLayerVisibility(boolean visible) {
+    // not supported at this time
+  }
+
+  /**
+   * Adjust the the pulsing LocationComponent circle based on the set options.
+   */
+  @Override
+  public void stylePulsingCircle(LocationComponentOptions options) {
+    // not supported at this time
+  }
+
+  /**
+   * Adjust the visual appearance of the pulsing LocationComponent circle.
+   */
+  @Override
+  public void updatePulsingUi(float radius, @Nullable Float opacity) {
+    // not supported at this time
+  }
+
   private void setImages(@RenderMode.Mode int renderMode, boolean isStale) {
     String topImage = "";
     String bearingImage = "";

MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LayerSourceProvider.java

@@ -32,6 +32,7 @@
 import static com.mapbox.mapboxsdk.location.LocationComponentConstants.PROPERTY_GPS_BEARING;
 import static com.mapbox.mapboxsdk.location.LocationComponentConstants.PROPERTY_LOCATION_STALE;
 import static com.mapbox.mapboxsdk.location.LocationComponentConstants.PROPERTY_SHADOW_ICON_OFFSET;
+import static com.mapbox.mapboxsdk.location.LocationComponentConstants.PULSING_CIRCLE_LAYER;
 import static com.mapbox.mapboxsdk.location.LocationComponentConstants.SHADOW_ICON;
 import static com.mapbox.mapboxsdk.location.LocationComponentConstants.SHADOW_LAYER;
 import static com.mapbox.mapboxsdk.style.expressions.Expression.get;
@@ -131,9 +132,23 @@ Layer generateLocationComponentLayer() {
     LocationIndicatorLayer layer = new LocationIndicatorLayer(FOREGROUND_LAYER);
     layer.setLocationTransition(new TransitionOptions(0, 0));
     layer.setProperties(
-      LocationPropertyFactory.perspectiveCompensation(0.9f),
-      LocationPropertyFactory.imageTiltDisplacement(4f)
+        LocationPropertyFactory.perspectiveCompensation(0.9f),
+        LocationPropertyFactory.imageTiltDisplacement(4f)
     );
     return layer;
   }
+
+  /**
+   * Adds a {@link CircleLayer} to the map to support the {@link LocationComponent} pulsing UI functionality.
+   *
+   * @return a {@link CircleLayer} with the correct data-driven styling. Tilting the map will keep the pulsing
+   * layer aligned with the map plane.
+   */
+  @NonNull
+  Layer generatePulsingCircleLayer() {
+    return new CircleLayer(PULSING_CIRCLE_LAYER, LOCATION_SOURCE)
+        .withProperties(
+            circlePitchAlignment(Property.CIRCLE_PITCH_ALIGNMENT_MAP)
+        );
+  }
 }

MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationAnimatorCoordinator.java

@@ -4,6 +4,7 @@
 import android.location.Location;
 import android.os.SystemClock;
 import android.util.SparseArray;
+import android.view.animation.DecelerateInterpolator;
 import android.view.animation.LinearInterpolator;
 
 import androidx.annotation.NonNull;
@@ -32,6 +33,7 @@
 import static com.mapbox.mapboxsdk.location.MapboxAnimator.ANIMATOR_LAYER_COMPASS_BEARING;
 import static com.mapbox.mapboxsdk.location.MapboxAnimator.ANIMATOR_LAYER_GPS_BEARING;
 import static com.mapbox.mapboxsdk.location.MapboxAnimator.ANIMATOR_LAYER_LATLNG;
+import static com.mapbox.mapboxsdk.location.MapboxAnimator.ANIMATOR_PULSING_CIRCLE;
 import static com.mapbox.mapboxsdk.location.MapboxAnimator.ANIMATOR_TILT;
 import static com.mapbox.mapboxsdk.location.MapboxAnimator.ANIMATOR_ZOOM;
 import static com.mapbox.mapboxsdk.location.Utils.immediateAnimation;
@@ -186,6 +188,28 @@ void feedNewAccuracyRadius(float targetAccuracyRadius, boolean noAnimation) {
     this.previousAccuracyRadius = targetAccuracyRadius;
   }
 
+  /**
+   * Initializes the {@link PulsingLocationCircleAnimator}, which is a type of {@link MapboxAnimator}.
+   * This method also adds the animator to this class' animator array.
+   *
+   * @param options the {@link LocationComponentOptions} passed to this class upstream from the
+   *                {@link LocationComponent}.
+   */
+  void startLocationComponentCirclePulsing(LocationComponentOptions options) {
+    cancelAnimator(ANIMATOR_PULSING_CIRCLE);
+    MapboxAnimator.AnimationsValueChangeListener listener = listeners.get(ANIMATOR_PULSING_CIRCLE);
+    if (listener != null) {
+      PulsingLocationCircleAnimator pulsingLocationCircleAnimator = animatorProvider.pulsingCircleAnimator(
+        listener,
+        maxAnimationFps,
+        options.pulseSingleDuration(),
+        options.pulseMaxRadius(),
+        options.pulseInterpolator() == null ? new DecelerateInterpolator() : options.pulseInterpolator());
+      animatorArray.put(ANIMATOR_PULSING_CIRCLE, pulsingLocationCircleAnimator);
+      playPulsingAnimator();
+    }
+  }
+
   void feedNewZoomLevel(double targetZoomLevel, @NonNull CameraPosition currentCameraPosition, long animationDuration,
                         @Nullable MapboxMap.CancelableCallback callback) {
     updateZoomAnimator((float) targetZoomLevel, (float) currentCameraPosition.zoom, callback);
@@ -349,6 +373,18 @@ private void playAnimators(long duration, @MapboxAnimator.Type int... animatorTy
     animatorSetProvider.startAnimation(animators, new LinearInterpolator(), duration);
   }
 
+  /**
+   * Starts the {@link PulsingLocationCircleAnimator} in the animator array. This method is separate
+   * from {@link #playAnimators(long, int...)} because the MapboxAnimatorSetProvider has many more
+   * customizable animation parameters than the other {@link MapboxAnimator}s.
+   */
+  private void playPulsingAnimator() {
+    Animator animator = animatorArray.get(ANIMATOR_PULSING_CIRCLE);
+    if (animator != null) {
+      animatorSetProvider.startSingleAnimation(animator);
+    }
+  }
+
   void resetAllCameraAnimations(@NonNull CameraPosition currentCameraPosition, boolean isGpsNorth) {
     resetCameraCompassAnimation(currentCameraPosition);
     boolean snap = resetCameraLocationAnimations(currentCameraPosition, isGpsNorth);
@@ -446,6 +482,13 @@ void cancelTiltAnimation() {
     cancelAnimator(ANIMATOR_TILT);
   }
 
+  /**
+   * Cancel the pulsing circle location animator.
+   */
+  void stopPulsingCircleAnimation() {
+    cancelAnimator(ANIMATOR_PULSING_CIRCLE);
+  }
+
   void cancelAllAnimations() {
     for (int i = 0; i < animatorArray.size(); i++) {
       @MapboxAnimator.Type int animatorType = animatorArray.keyAt(i);

MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationComponent.java

@@ -726,10 +726,25 @@ public void applyStyle(@NonNull final LocationComponentOptions options) {
       locationAnimatorCoordinator.setTrackingAnimationDurationMultiplier(options.trackingAnimationDurationMultiplier());
       locationAnimatorCoordinator.setCompassAnimationEnabled(options.compassAnimationEnabled());
       locationAnimatorCoordinator.setAccuracyAnimationEnabled(options.accuracyAnimationEnabled());
+      if (options.pulseEnabled()) {
+        startPulsingLocationCircle();
+      } else {
+        stopPulsingLocationCircle();
+      }
       updateMapWithOptions(options);
     }
   }
 
+  /**
+   * Starts the LocationComponent's pulsing circle UI.
+   */
+  private void startPulsingLocationCircle() {
+    if (isEnabled) {
+      locationAnimatorCoordinator.startLocationComponentCirclePulsing(options);
+      locationLayerController.adjustPulsingCircleLayerVisibility(true);
+    }
+  }
+
   /**
    * Zooms to the desired zoom level.
    * This API can only be used in pair with camera modes other than {@link CameraMode#NONE}.
@@ -1215,6 +1230,14 @@ public void onFinishLoadingStyle() {
     }
   }
 
+  /**
+   * Stop the LocationComponent's pulsing circle animation.
+   */
+  private void stopPulsingLocationCircle() {
+    locationAnimatorCoordinator.stopPulsingCircleAnimation();
+    locationLayerController.adjustPulsingCircleLayerVisibility(false);
+  }
+
   @SuppressLint("MissingPermission")
   private void onLocationLayerStart() {
     if (!isComponentInitialized || !isComponentStarted || mapboxMap.getStyle() == null) {
@@ -1240,6 +1263,11 @@ private void onLocationLayerStart() {
         }
       }
       setCameraMode(locationCameraController.getCameraMode());
+      if (options.pulseEnabled()) {
+        startPulsingLocationCircle();
+      } else {
+        stopPulsingLocationCircle();
+      }
       setLastLocation();
       updateCompassListenerState(true);
       setLastCompassHeading();
@@ -1256,6 +1284,8 @@ private void onLocationLayerStop() {
     if (compassEngine != null) {
       updateCompassListenerState(false);
     }
+
+    stopPulsingLocationCircle();
     locationAnimatorCoordinator.cancelAllAnimations();
     if (locationEngine != null) {
       locationEngine.removeLocationUpdates(currentLocationEngineListener);
@@ -1430,6 +1460,9 @@ private void showLocationLayerIfHidden() {
     boolean isLocationLayerHidden = locationLayerController.isHidden();
     if (isEnabled && isComponentStarted && isLocationLayerHidden) {
       locationLayerController.show();
+      if (options.pulseEnabled()) {
+        locationLayerController.adjustPulsingCircleLayerVisibility(true);
+      }
     }
   }
 

MapboxGLAndroidSDK/src/main/java/com/mapbox/mapboxsdk/location/LocationComponentConstants.java

@@ -52,6 +52,8 @@ public final class LocationComponentConstants {
   static final String PROPERTY_FOREGROUND_STALE_ICON = "mapbox-property-foreground-stale-icon";
   static final String PROPERTY_BACKGROUND_STALE_ICON = "mapbox-property-background-stale-icon";
   static final String PROPERTY_BEARING_ICON = "mapbox-property-shadow-icon";
+  static final String PROPERTY_PULSING_RADIUS = "mapbox-property-pulsing-circle-radius";
+  static final String PROPERTY_PULSING_OPACITY = "mapbox-property-pulsing-circle-opacity";
 
   // Layers
 
@@ -80,6 +82,11 @@ public final class LocationComponentConstants {
    */
   public static final String BEARING_LAYER = "mapbox-location-bearing-layer";
 
+  /**
+   * Layer ID of the location pulsing circle.
+   */
+  public static final String PULSING_CIRCLE_LAYER = "mapbox-location-pulsing-circle-layer";
+
   // Icons
   static final String FOREGROUND_ICON = "mapbox-location-icon";
   static final String BACKGROUND_ICON = "mapbox-location-stroke-icon";