dali/internal/update/gestures/scene-graph-pan-gesture.h

   1 #ifndef __DALI_INTERNAL_SCENE_GRAPH_PAN_GESTURE_H__
   2 #define __DALI_INTERNAL_SCENE_GRAPH_PAN_GESTURE_H__
   3
   4 /*
   5  * Copyright (c) 2016 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // INTERNAL INCLUDES
  22 #include <dali/public-api/common/vector-wrapper.h>
  23 #include <dali/public-api/events/pan-gesture.h>
  24 #include <dali/internal/update/common/property-owner.h>
  25 #include <dali/internal/update/gestures/gesture-properties.h>
  26
  27 namespace Dali
  28 {
  29
  30 struct PanGesture;
  31
  32 namespace Internal
  33 {
  34
  35 struct PanGestureProfiling;
  36
  37 namespace SceneGraph
  38 {
  39
  40 /**
  41  * The latest pan gesture information is stored in this scene object.
  42  */
  43 class PanGesture : public PropertyOwner
  44 {
  45 public:
  46
  47   enum PredictionMode
  48   {
  49     PREDICTION_NONE = 0,
  50     PREDICTION_1
  51   };
  52
  53   enum SmoothingMode
  54   {
  55     SMOOTHING_NONE,           // no smoothing
  56     SMOOTHING_LAST_VALUE,     // smooth between last value and latest value
  57   };
  58
  59   static const PredictionMode DEFAULT_PREDICTION_MODE;
  60   static const int NUM_PREDICTION_MODES;
  61
  62   static const SmoothingMode DEFAULT_SMOOTHING_MODE;
  63   static const int NUM_SMOOTHING_MODES;
  64
  65   // Latest Pan Information
  66
  67   /**
  68    * Only stores the information we actually require from Dali::PanGesture
  69    */
  70   struct PanInfo
  71   {
  72     /**
  73      * Stores the velocity, displacement and position.
  74      */
  75     struct Info
  76     {
  77       Info()
  78       {
  79       }
  80
  81       /**
  82        * Copy constructor
  83        */
  84       Info( const Info& rhs )
  85       : velocity( rhs.velocity ),
  86         displacement( rhs.displacement ),
  87         position( rhs.position )
  88       {
  89       }
  90
  91       /**
  92        * Assignment operator
  93        */
  94       Info& operator=( const Info& rhs )
  95       {
  96         if( this != &rhs )
  97         {
  98           velocity = rhs.velocity;
  99           displacement = rhs.displacement;
 100           position = rhs.position;
 101         }
 102
 103         return *this;
 104       }
 105
 106       // Data
 107
 108       Vector2 velocity;
 109       Vector2 displacement;
 110       Vector2 position;
 111     };
 112
 113     /**
 114      * Constructor
 115      */
 116     PanInfo()
 117     : time( 0u ),
 118       state( Gesture::Clear ),
 119       read( true )
 120     {
 121     }
 122
 123     /**
 124      * Copy constructor
 125      */
 126     PanInfo( const PanInfo& rhs )
 127     : time( rhs.time ),
 128       state( rhs.state ),
 129       local( rhs.local ),
 130       screen( rhs.screen ),
 131       read( true )
 132     {
 133     }
 134
 135     /**
 136      * Assignment operator
 137      */
 138     PanInfo& operator=( const PanInfo& rhs )
 139     {
 140       if( this != &rhs )
 141       {
 142         time = rhs.time;
 143         state = rhs.state;
 144         local = rhs.local;
 145         screen = rhs.screen;
 146       }
 147
 148       return *this;
 149     }
 150
 151     /**
 152      * Assignment operator
 153      * @param[in] gesture A Dali::Gesture
 154      */
 155     PanInfo& operator=( const Dali::PanGesture& rhs )
 156     {
 157       time = rhs.time;
 158       state = rhs.state;
 159
 160       local.velocity = rhs.velocity;
 161       local.displacement = rhs.displacement;
 162       local.position = rhs.position;
 163
 164       screen.velocity = rhs.screenVelocity;
 165       screen.displacement = rhs.screenDisplacement;
 166       screen.position = rhs.screenPosition;
 167
 168       return *this;
 169     }
 170
 171     // Data
 172     unsigned int time;
 173     Gesture::State state;
 174     Info local;
 175     Info screen;
 176     volatile bool read;
 177   };
 178
 179   typedef std::vector<PanInfo> PanInfoHistory;
 180   typedef PanInfoHistory::iterator PanInfoHistoryIter;
 181   typedef PanInfoHistory::const_iterator PanInfoHistoryConstIter;
 182
 183 private:
 184   static const unsigned int PAN_GESTURE_HISTORY = 10u;
 185
 186 public:
 187
 188   /**
 189    * Create a new PanGesture
 190    */
 191   static PanGesture* New();
 192
 193   /**
 194    * Virtual destructor
 195    */
 196   virtual ~PanGesture();
 197
 198   /**
 199    * Adds a PanGesture to the internal circular-buffer waiting to be handled by UpdateProperties.
 200    * @param[in]  gesture  The latest pan gesture.
 201    */
 202   void AddGesture( const Dali::PanGesture& gesture );
 203
 204   /**
 205    * @brief Removes pan events from the history that are older than maxAge, leaving at least minEvents
 206    *
 207    * @param[in] panHistory The pan event history container
 208    * @param[in] currentTime The current frame time
 209    * @param[in] maxAge Maximum age of an event before removing (in millis)
 210    * @param[in] minEvents The minimum number of events to leave in history, oldest events are removed before newest
 211    */
 212   void RemoveOldHistory(PanInfoHistory& panHistory, unsigned int currentTime, unsigned int maxAge, unsigned int minEvents);
 213
 214   /**
 215    * Uses elapsed time and time stamps
 216    */
 217   void PredictiveAlgorithm1(int eventsThisFrame, PanInfo& gestureOut, PanInfoHistory& panHistory, unsigned int lastVSyncTime, unsigned int nextVSyncTime);
 218
 219   /**
 220    * Uses last two gestures
 221    *
 222    * @param[in]  justStarted Whether the pan has just started.
 223    * @param[out] gestureOut Output gesture using average values from last two gestures
 224    * @param[in]  lastVSyncTime The time to set on gestureOut.
 225    */
 226   void SmoothingAlgorithm1(bool justStarted, PanInfo& gestureOut, unsigned int lastVSyncTime);
 227
 228   /**
 229    * Future smoothing method, implementation not complete
 230    */
 231   void SmoothingAlgorithm2(bool justStarted, PanInfo& gestureOut, unsigned int lastVSyncTime);
 232
 233   /**
 234    * Called by the update manager so that we can update the value of our properties.
 235    * @param[in]  nextRenderTime  The estimated time of the next render (in milliseconds).
 236    * @return true, if properties were updated.
 237    */
 238   bool UpdateProperties( unsigned int lastRenderTime, unsigned int nextRenderTime );
 239
 240   /**
 241    * Retrieves a reference to the panning flag property.
 242    * @return The panning flag property.
 243    */
 244   const GesturePropertyBool& GetPanningProperty() const;
 245
 246   /**
 247    * Retrieves a reference to the screen position property.
 248    * @return The screen position property.
 249    */
 250   const GesturePropertyVector2& GetScreenPositionProperty() const;
 251
 252   /**
 253    * Retrieves a reference to the screen velocity property.
 254    * @return The screen velocity property.
 255    */
 256   const GesturePropertyVector2& GetScreenVelocityProperty() const;
 257
 258   /**
 259    * Retrieves a reference to the screen displacement property.
 260    * @return The screen displacement property.
 261    */
 262   const GesturePropertyVector2& GetScreenDisplacementProperty() const;
 263
 264   /**
 265    * Retrieves a reference to the local position property.
 266    * @return The local position property.
 267    */
 268   const GesturePropertyVector2& GetLocalPositionProperty() const;
 269
 270   /**
 271    * Retrieves a reference to the local displacement property.
 272    * @return The local displacement property.
 273    */
 274   const GesturePropertyVector2& GetLocalDisplacementProperty() const;
 275
 276   /**
 277    * Retrieves a reference to the local velocity property.
 278    * @return The local velocity property.
 279    */
 280   const GesturePropertyVector2& GetLocalVelocityProperty() const;
 281
 282   /**
 283    * @brief Sets the prediction mode of the pan gesture
 284    *
 285    * @param[in] mode The prediction mode
 286    */
 287   void SetPredictionMode(PredictionMode mode);
 288
 289   /**
 290    * @brief Sets the prediction amount of the pan gesture
 291    *
 292    * @param[in] amount The prediction amount in milliseconds
 293    */
 294   void SetPredictionAmount(unsigned int amount);
 295
 296   /**
 297    * @brief Sets the upper bound of the prediction amount for clamping
 298    *
 299    * @param[in] amount The prediction amount in milliseconds
 300    */
 301   void SetMaximumPredictionAmount(unsigned int amount);
 302
 303   /**
 304    * @brief Sets the lower bound of the prediction amount for clamping
 305    *
 306    * @param[in] amount The prediction amount in milliseconds
 307    */
 308   void SetMinimumPredictionAmount(unsigned int amount);
 309
 310   /**
 311    * @brief Sets the amount of prediction interpolation to adjust when the pan velocity is changed
 312    *
 313    * @param[in] amount The prediction amount in milliseconds
 314    */
 315   void SetPredictionAmountAdjustment(unsigned int amount);
 316
 317   /**
 318    * @brief Sets the prediction mode of the pan gesture
 319    *
 320    * @param[in] mode The prediction mode
 321    */
 322   void SetSmoothingMode(SmoothingMode mode);
 323
 324   /**
 325    * @brief Sets the amount of smoothing to apply for the current smoothing mode
 326    *
 327    * @param[in] amount The amount of smoothing [0.0f,1.0f]
 328    */
 329   void SetSmoothingAmount(float amount);
 330
 331   /**
 332    * Called to provide pan-gesture profiling information.
 333    */
 334   void EnableProfiling();
 335
 336   /**
 337    * Reset default properties, custom ones not supported due to this being the only object in scene side
 338    * @param updateBufferIndex index to use
 339    */
 340   void ResetDefaultProperties( BufferIndex updateBufferIndex );
 341
 342 private:
 343
 344   /**
 345    * Protected constructor.
 346    */
 347   PanGesture();
 348
 349   // Undefined
 350   PanGesture(const PanGesture&);
 351
 352   // Undefined
 353   PanGesture& operator=(const PanGesture&);
 354
 355   // Defines information to be gathered by the gesture reading code.
 356   struct FrameGestureInfo
 357   {
 358     PanGesture::PanInfo frameGesture;
 359     float acceleration;
 360     unsigned int eventsThisFrame;
 361     bool justStarted;
 362     bool justFinished;
 363
 364     FrameGestureInfo()
 365     : acceleration( 0.0f ),
 366       eventsThisFrame( 0 ),
 367       justStarted( false ),
 368       justFinished( false )
 369     {
 370     }
 371   };
 372
 373   /**
 374    * Reads gestures from input, builds history.
 375    * @param[out] info Written to with information about gestures read this frame.
 376    * @param[in] currentTimestamp The time of this frame.
 377    */
 378   bool ReadGestures( FrameGestureInfo& info, unsigned int currentTimestamp );
 379
 380   /**
 381    * Reads gestures from input and resamples data, builds history.
 382    * @param[out] info Written to with information about gestures read this frame.
 383    * @param[in] currentTimestamp The time of this frame.
 384    */
 385   bool ReadAndResampleGestures( FrameGestureInfo& info, unsigned int currentTimestamp );
 386
 387 private:
 388
 389   // Properties
 390   GesturePropertyBool    mPanning;            ///< panning flag
 391   GesturePropertyVector2 mScreenPosition;     ///< screenPosition
 392   GesturePropertyVector2 mScreenDisplacement; ///< screenDisplacement
 393   GesturePropertyVector2 mScreenVelocity;     ///< screenVelocity
 394   GesturePropertyVector2 mLocalPosition;      ///< localPosition
 395   GesturePropertyVector2 mLocalDisplacement;  ///< localDisplacement
 396   GesturePropertyVector2 mLocalVelocity;      ///< localVelocity
 397
 398   PanInfoHistory mPanHistory;
 399   PanInfoHistory mPredictionHistory;
 400   PanInfo mGestures[PAN_GESTURE_HISTORY];     ///< Circular buffer storing the 4 most recent gestures.
 401   PanInfo mLastGesture;                       ///< The last gesture. (last update frame).
 402   PanInfo mTargetGesture;                     ///< The most recent input gesture, if the current used gesture does not match.
 403   PanInfo mLastUnmodifiedGesture;             ///< The last gesture before any processing was done on it.
 404   unsigned int mWritePosition;                ///< The next PanInfo buffer to write to. (starts at 0).
 405   unsigned int mReadPosition;                 ///< The next PanInfo buffer to read. (starts at 0).
 406   bool mNotAtTarget;                          ///< Keeps track of if the last gesture used was the most recent received.
 407   bool mInGesture;                            ///< True if the gesture is currently being handled i.e. between Started <-> Finished/Cancelled.
 408
 409   PredictionMode mPredictionMode;             ///< The pan gesture prediction mode
 410   unsigned int mPredictionAmount;             ///< how far into future to predict in milliseconds
 411   unsigned int mCurrentPredictionAmount;      ///< the current prediction amount used by the prediction algorithm
 412   unsigned int mMaxPredictionAmount;          ///< the maximum prediction amount used by the prediction algorithm
 413   unsigned int mMinPredictionAmount;          ///< the minimum prediction amount used by the prediction algorithm
 414   unsigned int mPredictionAmountAdjustment;   ///< the prediction amount to adjust in milliseconds when pan velocity changes
 415   SmoothingMode mSmoothingMode;               ///< The pan gesture prediction mode
 416   float         mSmoothingAmount;             ///< How much smoothing to apply [0.0f,1.0f]
 417   PanGestureProfiling* mProfiling;            ///< NULL unless pan-gesture profiling information is required.
 418 };
 419
 420 } // namespace SceneGraph
 421
 422 } // namespace Internal
 423
 424 } // namespace Dali
 425
 426 #endif // __DALI_INTERNAL_SCENE_GRAPH_PAN_GESTURE_H__