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) 2023 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 <dali/devel-api/threading/conditional-wait.h>
  23 #include <dali/devel-api/threading/semaphore.h>
  24 #include <dali/integration-api/core.h>
  25 #include <pthread.h>
  26 #include <semaphore.h>
  27 #include <stdint.h>
  28 #include <atomic>
  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 class RenderSurfaceInterface;
  41 class TriggerEventInterface;
  42
  43 namespace Internal
  44 {
  45 namespace Adaptor
  46 {
  47 class AdaptorInternalServices;
  48 class EnvironmentOptions;
  49
  50 /**
  51  * @brief Two threads where events/application interaction is handled on the main/event thread and the Update & Render
  52  * happen on the other thread.
  53  *
  54  * Key Points:
  55  *  1. Two Threads:
  56  *    a. Main/Event Thread.
  57  *    b. Update/Render Thread.
  58  *  2. There is NO VSync thread:
  59  *    a. We retrieve the time before Update.
  60  *    b. Then retrieve the time after Render.
  61  *    c. We calculate the difference between these two times and if:
  62  *      i.  The difference is less than the default frame time, we sleep.
  63  *      ii. If it’s more or the same, we continue.
  64  *  3. On the update/render thread, if we discover that we do not need to do any more updates, we use a trigger-event
  65  *     to inform the main/event thread. This is then processed as soon as the event thread is able to do so where it
  66  *     is easier to make a decision about whether we should stop the update/render thread or not (depending on any
  67  *     update requests etc.).
  68  *  4. The main thread is blocked while the surface is being replaced.
  69  *  5. When we resume from paused, elapsed time is used for the animations, i.e. the could have finished while we were paused.
  70  *     However, FinishedSignal emission will only happen upon resumption.
  71  *  6. Elapsed time is NOT used while if we are waking up from a sleep state or doing an UpdateOnce.
  72  */
  73 class CombinedUpdateRenderController : public ThreadControllerInterface,
  74                                        public ThreadSynchronizationInterface
  75 {
  76 public:
  77   /**
  78    * Constructor
  79    */
  80   CombinedUpdateRenderController(AdaptorInternalServices& adaptorInterfaces, const EnvironmentOptions& environmentOptions, ThreadMode threadMode);
  81
  82   /**
  83    * Non virtual destructor. Not intended as base class.
  84    */
  85   ~CombinedUpdateRenderController();
  86
  87   /**
  88    * @copydoc ThreadControllerInterface::Initialize()
  89    */
  90   void Initialize() override;
  91
  92   /**
  93    * @copydoc ThreadControllerInterface::Start()
  94    */
  95   void Start() override;
  96
  97   /**
  98    * @copydoc ThreadControllerInterface::Pause()
  99    */
 100   void Pause() override;
 101
 102   /**
 103    * @copydoc ThreadControllerInterface::Resume()
 104    */
 105   void Resume() override;
 106
 107   /**
 108    * @copydoc ThreadControllerInterface::Stop()
 109    */
 110   void Stop() override;
 111
 112   /**
 113    * @copydoc ThreadControllerInterface::RequestUpdate()
 114    */
 115   void RequestUpdate() override;
 116
 117   /**
 118    * @copydoc ThreadControllerInterface::RequestUpdateOnce()
 119    */
 120   void RequestUpdateOnce(UpdateMode updateMode) override;
 121
 122   /**
 123    * @copydoc ThreadControllerInterface::ReplaceSurface()
 124    */
 125   void ReplaceSurface(Dali::RenderSurfaceInterface* surface) override;
 126
 127   /**
 128    * @copydoc ThreadControllerInterface::DeleteSurface()
 129    */
 130   void DeleteSurface(Dali::RenderSurfaceInterface* surface) override;
 131
 132   /**
 133    * @copydoc ThreadControllerInterface::ResizeSurface()
 134    */
 135   void ResizeSurface() override;
 136
 137   /**
 138    * @copydoc ThreadControllerInterface::WaitForGraphicsInitialization()
 139    */
 140   void WaitForGraphicsInitialization() override;
 141
 142   /**
 143    * @copydoc ThreadControllerInterface::SetRenderRefreshRate()
 144    */
 145   void SetRenderRefreshRate(unsigned int numberOfFramesPerRender) override;
 146
 147   /**
 148    * @copydoc ThreadControllerInterface::SetPreRenderCallback
 149    */
 150   void SetPreRenderCallback(CallbackBase* callback) override;
 151
 152   /**
 153    * @copydoc ThreadControllerInterface::AddSurface()
 154    */
 155   void AddSurface(Dali::RenderSurfaceInterface* surface) override;
 156
 157   /**
 158    * @copydoc ThreadControllerInterface::GetThreadId()
 159    */
 160   int32_t GetThreadId() const override;
 161
 162 private:
 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    * Called by the Update/Render thread after a surface has been resized.
 270    *
 271    * This will lock the mutex in mEventThreadWaitCondition
 272    */
 273   void SurfaceResized();
 274
 275   /**
 276    * Helper for the thread calling the entry function
 277    * @param[in] This A pointer to the current object
 278    */
 279   static void* InternalUpdateRenderThreadEntryFunc(void* This)
 280   {
 281     (static_cast<CombinedUpdateRenderController*>(This))->UpdateRenderThread();
 282     return NULL;
 283   }
 284
 285   /////////////////////////////////////////////////////////////////////////////////////////////////
 286   // ALL Threads
 287   /////////////////////////////////////////////////////////////////////////////////////////////////
 288
 289   /**
 290    * Called by the update-render & v-sync threads when they up and running.
 291    *
 292    * This will lock the mutex in mEventThreadWaitCondition.
 293    */
 294   void NotifyThreadInitialised();
 295
 296   /**
 297    * Called by the update-render thread when graphics has been initialised.
 298    */
 299   void NotifyGraphicsInitialised();
 300
 301   /**
 302    * Helper to add a performance marker to the performance server (if it's active)
 303    * @param[in]  type  performance marker type
 304    */
 305   void AddPerformanceMarker(PerformanceInterface::MarkerType type);
 306
 307   /////////////////////////////////////////////////////////////////////////////////////////////////
 308   // POST RENDERING - ThreadSynchronizationInterface overrides
 309   /////////////////////////////////////////////////////////////////////////////////////////////////
 310
 311   /////////////////////////////////////////////////////////////////////////////////////////////////
 312   //// Called by the Event Thread if post-rendering is required
 313   /////////////////////////////////////////////////////////////////////////////////////////////////
 314
 315   /**
 316    * @copydoc ThreadSynchronizationInterface::PostRenderComplete()
 317    */
 318   void PostRenderComplete() override;
 319
 320   /////////////////////////////////////////////////////////////////////////////////////////////////
 321   //// Called by the Render Thread if post-rendering is required
 322   /////////////////////////////////////////////////////////////////////////////////////////////////
 323
 324   /**
 325    * @copydoc ThreadSynchronizationInterface::PostRenderStarted()
 326    */
 327   void PostRenderStarted() override;
 328
 329   /**
 330    * @copydoc ThreadSynchronizationInterface::PostRenderStarted()
 331    */
 332   void PostRenderWaitForCompletion() override;
 333
 334 private:
 335   FpsTracker         mFpsTracker;         ///< Object that tracks the FPS
 336   UpdateStatusLogger mUpdateStatusLogger; ///< Object that logs the update-status as required.
 337
 338   Semaphore<>     mEventThreadSemaphore;   ///< Used by the event thread to ensure all threads have been initialised, and when replacing the surface.
 339   ConditionalWait mGraphicsInitializeWait; ///< Used by the render thread to ensure the graphics has been initialised.
 340   Semaphore<>     mSurfaceSemaphore;       ///< Used by the event thread to ensure the surface has been deleted or replaced.
 341
 342   ConditionalWait mUpdateRenderThreadWaitCondition; ///< The wait condition for the update-render-thread.
 343
 344   AdaptorInternalServices&  mAdaptorInterfaces;    ///< The adaptor internal interface
 345   PerformanceInterface*     mPerformanceInterface; ///< The performance logging interface
 346   Integration::Core&        mCore;                 ///< Dali core reference
 347   const EnvironmentOptions& mEnvironmentOptions;   ///< Environment options
 348   TriggerEventInterface&    mNotificationTrigger;  ///< Reference to notification event trigger
 349   TriggerEventInterface*    mSleepTrigger;         ///< Used by the update-render thread to trigger the event thread when it no longer needs to do any updates
 350   CallbackBase*             mPreRenderCallback;    ///< Used by Update/Render thread when PreRender is about to be called on graphics.
 351
 352   pthread_t* mUpdateRenderThread; ///< The Update/Render thread.
 353
 354   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.
 355   // TODO: mDefaultFrameDurationMilliseconds is defined as uint64_t, the only place where it is used, it is converted to an unsigned int!!!
 356   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.
 357   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.
 358   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.
 359
 360   uint32_t mUpdateRequestCount; ///< Count of update-requests we have received to ensure we do not go to sleep too early.
 361   uint32_t mRunning;            ///< Read and set on the event-thread only to state whether we are running.
 362   int32_t  mThreadId;           ///< UpdateRender thread id
 363
 364   ThreadMode mThreadMode; ///< Whether the thread runs continuously or runs when it is requested.
 365
 366   //
 367   // NOTE: cannot use booleans as these are used from multiple threads, must use variable with machine word size for atomic read/write
 368   //
 369
 370   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).
 371   volatile unsigned int mDestroyUpdateRenderThread;  ///< Whether the Update/Render thread be destroyed (set by the event-thread, read by the update-render-thread).
 372   volatile unsigned int mUpdateRenderThreadCanSleep; ///< Whether the Update/Render thread can sleep (set by the event-thread, read by the update-render-thread).
 373   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).
 374                                                      ///< Ensures we do not go to sleep if we have not processed the most recent update-request.
 375
 376   volatile unsigned int mUseElapsedTimeAfterWait; ///< Whether we should use the elapsed time after waiting (set by the event-thread, read by the update-render-thread).
 377
 378   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).
 379   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).
 380
 381   volatile unsigned int mPostRendering;  ///< Whether post-rendering is taking place (set by the event & render threads, read by the render-thread).
 382   volatile unsigned int mSurfaceResized; ///< Will be set to resize the surface (set by the event-thread, read & cleared by the update-render thread).
 383   volatile unsigned int mForceClear;     ///< Will be set to clear forcibly
 384
 385   volatile unsigned int mUploadWithoutRendering; ///< Will be set to upload the resource only (with no rendering)
 386
 387   volatile unsigned int mFirstFrameAfterResume; ///< Will be set to check the first frame after resume (for log)
 388
 389   std::vector<Rect<int>> mDamagedRects; ///< Keeps collected damaged render items rects for one render pass
 390 };
 391
 392 } // namespace Adaptor
 393
 394 } // namespace Internal
 395
 396 } // namespace Dali
 397
 398 #endif // DALI_INTERNAL_COMBINED_UPDATE_RENDER_CONTROLLER_H