1 /*
2  * Copyright (C) 2006 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 android.view;
18 
19 import android.util.Pools.SynchronizedPool;
20 
21 /**
22  * Helper for tracking the velocity of touch events, for implementing
23  * flinging and other such gestures.
24  *
25  * Use {@link #obtain} to retrieve a new instance of the class when you are going
26  * to begin tracking.  Put the motion events you receive into it with
27  * {@link #addMovement(MotionEvent)}.  When you want to determine the velocity call
28  * {@link #computeCurrentVelocity(int)} and then call {@link #getXVelocity(int)}
29  * and {@link #getYVelocity(int)} to retrieve the velocity for each pointer id.
30  */
31 public final class VelocityTracker {
32     private static final SynchronizedPool<VelocityTracker> sPool =
33             new SynchronizedPool<VelocityTracker>(2);
34 
35     private static final int ACTIVE_POINTER_ID = -1;
36 
37     private long mPtr;
38     private final String mStrategy;
39 
nativeInitialize(String strategy)40     private static native long nativeInitialize(String strategy);
nativeDispose(long ptr)41     private static native void nativeDispose(long ptr);
nativeClear(long ptr)42     private static native void nativeClear(long ptr);
nativeAddMovement(long ptr, MotionEvent event)43     private static native void nativeAddMovement(long ptr, MotionEvent event);
nativeComputeCurrentVelocity(long ptr, int units, float maxVelocity)44     private static native void nativeComputeCurrentVelocity(long ptr, int units, float maxVelocity);
nativeGetXVelocity(long ptr, int id)45     private static native float nativeGetXVelocity(long ptr, int id);
nativeGetYVelocity(long ptr, int id)46     private static native float nativeGetYVelocity(long ptr, int id);
nativeGetEstimator(long ptr, int id, Estimator outEstimator)47     private static native boolean nativeGetEstimator(long ptr, int id, Estimator outEstimator);
48 
49     /**
50      * Retrieve a new VelocityTracker object to watch the velocity of a
51      * motion.  Be sure to call {@link #recycle} when done.  You should
52      * generally only maintain an active object while tracking a movement,
53      * so that the VelocityTracker can be re-used elsewhere.
54      *
55      * @return Returns a new VelocityTracker.
56      */
obtain()57     static public VelocityTracker obtain() {
58         VelocityTracker instance = sPool.acquire();
59         return (instance != null) ? instance : new VelocityTracker(null);
60     }
61 
62     /**
63      * Obtains a velocity tracker with the specified strategy.
64      * For testing and comparison purposes only.
65      *
66      * @param strategy The strategy, or null to use the default.
67      * @return The velocity tracker.
68      *
69      * @hide
70      */
obtain(String strategy)71     public static VelocityTracker obtain(String strategy) {
72         if (strategy == null) {
73             return obtain();
74         }
75         return new VelocityTracker(strategy);
76     }
77 
78     /**
79      * Return a VelocityTracker object back to be re-used by others.  You must
80      * not touch the object after calling this function.
81      */
recycle()82     public void recycle() {
83         if (mStrategy == null) {
84             clear();
85             sPool.release(this);
86         }
87     }
88 
VelocityTracker(String strategy)89     private VelocityTracker(String strategy) {
90         mPtr = nativeInitialize(strategy);
91         mStrategy = strategy;
92     }
93 
94     @Override
finalize()95     protected void finalize() throws Throwable {
96         try {
97             if (mPtr != 0) {
98                 nativeDispose(mPtr);
99                 mPtr = 0;
100             }
101         } finally {
102             super.finalize();
103         }
104     }
105 
106     /**
107      * Reset the velocity tracker back to its initial state.
108      */
clear()109     public void clear() {
110         nativeClear(mPtr);
111     }
112 
113     /**
114      * Add a user's movement to the tracker.  You should call this for the
115      * initial {@link MotionEvent#ACTION_DOWN}, the following
116      * {@link MotionEvent#ACTION_MOVE} events that you receive, and the
117      * final {@link MotionEvent#ACTION_UP}.  You can, however, call this
118      * for whichever events you desire.
119      *
120      * @param event The MotionEvent you received and would like to track.
121      */
addMovement(MotionEvent event)122     public void addMovement(MotionEvent event) {
123         if (event == null) {
124             throw new IllegalArgumentException("event must not be null");
125         }
126         nativeAddMovement(mPtr, event);
127     }
128 
129     /**
130      * Equivalent to invoking {@link #computeCurrentVelocity(int, float)} with a maximum
131      * velocity of Float.MAX_VALUE.
132      *
133      * @see #computeCurrentVelocity(int, float)
134      */
computeCurrentVelocity(int units)135     public void computeCurrentVelocity(int units) {
136         nativeComputeCurrentVelocity(mPtr, units, Float.MAX_VALUE);
137     }
138 
139     /**
140      * Compute the current velocity based on the points that have been
141      * collected.  Only call this when you actually want to retrieve velocity
142      * information, as it is relatively expensive.  You can then retrieve
143      * the velocity with {@link #getXVelocity()} and
144      * {@link #getYVelocity()}.
145      *
146      * @param units The units you would like the velocity in.  A value of 1
147      * provides pixels per millisecond, 1000 provides pixels per second, etc.
148      * @param maxVelocity The maximum velocity that can be computed by this method.
149      * This value must be declared in the same unit as the units parameter. This value
150      * must be positive.
151      */
computeCurrentVelocity(int units, float maxVelocity)152     public void computeCurrentVelocity(int units, float maxVelocity) {
153         nativeComputeCurrentVelocity(mPtr, units, maxVelocity);
154     }
155 
156     /**
157      * Retrieve the last computed X velocity.  You must first call
158      * {@link #computeCurrentVelocity(int)} before calling this function.
159      *
160      * @return The previously computed X velocity.
161      */
getXVelocity()162     public float getXVelocity() {
163         return nativeGetXVelocity(mPtr, ACTIVE_POINTER_ID);
164     }
165 
166     /**
167      * Retrieve the last computed Y velocity.  You must first call
168      * {@link #computeCurrentVelocity(int)} before calling this function.
169      *
170      * @return The previously computed Y velocity.
171      */
getYVelocity()172     public float getYVelocity() {
173         return nativeGetYVelocity(mPtr, ACTIVE_POINTER_ID);
174     }
175 
176     /**
177      * Retrieve the last computed X velocity.  You must first call
178      * {@link #computeCurrentVelocity(int)} before calling this function.
179      *
180      * @param id Which pointer's velocity to return.
181      * @return The previously computed X velocity.
182      */
getXVelocity(int id)183     public float getXVelocity(int id) {
184         return nativeGetXVelocity(mPtr, id);
185     }
186 
187     /**
188      * Retrieve the last computed Y velocity.  You must first call
189      * {@link #computeCurrentVelocity(int)} before calling this function.
190      *
191      * @param id Which pointer's velocity to return.
192      * @return The previously computed Y velocity.
193      */
getYVelocity(int id)194     public float getYVelocity(int id) {
195         return nativeGetYVelocity(mPtr, id);
196     }
197 
198     /**
199      * Get an estimator for the movements of a pointer using past movements of the
200      * pointer to predict future movements.
201      *
202      * It is not necessary to call {@link #computeCurrentVelocity(int)} before calling
203      * this method.
204      *
205      * @param id Which pointer's velocity to return.
206      * @param outEstimator The estimator to populate.
207      * @return True if an estimator was obtained, false if there is no information
208      * available about the pointer.
209      *
210      * @hide For internal use only.  Not a final API.
211      */
getEstimator(int id, Estimator outEstimator)212     public boolean getEstimator(int id, Estimator outEstimator) {
213         if (outEstimator == null) {
214             throw new IllegalArgumentException("outEstimator must not be null");
215         }
216         return nativeGetEstimator(mPtr, id, outEstimator);
217     }
218 
219     /**
220      * An estimator for the movements of a pointer based on a polynomial model.
221      *
222      * The last recorded position of the pointer is at time zero seconds.
223      * Past estimated positions are at negative times and future estimated positions
224      * are at positive times.
225      *
226      * First coefficient is position (in pixels), second is velocity (in pixels per second),
227      * third is acceleration (in pixels per second squared).
228      *
229      * @hide For internal use only.  Not a final API.
230      */
231     public static final class Estimator {
232         // Must match VelocityTracker::Estimator::MAX_DEGREE
233         private static final int MAX_DEGREE = 4;
234 
235         /**
236          * Polynomial coefficients describing motion in X.
237          */
238         public final float[] xCoeff = new float[MAX_DEGREE + 1];
239 
240         /**
241          * Polynomial coefficients describing motion in Y.
242          */
243         public final float[] yCoeff = new float[MAX_DEGREE + 1];
244 
245         /**
246          * Polynomial degree, or zero if only position information is available.
247          */
248         public int degree;
249 
250         /**
251          * Confidence (coefficient of determination), between 0 (no fit) and 1 (perfect fit).
252          */
253         public float confidence;
254 
255         /**
256          * Gets an estimate of the X position of the pointer at the specified time point.
257          * @param time The time point in seconds, 0 is the last recorded time.
258          * @return The estimated X coordinate.
259          */
estimateX(float time)260         public float estimateX(float time) {
261             return estimate(time, xCoeff);
262         }
263 
264         /**
265          * Gets an estimate of the Y position of the pointer at the specified time point.
266          * @param time The time point in seconds, 0 is the last recorded time.
267          * @return The estimated Y coordinate.
268          */
estimateY(float time)269         public float estimateY(float time) {
270             return estimate(time, yCoeff);
271         }
272 
273         /**
274          * Gets the X coefficient with the specified index.
275          * @param index The index of the coefficient to return.
276          * @return The X coefficient, or 0 if the index is greater than the degree.
277          */
getXCoeff(int index)278         public float getXCoeff(int index) {
279             return index <= degree ? xCoeff[index] : 0;
280         }
281 
282         /**
283          * Gets the Y coefficient with the specified index.
284          * @param index The index of the coefficient to return.
285          * @return The Y coefficient, or 0 if the index is greater than the degree.
286          */
getYCoeff(int index)287         public float getYCoeff(int index) {
288             return index <= degree ? yCoeff[index] : 0;
289         }
290 
estimate(float time, float[] c)291         private float estimate(float time, float[] c) {
292             float a = 0;
293             float scale = 1;
294             for (int i = 0; i <= degree; i++) {
295                 a += c[i] * scale;
296                 scale *= time;
297             }
298             return a;
299         }
300     }
301 }
302