adaptors/base/combined-update-render/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) 2015 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 <semaphore.h>
  23 #include <stdint.h>
  24 #include <dali/integration-api/core.h>
  25 #include <dali/devel-api/threading/conditional-wait.h>
  26
  27 // INTERNAL INCLUDES
  28 #include <integration-api/thread-synchronization-interface.h>
  29 #include <base/interfaces/performance-interface.h>
  30 #include <base/fps-tracker.h>
  31 #include <base/render-helper.h>
  32 #include <base/thread-controller-interface.h>
  33 #include <base/update-status-logger.h>
  34
  35 namespace Dali
  36 {
  37
  38 class RenderSurface;
  39 class TriggerEventInterface;
  40
  41 namespace Internal
  42 {
  43
  44 namespace Adaptor
  45 {
  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   /**
  79    * Constructor
  80    */
  81   CombinedUpdateRenderController( AdaptorInternalServices& adaptorInterfaces, const EnvironmentOptions& environmentOptions );
  82
  83   /**
  84    * Non virtual destructor. Not intended as base class.
  85    */
  86   ~CombinedUpdateRenderController();
  87
  88   /**
  89    * @copydoc ThreadControllerInterface::Initialize()
  90    */
  91   virtual void Initialize();
  92
  93   /**
  94    * @copydoc ThreadControllerInterface::Start()
  95    */
  96   virtual void Start();
  97
  98   /**
  99    * @copydoc ThreadControllerInterface::Pause()
 100    */
 101   virtual void Pause();
 102
 103   /**
 104    * @copydoc ThreadControllerInterface::Resume()
 105    */
 106   virtual void Resume();
 107
 108   /**
 109    * @copydoc ThreadControllerInterface::Stop()
 110    */
 111   virtual void Stop();
 112
 113   /**
 114    * @copydoc ThreadControllerInterface::RequestUpdate()
 115    */
 116   virtual void RequestUpdate();
 117
 118   /**
 119    * @copydoc ThreadControllerInterface::RequestUpdateOnce()
 120    */
 121   virtual void RequestUpdateOnce();
 122
 123   /**
 124    * @copydoc ThreadControllerInterface::ReplaceSurface()
 125    */
 126   virtual void ReplaceSurface( RenderSurface* surface );
 127
 128   /**
 129    * @copydoc ThreadControllerInterface::SetRenderRefreshRate()
 130    */
 131   virtual void SetRenderRefreshRate( unsigned int numberOfFramesPerRender );
 132
 133 private:
 134
 135   // Undefined copy constructor.
 136   CombinedUpdateRenderController( const CombinedUpdateRenderController& );
 137
 138   // Undefined assignment operator.
 139   CombinedUpdateRenderController& operator=( const CombinedUpdateRenderController& );
 140
 141   /////////////////////////////////////////////////////////////////////////////////////////////////
 142   // EventThread
 143   /////////////////////////////////////////////////////////////////////////////////////////////////
 144
 145   /**
 146    * Runs the Update/Render Thread.
 147    * This will lock the mutex in mUpdateRenderThreadWaitCondition.
 148    *
 149    * @param[in]  numberOfCycles           The number of times the update/render cycle should run. If -1, then it will run continuously.
 150    * @param[in]  useElapsedTimeAfterWait  If true, then the elapsed time during wait is used for animations, otherwise no animation progression is made.
 151    */
 152   inline void RunUpdateRenderThread( int numberOfCycles, bool useElapsedTimeAfterWait );
 153
 154   /**
 155    * Pauses the Update/Render Thread.
 156    * This will lock the mutex in mUpdateRenderThreadWaitCondition.
 157    */
 158   inline void PauseUpdateRenderThread();
 159
 160   /**
 161    * Stops the Update/Render Thread.
 162    * This will lock the mutex in mUpdateRenderThreadWaitCondition.
 163    *
 164    * @note Should only be called in Stop as calling this will kill the update-thread.
 165    */
 166   inline void StopUpdateRenderThread();
 167
 168   /**
 169    * Checks if the the Update/Render Thread is paused.
 170    * This will lock the mutex in mUpdateRenderThreadWaitCondition.
 171    *
 172    * @return true if paused, false otherwise
 173    */
 174   inline bool IsUpdateRenderThreadPaused();
 175
 176   /**
 177    * Used as the callback for the sleep-trigger.
 178    *
 179    * Will sleep when enough requests are made without any requests.
 180    */
 181   void ProcessSleepRequest();
 182
 183   /////////////////////////////////////////////////////////////////////////////////////////////////
 184   // UpdateRenderThread
 185   /////////////////////////////////////////////////////////////////////////////////////////////////
 186
 187   /**
 188    * The Update/Render thread loop. This thread will be destroyed on exit from this function.
 189    */
 190   void UpdateRenderThread();
 191
 192   /**
 193    * Called by the Update/Render Thread which ensures a wait if required.
 194    *
 195    * @param[out] useElapsedTime    If true when returned, then the actual elapsed time will be used for animation.
 196    *                               If false when returned, then there should NOT be any animation progression in the next Update.
 197    * @param[in]  updateRequired    Whether another update is required.
 198    * @param[out] timeToSleepUntil  The time in nanoseconds to put the thread to sleep until.
 199    * @return false, if the thread should stop.
 200    */
 201   bool UpdateRenderReady( bool& useElapsedTime, bool updateRequired, uint64_t& timeToSleepUntil );
 202
 203   /**
 204    * Checks to see if the surface needs to be replaced.
 205    * This will lock the mutex in mUpdateRenderThreadWaitCondition.
 206    *
 207    * @return Pointer to the new surface, NULL otherwise
 208    */
 209   RenderSurface* ShouldSurfaceBeReplaced();
 210
 211   /**
 212    * Called by the Update/Render thread after a surface has been replaced.
 213    *
 214    * This will lock the mutex in mEventThreadWaitCondition
 215    */
 216   void SurfaceReplaced();
 217
 218   /**
 219    * Helper for the thread calling the entry function
 220    * @param[in] This A pointer to the current object
 221    */
 222   static void* InternalUpdateRenderThreadEntryFunc( void* This )
 223   {
 224     ( static_cast<CombinedUpdateRenderController*>( This ) )->UpdateRenderThread();
 225     return NULL;
 226   }
 227
 228   /////////////////////////////////////////////////////////////////////////////////////////////////
 229   // ALL Threads
 230   /////////////////////////////////////////////////////////////////////////////////////////////////
 231
 232   /**
 233    * Called by the update-render & v-sync threads when they up and running.
 234    *
 235    * This will lock the mutex in mEventThreadWaitCondition.
 236    */
 237   void NotifyThreadInitialised();
 238
 239   /**
 240    * Helper to add a performance marker to the performance server (if it's active)
 241    * @param[in]  type  performance marker type
 242    */
 243   void AddPerformanceMarker( PerformanceInterface::MarkerType type );
 244
 245   /////////////////////////////////////////////////////////////////////////////////////////////////
 246   // POST RENDERING - ThreadSynchronizationInterface overrides
 247   /////////////////////////////////////////////////////////////////////////////////////////////////
 248
 249   /////////////////////////////////////////////////////////////////////////////////////////////////
 250   //// Called by the Event Thread if post-rendering is required
 251   /////////////////////////////////////////////////////////////////////////////////////////////////
 252
 253   /**
 254    * @copydoc ThreadSynchronizationInterface::PostRenderComplete()
 255    */
 256   virtual void PostRenderComplete();
 257
 258   /////////////////////////////////////////////////////////////////////////////////////////////////
 259   //// Called by the Render Thread if post-rendering is required
 260   /////////////////////////////////////////////////////////////////////////////////////////////////
 261
 262   /**
 263    * @copydoc ThreadSynchronizationInterface::PostRenderStarted()
 264    */
 265   virtual void PostRenderStarted();
 266
 267   /**
 268    * @copydoc ThreadSynchronizationInterface::PostRenderStarted()
 269    */
 270   virtual void PostRenderWaitForCompletion();
 271
 272 private:
 273
 274   FpsTracker                        mFpsTracker;                       ///< Object that tracks the FPS
 275   UpdateStatusLogger                mUpdateStatusLogger;               ///< Object that logs the update-status as required.
 276
 277   RenderHelper                      mRenderHelper;                     ///< Helper class for EGL, pre & post rendering
 278
 279   sem_t                             mEventThreadSemaphore;             ///< Used by the event thread to ensure all threads have been initialised, and when replacing the surface.
 280
 281   ConditionalWait                   mUpdateRenderThreadWaitCondition;  ///< The wait condition for the update-render-thread.
 282
 283   AdaptorInternalServices&          mAdaptorInterfaces;                ///< The adaptor internal interface
 284   PerformanceInterface*             mPerformanceInterface;             ///< The performance logging interface
 285   Integration::Core&                mCore;                             ///< Dali core reference
 286   const EnvironmentOptions&         mEnvironmentOptions;               ///< Environment options
 287   TriggerEventInterface&            mNotificationTrigger;              ///< Reference to notification event trigger
 288   TriggerEventInterface*            mSleepTrigger;                     ///< Used by the update-render thread to trigger the event thread when it no longer needs to do any updates
 289
 290   pthread_t*                        mUpdateRenderThread;               ///< The Update/Render thread.
 291
 292   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.
 293   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.
 294   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.
 295   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.
 296
 297   unsigned int                      mUpdateRequestCount;               ///< Count of update-requests we have received to ensure we do not go to sleep too early.
 298   unsigned int                      mRunning;                          ///< Read and set on the event-thread only to state whether we are running.
 299
 300   //
 301   // NOTE: cannot use booleans as these are used from multiple threads, must use variable with machine word size for atomic read/write
 302   //
 303
 304   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).
 305   volatile unsigned int             mDestroyUpdateRenderThread;        ///< Whether the Update/Render thread be destroyed (set by the event-thread, read by the update-render-thread).
 306   volatile unsigned int             mUpdateRenderThreadCanSleep;       ///< Whether the Update/Render thread can sleep (set by the event-thread, read by the update-render-thread).
 307   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).
 308                                                                        ///< Ensures we do not go to sleep if we have not processed the most recent update-request.
 309
 310   volatile unsigned int             mUseElapsedTimeAfterWait;          ///< Whether we should use the elapsed time after waiting (set by the event-thread, read by the update-render-thread).
 311
 312   RenderSurface* volatile           mNewSurface;                       ///< Will be set to the new-surface if requested (set by the event-thread, read & cleared by the update-render thread).
 313
 314   volatile unsigned int             mPostRendering;                    ///< Whether post-rendering is taking place (set by the event & render threads, read by the render-thread).
 315 };
 316
 317 } // namespace Adaptor
 318
 319 } // namespace Internal
 320
 321 } // namespace Dali
 322
 323 #endif // __DALI_INTERNAL_COMBINED_UPDATE_RENDER_CONTROLLER_H__