1 /*
2  * Copyright 2020 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 androidx.compose.animation.core
18 
19 /**
20  * [VectorizedDecayAnimationSpec]s are stateless vector based decay animation specifications. They
21  * do not assume any starting/ending conditions. Nor do they manage a lifecycle. All it stores is
22  * the configuration that is particular to the type of the decay animation: friction multiplier for
23  * [exponentialDecay]. Its stateless nature allows the same [VectorizedDecayAnimationSpec] to be
24  * reused by a few different running animations with different starting and ending values.
25  *
26  * Since [VectorizedDecayAnimationSpec]s are stateless, it requires starting value/velocity and
27  * ending value to be passed in, along with playtime, to calculate the value or velocity at that
28  * time. Play time here is the progress of the animation in terms of milliseconds, where 0 means the
29  * start of the animation and [getDurationNanos] returns the play time for the end of the animation.
30  *
31  * __Note__: For use cases where the starting values/velocity and ending values aren't expected to
32  * change, it is recommended to use [DecayAnimation] that caches these static values and hence does
33  * not require them to be supplied in the value/velocity calculation.
34  *
35  * @see DecayAnimation
36  */
37 public interface VectorizedDecayAnimationSpec<V : AnimationVector> {
38     /**
39      * This is the absolute value of a velocity threshold, below which the animation is considered
40      * finished.
41      */
42     public val absVelocityThreshold: Float
43 
44     /**
45      * Returns the value of the animation at the given time.
46      *
47      * @param playTimeNanos The time elapsed in milliseconds since the initialValue of the animation
48      * @param initialValue The initialValue value of the animation
49      * @param initialVelocity The initialValue velocity of the animation
50      */
getValueFromNanosnull51     public fun getValueFromNanos(playTimeNanos: Long, initialValue: V, initialVelocity: V): V
52 
53     /**
54      * Returns the duration of the decay animation, in nanoseconds.
55      *
56      * @param initialValue initialValue value of the animation
57      * @param initialVelocity initialValue velocity of the animation
58      */
59     @Suppress("MethodNameUnits")
60     public fun getDurationNanos(initialValue: V, initialVelocity: V): Long
61 
62     /**
63      * Returns the velocity of the animation at the given time.
64      *
65      * @param playTimeNanos The time elapsed in milliseconds since the initialValue of the animation
66      * @param initialValue The initialValue value of the animation
67      * @param initialVelocity The initialValue velocity of the animation
68      */
69     public fun getVelocityFromNanos(playTimeNanos: Long, initialValue: V, initialVelocity: V): V
70 
71     /**
72      * Returns the target value of the animation based on the initial condition of the animation (
73      * i.e. initial value and initial velocity).
74      *
75      * @param initialValue The initial value of the animation
76      * @param initialVelocity The initial velocity of the animation
77      */
78     public fun getTargetValue(initialValue: V, initialVelocity: V): V
79 }
80