1 /* 2 * Copyright (C) 2023 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.app.animation; 18 19 import android.graphics.Path; 20 21 import androidx.core.animation.AccelerateDecelerateInterpolator; 22 import androidx.core.animation.AccelerateInterpolator; 23 import androidx.core.animation.BounceInterpolator; 24 import androidx.core.animation.DecelerateInterpolator; 25 import androidx.core.animation.Interpolator; 26 import androidx.core.animation.LinearInterpolator; 27 import androidx.core.animation.OvershootInterpolator; 28 import androidx.core.animation.PathInterpolator; 29 30 /** 31 * Utility class to receive interpolators from. (androidx compatible version) 32 * 33 * This is the androidx compatible version of {@link Interpolators}. Make sure that changes made to 34 * this class are also reflected in {@link Interpolators}. 35 * 36 * Using the androidx versions of {@link androidx.core.animation.ValueAnimator} or 37 * {@link androidx.core.animation.ObjectAnimator} improves animation testability. This file provides 38 * the androidx compatible versions of the interpolators defined in {@link Interpolators}. 39 * AnimatorTestRule can be used in Tests to manipulate the animation under test (e.g. artificially 40 * advancing the time). 41 */ 42 public class InterpolatorsAndroidX { 43 44 /* 45 * ============================================================================================ 46 * Emphasized interpolators. 47 * ============================================================================================ 48 */ 49 50 /** 51 * The default emphasized interpolator. Used for hero / emphasized movement of content. 52 */ 53 public static final Interpolator EMPHASIZED = createEmphasizedInterpolator(); 54 55 /** 56 * Complement to {@link #EMPHASIZED}. Used when animating hero movement in two dimensions to 57 * create a smooth, emphasized, curved movement. 58 * <br> 59 * Example usage: Animate y-movement with {@link #EMPHASIZED} and x-movement with this. 60 */ 61 public static final Interpolator EMPHASIZED_COMPLEMENT = createEmphasizedComplement(); 62 63 /** 64 * The accelerated emphasized interpolator. Used for hero / emphasized movement of content that 65 * is disappearing e.g. when moving off screen. 66 */ 67 public static final Interpolator EMPHASIZED_ACCELERATE = new PathInterpolator( 68 0.3f, 0f, 0.8f, 0.15f); 69 70 /** 71 * The decelerating emphasized interpolator. Used for hero / emphasized movement of content that 72 * is appearing e.g. when coming from off screen 73 */ 74 public static final Interpolator EMPHASIZED_DECELERATE = new PathInterpolator( 75 0.05f, 0.7f, 0.1f, 1f); 76 77 public static final Interpolator EXAGGERATED_EASE; 78 static { 79 Path exaggeratedEase = new Path(); 80 exaggeratedEase.moveTo(0, 0); 81 exaggeratedEase.cubicTo(0.05f, 0f, 0.133333f, 0.08f, 0.166666f, 0.4f); 82 exaggeratedEase.cubicTo(0.225f, 0.94f, 0.5f, 1f, 1f, 1f); 83 EXAGGERATED_EASE = new PathInterpolator(exaggeratedEase); 84 } 85 86 public static final Interpolator INSTANT = t -> 1; 87 /** 88 * All values of t map to 0 until t == 1. This is primarily useful for setting view visibility, 89 * which should only happen at the very end of the animation (when it's already hidden). 90 */ 91 public static final Interpolator FINAL_FRAME = t -> t < 1 ? 0 : 1; 92 93 public static final Interpolator OVERSHOOT_0_75 = new OvershootInterpolator(0.75f); 94 public static final Interpolator OVERSHOOT_1_2 = new OvershootInterpolator(1.2f); 95 public static final Interpolator OVERSHOOT_1_7 = new OvershootInterpolator(1.7f); 96 97 /* 98 * ============================================================================================ 99 * Standard interpolators. 100 * ============================================================================================ 101 */ 102 103 /** 104 * The standard interpolator that should be used on every normal animation 105 */ 106 public static final Interpolator STANDARD = new PathInterpolator( 107 0.2f, 0f, 0f, 1f); 108 109 /** 110 * The standard accelerating interpolator that should be used on every regular movement of 111 * content that is disappearing e.g. when moving off screen. 112 */ 113 public static final Interpolator STANDARD_ACCELERATE = new PathInterpolator( 114 0.3f, 0f, 1f, 1f); 115 116 /** 117 * The standard decelerating interpolator that should be used on every regular movement of 118 * content that is appearing e.g. when coming from off screen. 119 */ 120 public static final Interpolator STANDARD_DECELERATE = new PathInterpolator( 121 0f, 0f, 0f, 1f); 122 123 /* 124 * ============================================================================================ 125 * Legacy 126 * ============================================================================================ 127 */ 128 129 /** 130 * The default legacy interpolator as defined in Material 1. Also known as FAST_OUT_SLOW_IN. 131 */ 132 public static final Interpolator LEGACY = new PathInterpolator(0.4f, 0f, 0.2f, 1f); 133 134 /** 135 * The default legacy accelerating interpolator as defined in Material 1. 136 * Also known as FAST_OUT_LINEAR_IN. 137 */ 138 public static final Interpolator LEGACY_ACCELERATE = new PathInterpolator(0.4f, 0f, 1f, 1f); 139 140 /** 141 * The default legacy decelerating interpolator as defined in Material 1. 142 * Also known as LINEAR_OUT_SLOW_IN. 143 */ 144 public static final Interpolator LEGACY_DECELERATE = new PathInterpolator(0f, 0f, 0.2f, 1f); 145 146 /** 147 * Linear interpolator. Often used if the interpolator is for different properties who need 148 * different interpolations. 149 */ 150 public static final Interpolator LINEAR = new LinearInterpolator(); 151 152 /* 153 * ============================================================================================ 154 * Custom interpolators 155 * ============================================================================================ 156 */ 157 158 public static final Interpolator FAST_OUT_SLOW_IN = LEGACY; 159 public static final Interpolator FAST_OUT_LINEAR_IN = LEGACY_ACCELERATE; 160 public static final Interpolator LINEAR_OUT_SLOW_IN = LEGACY_DECELERATE; 161 162 /** 163 * Like {@link #FAST_OUT_SLOW_IN}, but used in case the animation is played in reverse (i.e. t 164 * goes from 1 to 0 instead of 0 to 1). 165 */ 166 public static final Interpolator FAST_OUT_SLOW_IN_REVERSE = 167 new PathInterpolator(0.8f, 0f, 0.6f, 1f); 168 public static final Interpolator SLOW_OUT_LINEAR_IN = new PathInterpolator(0.8f, 0f, 1f, 1f); 169 public static final Interpolator AGGRESSIVE_EASE = new PathInterpolator(0.2f, 0f, 0f, 1f); 170 public static final Interpolator AGGRESSIVE_EASE_IN_OUT = new PathInterpolator(0.6f,0, 0.4f, 1); 171 172 public static final Interpolator DECELERATED_EASE = new PathInterpolator(0, 0, .2f, 1f); 173 public static final Interpolator ACCELERATED_EASE = new PathInterpolator(0.4f, 0, 1f, 1f); 174 public static final Interpolator ALPHA_IN = new PathInterpolator(0.4f, 0f, 1f, 1f); 175 public static final Interpolator ALPHA_OUT = new PathInterpolator(0f, 0f, 0.8f, 1f); 176 public static final Interpolator ACCELERATE = new AccelerateInterpolator(); 177 public static final Interpolator ACCELERATE_0_5 = new AccelerateInterpolator(0.5f); 178 public static final Interpolator ACCELERATE_0_75 = new AccelerateInterpolator(0.75f); 179 public static final Interpolator ACCELERATE_1_5 = new AccelerateInterpolator(1.5f); 180 public static final Interpolator ACCELERATE_2 = new AccelerateInterpolator(2); 181 public static final Interpolator ACCELERATE_DECELERATE = new AccelerateDecelerateInterpolator(); 182 public static final Interpolator DECELERATE = new DecelerateInterpolator(); 183 public static final Interpolator DECELERATE_1_5 = new DecelerateInterpolator(1.5f); 184 public static final Interpolator DECELERATE_1_7 = new DecelerateInterpolator(1.7f); 185 public static final Interpolator DECELERATE_2 = new DecelerateInterpolator(2); 186 public static final Interpolator DECELERATE_QUINT = new DecelerateInterpolator(2.5f); 187 public static final Interpolator DECELERATE_3 = new DecelerateInterpolator(3f); 188 public static final Interpolator CUSTOM_40_40 = new PathInterpolator(0.4f, 0f, 0.6f, 1f); 189 public static final Interpolator ICON_OVERSHOT = new PathInterpolator(0.4f, 0f, 0.2f, 1.4f); 190 public static final Interpolator ICON_OVERSHOT_LESS = new PathInterpolator(0.4f, 0f, 0.2f, 191 1.1f); 192 public static final Interpolator PANEL_CLOSE_ACCELERATED = new PathInterpolator(0.3f, 0, 0.5f, 193 1); 194 public static final Interpolator BOUNCE = new BounceInterpolator(); 195 /** 196 * For state transitions on the control panel that lives in GlobalActions. 197 */ 198 public static final Interpolator CONTROL_STATE = new PathInterpolator(0.4f, 0f, 0.2f, 199 1.0f); 200 201 /** 202 * Interpolator to be used when animating a move based on a click. Pair with enough duration. 203 */ 204 public static final Interpolator TOUCH_RESPONSE = 205 new PathInterpolator(0.3f, 0f, 0.1f, 1f); 206 207 /** 208 * Like {@link #TOUCH_RESPONSE}, but used in case the animation is played in reverse (i.e. t 209 * goes from 1 to 0 instead of 0 to 1). 210 */ 211 public static final Interpolator TOUCH_RESPONSE_REVERSE = 212 new PathInterpolator(0.9f, 0f, 0.7f, 1f); 213 214 public static final Interpolator TOUCH_RESPONSE_ACCEL_DEACCEL = 215 v -> ACCELERATE_DECELERATE.getInterpolation(TOUCH_RESPONSE.getInterpolation(v)); 216 217 218 /** 219 * Inversion of ZOOM_OUT, compounded with an ease-out. 220 */ 221 public static final Interpolator ZOOM_IN = new Interpolator() { 222 @Override 223 public float getInterpolation(float v) { 224 return DECELERATE_3.getInterpolation(1 - ZOOM_OUT.getInterpolation(1 - v)); 225 } 226 }; 227 228 public static final Interpolator ZOOM_OUT = new Interpolator() { 229 230 private static final float FOCAL_LENGTH = 0.35f; 231 232 @Override 233 public float getInterpolation(float v) { 234 return zInterpolate(v); 235 } 236 237 /** 238 * This interpolator emulates the rate at which the perceived scale of an object changes 239 * as its distance from a camera increases. When this interpolator is applied to a scale 240 * animation on a view, it evokes the sense that the object is shrinking due to moving away 241 * from the camera. 242 */ 243 private float zInterpolate(float input) { 244 return (1.0f - FOCAL_LENGTH / (FOCAL_LENGTH + input)) / 245 (1.0f - FOCAL_LENGTH / (FOCAL_LENGTH + 1.0f)); 246 } 247 }; 248 249 public static final Interpolator SCROLL = new Interpolator() { 250 @Override 251 public float getInterpolation(float t) { 252 t -= 1.0f; 253 return t*t*t*t*t + 1; 254 } 255 }; 256 257 public static final Interpolator SCROLL_CUBIC = new Interpolator() { 258 @Override 259 public float getInterpolation(float t) { 260 t -= 1.0f; 261 return t*t*t + 1; 262 } 263 }; 264 265 /** 266 * Use this interpolator for animating progress values coming from the back callback to get 267 * the predictive-back-typical decelerate motion. 268 * 269 * This interpolator is similar to {@link Interpolators#STANDARD_DECELERATE} but has a slight 270 * acceleration phase at the start. 271 */ 272 public static final Interpolator BACK_GESTURE = new PathInterpolator(0.1f, 0.1f, 0f, 1f); 273 274 private static final float FAST_FLING_PX_MS = 10; 275 276 /* 277 * ============================================================================================ 278 * Functions / Utilities 279 * ============================================================================================ 280 */ 281 scrollInterpolatorForVelocity(float velocity)282 public static Interpolator scrollInterpolatorForVelocity(float velocity) { 283 return Math.abs(velocity) > FAST_FLING_PX_MS ? SCROLL : SCROLL_CUBIC; 284 } 285 286 /** 287 * Create an OvershootInterpolator with tension directly related to the velocity (in px/ms). 288 * @param velocity The start velocity of the animation we want to overshoot. 289 */ overshootInterpolatorForVelocity(float velocity)290 public static Interpolator overshootInterpolatorForVelocity(float velocity) { 291 return new OvershootInterpolator(Math.min(Math.abs(velocity), 3f)); 292 } 293 294 /** 295 * Calculate the amount of overshoot using an exponential falloff function with desired 296 * properties, where the overshoot smoothly transitions at the 1.0f boundary into the 297 * overshoot, retaining its acceleration. 298 * 299 * @param progress a progress value going from 0 to 1 300 * @param overshootAmount the amount > 0 of overshoot desired. A value of 0.1 means the max 301 * value of the overall progress will be at 1.1. 302 * @param overshootStart the point in (0,1] where the result should reach 1 303 * @return the interpolated overshoot 304 */ getOvershootInterpolation(float progress, float overshootAmount, float overshootStart)305 public static float getOvershootInterpolation(float progress, float overshootAmount, 306 float overshootStart) { 307 if (overshootAmount == 0.0f || overshootStart == 0.0f) { 308 throw new IllegalArgumentException("Invalid values for overshoot"); 309 } 310 float b = MathUtils.log((overshootAmount + 1) / (overshootAmount)) / overshootStart; 311 return MathUtils.max(0.0f, 312 (float) (1.0f - Math.exp(-b * progress)) * (overshootAmount + 1.0f)); 313 } 314 315 /** 316 * Similar to {@link #getOvershootInterpolation(float, float, float)} but the overshoot 317 * starts immediately here, instead of first having a section of non-overshooting 318 * 319 * @param progress a progress value going from 0 to 1 320 */ getOvershootInterpolation(float progress)321 public static float getOvershootInterpolation(float progress) { 322 return MathUtils.max(0.0f, (float) (1.0f - Math.exp(-4 * progress))); 323 } 324 325 // Create the default emphasized interpolator createEmphasizedInterpolator()326 private static PathInterpolator createEmphasizedInterpolator() { 327 Path path = new Path(); 328 // Doing the same as fast_out_extra_slow_in 329 path.moveTo(0f, 0f); 330 path.cubicTo(0.05f, 0f, 0.133333f, 0.06f, 0.166666f, 0.4f); 331 path.cubicTo(0.208333f, 0.82f, 0.25f, 1f, 1f, 1f); 332 return new PathInterpolator(path); 333 } 334 335 /** 336 * Creates a complement to {@link #createEmphasizedInterpolator()} for use when animating in 337 * two dimensions. 338 */ createEmphasizedComplement()339 private static PathInterpolator createEmphasizedComplement() { 340 Path path = new Path(); 341 path.moveTo(0f, 0f); 342 path.cubicTo(0.1217f, 0.0462f, 0.15f, 0.4686f, 0.1667f, 0.66f); 343 path.cubicTo(0.1834f, 0.8878f, 0.1667f, 1f, 1f, 1f); 344 return new PathInterpolator(path); 345 } 346 347 /** 348 * Returns a function that runs the given interpolator such that the entire progress is set 349 * between the given bounds. That is, we set the interpolation to 0 until lowerBound and reach 350 * 1 by upperBound. 351 */ clampToProgress(Interpolator interpolator, float lowerBound, float upperBound)352 public static Interpolator clampToProgress(Interpolator interpolator, float lowerBound, 353 float upperBound) { 354 if (upperBound < lowerBound) { 355 throw new IllegalArgumentException( 356 String.format("upperBound (%f) must be greater than lowerBound (%f)", 357 upperBound, lowerBound)); 358 } 359 return t -> clampToProgress(interpolator, t, lowerBound, upperBound); 360 } 361 362 /** 363 * Returns the progress value's progress between the lower and upper bounds. That is, the 364 * progress will be 0f from 0f to lowerBound, and reach 1f by upperBound. 365 * 366 * Between lowerBound and upperBound, the progress value will be interpolated using the provided 367 * interpolator. 368 */ clampToProgress( Interpolator interpolator, float progress, float lowerBound, float upperBound)369 public static float clampToProgress( 370 Interpolator interpolator, float progress, float lowerBound, float upperBound) { 371 if (upperBound < lowerBound) { 372 throw new IllegalArgumentException( 373 String.format("upperBound (%f) must be greater than lowerBound (%f)", 374 upperBound, lowerBound)); 375 } 376 377 if (progress == lowerBound && progress == upperBound) { 378 return progress == 0f ? 0 : 1; 379 } 380 if (progress < lowerBound) { 381 return 0; 382 } 383 if (progress > upperBound) { 384 return 1; 385 } 386 return interpolator.getInterpolation((progress - lowerBound) / (upperBound - lowerBound)); 387 } 388 389 /** 390 * Returns the progress value's progress between the lower and upper bounds. That is, the 391 * progress will be 0f from 0f to lowerBound, and reach 1f by upperBound. 392 */ clampToProgress(float progress, float lowerBound, float upperBound)393 public static float clampToProgress(float progress, float lowerBound, float upperBound) { 394 return clampToProgress(LINEAR, progress, lowerBound, upperBound); 395 } 396 mapRange(float value, float min, float max)397 private static float mapRange(float value, float min, float max) { 398 return min + (value * (max - min)); 399 } 400 401 /** 402 * Runs the given interpolator such that the interpolated value is mapped to the given range. 403 * This is useful, for example, if we only use this interpolator for part of the animation, 404 * such as to take over a user-controlled animation when they let go. 405 */ mapToProgress(Interpolator interpolator, float lowerBound, float upperBound)406 public static Interpolator mapToProgress(Interpolator interpolator, float lowerBound, 407 float upperBound) { 408 return t -> mapRange(interpolator.getInterpolation(t), lowerBound, upperBound); 409 } 410 411 /** 412 * Returns the reverse of the provided interpolator, following the formula: g(x) = 1 - f(1 - x). 413 * In practice, this means that if f is an interpolator used to model a value animating between 414 * m and n, g is the interpolator to use to obtain the specular behavior when animating from n 415 * to m. 416 */ reverse(Interpolator interpolator)417 public static Interpolator reverse(Interpolator interpolator) { 418 return t -> 1 - interpolator.getInterpolation(1 - t); 419 } 420 }