Implement look ahead camera options hints for high-level animations (#3042)

Author: jush

maps-sdk/api/Release/metalava.txt

@@ -292,6 +292,7 @@ package com.mapbox.maps {
     method public com.mapbox.bindgen.Expected<java.lang.String,com.mapbox.bindgen.None> setBounds(com.mapbox.maps.CameraBoundsOptions options);
     method public void setCamera(com.mapbox.maps.CameraOptions cameraOptions);
     method public void setCamera(com.mapbox.maps.FreeCameraOptions freeCameraOptions);
+    method public void setCameraAnimationHint(com.mapbox.maps.CameraAnimationHint cameraAnimationHint);
     method public void setCenterAltitudeMode(com.mapbox.maps.MapCenterAltitudeMode mode);
     method public void setConstrainMode(com.mapbox.maps.ConstrainMode constrainMode);
     method @Deprecated public void setDebug(java.util.List<? extends com.mapbox.maps.MapDebugOptions> debugOptions, boolean enabled);

maps-sdk/api/maps-sdk.api

@@ -295,6 +295,7 @@ public final class com/mapbox/maps/MapboxMap : com/mapbox/maps/MapboxStyleManage
 	public fun setBounds (Lcom/mapbox/maps/CameraBoundsOptions;)Lcom/mapbox/bindgen/Expected;
 	public fun setCamera (Lcom/mapbox/maps/CameraOptions;)V
 	public fun setCamera (Lcom/mapbox/maps/FreeCameraOptions;)V
+	public fun setCameraAnimationHint (Lcom/mapbox/maps/CameraAnimationHint;)V
 	public fun setCenterAltitudeMode (Lcom/mapbox/maps/MapCenterAltitudeMode;)V
 	public fun setConstrainMode (Lcom/mapbox/maps/ConstrainMode;)V
 	public final fun setDebug (Ljava/util/List;Z)V

maps-sdk/src/main/java/com/mapbox/maps/MapboxMap.kt

@@ -618,6 +618,22 @@ class MapboxMap :
     nativeMap.setUserAnimationInProgress(inProgress)
   }
 
+  /**
+   * This method provides hints for animations, enabling the rendering engine to pre-process animation
+   * frames and apply performance optimizations.
+   *
+   * The provided data is taken into action on the next
+   * [setUserAnimationInProgress(true)][setUserAnimationInProgress] call.
+   *
+   * @param cameraAnimationHint the camera animation hint
+   */
+  @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX)
+  @MapboxExperimental
+  override fun setCameraAnimationHint(cameraAnimationHint: CameraAnimationHint) {
+    checkNativeMap("setCameraAnimationHint")
+    nativeMap.setCameraAnimationHint(cameraAnimationHint)
+  }
+
   /**
    * Returns if user animation is currently in progress.
    *

maps-sdk/src/main/java/com/mapbox/maps/NativeMapImpl.kt

@@ -111,6 +111,12 @@ internal class NativeMapImpl(val map: Map) {
     map.isUserAnimationInProgress = inProgress
   }
 
+  @MapboxExperimental
+  @OptIn(com.mapbox.annotation.MapboxExperimental::class)
+  fun setCameraAnimationHint(cameraAnimationHint: CameraAnimationHint) {
+    map.setCameraAnimationHint(cameraAnimationHint)
+  }
+
   fun invalidateStyleCustomGeometrySourceRegion(
     sourceId: String,
     coordinateBounds: CoordinateBounds

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

@@ -9,6 +9,8 @@ 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
@@ -353,14 +355,18 @@ internal class CameraAnimationsPluginImpl : CameraAnimationsPlugin, MapCameraPlu
     CameraAnimatorType.PITCH -> animationObjectValues.all { Objects.equals(pitch, it) }
   }
 
-  private fun updateCameraValue(cameraAnimator: CameraAnimator<*>) {
+  private fun updateCameraValue(
+    cameraAnimator: CameraAnimator<*>,
+    animatedValue: Any?,
+    cameraOptionsBuilder: CameraOptions.Builder
+  ) {
     when (cameraAnimator) {
-      is CameraCenterAnimator -> cameraOptionsBuilder.center(cameraAnimator.animatedValue as? Point)
-      is CameraZoomAnimator -> cameraOptionsBuilder.zoom(cameraAnimator.animatedValue as? Double)
-      is CameraAnchorAnimator -> cameraOptionsBuilder.anchor(cameraAnimator.animatedValue as? ScreenCoordinate)
-      is CameraPaddingAnimator -> cameraOptionsBuilder.padding(cameraAnimator.animatedValue as? EdgeInsets)
-      is CameraBearingAnimator -> cameraOptionsBuilder.bearing(cameraAnimator.animatedValue as? Double)
-      is CameraPitchAnimator -> cameraOptionsBuilder.pitch(cameraAnimator.animatedValue as? Double)
+      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)
     }
   }
 
@@ -482,6 +488,86 @@ 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) }
@@ -493,7 +579,7 @@ internal class CameraAnimationsPluginImpl : CameraAnimationsPlugin, MapCameraPlu
     runningAnimatorsQueue.add(animator)
 
     // set current animator value in any case
-    updateCameraValue(animator)
+    updateCameraValue(animator, animator.animatedValue, cameraOptionsBuilder)
 
     if (animator.type == CameraAnimatorType.ANCHOR) {
       anchor = valueAnimator.animatedValue as ScreenCoordinate
@@ -1054,6 +1140,8 @@ internal class CameraAnimationsPluginImpl : CameraAnimationsPlugin, MapCameraPlu
       }
       playTogether(*animators)
     }
+    calculateCameraAnimationHint(animatorSet)
+
     return HighLevelAnimatorSet(animationOptions?.owner, animatorSet).also {
       highLevelAnimatorSet = it
       postOnAnimatorThread { it.animatorSet.start() }

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

@@ -20,7 +20,7 @@ abstract class CameraAnimator<out T> (
   /**
    * [TypeEvaluator] for generic type
    */
-  evaluator: TypeEvaluator<T>,
+  private val evaluator: TypeEvaluator<T>,
   /**
    * Camera animator options.
    */
@@ -123,6 +123,19 @@ abstract class CameraAnimator<out T> (
     return super.getAnimatedValue()
   }
 
+  /**
+   * @throws UnsupportedOperationException if this animator does not support this method
+   */
+  internal fun getAnimatedValueAt(fraction: Float): T {
+    if (startValue == null || targets.size > 1) {
+      throw UnsupportedOperationException(
+        "getAnimatedValueAt() is only supported for single target animations with a start value."
+      )
+    }
+    val interpolation = interpolator.getInterpolation(fraction)
+    return evaluator.evaluate(interpolation, startValue, targets.last())
+  }
+
   /**
    * Handle immediate animation(when duration and startDelay of the animation is 0)
    * we trigger animator listeners directly without triggering [ValueAnimator]'s start().

sdk-base/api/Release/metalava.txt

@@ -2236,6 +2236,7 @@ package com.mapbox.maps.plugin.delegates {
     method public com.mapbox.maps.Size getSize();
     method public boolean isGestureInProgress();
     method public boolean isUserAnimationInProgress();
+    method public void setCameraAnimationHint(com.mapbox.maps.CameraAnimationHint cameraAnimationHint);
     method public void setConstrainMode(com.mapbox.maps.ConstrainMode constrainMode);
     method public void setGestureInProgress(boolean inProgress);
     method public void setNorthOrientation(com.mapbox.maps.NorthOrientation northOrientation);

sdk-base/api/sdk-base.api

@@ -2265,6 +2265,7 @@ public abstract interface class com/mapbox/maps/plugin/delegates/MapTransformDel
 	public abstract fun getSize ()Lcom/mapbox/maps/Size;
 	public abstract fun isGestureInProgress ()Z
 	public abstract fun isUserAnimationInProgress ()Z
+	public abstract fun setCameraAnimationHint (Lcom/mapbox/maps/CameraAnimationHint;)V
 	public abstract fun setConstrainMode (Lcom/mapbox/maps/ConstrainMode;)V
 	public abstract fun setGestureInProgress (Z)V
 	public abstract fun setNorthOrientation (Lcom/mapbox/maps/NorthOrientation;)V

sdk-base/src/main/java/com/mapbox/maps/plugin/delegates/MapTransformDelegate.kt

@@ -1,5 +1,6 @@
 package com.mapbox.maps.plugin.delegates
 
+import androidx.annotation.RestrictTo
 import com.mapbox.maps.*
 
 /**
@@ -52,6 +53,19 @@ interface MapTransformDelegate {
    */
   fun setUserAnimationInProgress(inProgress: Boolean)
 
+  /**
+   * This method provides hints for animations, enabling the rendering engine to pre-process animation
+   * frames and apply performance optimizations.
+   *
+   * The provided data is taken into action on the next
+   * [setUserAnimationInProgress(true)][setUserAnimationInProgress] call.
+   *
+   * @param cameraAnimationHint the camera animation hint
+   */
+  @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX)
+  @MapboxExperimental
+  fun setCameraAnimationHint(cameraAnimationHint: CameraAnimationHint)
+
   /**
    * Returns if user animation is currently in progress.
    *