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
17package android.view;
18
19import 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 */
31public 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
40    private static native long nativeInitialize(String strategy);
41    private static native void nativeDispose(long ptr);
42    private static native void nativeClear(long ptr);
43    private static native void nativeAddMovement(long ptr, MotionEvent event);
44    private static native void nativeComputeCurrentVelocity(long ptr, int units, float maxVelocity);
45    private static native float nativeGetXVelocity(long ptr, int id);
46    private static native float nativeGetYVelocity(long ptr, int id);
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     */
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     */
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     */
82    public void recycle() {
83        if (mStrategy == null) {
84            clear();
85            sPool.release(this);
86        }
87    }
88
89    private VelocityTracker(String strategy) {
90        mPtr = nativeInitialize(strategy);
91        mStrategy = strategy;
92    }
93
94    @Override
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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     */
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         */
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         */
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         */
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         */
287        public float getYCoeff(int index) {
288            return index <= degree ? yCoeff[index] : 0;
289        }
290
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