docs/content/shared-javascript-and-cpp-documentation/animation.md

   1 <!--
   2 /**-->
   3
   4 # Animation {#animation}
   5
   6 DALi provides a rich and easy to use animation framework which allows the creation of visually rich applications.
   7 Dali::Animation can be used to animate the properties of any number of objects, typically Actors.
   8
   9 ## Creating a basic Animation {#animation-basics}
  10
  11 Create an animation object that will take place over 3 seconds:
  12 ~~~{.cpp}
  13 Dali::Animation animation = Animation::New( 3.0f );
  14 ~~~
  15
  16 ### Animating Properties
  17
  18 There are two distint ways in which properties can be animated within DALi:
  19 - **AnimateTo:** The property will animate **TO** the value in the given time.
  20 - **AnimateBy:** The property will animate **BY** the value in the given time.
  21
  22 (Assume actor1 & actor2 are at position 10.0f, 10.0f, 0.0f at the start of the animation)
  23 ~~~{.cpp}
  24 // Animate the position of actor1 TO 10.0f, 50.0f, 0.0f
  25 animation.AnimateTo( Property( actor1, Dali::Actor::Property::POSITION ), Vector3(10.0f, 50.0f, 0.0f) ); // End Position: 10.0f, 50.0f, 0.0f
  26
  27 // Animate the position of actor2 BY 10.0f, 50.0f, 0.0f
  28 animation.AnimateBy( Property( actor2, Dali::Actor::Property::POSITION ), Vector3(10.0f, 50.0f, 0.0f) ); // End Position: 20.0f, 60.0f, 0.0f
  29 ~~~
  30
  31 ### Playback Control
  32
  33 When an animation is created, it can be played:
  34 ~~~{.cpp}
  35 animation.Play();
  36 ~~~
  37
  38 Stop and Pause are also supported.
  39 ~~~{.cpp}
  40 animation.Stop();
  41 animation.Pause();
  42 ~~~
  43
  44 ### Notifications
  45
  46 Using DALi's signal framework, applications can be notified when the animation finishes:
  47
  48 ~~~{.cpp}
  49
  50 void ExampleCallback( Animation& source )
  51 {
  52   std::cout << "Animation has finished" << std::endl;
  53 }
  54 ...
  55 animation.FinishedSignal().Connect( ExampleCallback );
  56 ~~~
  57
  58 ### Alpha Functions
  59
  60 Alpha functions are used in animations to specify the rate of change of the animation parameter over time.
  61 The built in supported functions can be viewed in Dali::AlphaFunction::BuiltinFunction.
  62
  63 It is possible to specify a different alpha function for each animator in an Animation object:
  64 ~~~{.cpp}
  65 animation.AnimateTo( Property( actor1, Dali::Actor::Property::POSITION ), Vector3(10.0f, 50.0f, 0.0f), Dali::AlphaFunction::EASE_IN );
  66 ~~~
  67
  68 ### Other Actions
  69
  70 An animation can be looped:
  71 ~~~{.cpp}
  72 animation.SetLooping( true );
  73 ~~~
  74
  75 By default, when an animation ends, the properties that it was animating are BAKED.
  76 However, the property changes can be **discarded** when the animation ends (or is stopped):
  77 ~~~{.cpp}
  78 animation.SetEndAction( Animation::Discard );
  79 ~~~
  80
  81 ## Key-Frame Animation {#animation-key-frame}
  82
  83 TODO