content: /*
   * Copyright (C) 2006 The Android Open Source Project
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package android.view;
  
  import android.annotation.UnsupportedAppUsage;
  import android.util.Pools.SynchronizedPool;
  
  /**
   * Helper for tracking the velocity of touch events, for implementing
   * flinging and other such gestures.
   *
   * Use {@link #obtain} to retrieve a new instance of the class when you are going
   * to begin tracking.  Put the motion events you receive into it with
   * {@link #addMovement(MotionEvent)}.  When you want to determine the velocity call
   * {@link #computeCurrentVelocity(int)} and then call {@link #getXVelocity(int)}
   * and {@link #getYVelocity(int)} to retrieve the velocity for each pointer id.
   */
  public final class VelocityTracker {
      private static final SynchronizedPool<VelocityTracker> sPool =
              new SynchronizedPool<VelocityTracker>(2);
  
      private static final int ACTIVE_POINTER_ID = -1;
  
      private long mPtr;
      private final String mStrategy;
  
      private static native long nativeInitialize(String strategy);
      private static native void nativeDispose(long ptr);
      private static native void nativeClear(long ptr);
      private static native void nativeAddMovement(long ptr, MotionEvent event);
      private static native void nativeComputeCurrentVelocity(long ptr, int units, float maxVelocity);
      private static native float nativeGetXVelocity(long ptr, int id);
      private static native float nativeGetYVelocity(long ptr, int id);
      private static native boolean nativeGetEstimator(long ptr, int id, Estimator outEstimator);
  
      /**
       * Retrieve a new VelocityTracker object to watch the velocity of a
       * motion.  Be sure to call {@link #recycle} when done.  You should
       * generally only maintain an active object while tracking a movement,
       * so that the VelocityTracker can be re-used elsewhere.
       *
       * @return Returns a new VelocityTracker.
       */
      static public VelocityTracker obtain() {
          VelocityTracker instance = sPool.acquire();
          return (instance != null) ? instance : new VelocityTracker(null);
      }
  
      /**
       * Obtains a velocity tracker with the specified strategy.
       * For testing and comparison purposes only.
       *
       * @param strategy The strategy, or null to use the default.
       * @return The velocity tracker.
       *
       * @hide
       */
      @UnsupportedAppUsage
      public static VelocityTracker obtain(String strategy) {
          if (strategy == null) {
              return obtain();
          }
          return new VelocityTracker(strategy);
      }
  
      /**
       * Return a VelocityTracker object back to be re-used by others.  You must
       * not touch the object after calling this function.
       */
      public void recycle() {
          if (mStrategy == null) {
              clear();
              sPool.release(this);
          }
      }
  
      private VelocityTracker(String strategy) {
          mPtr = nativeInitialize(strategy);
          mStrategy = strategy;
      }
  
      @Override
      protected void finalize() throws Throwable {
          try {
              if (mPtr != 0) {
                  nativeDispose(mPtr);
                  mPtr = 0;
              }
          } finally {
              super.finalize();
          }
      }
  
      /**
       * Reset the velocity tracker back to its initial state.
       */
      public void clear() {
          nativeClear(mPtr);
      }
      
      /**
       * Add a user's movement to the tracker.  You should call this for the
       * initial {@link MotionEvent#ACTION_DOWN}, the following
       * {@link MotionEvent#ACTION_MOVE} events that you receive, and the
       * final {@link MotionEvent#ACTION_UP}.  You can, however, call this
       * for whichever events you desire.
       * 
       * @param event The MotionEvent you received and would like to track.
       */
      public void addMovement(MotionEvent event) {
          if (event == null) {
              throw new IllegalArgumentException("event must not be null");
          }
          nativeAddMovement(mPtr, event);
      }
  
      /**
       * Equivalent to invoking {@link #computeCurrentVelocity(int, float)} with a maximum
       * velocity of Float.MAX_VALUE.
       * 
       * @see #computeCurrentVelocity(int, float) 
       */
      public void computeCurrentVelocity(int units) {
          nativeComputeCurrentVelocity(mPtr, units, Float.MAX_VALUE);
      }
  
      /**
       * Compute the current velocity based on the points that have been
       * collected.  Only call this when you actually want to retrieve velocity
       * information, as it is relatively expensive.  You can then retrieve
       * the velocity with {@link #getXVelocity()} and
       * {@link #getYVelocity()}.
       * 
       * @param units The units you would like the velocity in.  A value of 1
       * provides pixels per millisecond, 1000 provides pixels per second, etc.
       * @param maxVelocity The maximum velocity that can be computed by this method.
       * This value must be declared in the same unit as the units parameter. This value
       * must be positive.
       */
      public void computeCurrentVelocity(int units, float maxVelocity) {
          nativeComputeCurrentVelocity(mPtr, units, maxVelocity);
      }
      
      /**
       * Retrieve the last computed X velocity.  You must first call
       * {@link #computeCurrentVelocity(int)} before calling this function.
       * 
       * @return The previously computed X velocity.
       */
      public float getXVelocity() {
          return nativeGetXVelocity(mPtr, ACTIVE_POINTER_ID);
      }
      
      /**
       * Retrieve the last computed Y velocity.  You must first call
       * {@link #computeCurrentVelocity(int)} before calling this function.
       * 
       * @return The previously computed Y velocity.
       */
      public float getYVelocity() {
          return nativeGetYVelocity(mPtr, ACTIVE_POINTER_ID);
      }
      
      /**
       * Retrieve the last computed X velocity.  You must first call
       * {@link #computeCurrentVelocity(int)} before calling this function.
       * 
       * @param id Which pointer's velocity to return.
       * @return The previously computed X velocity.
       */
      public float getXVelocity(int id) {
          return nativeGetXVelocity(mPtr, id);
      }
      
      /**
       * Retrieve the last computed Y velocity.  You must first call
       * {@link #computeCurrentVelocity(int)} before calling this function.
       * 
       * @param id Which pointer's velocity to return.
       * @return The previously computed Y velocity.
       */
      public float getYVelocity(int id) {
          return nativeGetYVelocity(mPtr, id);
      }
  
      /**
       * Get an estimator for the movements of a pointer using past movements of the
       * pointer to predict future movements.
       *
       * It is not necessary to call {@link #computeCurrentVelocity(int)} before calling
       * this method.
       *
       * @param id Which pointer's velocity to return.
       * @param outEstimator The estimator to populate.
       * @return True if an estimator was obtained, false if there is no information
       * available about the pointer.
       *
       * @hide For internal use only.  Not a final API.
       */
      public boolean getEstimator(int id, Estimator outEstimator) {
          if (outEstimator == null) {
              throw new IllegalArgumentException("outEstimator must not be null");
          }
          return nativeGetEstimator(mPtr, id, outEstimator);
      }
  
      /**
       * An estimator for the movements of a pointer based on a polynomial model.
       *
       * The last recorded position of the pointer is at time zero seconds.
       * Past estimated positions are at negative times and future estimated positions
       * are at positive times.
       *
       * First coefficient is position (in pixels), second is velocity (in pixels per second),
       * third is acceleration (in pixels per second squared).
       *
       * @hide For internal use only.  Not a final API.
       */
      public static final class Estimator {
          // Must match VelocityTracker::Estimator::MAX_DEGREE
          private static final int MAX_DEGREE = 4;
  
          /**
           * Polynomial coefficients describing motion in X.
           */
          @UnsupportedAppUsage
          public final float[] xCoeff = new float[MAX_DEGREE + 1];
  
          /**
           * Polynomial coefficients describing motion in Y.
           */
          @UnsupportedAppUsage
          public final float[] yCoeff = new float[MAX_DEGREE + 1];
  
          /**
           * Polynomial degree, or zero if only position information is available.
           */
          @UnsupportedAppUsage
          public int degree;
  
          /**
           * Confidence (coefficient of determination), between 0 (no fit) and 1 (perfect fit).
           */
          @UnsupportedAppUsage
          public float confidence;
  
          /**
           * Gets an estimate of the X position of the pointer at the specified time point.
           * @param time The time point in seconds, 0 is the last recorded time.
           * @return The estimated X coordinate.
           */
          public float estimateX(float time) {
              return estimate(time, xCoeff);
          }
  
          /**
           * Gets an estimate of the Y position of the pointer at the specified time point.
           * @param time The time point in seconds, 0 is the last recorded time.
           * @return The estimated Y coordinate.
           */
          public float estimateY(float time) {
              return estimate(time, yCoeff);
          }
  
          /**
           * Gets the X coefficient with the specified index.
           * @param index The index of the coefficient to return.
           * @return The X coefficient, or 0 if the index is greater than the degree.
           */
          public float getXCoeff(int index) {
              return index <= degree ? xCoeff[index] : 0;
          }
  
          /**
           * Gets the Y coefficient with the specified index.
           * @param index The index of the coefficient to return.
           * @return The Y coefficient, or 0 if the index is greater than the degree.
           */
          public float getYCoeff(int index) {
              return index <= degree ? yCoeff[index] : 0;
          }
  
          private float estimate(float time, float[] c) {
              float a = 0;
              float scale = 1;
              for (int i = 0; i <= degree; i++) {
                  a += c[i] * scale;
                  scale *= time;
              }
              return a;
          }
      }
  }
  