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 Note, for rotations, AnimateTo uses spherical linear interpolation to animate to the new orientation (i.e. it will take the shortest path). Because of this, the number of complete revolutions in any given angle will be reduced to 0. For example,
  32
  33 (Assume actor1 is at orientation 0 degrees about Z-Axis at the start of the animation)
  34 ~~~{.cpp}
  35 // Animate the orientation of actor1 to 390 degrees about the Z-AXIS
  36 animation.AnimateTo( Property( actor1, Dali::Actor::Property::ORIENTATION ), AngleAxis( Degree( 390 ), Vector3::ZAXIS ) );
  37 ~~~
  38
  39 will only rotate 30 degrees about the Z axis, as that is the shortest path to the final orientation.
  40
  41 AnimateBy will preserve the full revolution count of any angle passed in using AngleAxis, for example, AngleAxis( Degree( 770 ), Vector3::ZAXIS ) will revolve 2 full times before reaching the final angle of 50 degrees from the original orientation.
  42
  43 However, because Quaternions do not preserve the revolution count, AnimateBy will only rotate 50 degrees if the relative value is constructed using a Quaternion. For example,
  44
  45 (Assume actor1 and actor 2 are at orientation 0 degrees about Z-Axis at the start of the animation)
  46 ~~~{.cpp}
  47 // Animate the orientation of actor1 3.5 times about the Z-AXIS
  48 animation.AnimateBy( Property( actor1, Dali::Actor::Property::ORIENTATION ), AngleAxis( Degree( 360 * 3.5 ), Vector3::ZAXIS ) );
  49
  50 // But the same degree value will only rotate 180 degrees if a Quaternion is used instead:
  51 animation.AnimateBy( Property( actor2, Dali::Actor::Property::ORIENTATION ), Quaternion( Degree( 360 * 3.5 ), Vector3::ZAXIS ) );
  52 ~~~
  53
  54 ### Playback Control
  55
  56 When an animation is created, it can be played:
  57 ~~~{.cpp}
  58 animation.Play();
  59 ~~~
  60
  61 Stop and Pause are also supported.
  62 ~~~{.cpp}
  63 animation.Stop();
  64 animation.Pause();
  65 ~~~
  66
  67 ### Notifications
  68
  69 Using DALi's signal framework, applications can be notified when the animation finishes:
  70
  71 ~~~{.cpp}
  72
  73 void ExampleCallback( Animation& source )
  74 {
  75   std::cout << "Animation has finished" << std::endl;
  76 }
  77 ...
  78 animation.FinishedSignal().Connect( ExampleCallback );
  79 ~~~
  80
  81 ### Alpha Functions
  82
  83 Alpha functions are used in animations to specify the rate of change of the animation parameter over time.
  84 The built in supported functions can be viewed in Dali::AlphaFunction::BuiltinFunction.
  85
  86 It is possible to specify a different alpha function for each animator in an Animation object:
  87 ~~~{.cpp}
  88 animation.AnimateTo( Property( actor1, Dali::Actor::Property::POSITION ), Vector3(10.0f, 50.0f, 0.0f), Dali::AlphaFunction::EASE_IN );
  89 ~~~
  90
  91 ### Other Actions
  92
  93 An animation can be looped:
  94 ~~~{.cpp}
  95 animation.SetLooping( true );
  96 ~~~
  97
  98 By default, when an animation ends, the properties that it was animating are BAKED.
  99 However, the property changes can be **discarded** when the animation ends (or is stopped):
 100 ~~~{.cpp}
 101 animation.SetEndAction( Animation::Discard );
 102 ~~~
 103
 104 ## Key-Frame Animation {#animation-key-frame}
 105
 106 DALi provides support for animating between several different values, i.e. key-frames.
 107 A key frame takes a progress value between 0.0f and 1.0f (0 and 100% respectively) and portrays the value of the property when the animation has progressed that much.
 108 You can create several key frames:
 109 ~~~{.cpp}
 110 Dali::KeyFrames keyFrames = Dali::KeyFrames::New();
 111 keyFrames.Add( 0.0f, Vector3( 10.0f, 10.0f, 10.0f ) );
 112 keyFrames.Add( 0.7f, Vector3( 200.0f, 200.0f, 200.0f ) );
 113 keyFrames.Add( 1.0f, Vector3( 100.0f, 100.0f, 100.0f ) );
 114 ~~~
 115 And then add them to your animation.
 116 ~~~{.cpp}
 117 animation.AnimateBetween( Property( actor1, Dali::Actor::Property::POSITION ), keyFrames );
 118 ~~~
 119 When you play the animation, DALi will animate the position of actor1 between the key-frames specified.
 120 'actor1' will animate from (10.0f, 10.0f, 10.0f) to (200.0f, 200.f, 200.0f) by 70% of the animation time,
 121 and then spend the remaining time animating back to (100.0f, 100.0f, 100.0f).
 122
 123 The advantage of specifying a key-frame at 0% is that regardless of where 'actor1' is, it will start from position (10.0f, 10.0f, 10.0f).
 124 If AnimateTo was used, then the start position would have been actor1's current position.
 125
 126 ## Path Animations {#animation-paths}
 127
 128 A Dali::Path can be used to animate the position and orientation of actors.
 129
 130 ![ ](animation/animated-path.png)
 131
 132 The black points in the diagram are points where the DALi logo will travel to.
 133 The red points are the control points which express the curvature of the path on the black points.
 134
 135 This, in code will be represented as follows:
 136 ~~~{.cpp}
 137 Path path = Path::New();
 138 path.AddPoint( Vector3( 50.0f, 10.0f, 0.0f ));
 139 path.AddPoint( Vector3( 90.0f, 50.0f, 0.0f ));
 140 path.AddPoint( Vector3( 10.0f, 90.0f, 0.0f ));
 141 ~~~
 142 The control points can be added manually using Dali::Path::AddControlPoint or Path can auto-generate them for you:
 143 ~~~{.cpp}
 144 path.GenerateControlPoints(0.25f);
 145 ~~~
 146 Here 0.25f represents the curvature of the path you require. Please see Dali::Path::GenerateControlPoints for more information.
 147
 148 To animate actor1 along this path:
 149 ~~~{.cpp}
 150 animation.Animate( actor1, path, Vector3::ZERO );
 151 ~~~
 152 The third parameter is the forward vector (in local space coordinate system) that will be oriented with the path's tangent direction.