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) 2017 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         read = rhs.read;
 147       }
 148
 149       return *this;
 150     }
 151
 152     /**
 153      * Assignment operator
 154      * @param[in] gesture A Dali::Gesture
 155      */
 156     PanInfo& operator=( const Dali::PanGesture& rhs )
 157     {
 158       time = rhs.time;
 159       state = rhs.state;
 160
 161       local.velocity = rhs.velocity;
 162       local.displacement = rhs.displacement;
 163       local.position = rhs.position;
 164
 165       screen.velocity = rhs.screenVelocity;
 166       screen.displacement = rhs.screenDisplacement;
 167       screen.position = rhs.screenPosition;
 168
 169       return *this;
 170     }
 171
 172     // Data
 173     unsigned int time;
 174     Gesture::State state;
 175     Info local;
 176     Info screen;
 177     volatile bool read;
 178   };
 179
 180   typedef std::vector<PanInfo> PanInfoHistory;
 181   typedef PanInfoHistory::iterator PanInfoHistoryIter;
 182   typedef PanInfoHistory::const_iterator PanInfoHistoryConstIter;
 183
 184 private:
 185   static const unsigned int PAN_GESTURE_HISTORY = 10u;
 186
 187 public:
 188
 189   /**
 190    * Create a new PanGesture
 191    */
 192   static PanGesture* New();
 193
 194   /**
 195    * Virtual destructor
 196    */
 197   virtual ~PanGesture();
 198
 199   /**
 200    * Adds a PanGesture to the internal circular-buffer waiting to be handled by UpdateProperties.
 201    * @param[in]  gesture  The latest pan gesture.
 202    */
 203   void AddGesture( const Dali::PanGesture& gesture );
 204
 205   /**
 206    * @brief Removes pan events from the history that are older than maxAge, leaving at least minEvents
 207    *
 208    * @param[in] panHistory The pan event history container
 209    * @param[in] currentTime The current frame time
 210    * @param[in] maxAge Maximum age of an event before removing (in millis)
 211    * @param[in] minEvents The minimum number of events to leave in history, oldest events are removed before newest
 212    */
 213   void RemoveOldHistory(PanInfoHistory& panHistory, unsigned int currentTime, unsigned int maxAge, unsigned int minEvents);
 214
 215   /**
 216    * Uses elapsed time and time stamps
 217    */
 218   void PredictiveAlgorithm1(int eventsThisFrame, PanInfo& gestureOut, PanInfoHistory& panHistory, unsigned int lastVSyncTime, unsigned int nextVSyncTime);
 219
 220   /**
 221    * Uses last two gestures
 222    *
 223    * @param[in]  justStarted Whether the pan has just started.
 224    * @param[out] gestureOut Output gesture using average values from last two gestures
 225    * @param[in]  lastVSyncTime The time to set on gestureOut.
 226    */
 227   void SmoothingAlgorithm1(bool justStarted, PanInfo& gestureOut, unsigned int lastVSyncTime);
 228
 229   /**
 230    * Future smoothing method, implementation not complete
 231    */
 232   void SmoothingAlgorithm2(bool justStarted, PanInfo& gestureOut, unsigned int lastVSyncTime);
 233
 234   /**
 235    * Called by the update manager so that we can update the value of our properties.
 236    * @param[in]  nextRenderTime  The estimated time of the next render (in milliseconds).
 237    * @return true, if properties were updated.
 238    */
 239   bool UpdateProperties( unsigned int lastRenderTime, unsigned int nextRenderTime );
 240
 241   /**
 242    * Retrieves a reference to the panning flag property.
 243    * @return The panning flag property.
 244    */
 245   const GesturePropertyBool& GetPanningProperty() const;
 246
 247   /**
 248    * Retrieves a reference to the screen position property.
 249    * @return The screen position property.
 250    */
 251   const GesturePropertyVector2& GetScreenPositionProperty() const;
 252
 253   /**
 254    * Retrieves a reference to the screen velocity property.
 255    * @return The screen velocity property.
 256    */
 257   const GesturePropertyVector2& GetScreenVelocityProperty() const;
 258
 259   /**
 260    * Retrieves a reference to the screen displacement property.
 261    * @return The screen displacement property.
 262    */
 263   const GesturePropertyVector2& GetScreenDisplacementProperty() const;
 264
 265   /**
 266    * Retrieves a reference to the local position property.
 267    * @return The local position property.
 268    */
 269   const GesturePropertyVector2& GetLocalPositionProperty() const;
 270
 271   /**
 272    * Retrieves a reference to the local displacement property.
 273    * @return The local displacement property.
 274    */
 275   const GesturePropertyVector2& GetLocalDisplacementProperty() const;
 276
 277   /**
 278    * Retrieves a reference to the local velocity property.
 279    * @return The local velocity property.
 280    */
 281   const GesturePropertyVector2& GetLocalVelocityProperty() const;
 282
 283   /**
 284    * @brief Sets the prediction mode of the pan gesture
 285    *
 286    * @param[in] mode The prediction mode
 287    */
 288   void SetPredictionMode(PredictionMode mode);
 289
 290   /**
 291    * @brief Sets the prediction amount of the pan gesture
 292    *
 293    * @param[in] amount The prediction amount in milliseconds
 294    */
 295   void SetPredictionAmount(unsigned int amount);
 296
 297   /**
 298    * @brief Sets the upper bound of the prediction amount for clamping
 299    *
 300    * @param[in] amount The prediction amount in milliseconds
 301    */
 302   void SetMaximumPredictionAmount(unsigned int amount);
 303
 304   /**
 305    * @brief Sets the lower bound of the prediction amount for clamping
 306    *
 307    * @param[in] amount The prediction amount in milliseconds
 308    */
 309   void SetMinimumPredictionAmount(unsigned int amount);
 310
 311   /**
 312    * @brief Sets the amount of prediction interpolation to adjust when the pan velocity is changed
 313    *
 314    * @param[in] amount The prediction amount in milliseconds
 315    */
 316   void SetPredictionAmountAdjustment(unsigned int amount);
 317
 318   /**
 319    * @brief Sets the prediction mode of the pan gesture
 320    *
 321    * @param[in] mode The prediction mode
 322    */
 323   void SetSmoothingMode(SmoothingMode mode);
 324
 325   /**
 326    * @brief Sets the amount of smoothing to apply for the current smoothing mode
 327    *
 328    * @param[in] amount The amount of smoothing [0.0f,1.0f]
 329    */
 330   void SetSmoothingAmount(float amount);
 331
 332   /**
 333    * Called to provide pan-gesture profiling information.
 334    */
 335   void EnableProfiling();
 336
 337   /**
 338    * Reset default properties, custom ones not supported due to this being the only object in scene side
 339    * @param updateBufferIndex index to use
 340    */
 341   void ResetDefaultProperties( BufferIndex updateBufferIndex );
 342
 343 private:
 344
 345   /**
 346    * Protected constructor.
 347    */
 348   PanGesture();
 349
 350   // Undefined
 351   PanGesture(const PanGesture&);
 352
 353   // Undefined
 354   PanGesture& operator=(const PanGesture&);
 355
 356   // Defines information to be gathered by the gesture reading code.
 357   struct FrameGestureInfo
 358   {
 359     PanGesture::PanInfo frameGesture;
 360     float acceleration;
 361     unsigned int eventsThisFrame;
 362     bool justStarted;
 363     bool justFinished;
 364
 365     FrameGestureInfo()
 366     : acceleration( 0.0f ),
 367       eventsThisFrame( 0 ),
 368       justStarted( false ),
 369       justFinished( false )
 370     {
 371     }
 372   };
 373
 374   /**
 375    * Reads gestures from input, builds history.
 376    * @param[out] info Written to with information about gestures read this frame.
 377    * @param[in] currentTimestamp The time of this frame.
 378    */
 379   bool ReadGestures( FrameGestureInfo& info, unsigned int currentTimestamp );
 380
 381   /**
 382    * Reads gestures from input and resamples data, builds history.
 383    * @param[out] info Written to with information about gestures read this frame.
 384    * @param[in] currentTimestamp The time of this frame.
 385    */
 386   bool ReadAndResampleGestures( FrameGestureInfo& info, unsigned int currentTimestamp );
 387
 388 private:
 389
 390   // Properties
 391   GesturePropertyBool    mPanning;            ///< panning flag
 392   GesturePropertyVector2 mScreenPosition;     ///< screenPosition
 393   GesturePropertyVector2 mScreenDisplacement; ///< screenDisplacement
 394   GesturePropertyVector2 mScreenVelocity;     ///< screenVelocity
 395   GesturePropertyVector2 mLocalPosition;      ///< localPosition
 396   GesturePropertyVector2 mLocalDisplacement;  ///< localDisplacement
 397   GesturePropertyVector2 mLocalVelocity;      ///< localVelocity
 398
 399   PanInfoHistory mPanHistory;
 400   PanInfoHistory mPredictionHistory;
 401   PanInfo mGestures[PAN_GESTURE_HISTORY];     ///< Circular buffer storing the 4 most recent gestures.
 402   PanInfo mLastGesture;                       ///< The last gesture. (last update frame).
 403   PanInfo mTargetGesture;                     ///< The most recent input gesture, if the current used gesture does not match.
 404   PanInfo mLastUnmodifiedGesture;             ///< The last gesture before any processing was done on it.
 405   unsigned int mWritePosition;                ///< The next PanInfo buffer to write to. (starts at 0).
 406   unsigned int mReadPosition;                 ///< The next PanInfo buffer to read. (starts at 0).
 407   bool mNotAtTarget;                          ///< Keeps track of if the last gesture used was the most recent received.
 408   bool mInGesture;                            ///< True if the gesture is currently being handled i.e. between Started <-> Finished/Cancelled.
 409
 410   PredictionMode mPredictionMode;             ///< The pan gesture prediction mode
 411   unsigned int mPredictionAmount;             ///< how far into future to predict in milliseconds
 412   unsigned int mCurrentPredictionAmount;      ///< the current prediction amount used by the prediction algorithm
 413   unsigned int mMaxPredictionAmount;          ///< the maximum prediction amount used by the prediction algorithm
 414   unsigned int mMinPredictionAmount;          ///< the minimum prediction amount used by the prediction algorithm
 415   unsigned int mPredictionAmountAdjustment;   ///< the prediction amount to adjust in milliseconds when pan velocity changes
 416   SmoothingMode mSmoothingMode;               ///< The pan gesture prediction mode
 417   float         mSmoothingAmount;             ///< How much smoothing to apply [0.0f,1.0f]
 418   PanGestureProfiling* mProfiling;            ///< NULL unless pan-gesture profiling information is required.
 419 };
 420
 421 } // namespace SceneGraph
 422
 423 } // namespace Internal
 424
 425 } // namespace Dali
 426
 427 #endif // __DALI_INTERNAL_SCENE_GRAPH_PAN_GESTURE_H__