dali/internal/adaptor/common/combined-update-render-controller.h

   1 #ifndef DALI_INTERNAL_COMBINED_UPDATE_RENDER_CONTROLLER_H
   2 #define DALI_INTERNAL_COMBINED_UPDATE_RENDER_CONTROLLER_H
   3
   4 /*
   5  * Copyright (c) 2020 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 // EXTERNAL INCLUDES
  22 #include <pthread.h>
  23 #include <semaphore.h>
  24 #include <atomic>
  25 #include <stdint.h>
  26 #include <dali/devel-api/threading/conditional-wait.h>
  27 #include <dali/devel-api/threading/semaphore.h>
  28 #include <dali/integration-api/core.h>
  29
  30 // INTERNAL INCLUDES
  31 #include <dali/integration-api/adaptor-framework/thread-synchronization-interface.h>
  32 #include <dali/internal/adaptor/common/thread-controller-interface.h>
  33 #include <dali/internal/system/common/fps-tracker.h>
  34 #include <dali/internal/system/common/performance-interface.h>
  35 #include <dali/internal/system/common/update-status-logger.h>
  36 #include <dali/internal/window-system/common/display-connection.h>
  37
  38 namespace Dali
  39 {
  40
  41 class RenderSurfaceInterface;
  42 class TriggerEventInterface;
  43
  44 namespace Internal
  45 {
  46
  47 namespace Adaptor
  48 {
  49
  50 class AdaptorInternalServices;
  51 class EnvironmentOptions;
  52
  53 /**
  54  * @brief Two threads where events/application interaction is handled on the main/event thread and the Update & Render
  55  * happen on the other thread.
  56  *
  57  * Key Points:
  58  *  1. Two Threads:
  59  *    a. Main/Event Thread.
  60  *    b. Update/Render Thread.
  61  *  2. There is NO VSync thread:
  62  *    a. We retrieve the time before Update.
  63  *    b. Then retrieve the time after Render.
  64  *    c. We calculate the difference between these two times and if:
  65  *      i.  The difference is less than the default frame time, we sleep.
  66  *      ii. If it’s more or the same, we continue.
  67  *  3. On the update/render thread, if we discover that we do not need to do any more updates, we use a trigger-event
  68  *     to inform the main/event thread. This is then processed as soon as the event thread is able to do so where it
  69  *     is easier to make a decision about whether we should stop the update/render thread or not (depending on any
  70  *     update requests etc.).
  71  *  4. The main thread is blocked while the surface is being replaced.
  72  *  5. When we resume from paused, elapsed time is used for the animations, i.e. the could have finished while we were paused.
  73  *     However, FinishedSignal emission will only happen upon resumption.
  74  *  6. Elapsed time is NOT used while if we are waking up from a sleep state or doing an UpdateOnce.
  75  */
  76 class CombinedUpdateRenderController : public ThreadControllerInterface,
  77                                        public ThreadSynchronizationInterface
  78 {
  79 public:
  80
  81   /**
  82    * Constructor
  83    */
  84   CombinedUpdateRenderController( AdaptorInternalServices& adaptorInterfaces, const EnvironmentOptions& environmentOptions, ThreadMode threadMode );
  85
  86   /**
  87    * Non virtual destructor. Not intended as base class.
  88    */
  89   ~CombinedUpdateRenderController();
  90
  91   /**
  92    * @copydoc ThreadControllerInterface::Initialize()
  93    */
  94   void Initialize() override;
  95
  96   /**
  97    * @copydoc ThreadControllerInterface::Start()
  98    */
  99   void Start() override;
 100
 101   /**
 102    * @copydoc ThreadControllerInterface::Pause()
 103    */
 104   void Pause() override;
 105
 106   /**
 107    * @copydoc ThreadControllerInterface::Resume()
 108    */
 109   void Resume() override;
 110
 111   /**
 112    * @copydoc ThreadControllerInterface::Stop()
 113    */
 114   void Stop() override;
 115
 116   /**
 117    * @copydoc ThreadControllerInterface::RequestUpdate()
 118    */
 119   void RequestUpdate() override;
 120
 121   /**
 122    * @copydoc ThreadControllerInterface::RequestUpdateOnce()
 123    */
 124   void RequestUpdateOnce( UpdateMode updateMode ) override;
 125
 126   /**
 127    * @copydoc ThreadControllerInterface::ReplaceSurface()
 128    */
 129   void ReplaceSurface( Dali::RenderSurfaceInterface* surface ) override;
 130
 131   /**
 132    * @copydoc ThreadControllerInterface::DeleteSurface()
 133    */
 134   void DeleteSurface( Dali::RenderSurfaceInterface* surface ) override;
 135
 136   /**
 137    * @copydoc ThreadControllerInterface::ResizeSurface()
 138    */
 139   void ResizeSurface() override;
 140
 141   /**
 142    * @copydoc ThreadControllerInterface::WaitForGraphicsInitialization()
 143    */
 144   void WaitForGraphicsInitialization() override;
 145
 146   /**
 147    * @copydoc ThreadControllerInterface::SetRenderRefreshRate()
 148    */
 149   void SetRenderRefreshRate( unsigned int numberOfFramesPerRender ) override;
 150
 151   /**
 152    * @copydoc ThreadControllerInterface::SetPreRenderCallback
 153    */
 154   void SetPreRenderCallback( CallbackBase* callback ) override;
 155
 156   /**
 157    * @copydoc ThreadControllerInterface::AddSurface()
 158    */
 159   void AddSurface( Dali::RenderSurfaceInterface* surface ) override;
 160
 161 private:
 162
 163   // Undefined copy constructor.
 164   CombinedUpdateRenderController( const CombinedUpdateRenderController& );
 165
 166   // Undefined assignment operator.
 167   CombinedUpdateRenderController& operator=( const CombinedUpdateRenderController& );
 168
 169   /////////////////////////////////////////////////////////////////////////////////////////////////
 170   // EventThread
 171   /////////////////////////////////////////////////////////////////////////////////////////////////
 172
 173   enum AnimationProgression
 174   {
 175     USE_ELAPSED_TIME,          ///< Animation progression using elapsed time
 176     NONE                       ///< No animation progression
 177   };
 178
 179   /**
 180    * Runs the Update/Render Thread.
 181    * This will lock the mutex in mUpdateRenderThreadWaitCondition.
 182    *
 183    * @param[in]  numberOfCycles           The number of times the update/render cycle should run. If -1, then it will run continuously.
 184    * @param[in]  animationProgression     Whether to progress animation using time elapsed since the last frame.
 185    * @param[in]  updateMode               The update mode (i.e. either update & render or skip rendering)
 186    */
 187   inline void RunUpdateRenderThread( int numberOfCycles, AnimationProgression animationProgression, UpdateMode updateMode );
 188
 189   /**
 190    * Pauses the Update/Render Thread.
 191    * This will lock the mutex in mUpdateRenderThreadWaitCondition.
 192    */
 193   inline void PauseUpdateRenderThread();
 194
 195   /**
 196    * Stops the Update/Render Thread.
 197    * This will lock the mutex in mUpdateRenderThreadWaitCondition.
 198    *
 199    * @note Should only be called in Stop as calling this will kill the update-thread.
 200    */
 201   inline void StopUpdateRenderThread();
 202
 203   /**
 204    * Checks if the the Update/Render Thread is paused.
 205    * This will lock the mutex in mUpdateRenderThreadWaitCondition.
 206    *
 207    * @return true if paused, false otherwise
 208    */
 209   inline bool IsUpdateRenderThreadPaused();
 210
 211   /**
 212    * Used as the callback for the sleep-trigger.
 213    *
 214    * Will sleep when enough requests are made without any requests.
 215    */
 216   void ProcessSleepRequest();
 217
 218   /////////////////////////////////////////////////////////////////////////////////////////////////
 219   // UpdateRenderThread
 220   /////////////////////////////////////////////////////////////////////////////////////////////////
 221
 222   /**
 223    * The Update/Render thread loop. This thread will be destroyed on exit from this function.
 224    */
 225   void UpdateRenderThread();
 226
 227   /**
 228    * Called by the Update/Render Thread which ensures a wait if required.
 229    *
 230    * @param[out] useElapsedTime    If true when returned, then the actual elapsed time will be used for animation.
 231    *                               If false when returned, then there should NOT be any animation progression in the next Update.
 232    * @param[in]  updateRequired    Whether another update is required.
 233    * @param[out] timeToSleepUntil  The time remaining in nanoseconds to keep the thread sleeping before resuming.
 234    * @return false, if the thread should stop.
 235    */
 236   bool UpdateRenderReady( bool& useElapsedTime, bool updateRequired, uint64_t& timeToSleepUntil );
 237
 238   /**
 239    * Checks to see if the surface needs to be replaced.
 240    * This will lock the mutex in mUpdateRenderThreadWaitCondition.
 241    *
 242    * @return Pointer to the new surface, NULL otherwise
 243    */
 244   Dali::RenderSurfaceInterface* ShouldSurfaceBeReplaced();
 245
 246   /**
 247    * Called by the Update/Render thread after a surface has been replaced.
 248    *
 249    * This will lock the mutex in mEventThreadWaitCondition
 250    */
 251   void SurfaceReplaced();
 252
 253   /**
 254    * Checks to see if the surface needs to be deleted.
 255    * This will lock the mutex in mUpdateRenderThreadWaitCondition.
 256    *
 257    * @return Pointer to the deleted surface, nullptr otherwise
 258    */
 259   Dali::RenderSurfaceInterface* ShouldSurfaceBeDeleted();
 260
 261   /**
 262    * Called by the Update/Render thread after a surface has been deleted.
 263    *
 264    * This will lock the mutex in mEventThreadWaitCondition
 265    */
 266   void SurfaceDeleted();
 267
 268   /**
 269    * Checks to see if the surface needs to be resized.
 270    * This will lock the mutex in mUpdateRenderThreadWaitCondition.
 271    *
 272    * @return true if the surface should be resized, false otherwise
 273    */
 274   bool ShouldSurfaceBeResized();
 275
 276   /**
 277    * Called by the Update/Render thread after a surface has been resized.
 278    *
 279    * This will lock the mutex in mEventThreadWaitCondition
 280    */
 281   void SurfaceResized();
 282
 283   /**
 284    * Helper for the thread calling the entry function
 285    * @param[in] This A pointer to the current object
 286    */
 287   static void* InternalUpdateRenderThreadEntryFunc( void* This )
 288   {
 289     ( static_cast<CombinedUpdateRenderController*>( This ) )->UpdateRenderThread();
 290     return NULL;
 291   }
 292
 293   /////////////////////////////////////////////////////////////////////////////////////////////////
 294   // ALL Threads
 295   /////////////////////////////////////////////////////////////////////////////////////////////////
 296
 297   /**
 298    * Called by the update-render & v-sync threads when they up and running.
 299    *
 300    * This will lock the mutex in mEventThreadWaitCondition.
 301    */
 302   void NotifyThreadInitialised();
 303
 304   /**
 305    * Called by the update-render thread when graphics has been initialised.
 306    */
 307   void NotifyGraphicsInitialised();
 308
 309   /**
 310    * Helper to add a performance marker to the performance server (if it's active)
 311    * @param[in]  type  performance marker type
 312    */
 313   void AddPerformanceMarker( PerformanceInterface::MarkerType type );
 314
 315   /////////////////////////////////////////////////////////////////////////////////////////////////
 316   // POST RENDERING - ThreadSynchronizationInterface overrides
 317   /////////////////////////////////////////////////////////////////////////////////////////////////
 318
 319   /////////////////////////////////////////////////////////////////////////////////////////////////
 320   //// Called by the Event Thread if post-rendering is required
 321   /////////////////////////////////////////////////////////////////////////////////////////////////
 322
 323   /**
 324    * @copydoc ThreadSynchronizationInterface::PostRenderComplete()
 325    */
 326   void PostRenderComplete() override;
 327
 328   /////////////////////////////////////////////////////////////////////////////////////////////////
 329   //// Called by the Render Thread if post-rendering is required
 330   /////////////////////////////////////////////////////////////////////////////////////////////////
 331
 332   /**
 333    * @copydoc ThreadSynchronizationInterface::PostRenderStarted()
 334    */
 335   void PostRenderStarted() override;
 336
 337   /**
 338    * @copydoc ThreadSynchronizationInterface::PostRenderStarted()
 339    */
 340   void PostRenderWaitForCompletion() override;
 341
 342 private:
 343
 344   FpsTracker                        mFpsTracker;                       ///< Object that tracks the FPS
 345   UpdateStatusLogger                mUpdateStatusLogger;               ///< Object that logs the update-status as required.
 346
 347   Semaphore<>                       mEventThreadSemaphore;             ///< Used by the event thread to ensure all threads have been initialised, and when replacing the surface.
 348   ConditionalWait                   mGraphicsInitializeWait;           ///< Used by the render thread to ensure the graphics has been initialised.
 349   Semaphore<>                       mSurfaceSemaphore;                 ///< Used by the event thread to ensure the surface has been deleted or replaced.
 350
 351   ConditionalWait                   mUpdateRenderThreadWaitCondition;  ///< The wait condition for the update-render-thread.
 352
 353   AdaptorInternalServices&          mAdaptorInterfaces;                ///< The adaptor internal interface
 354   PerformanceInterface*             mPerformanceInterface;             ///< The performance logging interface
 355   Integration::Core&                mCore;                             ///< Dali core reference
 356   const EnvironmentOptions&         mEnvironmentOptions;               ///< Environment options
 357   TriggerEventInterface&            mNotificationTrigger;              ///< Reference to notification event trigger
 358   TriggerEventInterface*            mSleepTrigger;                     ///< Used by the update-render thread to trigger the event thread when it no longer needs to do any updates
 359   CallbackBase*                     mPreRenderCallback;                ///< Used by Update/Render thread when PreRender is about to be called on graphics.
 360
 361   pthread_t*                        mUpdateRenderThread;               ///< The Update/Render thread.
 362
 363   float                             mDefaultFrameDelta;                ///< Default time delta between each frame (used for animations). Not protected by lock, but written to rarely so not worth adding a lock when reading.
 364   // TODO: mDefaultFrameDurationMilliseconds is defined as uint64_t, the only place where it is used, it is converted to an unsigned int!!!
 365   uint64_t                          mDefaultFrameDurationMilliseconds; ///< Default duration of a frame (used for predicting the time of the next frame). Not protected by lock, but written to rarely so not worth adding a lock when reading.
 366   uint64_t                          mDefaultFrameDurationNanoseconds;  ///< Default duration of a frame (used for sleeping if not enough time elapsed). Not protected by lock, but written to rarely so not worth adding a lock when reading.
 367   uint64_t                          mDefaultHalfFrameNanoseconds;      ///< Is half of mDefaultFrameDurationNanoseconds. Using a member variable avoids having to do the calculation every frame. Not protected by lock, but written to rarely so not worth adding a lock when reading.
 368
 369   unsigned int                      mUpdateRequestCount;               ///< Count of update-requests we have received to ensure we do not go to sleep too early.
 370   unsigned int                      mRunning;                          ///< Read and set on the event-thread only to state whether we are running.
 371
 372   ThreadMode                        mThreadMode;                       ///< Whether the thread runs continuously or runs when it is requested.
 373
 374   //
 375   // NOTE: cannot use booleans as these are used from multiple threads, must use variable with machine word size for atomic read/write
 376   //
 377
 378   volatile int                      mUpdateRenderRunCount;             ///< The number of times Update/Render cycle should run. If -1, then will run continuously (set by the event-thread, read by v-sync-thread).
 379   volatile unsigned int             mDestroyUpdateRenderThread;        ///< Whether the Update/Render thread be destroyed (set by the event-thread, read by the update-render-thread).
 380   volatile unsigned int             mUpdateRenderThreadCanSleep;       ///< Whether the Update/Render thread can sleep (set by the event-thread, read by the update-render-thread).
 381   volatile unsigned int             mPendingRequestUpdate;             ///< Is set as soon as an RequestUpdate is made and unset when the next update happens (set by the event-thread and update-render thread, read by the update-render-thread).
 382                                                                        ///< Ensures we do not go to sleep if we have not processed the most recent update-request.
 383
 384   volatile unsigned int             mUseElapsedTimeAfterWait;          ///< Whether we should use the elapsed time after waiting (set by the event-thread, read by the update-render-thread).
 385
 386   Dali::RenderSurfaceInterface* volatile mNewSurface;                  ///< Will be set to the new-surface if requested (set by the event-thread, read & cleared by the update-render thread).
 387   Dali::RenderSurfaceInterface* volatile mDeletedSurface;              ///< Will be set to the deleted surface if requested (set by the event-thread, read & cleared by the update-render thread).
 388
 389   volatile unsigned int             mPostRendering;                    ///< Whether post-rendering is taking place (set by the event & render threads, read by the render-thread).
 390   volatile unsigned int             mSurfaceResized;                   ///< Will be set to resize the surface (set by the event-thread, read & cleared by the update-render thread).
 391   volatile unsigned int             mForceClear;                       ///< Will be set to clear forcibly
 392
 393   volatile unsigned int             mUploadWithoutRendering;           ///< Will be set to upload the resource only (with no rendering)
 394
 395   volatile unsigned int             mFirstFrameAfterResume;            ///< Will be set to check the first frame after resume (for log)
 396
 397   std::vector<Rect<int>>            mDamagedRects;                     ///< Keeps collected damaged render items rects for one render pass
 398 };
 399
 400 } // namespace Adaptor
 401
 402 } // namespace Internal
 403
 404 } // namespace Dali
 405
 406 #endif // DALI_INTERNAL_COMBINED_UPDATE_RENDER_CONTROLLER_H