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