dali/public-api/animation/animation.h

   1 #ifndef __DALI_ANIMATION_H__
   2 #define __DALI_ANIMATION_H__
   3
   4 /*
   5  * Copyright (c) 2014 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 <boost/function.hpp>
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/public-api/animation/alpha-functions.h>
  26 #include <dali/public-api/animation/key-frames.h>
  27 #include <dali/public-api/animation/time-period.h>
  28 #include <dali/public-api/object/any.h>
  29 #include <dali/public-api/object/handle.h>
  30 #include <dali/public-api/object/property.h>
  31 #include <dali/public-api/signals/dali-signal-v2.h>
  32
  33 namespace Dali DALI_IMPORT_API
  34 {
  35
  36 class Actor;
  37 struct Degree;
  38 class Quaternion;
  39 struct Radian;
  40 class ShaderEffect;
  41 struct Property;
  42 struct Vector2;
  43 struct Vector3;
  44 struct Vector4;
  45
  46 typedef boost::function<bool       (float alpha, const bool& current)>       AnimatorFunctionBool;      ///< Animator function signature for boolean properties.
  47 typedef boost::function<float      (float alpha, const float& current)>      AnimatorFunctionFloat;     ///< Animator function signature for float properties.
  48 typedef boost::function<int        (float alpha, const int& current)>        AnimatorFunctionInteger;   ///< Animator function signature for integer properties.
  49 typedef boost::function<Vector2    (float alpha, const Vector2& current)>    AnimatorFunctionVector2;   ///< Animator function signature for Vector2 properties.
  50 typedef boost::function<Vector3    (float alpha, const Vector3& current)>    AnimatorFunctionVector3;   ///< Animator function signature for Vector3 properties.
  51 typedef boost::function<Vector4    (float alpha, const Vector4& current)>    AnimatorFunctionVector4;   ///< Animator function signature for Vector4 properties.
  52 typedef boost::function<Quaternion (float alpha, const Quaternion& current)> AnimatorFunctionQuaternion;///< Animator function signature for Quaternion properties.
  53
  54 namespace Internal DALI_INTERNAL
  55 {
  56 class Animation;
  57 }
  58
  59 /**
  60  * @brief Dali::Animation can be used to animate the properties of any number of objects, typically Actors.
  61  *
  62  * An example animation setup is shown below:
  63  *
  64  * @code
  65  *
  66  * struct MyProgram
  67  * {
  68  *   Actor mActor; // The object we wish to animate
  69  *   Animation mAnimation; // Keep this to control the animation
  70  * }
  71  *
  72  * // ...To play the animation
  73  *
  74  * mAnimation = Animation::New(3.0f); // duration 3 seconds
  75  * mAnimation.MoveTo(mActor, 10.0f, 50.0f, 0.0f);
  76  * mAnimation.Play();
  77  *
  78  * @endcode
  79  *
  80  * Dali::Animation supports "fire and forget" behaviour i.e. an animation continues to play if the handle is discarded.
  81  * Note that in the following example, the "Finish" signal will be emitted:
  82  *
  83  * @code
  84  *
  85  * void ExampleCallback( Animation& source )
  86  * {
  87  *   std::cout << "Animation has finished" << std::endl;
  88  * }
  89  *
  90  * void ExampleAnimation( Actor actor )
  91  * {
  92  *   Animation animation = Animation::New(2.0f); // duration 2 seconds
  93  *   animation.MoveTo(actor, 10.0f, 50.0f, 0.0f);
  94  *   animation.SignalFinished().Connect( ExampleCallback );
  95  *   animation.Play();
  96  * } // At this point the animation handle has gone out of scope
  97  *
  98  * Actor actor = Actor::New();
  99  * Stage::GetCurrent().Add( actor );
 100  *
 101  * // Fire animation and forget about it
 102  * ExampleAnimation( actor );
 103  *
 104  * // However the animation will continue, and "Animation has finished" will be printed after 2 seconds.
 105  *
 106  * @endcode
 107  *
 108  * If the "Finish" signal is connected to a member function of an object, it must be disconnected before the object is destroyed.
 109  * This is typically done in the object destructor, and requires either the Dali::Connection object or Dali::Animation handle to be stored.
 110  */
 111 class DALI_IMPORT_API Animation : public BaseHandle
 112 {
 113 public:
 114
 115   typedef SignalV2< void (Animation&) > AnimationSignalV2; ///< Animation finished signal type
 116
 117   typedef Any AnyFunction; ///< Interpolation function
 118   typedef boost::function<Vector3 (float alpha, const Vector3& current)> Vector3AnimatorFunc; ///< Interpolation function
 119   typedef boost::function<Quaternion (float alpha, const Quaternion& current)> QuaternionAnimatorFunc; ///< Interpolation function
 120
 121   /**
 122    * @brief What to do when the animation ends, is stopped or is destroyed
 123    */
 124   enum EndAction
 125   {
 126     Bake,     ///< When the animation ends, the animated property values are saved.
 127     Discard,  ///< When the animation ends, the animated property values are forgotten.
 128     BakeFinal ///< If the animation is stopped, the animated property values are saved as if the animation had run to completion, otherwise behaves like Bake.
 129   };
 130
 131   //Signal Names
 132   static const char* const SIGNAL_FINISHED; ///< name "finished"
 133
 134   //Action Names
 135   static const char* const ACTION_PLAY;     ///< name "play"
 136   static const char* const ACTION_STOP;     ///< name "stop"
 137   static const char* const ACTION_PAUSE;    ///< name "pause"
 138
 139   /**
 140    * @brief Create an uninitialized Animation; this can be initialized with Animation::New().
 141    *
 142    * Calling member functions with an uninitialized Dali::Object is not allowed.
 143    */
 144   Animation();
 145
 146   /**
 147    * @brief Create an initialized Animation.
 148    *
 149    * The animation will not loop.
 150    * The default end action is "Bake".
 151    * The default alpha function is linear.
 152    * @pre durationSeconds must be greater than zero.
 153    * @param [in] durationSeconds The duration in seconds.
 154    * @return A handle to a newly allocated Dali resource.
 155    */
 156   static Animation New(float durationSeconds);
 157
 158   /**
 159    * @brief Downcast an Object handle to Animation.
 160    *
 161    * If handle points to an Animation object the downcast produces
 162    * valid handle. If not the returned handle is left uninitialized.
 163    *
 164    * @param[in] handle to An object
 165    * @return handle to a Animation object or an uninitialized handle
 166    */
 167   static Animation DownCast( BaseHandle handle );
 168
 169   /**
 170    * @brief Destructor
 171    *
 172    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 173    */
 174   ~Animation();
 175
 176   /**
 177    * @copydoc Dali::BaseHandle::operator=
 178    */
 179   using BaseHandle::operator=;
 180
 181   /**
 182    * @brief Set the duration of an animation.
 183    *
 184    * @pre durationSeconds must be greater than zero.
 185    * @param[in] seconds The duration in seconds.
 186    */
 187   void SetDuration(float seconds);
 188
 189   /**
 190    * @brief Retrieve the duration of an animation.
 191    *
 192    * @return The duration in seconds.
 193    */
 194   float GetDuration() const;
 195
 196   /**
 197    * @brief Set whether the animation will loop.
 198    *
 199    * @param[in] looping True if the animation will loop.
 200    */
 201   void SetLooping(bool looping);
 202
 203   /**
 204    * @brief Query whether the animation will loop.
 205    *
 206    * @return True if the animation will loop.
 207    */
 208   bool IsLooping() const;
 209
 210   /**
 211    * @brief Set the end action of the animation.
 212    *
 213    * This action is performed when the animation ends.
 214    * Default end action is bake
 215    * @param[in] action The end action.
 216    */
 217   void SetEndAction(EndAction action);
 218
 219   /**
 220    * @brief Returns the end action of the animation.
 221    *
 222    * @return The end action.
 223    */
 224   EndAction GetEndAction() const;
 225
 226   /**
 227    * @brief Set the destroy action of the animation.
 228    *
 229    * If the animation is destroyed this action is performed on the following update.
 230    * Default destroy action is bake
 231    * @param[in] action The destroy action.
 232    */
 233   void SetDestroyAction(EndAction action);
 234
 235   /**
 236    * @brief Returns the destroy action of the animation.
 237    *
 238    * @return The destroy action.
 239    */
 240   EndAction GetDestroyAction() const;
 241
 242   /**
 243    * @brief Set the default alpha function for an animation.
 244    *
 245    * This is applied to individual property animations, if no further alpha functions are supplied.
 246    * @param[in] alpha The default alpha function.
 247    */
 248   void SetDefaultAlphaFunction(AlphaFunction alpha);
 249
 250   /**
 251    * @brief Retrieve the default alpha function for an animation.
 252    *
 253    * @return The default alpha function.
 254    */
 255   AlphaFunction GetDefaultAlphaFunction() const;
 256
 257   /**
 258   * @brief Retrieve the current progress of the animation.
 259   *
 260   * @return The current progress as a normalized value between [0,1].
 261   */
 262   float GetCurrentProgress();
 263
 264   /*
 265    * @brief Sets the progress of the animation.
 266    * The animation will play (or continue playing) from this point
 267    *
 268    * @param[in] progress The new progress as a normalized value between [0,1].
 269    */
 270   void SetCurrentProgress( float progress );
 271
 272   /**
 273    * @brief Play the animation.
 274    */
 275   void Play();
 276
 277   /**
 278    * @brief Play the animation from a given point.
 279    * @param[in] progress A value between [0,1] form where the animation should start playing
 280    */
 281   void PlayFrom( float progress );
 282
 283   /**
 284    * @brief Pause the animation.
 285    */
 286   void Pause();
 287
 288   /**
 289    * @brief Stop the animation.
 290    */
 291   void Stop();
 292
 293   /**
 294    * @brief Clear the animation.
 295    *
 296    * This disconnects any objects that were being animated, effectively stopping the animation.
 297    */
 298   void Clear();
 299
 300   /**
 301    * @brief Connect to this signal to be notified when an Animation's animations have finished.
 302    *
 303    * @return A signal object to Connect() with.
 304    */
 305   AnimationSignalV2& FinishedSignal();
 306
 307   /**
 308    * @brief Animate a property value by a relative amount.
 309    *
 310    * The default alpha function will be used.
 311    * The effect will start & end when the animation begins & ends.
 312    * @param [in] target The target object/property to animate.
 313    * @param [in] relativeValue The property value will change by this amount.
 314    */
 315   void AnimateBy(Property target, Property::Value relativeValue);
 316
 317   /**
 318    * @brief Animate a property value by a relative amount.
 319    *
 320    * The effect will start & end when the animation begins & ends.
 321    * @param [in] target The target object/property to animate.
 322    * @param [in] relativeValue The property value will change by this amount.
 323    * @param [in] alpha The alpha function to apply.
 324    */
 325   void AnimateBy(Property target, Property::Value relativeValue, AlphaFunction alpha);
 326
 327   /**
 328    * @brief Animate a property value by a relative amount.
 329    *
 330    * The default alpha function will be used.
 331    * @param [in] target The target object/property to animate.
 332    * @param [in] relativeValue The property value will increase/decrease by this amount.
 333    * @param [in] period The effect will occur during this time period.
 334    */
 335   void AnimateBy(Property target, Property::Value relativeValue, TimePeriod period);
 336
 337   /**
 338    * @brief Animate a property value by a relative amount.
 339    *
 340    * @param [in] target The target object/property to animate.
 341    * @param [in] relativeValue The property value will increase/decrease by this amount.
 342    * @param [in] alpha The alpha function to apply.
 343    * @param [in] period The effect will occur during this time period.
 344    */
 345   void AnimateBy(Property target, Property::Value relativeValue, AlphaFunction alpha, TimePeriod period);
 346
 347   /**
 348    * @brief Animate a property to a destination value.
 349    *
 350    * The default alpha function will be used.
 351    * The effect will start & end when the animation begins & ends.
 352    * @param [in] target The target object/property to animate.
 353    * @param [in] destinationValue The destination value.
 354    */
 355   void AnimateTo(Property target, Property::Value destinationValue);
 356
 357   /**
 358    * @brief Animate a property to a destination value.
 359    *
 360    * The effect will start & end when the animation begins & ends.
 361    * @param [in] target The target object/property to animate.
 362    * @param [in] destinationValue The destination value.
 363    * @param [in] alpha The alpha function to apply.
 364    */
 365   void AnimateTo(Property target, Property::Value destinationValue, AlphaFunction alpha);
 366
 367   /**
 368    * @brief Animate a property to a destination value.
 369    *
 370    * The default alpha function will be used.
 371    * @param [in] target The target object/property to animate.
 372    * @param [in] destinationValue The destination value.
 373    * @param [in] period The effect will occur during this time period.
 374    */
 375   void AnimateTo(Property target, Property::Value destinationValue, TimePeriod period);
 376
 377   /**
 378    * @brief Animate a property to a destination value.
 379    *
 380    * @param [in] target The target object/property to animate.
 381    * @param [in] destinationValue The destination value.
 382    * @param [in] alpha The alpha function to apply.
 383    * @param [in] period The effect will occur during this time period.
 384    */
 385   void AnimateTo(Property target, Property::Value destinationValue, AlphaFunction alpha, TimePeriod period);
 386
 387   /**
 388    * @brief Animate a property between keyframes.
 389    *
 390    * @param [in] target The target object/property to animate.
 391    * @param [in] keyFrames The key frames
 392    */
 393   void AnimateBetween(Property target, KeyFrames& keyFrames);
 394
 395   /**
 396    * @brief Animate a property between keyframes.
 397    *
 398    * @param [in] target The target object/property to animate.
 399    * @param [in] keyFrames The key frames
 400    * @param [in] alpha The alpha function to apply.
 401    */
 402   void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha);
 403
 404   /**
 405    * @brief Animate a property between keyframes.
 406    *
 407    * @param [in] target The target object/property to animate.
 408    * @param [in] keyFrames The key frames
 409    * @param [in] period The effect will occur during this time period.
 410    */
 411   void AnimateBetween(Property target, KeyFrames& keyFrames, TimePeriod period);
 412
 413   /**
 414    * @brief Animate a property between keyframes.
 415    *
 416    * @param [in] target The target object/property to animate.
 417    * @param [in] keyFrames The key frames
 418    * @param [in] alpha The alpha function to apply.
 419    * @param [in] period The effect will occur during this time period.
 420    */
 421   void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha, TimePeriod period);
 422
 423   /**
 424    * @brief Animate a property using a custom function.
 425    *
 426    * The function will be called from a separate animation-thread; it should return quickly, to avoid performance degredation.
 427    * @pre The property type is equal PropertyTypes::Get<P>().
 428    * @param [in] target The target object/property to animate.
 429    * @param [in] animatorFunc The function to call during the animation.
 430    */
 431   template <class P>
 432   void Animate( Property target, boost::function<P (float alpha, const P& current)> animatorFunc )
 433   {
 434     Animate( target, PropertyTypes::Get<P>(), animatorFunc );
 435   }
 436
 437   /**
 438    * @brief Animate a property using a custom function.
 439    *
 440    * The function will be called from a separate animation-thread; it should return quickly, to avoid performance degredation.
 441    * @pre The property type is equal PropertyTypes::Get<P>().
 442    * @param [in] target The target object/property to animate.
 443    * @param [in] animatorFunc The function to call during the animation.
 444    * @param [in] alpha The alpha function to apply.
 445    */
 446   template <class P>
 447   void Animate( Property target, boost::function<P (float alpha, const P& current)> animatorFunc, AlphaFunction alpha )
 448   {
 449     Animate( target, PropertyTypes::Get<P>(), animatorFunc, alpha );
 450   }
 451
 452   /**
 453    * @brief Animate a property using a custom function.
 454    *
 455    * The function will be called from a separate animation-thread; it should return quickly, to avoid performance degredation.
 456    * @pre The property type is equal PropertyTypes::Get<P>().
 457    * @param [in] target The target object/property to animate.
 458    * @param [in] animatorFunc The function to call during the animation.
 459    * @param [in] period The effect will occur during this time period.
 460    */
 461   template <class P>
 462   void Animate( Property target, boost::function<P (float alpha, const P& current)> animatorFunc, TimePeriod period )
 463   {
 464     Animate( target, PropertyTypes::Get<P>(), animatorFunc, period );
 465   }
 466
 467   /**
 468    * @brief Animate a property using a custom function.
 469    *
 470    * The function will be called from a separate animation-thread; it should return quickly, to avoid performance degredation.
 471    * @pre The property type is equal PropertyTypes::Get<P>().
 472    * @param [in] target The target object/property to animate.
 473    * @param [in] animatorFunc The function to call during the animation.
 474    * @param [in] alpha The alpha function to apply.
 475    * @param [in] period The effect will occur during this time period.
 476    */
 477   template <class P>
 478   void Animate( Property target, boost::function<P (float alpha, const P& current)> animatorFunc, AlphaFunction alpha, TimePeriod period )
 479   {
 480     Animate( target, PropertyTypes::Get<P>(), animatorFunc, alpha, period );
 481   }
 482
 483   // Actor-specific convenience methods
 484
 485   /**
 486    * @brief Move an actor relative to its position.
 487    *
 488    * The default alpha function will be used.
 489    * The move will start & end when the animation begins & ends.
 490    * @param [in] actor The actor to animate.
 491    * @param [in] x axis displacement.
 492    * @param [in] y axis displacement.
 493    * @param [in] z axis displacement.
 494    */
 495   void MoveBy(Actor actor, float x, float y, float z);
 496
 497   /**
 498    * @brief Move an actor relative to its position.
 499    *
 500    * This overload allows the alpha function to be customized.
 501    * The move will start & end when the animation begins & ends.
 502    * @param [in] actor The actor to animate.
 503    * @param [in] displacement relative to current position.
 504    * @param [in] alpha The alpha function to apply.
 505    */
 506   void MoveBy(Actor actor, Vector3 displacement, AlphaFunction alpha);
 507
 508   /**
 509    * @brief Move an actor relative to its position.
 510    *
 511    * This overload allows the translation start & end time to be customized.
 512    * @pre delaySeconds must be zero or greater.
 513    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 514    * @param [in] actor The actor to animate.
 515    * @param [in] displacement relative to current position.
 516    * @param [in] alpha The alpha function to apply.
 517    * @param [in] delaySeconds The initial delay from the start of the animation.
 518    * @param [in] durationSeconds The duration of the translation.
 519    */
 520   void MoveBy(Actor actor, Vector3 displacement, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 521
 522   /**
 523    * @brief Move an actor to a target position.
 524    *
 525    * The default alpha function will be used.
 526    * The move will start & end when the animation begins & ends.
 527    * @param [in] actor The actor to animate.
 528    * @param [in] x axis position.
 529    * @param [in] y axis position.
 530    * @param [in] z axis position.
 531    */
 532   void MoveTo(Actor actor, float x, float y, float z);
 533
 534   /**
 535    * @brief Move an actor to a target position.
 536    *
 537    * This overload allows the alpha function to be customized.
 538    * The move will start & end when the animation begins & ends.
 539    * @param [in] actor The actor to animate.
 540    * @param [in] position to move to
 541    * @param [in] alpha The alpha function to apply.
 542    */
 543   void MoveTo(Actor actor, Vector3 position, AlphaFunction alpha);
 544
 545   /**
 546    * @brief Move an actor to a target position.
 547    *
 548    * This overload allows the translation start & end time to be customized.
 549    * @pre delaySeconds must be zero or greater.
 550    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 551    * @param [in] actor The actor to animate.
 552    * @param [in] position to move to
 553    * @param [in] alpha The alpha function to apply.
 554    * @param [in] delaySeconds The initial delay from the start of the animation.
 555    * @param [in] durationSeconds The duration of the translation.
 556    */
 557   void MoveTo(Actor actor, Vector3 position, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 558
 559   /**
 560    * @brief Move an actor using a custom function.
 561    *
 562    * The animatorFunc will be called from a separate animation-thread; it should return quickly, to avoid performance degredation.
 563    * @pre delaySeconds must be zero or greater.
 564    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 565    * @param [in] actor The actor to animate.
 566    * @param [in] animatorFunc The function to call during the animation.
 567    * @param [in] alpha The alpha function to apply.
 568    * @param [in] delaySeconds The initial delay from the start of the animation.
 569    * @param [in] durationSeconds The duration of the translation.
 570    */
 571   void Move(Actor actor, AnimatorFunctionVector3 animatorFunc, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 572
 573   /**
 574    * @brief Rotate an actor around an arbitrary axis.
 575    *
 576    * The default alpha function will be used.
 577    * The rotation will start & end when the animation begins & ends.
 578    * @param [in] actor The actor to animate.
 579    * @param [in] angle The angle in degrees.
 580    * @param [in] axis The axis to rotate around
 581    */
 582   void RotateBy(Actor actor, Degree angle, Vector3 axis);
 583
 584   /**
 585    * @brief Rotate an actor around an arbitrary axis.
 586    *
 587    * The default alpha function will be used.
 588    * The rotation will start & end when the animation begins & ends.
 589    * @param [in] actor The actor to animate.
 590    * @param [in] angle The angle in radians.
 591    * @param [in] axis The axis to rotate around
 592    */
 593   void RotateBy(Actor actor, Radian angle, Vector3 axis);
 594
 595   /**
 596    * @brief Rotate an actor around an arbitrary axis.
 597    *
 598    * This overload allows the alpha function to be customized.
 599    * The rotation will start & end when the animation begins & ends.
 600    * @param [in] actor The actor to animate.
 601    * @param [in] angle The angle in radians.
 602    * @param [in] axis The axis to rotate around.
 603    * @param [in] alpha The alpha function to apply.
 604    */
 605   void RotateBy(Actor actor, Degree angle, Vector3 axis, AlphaFunction alpha);
 606
 607   /**
 608    * @brief Rotate an actor around an arbitrary axis.
 609    *
 610    * This overload allows the alpha function to be customized.
 611    * The rotation will start & end when the animation begins & ends.
 612    * @param [in] actor The actor to animate.
 613    * @param [in] angle The angle in radians.
 614    * @param [in] axis The axis to rotate around.
 615    * @param [in] alpha The alpha function to apply.
 616    */
 617   void RotateBy(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha);
 618
 619   /**
 620    * @brief Rotate an actor around an arbitrary axis.
 621    *
 622    * This overload allows the rotation start & end time to be customized.
 623    * @pre delaySeconds must be zero or greater.
 624    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 625    * @param [in] actor The actor to animate.
 626    * @param [in] angle The angle in degrees.
 627    * @param [in] axis The axis to rotate around
 628    * @param [in] alpha The alpha function to apply.
 629    * @param [in] delaySeconds The initial delay from the start of the animation.
 630    * @param [in] durationSeconds The duration of the rotation.
 631    */
 632   void RotateBy(Actor actor, Degree angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 633
 634   /**
 635    * @brief Rotate an actor around an arbitrary axis.
 636    *
 637    * This overload allows the rotation start & end time to be customized.
 638    * @pre delaySeconds must be zero or greater.
 639    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 640    * @param [in] actor The actor to animate.
 641    * @param [in] angle The angle in radians.
 642    * @param [in] axis The axis to rotate around
 643    * @param [in] alpha The alpha function to apply.
 644    * @param [in] delaySeconds The initial delay from the start of the animation.
 645    * @param [in] durationSeconds The duration of the rotation.
 646    */
 647   void RotateBy(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 648
 649   /**
 650    * @brief Rotate an actor to a target orientation.
 651    *
 652    * The default alpha function will be used.
 653    * The rotation will start & end when the animation begins & ends.
 654    * @param [in] actor The actor to animate.
 655    * @param [in] angle The target rotation angle in degrees.
 656    * @param [in] axis The target axis of rotation.
 657    */
 658   void RotateTo(Actor actor, Degree angle, Vector3 axis);
 659
 660   /**
 661    * @brief Rotate an actor to a target orientation.
 662    *
 663    * The default alpha function will be used.
 664    * The rotation will start & end when the animation begins & ends.
 665    * @param [in] actor The actor to animate.
 666    * @param [in] angle The target rotation angle in radians.
 667    * @param [in] axis The target axis of rotation.
 668    */
 669   void RotateTo(Actor actor, Radian angle, Vector3 axis);
 670
 671   /**
 672    * @brief Rotate an actor to a target orientation.
 673    *
 674    * The default alpha function will be used.
 675    * The rotation will start & end when the animation begins & ends.
 676    * @param [in] actor The actor to animate.
 677    * @param [in] orientation The target orientation.
 678    */
 679   void RotateTo(Actor actor, Quaternion orientation);
 680
 681   /**
 682    * @brief Rotate an actor to a target orientation.
 683    *
 684    * This overload allows the alpha function to be customized.
 685    * The rotation will start & end when the animation begins & ends.
 686    * @param [in] actor The actor to animate.
 687    * @param [in] angle The target rotation angle in degrees.
 688    * @param [in] axis The target axis of rotation.
 689    * @param [in] alpha The alpha function to apply.
 690    */
 691   void RotateTo(Actor actor, Degree angle, Vector3 axis, AlphaFunction alpha);
 692
 693   /**
 694    * @brief Rotate an actor to a target orientation.
 695    *
 696    * This overload allows the alpha function to be customized.
 697    * The rotation will start & end when the animation begins & ends.
 698    * @param [in] actor The actor to animate.
 699    * @param [in] angle The target rotation angle in radians.
 700    * @param [in] axis The target axis of rotation.
 701    * @param [in] alpha The alpha function to apply.
 702    */
 703   void RotateTo(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha);
 704
 705   /**
 706    * @brief Rotate an actor to a target orientation.
 707    *
 708    * This overload allows the alpha function to be customized.
 709    * The rotation will start & end when the animation begins & ends.
 710    * @param [in] actor The actor to animate.
 711    * @param [in] orientation The target orientation.
 712    * @param [in] alpha The alpha function to apply.
 713    */
 714   void RotateTo(Actor actor, Quaternion orientation, AlphaFunction alpha);
 715
 716   /**
 717    * @brief Rotate an actor to a target orientation.
 718    *
 719    * This overload allows the rotation start & end time to be customized.
 720    * @pre delaySeconds must be zero or greater.
 721    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 722    * @param [in] actor The actor to animate.
 723    * @param [in] angle The target rotation angle in degrees.
 724    * @param [in] axis The target axis of rotation.
 725    * @param [in] alpha The alpha function to apply.
 726    * @param [in] delaySeconds The initial delay from the start of the animation.
 727    * @param [in] durationSeconds The duration of the rotation.
 728    */
 729   void RotateTo(Actor actor, Degree angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 730
 731   /**
 732    * @brief Rotate an actor to a target orientation.
 733    *
 734    * This overload allows the rotation start & end time to be customized.
 735    * @pre delaySeconds must be zero or greater.
 736    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 737    * @param [in] actor The actor to animate.
 738    * @param [in] angle The target rotation angle in radians.
 739    * @param [in] axis The target axis of rotation.
 740    * @param [in] alpha The alpha function to apply.
 741    * @param [in] delaySeconds The initial delay from the start of the animation.
 742    * @param [in] durationSeconds The duration of the rotation.
 743    */
 744   void RotateTo(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 745
 746   /**
 747    * @brief Rotate an actor to a target orientation.
 748    *
 749    * This overload allows the rotation start & end time to be customized.
 750    * @pre delaySeconds must be zero or greater.
 751    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 752    * @param [in] actor The actor to animate.
 753    * @param [in] orientation The target orientation.
 754    * @param [in] alpha The alpha function to apply.
 755    * @param [in] delaySeconds The initial delay from the start of the animation.
 756    * @param [in] durationSeconds The duration of the rotation.
 757    */
 758   void RotateTo(Actor actor, Quaternion orientation, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 759
 760   /**
 761    * @brief Rotate an actor using a custom function.
 762    *
 763    * The animatorFunc will be called from a separate animation-thread; it should return quickly, to avoid performance degredation.
 764    * @pre delaySeconds must be zero or greater.
 765    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 766    * @param [in] actor The actor to animate.
 767    * @param [in] animatorFunc The function to call during the animation.
 768    * @param [in] alpha The alpha function to apply.
 769    * @param [in] delaySeconds The initial delay from the start of the animation.
 770    * @param [in] durationSeconds The duration of the rotation.
 771    */
 772   void Rotate(Actor actor, AnimatorFunctionQuaternion animatorFunc, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 773
 774   /**
 775    * @brief Scale an actor.
 776    *
 777    * The default alpha function will be used.
 778    * The scaling will start & end when the animation begins & ends.
 779    * @param [in] actor The actor to animate.
 780    * @param [in] x Scale factor in the X-direction.
 781    * @param [in] y Scale factor in the Y-direction.
 782    * @param [in] z Scale factor in the Z-direction.
 783    */
 784   void ScaleBy(Actor actor, float x, float y, float z);
 785
 786   /**
 787    * @brief Scale an actor.
 788    *
 789    * This overload allows the alpha function to be customized.
 790    * The scaling will start & end when the animation begins & ends.
 791    * @param [in] actor The actor to animate.
 792    * @param [in] scale The scale factor.
 793    * @param [in] alpha The alpha function to apply.
 794    */
 795   void ScaleBy(Actor actor, Vector3 scale, AlphaFunction alpha);
 796
 797   /**
 798    * @brief Scale an actor.
 799    *
 800    * This overload allows the scaling start & end time to be customized.
 801    * @pre delaySeconds must be zero or greater.
 802    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 803    * @param [in] actor The actor to animate.
 804    * @param [in] scale The scale factor.
 805    * @param [in] alpha The alpha function to apply.
 806    * @param [in] delaySeconds The initial delay from the start of the animation.
 807    * @param [in] durationSeconds The duration of the scaling.
 808    */
 809   void ScaleBy(Actor actor, Vector3 scale, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 810
 811   /**
 812    * @brief Scale an actor to a target scale factor.
 813    *
 814    * The default alpha function will be used.
 815    * The scaling will start & end when the animation begins & ends.
 816    * @param [in] actor The actor to animate.
 817    * @param [in] x Target scale-factor in the X-direction.
 818    * @param [in] y Target scale-factor in the Y-direction.
 819    * @param [in] z Target scale-factor in the Z-direction.
 820    */
 821   void ScaleTo(Actor actor, float x, float y, float z);
 822
 823   /**
 824    * @brief Scale an actor to a target scale factor.
 825    *
 826    * This overload allows the alpha function to be customized.
 827    * The scaling will start & end when the animation begins & ends.
 828    * @param [in] actor The actor to animate.
 829    * @param [in] scale The target scale factor.
 830    * @param [in] alpha The alpha function to apply.
 831    */
 832   void ScaleTo(Actor actor, Vector3 scale, AlphaFunction alpha);
 833
 834   /**
 835    * @brief Scale an actor to a target scale factor.
 836    *
 837    * This overload allows the scaling start & end time to be customized.
 838    * @pre delaySeconds must be zero or greater.
 839    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 840    * @param [in] actor The actor to animate.
 841    * @param [in] scale The target scale factor.
 842    * @param [in] alpha The alpha function to apply.
 843    * @param [in] delaySeconds The initial delay from the start of the animation.
 844    * @param [in] durationSeconds The duration of the scaling.
 845    */
 846   void ScaleTo(Actor actor, Vector3 scale, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 847
 848   /**
 849    * @brief Show an actor during the animation.
 850    *
 851    * @param [in] actor The actor to animate.
 852    * @param [in] delaySeconds The initial delay from the start of the animation.
 853    */
 854   void Show(Actor actor, float delaySeconds);
 855
 856   /**
 857    * @brief Hide an actor during the animation.
 858    *
 859    * @param [in] actor The actor to animate.
 860    * @param [in] delaySeconds The initial delay from the start of the animation.
 861    */
 862   void Hide(Actor actor, float delaySeconds);
 863
 864   /**
 865    * @brief Animate the opacity of an actor.
 866    *
 867    * The default alpha function will be used.
 868    * The effect will start & end when the animation begins & ends.
 869    * @param [in] actor The actor to animate.
 870    * @param [in] opacity The relative change in opacity.
 871    */
 872   void OpacityBy(Actor actor, float opacity);
 873
 874   /**
 875    * @brief Animate the opacity of an actor.
 876    *
 877    * This overload allows the alpha function to be customized.
 878    * The effect will start & end when the animation begins & ends.
 879    * @param [in] actor The actor to animate.
 880    * @param [in] opacity The relative change in opacity.
 881    * @param [in] alpha The alpha function to apply.
 882    */
 883   void OpacityBy(Actor actor, float opacity, AlphaFunction alpha);
 884
 885   /**
 886    * @brief Animate the opacity of an actor.
 887    *
 888    * This overload allows the animation start & end time to be customized.
 889    * @pre delaySeconds must be zero or greater.
 890    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 891    * @param [in] actor The actor to animate.
 892    * @param [in] opacity The relative change in opacity.
 893    * @param [in] alpha The alpha function to apply.
 894    * @param [in] delaySeconds The initial delay from the start of the animation.
 895    * @param [in] durationSeconds The duration of the opacity animation.
 896    */
 897   void OpacityBy(Actor actor, float opacity, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 898
 899   /**
 900    * @brief Animate an actor to a target opacity.
 901    *
 902    * The default alpha function will be used.
 903    * The effect will start & end when the animation begins & ends.
 904    * @param [in] actor The actor to animate.
 905    * @param [in] opacity The target opacity.
 906    */
 907   void OpacityTo(Actor actor, float opacity);
 908
 909   /**
 910    * @brief Animate an actor to a target opacity.
 911    *
 912    * This overload allows the alpha function to be customized.
 913    * The effect will start & end when the animation begins & ends.
 914    * @param [in] actor The actor to animate.
 915    * @param [in] opacity The target opacity.
 916    * @param [in] alpha The alpha function to apply.
 917    */
 918   void OpacityTo(Actor actor, float opacity, AlphaFunction alpha);
 919
 920   /**
 921    * @brief Animate an actor to a target opacity.
 922    *
 923    * This overload allows the animation start & end time to be customized.
 924    * @pre delaySeconds must be zero or greater.
 925    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 926    * @param [in] actor The actor to animate.
 927    * @param [in] opacity The target opacity.
 928    * @param [in] alpha The alpha function to apply.
 929    * @param [in] delaySeconds The initial delay from the start of the animation.
 930    * @param [in] durationSeconds The duration of the opacity animation.
 931    */
 932   void OpacityTo(Actor actor, float opacity, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 933
 934   /**
 935    * @brief Animate the color of an actor.
 936    *
 937    * The default alpha function will be used.
 938    * The effect will start & end when the animation begins & ends.
 939    * @param [in] actor The actor to animate.
 940    * @param [in] color The relative change in color.
 941    */
 942   void ColorBy(Actor actor, Vector4 color);
 943
 944   /**
 945    * @brief Animate the color of an actor.
 946    *
 947    * This overload allows the alpha function to be customized.
 948    * The effect will start & end when the animation begins & ends.
 949    * @param [in] actor The actor to animate.
 950    * @param [in] color The relative change in color.
 951    * @param [in] alpha The alpha function to apply.
 952    */
 953   void ColorBy(Actor actor, Vector4 color, AlphaFunction alpha);
 954
 955   /**
 956    * @brief Animate the color of an actor.
 957    *
 958    * This overload allows the animation start & end time to be customized.
 959    * @pre delaySeconds must be zero or greater.
 960    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 961    * @param [in] actor The actor to animate.
 962    * @param [in] color The relative change in color.
 963    * @param [in] alpha The alpha function to apply.
 964    * @param [in] delaySeconds The initial delay from the start of the animation.
 965    * @param [in] durationSeconds The duration of the color animation.
 966    */
 967   void ColorBy(Actor actor, Vector4 color, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 968
 969   /**
 970    * @brief Animate an actor to a target color.
 971    *
 972    * The default alpha function will be used.
 973    * The effect will start & end when the animation begins & ends.
 974    * @param [in] actor The actor to animate.
 975    * @param [in] color The target color.
 976    */
 977   void ColorTo(Actor actor, Vector4 color);
 978
 979   /**
 980    * @brief Animate an actor to a target color.
 981    *
 982    * This overload allows the alpha function to be customized.
 983    * The effect will start & end when the animation begins & ends.
 984    * @param [in] actor The actor to animate.
 985    * @param [in] color The target color.
 986    * @param [in] alpha The alpha function to apply.
 987    */
 988   void ColorTo(Actor actor, Vector4 color, AlphaFunction alpha);
 989
 990   /**
 991    * @brief Animate an actor to a target color.
 992    *
 993    * This overload allows the animation start & end time to be customized.
 994    * @pre delaySeconds must be zero or greater.
 995    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 996    * @param [in] actor The actor to animate.
 997    * @param [in] color The target color.
 998    * @param [in] alpha The alpha function to apply.
 999    * @param [in] delaySeconds The initial delay from the start of the animation.
1000    * @param [in] durationSeconds The duration of the color animation.
1001    */
1002   void ColorTo(Actor actor, Vector4 color, AlphaFunction alpha, float delaySeconds, float durationSeconds);
1003
1004   /**
1005    * @brief Resize an actor.
1006    *
1007    * The default alpha function will be used.
1008    * The resizing will start & end when the animation begins & ends.
1009    * The depth defaults to the minimum of width & height.
1010    * @param [in] actor The actor to animate.
1011    * @param [in] width The target width.
1012    * @param [in] height The target height.
1013    */
1014   void Resize(Actor actor, float width, float height);
1015
1016   /**
1017    * @brief Resize an actor.
1018    *
1019    * This overload allows the alpha function to be customized.
1020    * The resizing will start & end when the animation begins & ends.
1021    * The depth defaults to the minimum of width & height.
1022    * @param [in] actor The actor to animate.
1023    * @param [in] width The target width.
1024    * @param [in] height The target height.
1025    * @param [in] alpha The alpha function to apply.
1026    */
1027   void Resize(Actor actor, float width, float height, AlphaFunction alpha);
1028
1029   /**
1030    * @brief Resize an actor.
1031    *
1032    * This overload allows the resizing start & end time to be customized.
1033    * The depth defaults to the minimum of width & height.
1034    * @pre delaySeconds must be zero or greater.
1035    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
1036    * @param [in] actor The actor to animate.
1037    * @param [in] width The target width.
1038    * @param [in] height The target height.
1039    * @param [in] alpha The alpha function to apply.
1040    * @param [in] delaySeconds The initial delay from the start of the animation.
1041    * @param [in] durationSeconds The duration of the resizing.
1042    */
1043   void Resize(Actor actor, float width, float height, AlphaFunction alpha, float delaySeconds, float durationSeconds);
1044
1045   /**
1046    * @brief Resize an actor.
1047    *
1048    * The default alpha function will be used.
1049    * The resizing will start & end when the animation begins & ends.
1050    * @param [in] actor The actor to animate.
1051    * @param [in] size The target size.
1052    */
1053   void Resize(Actor actor, Vector3 size);
1054
1055   /**
1056    * @brief Resize an actor.
1057    *
1058    * This overload allows the alpha function to be customized.
1059    * The resizing will start & end when the animation begins & ends.
1060    * @param [in] actor The actor to animate.
1061    * @param [in] size The target size.
1062    * @param [in] alpha The alpha function to apply.
1063    */
1064   void Resize(Actor actor, Vector3 size, AlphaFunction alpha);
1065
1066   /**
1067    * @brief Resize an actor.
1068    *
1069    * This overload allows the resizing start & end time to be customized.
1070    * @pre delaySeconds must be zero or greater.
1071    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
1072    * @param [in] actor The actor to animate.
1073    * @param [in] size The target size.
1074    * @param [in] alpha The alpha function to apply.
1075    * @param [in] delaySeconds The initial delay from the start of the animation.
1076    * @param [in] durationSeconds The duration of the resizing.
1077    */
1078   void Resize(Actor actor, Vector3 size, AlphaFunction alpha, float delaySeconds, float durationSeconds);
1079
1080 public: // Not intended for use by Application developers
1081
1082   /**
1083    * @brief This constructor is used by Dali New() methods
1084    * @param [in] animation A pointer to a newly allocated Dali resource
1085    */
1086   explicit DALI_INTERNAL Animation(Internal::Animation* animation);
1087
1088 private:
1089
1090   /**
1091    * @brief Animate a property using a custom function.
1092    *
1093    * @pre The property type is equal expectedType.
1094    * @param [in] target The target object/property to animate.
1095    * @param [in] targetType The expected type of the property.
1096    * @param [in] func The function to call during the animation.
1097    */
1098   void Animate( Property target,
1099                 Property::Type targetType,
1100                 AnyFunction func );
1101
1102   /**
1103    * @brief Animate a property using a custom function.
1104    *
1105    * @pre The property type is equal expectedType.
1106    * @param [in] target The target object/property to animate.
1107    * @param [in] targetType The expected type of the property.
1108    * @param [in] func The function to call during the animation.
1109    * @param [in] alpha The alpha function to apply.
1110    */
1111   void Animate( Property target,
1112                 Property::Type targetType,
1113                 AnyFunction func,
1114                 AlphaFunction alpha );
1115
1116   /**
1117    * @brief Animate a property using a custom function.
1118    *
1119    * @pre The property type is equal expectedType.
1120    * @param [in] target The target object/property to animate.
1121    * @param [in] targetType The expected type of the property.
1122    * @param [in] func The function to call during the animation.
1123    * @param [in] period The effect will occur during this time period.
1124    */
1125   void Animate( Property target,
1126                 Property::Type targetType,
1127                 AnyFunction func,
1128                 TimePeriod period );
1129
1130   /**
1131    * @brief Animate a property using a custom function.
1132    *
1133    * @pre The property type is equal expectedType.
1134    * @param [in] target The target object/property to animate.
1135    * @param [in] targetType The expected type of the property.
1136    * @param [in] func The function to call during the animation.
1137    * @param [in] alpha The alpha function to apply.
1138    * @param [in] period The effect will occur during this time period.
1139    */
1140   void Animate( Property target,
1141                 Property::Type targetType,
1142                 AnyFunction func,
1143                 AlphaFunction alpha,
1144                 TimePeriod period );
1145 };
1146
1147 } // namespace Dali
1148
1149 #endif // __DALI_ANIMATION_H__