ui/events/gesture_detection/velocity_tracker.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef UI_EVENTS_GESTURE_DETECTION_VELOCITY_TRACKER_H_
   6 #define UI_EVENTS_GESTURE_DETECTION_VELOCITY_TRACKER_H_
   7
   8 #include "base/basictypes.h"
   9 #include "base/memory/scoped_ptr.h"
  10 #include "base/time/time.h"
  11 #include "ui/events/gesture_detection/bitset_32.h"
  12
  13 namespace ui {
  14
  15 class MotionEvent;
  16 class VelocityTrackerStrategy;
  17
  18 namespace {
  19 struct Estimator;
  20 struct Position;
  21 }
  22
  23 // Port of VelocityTracker from Android
  24 // * platform/frameworks/native/include/input/VelocityTracker.h
  25 // * Change-Id: I4983db61b53e28479fc90d9211fafff68f7f49a6
  26 // * Please update the Change-Id as upstream Android changes are pulled.
  27 class VelocityTracker {
  28  public:
  29   enum {
  30     // The maximum number of pointers to use when computing the velocity.
  31     // Note that the supplied MotionEvent may expose more than 16 pointers, but
  32     // at most |MAX_POINTERS| will be used.
  33     MAX_POINTERS = 16,
  34   };
  35
  36   enum Strategy {
  37     // 1st order least squares.  Quality: POOR.
  38     // Frequently underfits the touch data especially when the finger
  39     // accelerates or changes direction.  Often underestimates velocity.  The
  40     // direction is overly influenced by historical touch points.
  41     LSQ1,
  42
  43     // 2nd order least squares.  Quality: VERY GOOD.
  44     // Pretty much ideal, but can be confused by certain kinds of touch data,
  45     // particularly if the panel has a tendency to generate delayed, duplicate
  46     // or jittery touch coordinates when the finger is released.  This is the
  47     // default velocity tracker strategy.  Although other strategies are
  48     // available for testing and comparison purposes, this is the strategy that
  49     // applications will actually use.  Be very careful when adjusting the
  50     // default strategy because it can dramatically affect (often in a bad way)
  51     // the user experience.
  52     LSQ2,
  53
  54     // The same as LSQ2, but reports 0 if the direction of the velocity returned
  55     // is sufficiently different from the primary direction of movement of the
  56     // touches contributing to the velocity.
  57     LSQ2_RESTRICTED,
  58
  59     // 3rd order least squares.  Quality: UNUSABLE.
  60     // Frequently overfits the touch data yielding wildly divergent estimates
  61     // of the velocity when the finger is released.
  62     LSQ3,
  63
  64     // 2nd order weighted least squares, delta weighting.
  65     // Quality: EXPERIMENTAL
  66     WLSQ2_DELTA,
  67
  68     // 2nd order weighted least squares, central weighting.
  69     // Quality: EXPERIMENTAL
  70     WLSQ2_CENTRAL,
  71
  72     // 2nd order weighted least squares, recent weighting.
  73     // Quality: EXPERIMENTAL
  74     WLSQ2_RECENT,
  75
  76     // 1st order integrating filter.  Quality: GOOD.
  77     // Not as good as 'lsq2' because it cannot estimate acceleration but it is
  78     // more tolerant of errors.  Like 'lsq1', this strategy tends to
  79     // underestimate
  80     // the velocity of a fling but this strategy tends to respond to changes in
  81     // direction more quickly and accurately.
  82     INT1,
  83
  84     // 2nd order integrating filter.  Quality: EXPERIMENTAL.
  85     // For comparison purposes only.  Unlike 'int1' this strategy can compensate
  86     // for acceleration but it typically overestimates the effect.
  87     INT2,
  88     STRATEGY_MAX = INT2,
  89
  90     // The default velocity tracker strategy.
  91     STRATEGY_DEFAULT = LSQ2,
  92   };
  93
  94   // Creates a velocity tracker using the specified strategy.
  95   // If strategy is NULL, uses the default strategy for the platform.
  96   explicit VelocityTracker(Strategy strategy);
  97
  98   ~VelocityTracker();
  99
 100   // Resets the velocity tracker state.
 101   void Clear();
 102
 103   // Adds movement information for all pointers in a MotionEvent, including
 104   // historical samples.
 105   void AddMovement(const MotionEvent& event);
 106
 107   // Gets the velocity of the specified pointer id in position units per second.
 108   // Returns false and sets the velocity components to zero if there is
 109   // insufficient movement information for the pointer.
 110   bool GetVelocity(uint32_t id, float* outVx, float* outVy) const;
 111
 112   // Gets the active pointer id, or -1 if none.
 113   inline int32_t GetActivePointerId() const { return active_pointer_id_; }
 114
 115   // Gets a bitset containing all pointer ids from the most recent movement.
 116   inline BitSet32 GetCurrentPointerIdBits() const {
 117     return current_pointer_id_bits_;
 118   }
 119
 120  private:
 121   // Resets the velocity tracker state for specific pointers.
 122   // Call this method when some pointers have changed and may be reusing
 123   // an id that was assigned to a different pointer earlier.
 124   void ClearPointers(BitSet32 id_bits);
 125
 126   // Adds movement information for a set of pointers.
 127   // The id_bits bitfield specifies the pointer ids of the pointers whose
 128   // positions
 129   // are included in the movement.
 130   // The positions array contains position information for each pointer in order
 131   // by
 132   // increasing id.  Its size should be equal to the number of one bits in
 133   // id_bits.
 134   void AddMovement(const base::TimeTicks& event_time,
 135                    BitSet32 id_bits,
 136                    const Position* positions);
 137
 138   // Gets an estimator for the recent movements of the specified pointer id.
 139   // Returns false if the pointer velocity is unknown.
 140   bool GetEstimator(uint32_t id, Estimator* out_estimator) const;
 141
 142   base::TimeTicks last_event_time_;
 143   BitSet32 current_pointer_id_bits_;
 144   int32_t active_pointer_id_;
 145   scoped_ptr<VelocityTrackerStrategy> strategy_;
 146
 147   DISALLOW_COPY_AND_ASSIGN(VelocityTracker);
 148 };
 149
 150 }  // namespace ui
 151
 152 #endif  // UI_EVENTS_GESTURE_DETECTION_VELOCITY_TRACKER_H_