docs/content/programming-guide/animation-multi-threading-notes.h

   1 /*! \page animation-multi-threading-notes Animation: Multi-threading Notes
   2  *
   3
   4 <h2 class="pg">Multi-threaded Architecture</h2>
   5
   6 Dali animations and rendering occur in a dedicated rendering thread.  This allows animations to run smoothly, regardless of the time taken to process inputs events etc. in application code.
   7
   8 Internally Dali contains a scene-graph, which mirrors the Actor hierachy.  The scene-graph objects perform the actual animation & rendering, whilst Actors provide thread-safe access.
   9
  10 An example actor hierachy is shown below, in which one of the actors is being animated.  The objects in green are created by the application code, whilst the private objects in blue are used in the dedicated rendering thread.
  11
  12 \image html multi-threaded-animation.png
  13
  14 <h2 class="pg">Reading an animated value</h2>
  15
  16 When a property is animatable, it can only be modified in the rendering thread.  The value returned from a getter method, is the value used when the previous frame was rendered.
  17
  18 For example \ref Dali::Actor::GetCurrentPosition "Dali::Actor::GetCurrentPosition" returns the position at which the Actor was last rendered.  Since \ref Dali::Actor::SetPosition "Dali::Actor::SetPosition" is asynchronous, a call to \ref Dali::Actor::GetCurrentPosition "Dali::Actor::GetCurrentPosition" won't immediately return the same value.
  19
  20 @code
  21 // Whilst handling an event...
  22
  23 Actor actor = Actor::New();
  24 Stage::GetCurrent().Add(actor); // initial position is 0,0,0
  25
  26 actor.SetPosition(Vector3(10,10,10));
  27
  28 Vector3 current;
  29 current = actor.GetCurrentPosition();
  30 std::cout << "Current position: " << current.x << ", " << current.y << ", " << current.z << std::endl;
  31
  32 std::cout << "..." << std::endl;
  33
  34 // Whilst handling another event...
  35
  36 current = actor.GetCurrentPosition();
  37 std::cout << "Current position: " << current.x << ", " << current.y << ", " << current.z << std::endl;
  38
  39 @endcode
  40
  41 The example code above would likely output:
  42
  43 @code
  44 "Current position: 0,0,0"
  45 "..."
  46 "Current position: 10,10,10"
  47 @endcode
  48
  49 <h2 class="pg">Setting a property during an animation</h2>
  50
  51 When a property is being animated, the Animation will override any values set e.g. with Actor::SetPosition()
  52
  53 \image html multi-threaded-animation-2.png
  54
  55 The order of execution in the render thread is:
  56
  57 @code
  58 1) Process message => SetPosition
  59 2) Apply animation => SetPosition
  60 3) Render frame
  61 @endcode
  62
  63 *
  64 */