NAVAND-5894: refactor calculateCameraAnimationHint, support more cases

GitOrigin-RevId: 042a1a046e3ecfa2a96716c0a4c48342a44e228b

Author: dzinad

plugin-animation/api/plugin-animation.api

@@ -1,4 +1,8 @@
 public final class com/mapbox/maps/plugin/animation/CameraAnimationsUtils {
+	public static final synthetic fun calculateCameraAnimationHint (Landroid/animation/AnimatorSet;Ljava/util/List;Lcom/mapbox/maps/CameraState;)Lcom/mapbox/maps/CameraAnimationHint;
+	public static final synthetic fun calculateCameraAnimationHint (Ljava/util/List;Ljava/util/List;Lcom/mapbox/maps/CameraState;)Lcom/mapbox/maps/CameraAnimationHint;
+	public static synthetic fun calculateCameraAnimationHint$default (Landroid/animation/AnimatorSet;Ljava/util/List;Lcom/mapbox/maps/CameraState;ILjava/lang/Object;)Lcom/mapbox/maps/CameraAnimationHint;
+	public static synthetic fun calculateCameraAnimationHint$default (Ljava/util/List;Ljava/util/List;Lcom/mapbox/maps/CameraState;ILjava/lang/Object;)Lcom/mapbox/maps/CameraAnimationHint;
 	public static final synthetic fun createCameraAnimationPlugin ()Lcom/mapbox/maps/plugin/animation/CameraAnimationsPlugin;
 	public static final fun easeTo (Lcom/mapbox/maps/plugin/delegates/MapPluginExtensionsDelegate;Lcom/mapbox/maps/CameraOptions;)Lcom/mapbox/common/Cancelable;
 	public static final fun easeTo (Lcom/mapbox/maps/plugin/delegates/MapPluginExtensionsDelegate;Lcom/mapbox/maps/CameraOptions;Lcom/mapbox/maps/plugin/animation/MapAnimationOptions;)Lcom/mapbox/common/Cancelable;

plugin-animation/src/main/java/com/mapbox/maps/plugin/animation/CameraAnimationsExt.kt

@@ -2,12 +2,29 @@
 package com.mapbox.maps.plugin.animation
 
 import android.animation.Animator
+import android.animation.Animator.DURATION_INFINITE
+import android.animation.AnimatorSet
+import android.os.Build
 import androidx.annotation.RestrictTo
 import com.mapbox.common.Cancelable
+import com.mapbox.geojson.Point
+import com.mapbox.maps.CameraAnimationHint
+import com.mapbox.maps.CameraAnimationHintStage
 import com.mapbox.maps.CameraOptions
+import com.mapbox.maps.CameraState
+import com.mapbox.maps.EdgeInsets
 import com.mapbox.maps.ScreenCoordinate
+import com.mapbox.maps.logW
 import com.mapbox.maps.plugin.Plugin
 import com.mapbox.maps.plugin.Plugin.Companion.MAPBOX_CAMERA_PLUGIN_ID
+import com.mapbox.maps.plugin.animation.CameraAnimationsPluginImpl.Companion.TAG
+import com.mapbox.maps.plugin.animation.animator.CameraAnchorAnimator
+import com.mapbox.maps.plugin.animation.animator.CameraAnimator
+import com.mapbox.maps.plugin.animation.animator.CameraBearingAnimator
+import com.mapbox.maps.plugin.animation.animator.CameraCenterAnimator
+import com.mapbox.maps.plugin.animation.animator.CameraPaddingAnimator
+import com.mapbox.maps.plugin.animation.animator.CameraPitchAnimator
+import com.mapbox.maps.plugin.animation.animator.CameraZoomAnimator
 import com.mapbox.maps.plugin.delegates.MapPluginExtensionsDelegate
 import com.mapbox.maps.plugin.delegates.MapPluginProviderDelegate
 
@@ -156,4 +173,178 @@ fun createCameraAnimationPlugin(): CameraAnimationsPlugin {
 @JvmSynthetic
 fun CameraAnimationsPlugin.getCameraAnimatorsFactory(): CameraAnimatorsFactory {
   return (this as CameraAnimationsPluginImpl).cameraAnimationsFactory
+}
+
+/**
+ * Calculates camera animation hints for provided [AnimatorSet] at specified fractions.
+ * This API must be called right before the animation is started: moving camera in-between should be avoided.
+ *
+ * Requirements:
+ * 1. [AnimatorSet] must have startDelay = 0 (TODO support non-zero startDelay).
+ *  However, a child animator is allowed to have a non-zero startDelay.
+ * 2. All child animations must be instances of [CameraAnimator].
+ * 3. None of the child animations are allowed to have infinite duration.
+ *  Note: [AnimatorSet] itself may have infinite duration.
+ *
+ * If [AnimatorSet] has zero duration, no camera animation hints are calculated: null is returned.
+ *
+ * @param fractions list of fractions at which to calculate intermediate camera states
+ * @param startCameraState start value of the animations.
+ *  Must be provided in case your [AnimatorSet]'s child animators do not have a startValue.
+ *
+ *  @return [CameraAnimationHint] object, null if calculation could not be performed
+ */
+@RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX)
+@JvmSynthetic
+fun AnimatorSet.calculateCameraAnimationHint(
+  fractions: List<Float>,
+  startCameraState: CameraState? = null,
+): CameraAnimationHint? {
+  // Make sure all animators in animatorSet are camera animators
+  val cameraAnimators = childAnimations.filterIsInstance<CameraAnimator<*>>()
+  if (cameraAnimators.size != childAnimations.size) {
+    logW(TAG, "Incompatible animators: all should be instances of CameraAnimator")
+    return null
+  }
+
+  if (startDelay != 0L) {
+    logW(TAG, "AnimatorSets with non-zero startDelay are not supported.")
+    return null
+  }
+
+  if (childAnimations.isEmpty()) {
+    logW(TAG, "AnimatorSet has no child animations.")
+    return null
+  }
+
+  val totalDuration = if (duration >= 0) {
+    duration
+  } else {
+    cameraAnimators.maxOf { it.safeTotalDuration() }
+  }
+  return cameraAnimators.calculateCameraAnimationHint(fractions, totalDuration, startCameraState)
+}
+
+/**
+ * Calculates camera animation hints for provided list of [Animator] at specified fractions.
+ * This API must be called right before the animation is started: moving camera in-between should be avoided.
+ *
+ * Requirements:
+ * 1. None of the animations are allowed to have infinite duration.
+ *
+ * If all animators have zero duration, no camera animation hints are calculated: null is returned.
+ *
+ * @param fractions list of fractions at which to calculate intermediate camera states
+ * @param startCameraState start value of the animations.
+ *  Must be provided in case your [AnimatorSet]'s child animators do not have a startValue.
+ *
+ *  @return [CameraAnimationHint] object, null if calculation could not be performed
+ */
+@RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX)
+@JvmSynthetic
+fun <T : CameraAnimator<*>> List<T>.calculateCameraAnimationHint(
+  fractions: List<Float>,
+  startCameraState: CameraState? = null,
+): CameraAnimationHint? {
+  if (isEmpty()) {
+    return null
+  }
+  val totalDuration = maxOf { it.safeTotalDuration() }
+  return calculateCameraAnimationHint(fractions, totalDuration, startCameraState)
+}
+
+private fun Animator.safeTotalDuration(): Long {
+  return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {
+    totalDuration
+  } else {
+    // For pre-N devices, totalDuration is not available, so we use the duration of the animator.
+    duration + startDelay
+  }
+}
+
+private fun <T : CameraAnimator<*>> List<T>.calculateCameraAnimationHint(
+  fractions: List<Float>,
+  totalDuration: Long,
+  startCameraState: CameraState?,
+): CameraAnimationHint? {
+  if (isEmpty()) {
+    return null
+  }
+
+  // No need to calculate camera animation hints if the animation is instant
+  if (totalDuration == 0L) {
+    return null
+  }
+
+  if (totalDuration == DURATION_INFINITE || this.any { it.duration == DURATION_INFINITE }) {
+    logW(
+      TAG,
+      "Animators with infinite duration are not supported. " +
+        "Please use finite duration for all animators.",
+    )
+    return null
+  }
+
+  val cameraOptionsBuilder = CameraOptions.Builder()
+
+  val stages = fractions.map { totalFraction ->
+    cameraOptionsBuilder.clear()
+    this.map { cameraAnimator ->
+      try {
+        val fraction = getRelativeFraction(cameraAnimator, totalDuration, totalFraction)
+        val value = cameraAnimator.getAnimatedValueAt(fraction, startCameraState)
+        updateCameraValue(cameraAnimator, value, cameraOptionsBuilder)
+      } catch (e: UnsupportedOperationException) {
+        logW(
+          TAG,
+          "Unable to calculate animated value ahead of time for ${cameraAnimator.type.name}: ${e.message}"
+        )
+      }
+    }
+    val camera = cameraOptionsBuilder.build()
+    // We use totalDuration to keep track of the progress because that's the total duration of the animation. That is,
+    // the time between `setUserAnimationInProgress(true)` and `setUserAnimationInProgress(false)`
+    val progress = (totalDuration * totalFraction).toLong()
+    CameraAnimationHintStage.Builder()
+      .camera(camera)
+      .progress(progress)
+      .build()
+  }
+  return CameraAnimationHint.Builder().stages(stages).build()
+}
+
+private fun getRelativeFraction(cameraAnimator: CameraAnimator<*>, totalDuration: Long, totalFraction: Float): Float {
+  val childDuration = cameraAnimator.duration
+  if (childDuration <= 0L) {
+    return 1f
+  }
+  return ((totalFraction * totalDuration - cameraAnimator.startDelay) / childDuration).coerceIn(0f, 1f)
+}
+
+internal fun updateCameraValue(
+  cameraAnimator: CameraAnimator<*>,
+  animatedValue: Any?,
+  cameraOptionsBuilder: CameraOptions.Builder
+) {
+  when (cameraAnimator) {
+    is CameraCenterAnimator -> cameraOptionsBuilder.center(animatedValue as? Point)
+    is CameraZoomAnimator -> cameraOptionsBuilder.zoom(animatedValue as? Double)
+    is CameraAnchorAnimator -> cameraOptionsBuilder.anchor(animatedValue as? ScreenCoordinate)
+    is CameraPaddingAnimator -> cameraOptionsBuilder.padding(animatedValue as? EdgeInsets)
+    is CameraBearingAnimator -> cameraOptionsBuilder.bearing(animatedValue as? Double)
+    is CameraPitchAnimator -> cameraOptionsBuilder.pitch(animatedValue as? Double)
+  }
+}
+
+/**
+ * Convenience method to clear camera options so it can be reused instead of creating
+ * new [CameraOptions.Builder].
+ */
+private fun CameraOptions.Builder.clear() {
+  center(null)
+    .padding(null)
+    .anchor(null)
+    .zoom(null)
+    .bearing(null)
+    .pitch(null)
 }

plugin-animation/src/main/java/com/mapbox/maps/plugin/animation/CameraAnimationsPluginImpl.kt

@@ -9,8 +9,6 @@ import androidx.annotation.VisibleForTesting
 import androidx.annotation.VisibleForTesting.Companion.PRIVATE
 import com.mapbox.common.Cancelable
 import com.mapbox.geojson.Point
-import com.mapbox.maps.CameraAnimationHint
-import com.mapbox.maps.CameraAnimationHintStage
 import com.mapbox.maps.CameraOptions
 import com.mapbox.maps.EdgeInsets
 import com.mapbox.maps.MapboxCameraAnimationException
@@ -80,6 +78,12 @@ internal class CameraAnimationsPluginImpl : CameraAnimationsPlugin, MapCameraPlu
 
   private val lifecycleListeners = CopyOnWriteArraySet<CameraAnimationsLifecycleListener>()
 
+  /**
+   * Animation fraction at which the camera animation hints will be calculated.
+   * Note: at least 1.0F should be present and entries should be in ascent order.
+   */
+  private val cameraAnimationHintFractions = listOf(0.25F, 0.5F, 0.75F, 1.0F)
+
   /**
    * If debug mode is enabled extra logs will be written about animation lifecycle and
    * some other events that may be useful for debugging.
@@ -355,21 +359,6 @@ internal class CameraAnimationsPluginImpl : CameraAnimationsPlugin, MapCameraPlu
     CameraAnimatorType.PITCH -> animationObjectValues.all { Objects.equals(pitch, it) }
   }
 
-  private fun updateCameraValue(
-    cameraAnimator: CameraAnimator<*>,
-    animatedValue: Any?,
-    cameraOptionsBuilder: CameraOptions.Builder
-  ) {
-    when (cameraAnimator) {
-      is CameraCenterAnimator -> cameraOptionsBuilder.center(animatedValue as? Point)
-      is CameraZoomAnimator -> cameraOptionsBuilder.zoom(animatedValue as? Double)
-      is CameraAnchorAnimator -> cameraOptionsBuilder.anchor(animatedValue as? ScreenCoordinate)
-      is CameraPaddingAnimator -> cameraOptionsBuilder.padding(animatedValue as? EdgeInsets)
-      is CameraBearingAnimator -> cameraOptionsBuilder.bearing(animatedValue as? Double)
-      is CameraPitchAnimator -> cameraOptionsBuilder.pitch(animatedValue as? Double)
-    }
-  }
-
   private fun registerInternalListener(animator: CameraAnimator<*>) {
     postOnAnimatorThread {
       animator.addInternalListener(object : Animator.AnimatorListener {
@@ -488,86 +477,6 @@ internal class CameraAnimationsPluginImpl : CameraAnimationsPlugin, MapCameraPlu
     }
   }
 
-  /**
-   * Animation fraction at which the camera animation hints will be calculated.
-   * Note: at least 1.0F should be present and entries should be in ascent order.
-   */
-  private val cameraAnimationHintFractions = listOf(0.25F, 0.5F, 0.75F, 1.0F)
-  private fun calculateCameraAnimationHint(animatorSet: AnimatorSet) {
-    // this method requires that all animators have:
-    // 1. same duration
-    // 2. no delay
-    // 3. start value
-    // TODO: support different duration, start delay and no start value
-
-    // No need to calculate camera animation hints if the animation is instant
-    if (animatorSet.duration == 0L) {
-      return
-    }
-
-    // Make sure all animators in animatorSet are camera animators
-    val cameraAnimators = animatorSet.childAnimations.map { it as CameraAnimator<*> }
-    if (cameraAnimators.isEmpty() || cameraAnimators.size != animatorSet.childAnimations.size) {
-      return
-    }
-
-    val cameraOptionsBuilder = CameraOptions.Builder()
-    // Keep track of the duration to make sure all animators have the same duration
-    val duration = cameraAnimators[0].duration
-
-    val stages = cameraAnimationHintFractions.map { fraction ->
-      cameraOptionsBuilder.clear()
-      cameraAnimators.map { cameraAnimator ->
-        if (cameraAnimator.startDelay != 0L) {
-          logW(
-            TAG,
-            "Unable to calculate animated value ahead of time for ${cameraAnimator.type.name}: startDelay != 0 is not supported"
-          )
-          return
-        }
-        if (cameraAnimator.duration != duration) {
-          logW(
-            TAG,
-            "Unable to calculate animated value ahead of time for ${cameraAnimator.type.name}: different duration is not supported"
-          )
-          return
-        }
-        try {
-          val value = cameraAnimator.getAnimatedValueAt(fraction)
-          updateCameraValue(cameraAnimator, value, cameraOptionsBuilder)
-        } catch (e: UnsupportedOperationException) {
-          logW(
-            TAG,
-            "Unable to calculate animated value ahead of time for ${cameraAnimator.type.name}: ${e.message}"
-          )
-        }
-      }
-      val camera = cameraOptionsBuilder.build()
-      // We use animatorSet.duration to keep track of the progress because that's the total duration of the animation. That is,
-      // the time between `setUserAnimationInProgress(true)` and `setUserAnimationInProgress(false)`
-      val progress = (animatorSet.duration * fraction).toLong()
-      CameraAnimationHintStage.Builder()
-        .camera(camera)
-        .progress(progress)
-        .build()
-    }
-    val cameraAnimationHint = CameraAnimationHint.Builder().stages(stages).build()
-    mapTransformDelegate.setCameraAnimationHint(cameraAnimationHint)
-  }
-
-  /**
-   * Convenience method to clear camera options so it can be reused instead of creating
-   * new [CameraOptions.Builder].
-   */
-  private fun CameraOptions.Builder.clear() {
-    center(null)
-      .padding(null)
-      .anchor(null)
-      .zoom(null)
-      .bearing(null)
-      .pitch(null)
-  }
-
   private fun registerInternalUpdateListener(animator: CameraAnimator<*>) {
     animator.addInternalUpdateListener {
       postOnMainThread { onAnimationUpdateInternal(animator, it) }
@@ -1140,7 +1049,9 @@ internal class CameraAnimationsPluginImpl : CameraAnimationsPlugin, MapCameraPlu
       }
       playTogether(*animators)
     }
-    calculateCameraAnimationHint(animatorSet)
+    animatorSet.calculateCameraAnimationHint(cameraAnimationHintFractions)?.let {
+      mapTransformDelegate.setCameraAnimationHint(it)
+    }
 
     return HighLevelAnimatorSet(animationOptions?.owner, animatorSet).also {
       highLevelAnimatorSet = it