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.FinishedSignal().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    * @brief This copy constructor is required for (smart) pointer semantics.
 178    *
 179    * @param [in] handle A reference to the copied handle
 180    */
 181   Animation(const Animation& handle);
 182
 183   /**
 184    * @brief This assignment operator is required for (smart) pointer semantics.
 185    *
 186    * @param [in] rhs  A reference to the copied handle
 187    * @return A reference to this
 188    */
 189   Animation& operator=(const Animation& rhs);
 190
 191   /**
 192    * @brief This method is defined to allow assignment of the NULL value,
 193    * and will throw an exception if passed any other value.
 194    *
 195    * Assigning to NULL is an alias for Reset().
 196    * @param [in] rhs  A NULL pointer
 197    * @return A reference to this handle
 198    */
 199   Animation& operator=(BaseHandle::NullType* rhs);
 200
 201   /**
 202    * @brief Set the duration of an animation.
 203    *
 204    * @pre durationSeconds must be greater than zero.
 205    * @param[in] seconds The duration in seconds.
 206    */
 207   void SetDuration(float seconds);
 208
 209   /**
 210    * @brief Retrieve the duration of an animation.
 211    *
 212    * @return The duration in seconds.
 213    */
 214   float GetDuration() const;
 215
 216   /**
 217    * @brief Set whether the animation will loop.
 218    *
 219    * @param[in] looping True if the animation will loop.
 220    */
 221   void SetLooping(bool looping);
 222
 223   /**
 224    * @brief Query whether the animation will loop.
 225    *
 226    * @return True if the animation will loop.
 227    */
 228   bool IsLooping() const;
 229
 230   /**
 231    * @brief Set the end action of the animation.
 232    *
 233    * This action is performed when the animation ends.
 234    * Default end action is bake
 235    * @param[in] action The end action.
 236    */
 237   void SetEndAction(EndAction action);
 238
 239   /**
 240    * @brief Returns the end action of the animation.
 241    *
 242    * @return The end action.
 243    */
 244   EndAction GetEndAction() const;
 245
 246   /**
 247    * @brief Set the destroy action of the animation.
 248    *
 249    * If the animation is destroyed this action is performed on the following update.
 250    * Default destroy action is bake
 251    * @param[in] action The destroy action.
 252    */
 253   void SetDestroyAction(EndAction action);
 254
 255   /**
 256    * @brief Returns the destroy action of the animation.
 257    *
 258    * @return The destroy action.
 259    */
 260   EndAction GetDestroyAction() const;
 261
 262   /**
 263    * @brief Set the default alpha function for an animation.
 264    *
 265    * This is applied to individual property animations, if no further alpha functions are supplied.
 266    * @param[in] alpha The default alpha function.
 267    */
 268   void SetDefaultAlphaFunction(AlphaFunction alpha);
 269
 270   /**
 271    * @brief Retrieve the default alpha function for an animation.
 272    *
 273    * @return The default alpha function.
 274    */
 275   AlphaFunction GetDefaultAlphaFunction() const;
 276
 277   /**
 278   * @brief Retrieve the current progress of the animation.
 279   *
 280   * @return The current progress as a normalized value between [0,1].
 281   */
 282   float GetCurrentProgress();
 283
 284   /*
 285    * @brief Sets the progress of the animation.
 286    * The animation will play (or continue playing) from this point
 287    *
 288    * @param[in] progress The new progress as a normalized value between [0,1].
 289    */
 290   void SetCurrentProgress( float progress );
 291
 292   /**
 293    * @brief Play the animation.
 294    */
 295   void Play();
 296
 297   /**
 298    * @brief Play the animation from a given point.
 299    * @param[in] progress A value between [0,1] form where the animation should start playing
 300    */
 301   void PlayFrom( float progress );
 302
 303   /**
 304    * @brief Pause the animation.
 305    */
 306   void Pause();
 307
 308   /**
 309    * @brief Stop the animation.
 310    */
 311   void Stop();
 312
 313   /**
 314    * @brief Clear the animation.
 315    *
 316    * This disconnects any objects that were being animated, effectively stopping the animation.
 317    */
 318   void Clear();
 319
 320   /**
 321    * @brief Connect to this signal to be notified when an Animation's animations have finished.
 322    *
 323    * @return A signal object to Connect() with.
 324    */
 325   AnimationSignalV2& FinishedSignal();
 326
 327   /**
 328    * @brief Animate a property value by a relative amount.
 329    *
 330    * The default alpha function will be used.
 331    * The effect will start & end when the animation begins & ends.
 332    * @param [in] target The target object/property to animate.
 333    * @param [in] relativeValue The property value will change by this amount.
 334    */
 335   void AnimateBy(Property target, Property::Value relativeValue);
 336
 337   /**
 338    * @brief Animate a property value by a relative amount.
 339    *
 340    * The effect will start & end when the animation begins & ends.
 341    * @param [in] target The target object/property to animate.
 342    * @param [in] relativeValue The property value will change by this amount.
 343    * @param [in] alpha The alpha function to apply.
 344    */
 345   void AnimateBy(Property target, Property::Value relativeValue, AlphaFunction alpha);
 346
 347   /**
 348    * @brief Animate a property value by a relative amount.
 349    *
 350    * The default alpha function will be used.
 351    * @param [in] target The target object/property to animate.
 352    * @param [in] relativeValue The property value will increase/decrease by this amount.
 353    * @param [in] period The effect will occur during this time period.
 354    */
 355   void AnimateBy(Property target, Property::Value relativeValue, TimePeriod period);
 356
 357   /**
 358    * @brief Animate a property value by a relative amount.
 359    *
 360    * @param [in] target The target object/property to animate.
 361    * @param [in] relativeValue The property value will increase/decrease by this amount.
 362    * @param [in] alpha The alpha function to apply.
 363    * @param [in] period The effect will occur during this time period.
 364    */
 365   void AnimateBy(Property target, Property::Value relativeValue, AlphaFunction alpha, TimePeriod period);
 366
 367   /**
 368    * @brief Animate a property to a destination value.
 369    *
 370    * The default alpha function will be used.
 371    * The effect will start & end when the animation begins & ends.
 372    * @param [in] target The target object/property to animate.
 373    * @param [in] destinationValue The destination value.
 374    */
 375   void AnimateTo(Property target, Property::Value destinationValue);
 376
 377   /**
 378    * @brief Animate a property to a destination value.
 379    *
 380    * The effect will start & end when the animation begins & ends.
 381    * @param [in] target The target object/property to animate.
 382    * @param [in] destinationValue The destination value.
 383    * @param [in] alpha The alpha function to apply.
 384    */
 385   void AnimateTo(Property target, Property::Value destinationValue, AlphaFunction alpha);
 386
 387   /**
 388    * @brief Animate a property to a destination value.
 389    *
 390    * The default alpha function will be used.
 391    * @param [in] target The target object/property to animate.
 392    * @param [in] destinationValue The destination value.
 393    * @param [in] period The effect will occur during this time period.
 394    */
 395   void AnimateTo(Property target, Property::Value destinationValue, TimePeriod period);
 396
 397   /**
 398    * @brief Animate a property to a destination value.
 399    *
 400    * @param [in] target The target object/property to animate.
 401    * @param [in] destinationValue The destination value.
 402    * @param [in] alpha The alpha function to apply.
 403    * @param [in] period The effect will occur during this time period.
 404    */
 405   void AnimateTo(Property target, Property::Value destinationValue, AlphaFunction alpha, TimePeriod period);
 406
 407   /**
 408    * @brief Animate a property between keyframes.
 409    *
 410    * @param [in] target The target object/property to animate.
 411    * @param [in] keyFrames The key frames
 412    */
 413   void AnimateBetween(Property target, KeyFrames& keyFrames);
 414
 415   /**
 416    * @brief Animate a property between keyframes.
 417    *
 418    * @param [in] target The target object/property to animate.
 419    * @param [in] keyFrames The key frames
 420    * @param [in] alpha The alpha function to apply.
 421    */
 422   void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha);
 423
 424   /**
 425    * @brief Animate a property between keyframes.
 426    *
 427    * @param [in] target The target object/property to animate.
 428    * @param [in] keyFrames The key frames
 429    * @param [in] period The effect will occur during this time period.
 430    */
 431   void AnimateBetween(Property target, KeyFrames& keyFrames, TimePeriod period);
 432
 433   /**
 434    * @brief Animate a property between keyframes.
 435    *
 436    * @param [in] target The target object/property to animate.
 437    * @param [in] keyFrames The key frames
 438    * @param [in] alpha The alpha function to apply.
 439    * @param [in] period The effect will occur during this time period.
 440    */
 441   void AnimateBetween(Property target, KeyFrames& keyFrames, AlphaFunction alpha, TimePeriod period);
 442
 443   /**
 444    * @brief Animate a property using a custom function.
 445    *
 446    * The function will be called from a separate animation-thread; it should return quickly, to avoid performance degredation.
 447    * @pre The property type is equal PropertyTypes::Get<P>().
 448    * @param [in] target The target object/property to animate.
 449    * @param [in] animatorFunc The function to call during the animation.
 450    */
 451   template <class P>
 452   void Animate( Property target, boost::function<P (float alpha, const P& current)> animatorFunc )
 453   {
 454     Animate( target, PropertyTypes::Get<P>(), animatorFunc );
 455   }
 456
 457   /**
 458    * @brief Animate a property using a custom function.
 459    *
 460    * The function will be called from a separate animation-thread; it should return quickly, to avoid performance degredation.
 461    * @pre The property type is equal PropertyTypes::Get<P>().
 462    * @param [in] target The target object/property to animate.
 463    * @param [in] animatorFunc The function to call during the animation.
 464    * @param [in] alpha The alpha function to apply.
 465    */
 466   template <class P>
 467   void Animate( Property target, boost::function<P (float alpha, const P& current)> animatorFunc, AlphaFunction alpha )
 468   {
 469     Animate( target, PropertyTypes::Get<P>(), animatorFunc, alpha );
 470   }
 471
 472   /**
 473    * @brief Animate a property using a custom function.
 474    *
 475    * The function will be called from a separate animation-thread; it should return quickly, to avoid performance degredation.
 476    * @pre The property type is equal PropertyTypes::Get<P>().
 477    * @param [in] target The target object/property to animate.
 478    * @param [in] animatorFunc The function to call during the animation.
 479    * @param [in] period The effect will occur during this time period.
 480    */
 481   template <class P>
 482   void Animate( Property target, boost::function<P (float alpha, const P& current)> animatorFunc, TimePeriod period )
 483   {
 484     Animate( target, PropertyTypes::Get<P>(), animatorFunc, period );
 485   }
 486
 487   /**
 488    * @brief Animate a property using a custom function.
 489    *
 490    * The function will be called from a separate animation-thread; it should return quickly, to avoid performance degredation.
 491    * @pre The property type is equal PropertyTypes::Get<P>().
 492    * @param [in] target The target object/property to animate.
 493    * @param [in] animatorFunc The function to call during the animation.
 494    * @param [in] alpha The alpha function to apply.
 495    * @param [in] period The effect will occur during this time period.
 496    */
 497   template <class P>
 498   void Animate( Property target, boost::function<P (float alpha, const P& current)> animatorFunc, AlphaFunction alpha, TimePeriod period )
 499   {
 500     Animate( target, PropertyTypes::Get<P>(), animatorFunc, alpha, period );
 501   }
 502
 503   // Actor-specific convenience methods
 504
 505   /**
 506    * @brief Move an actor relative to its position.
 507    *
 508    * The default alpha function will be used.
 509    * The move will start & end when the animation begins & ends.
 510    * @param [in] actor The actor to animate.
 511    * @param [in] x axis displacement.
 512    * @param [in] y axis displacement.
 513    * @param [in] z axis displacement.
 514    */
 515   void MoveBy(Actor actor, float x, float y, float z);
 516
 517   /**
 518    * @brief Move an actor relative to its position.
 519    *
 520    * This overload allows the alpha function to be customized.
 521    * The move will start & end when the animation begins & ends.
 522    * @param [in] actor The actor to animate.
 523    * @param [in] displacement relative to current position.
 524    * @param [in] alpha The alpha function to apply.
 525    */
 526   void MoveBy(Actor actor, Vector3 displacement, AlphaFunction alpha);
 527
 528   /**
 529    * @brief Move an actor relative to its position.
 530    *
 531    * This overload allows the translation start & end time to be customized.
 532    * @pre delaySeconds must be zero or greater.
 533    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 534    * @param [in] actor The actor to animate.
 535    * @param [in] displacement relative to current position.
 536    * @param [in] alpha The alpha function to apply.
 537    * @param [in] delaySeconds The initial delay from the start of the animation.
 538    * @param [in] durationSeconds The duration of the translation.
 539    */
 540   void MoveBy(Actor actor, Vector3 displacement, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 541
 542   /**
 543    * @brief Move an actor to a target position.
 544    *
 545    * The default alpha function will be used.
 546    * The move will start & end when the animation begins & ends.
 547    * @param [in] actor The actor to animate.
 548    * @param [in] x axis position.
 549    * @param [in] y axis position.
 550    * @param [in] z axis position.
 551    */
 552   void MoveTo(Actor actor, float x, float y, float z);
 553
 554   /**
 555    * @brief Move an actor to a target position.
 556    *
 557    * This overload allows the alpha function to be customized.
 558    * The move will start & end when the animation begins & ends.
 559    * @param [in] actor The actor to animate.
 560    * @param [in] position to move to
 561    * @param [in] alpha The alpha function to apply.
 562    */
 563   void MoveTo(Actor actor, Vector3 position, AlphaFunction alpha);
 564
 565   /**
 566    * @brief Move an actor to a target position.
 567    *
 568    * This overload allows the translation start & end time to be customized.
 569    * @pre delaySeconds must be zero or greater.
 570    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 571    * @param [in] actor The actor to animate.
 572    * @param [in] position to move to
 573    * @param [in] alpha The alpha function to apply.
 574    * @param [in] delaySeconds The initial delay from the start of the animation.
 575    * @param [in] durationSeconds The duration of the translation.
 576    */
 577   void MoveTo(Actor actor, Vector3 position, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 578
 579   /**
 580    * @brief Move an actor using a custom function.
 581    *
 582    * The animatorFunc will be called from a separate animation-thread; it should return quickly, to avoid performance degredation.
 583    * @pre delaySeconds must be zero or greater.
 584    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 585    * @param [in] actor The actor to animate.
 586    * @param [in] animatorFunc The function to call during the animation.
 587    * @param [in] alpha The alpha function to apply.
 588    * @param [in] delaySeconds The initial delay from the start of the animation.
 589    * @param [in] durationSeconds The duration of the translation.
 590    */
 591   void Move(Actor actor, AnimatorFunctionVector3 animatorFunc, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 592
 593   /**
 594    * @brief Rotate an actor around an arbitrary axis.
 595    *
 596    * The default alpha function will be used.
 597    * The rotation will start & end when the animation begins & ends.
 598    * @param [in] actor The actor to animate.
 599    * @param [in] angle The angle in degrees.
 600    * @param [in] axis The axis to rotate around
 601    */
 602   void RotateBy(Actor actor, Degree angle, Vector3 axis);
 603
 604   /**
 605    * @brief Rotate an actor around an arbitrary axis.
 606    *
 607    * The default alpha function will be used.
 608    * The rotation will start & end when the animation begins & ends.
 609    * @param [in] actor The actor to animate.
 610    * @param [in] angle The angle in radians.
 611    * @param [in] axis The axis to rotate around
 612    */
 613   void RotateBy(Actor actor, Radian angle, Vector3 axis);
 614
 615   /**
 616    * @brief Rotate an actor around an arbitrary axis.
 617    *
 618    * This overload allows the alpha function to be customized.
 619    * The rotation will start & end when the animation begins & ends.
 620    * @param [in] actor The actor to animate.
 621    * @param [in] angle The angle in radians.
 622    * @param [in] axis The axis to rotate around.
 623    * @param [in] alpha The alpha function to apply.
 624    */
 625   void RotateBy(Actor actor, Degree angle, Vector3 axis, AlphaFunction alpha);
 626
 627   /**
 628    * @brief Rotate an actor around an arbitrary axis.
 629    *
 630    * This overload allows the alpha function to be customized.
 631    * The rotation will start & end when the animation begins & ends.
 632    * @param [in] actor The actor to animate.
 633    * @param [in] angle The angle in radians.
 634    * @param [in] axis The axis to rotate around.
 635    * @param [in] alpha The alpha function to apply.
 636    */
 637   void RotateBy(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha);
 638
 639   /**
 640    * @brief Rotate an actor around an arbitrary axis.
 641    *
 642    * This overload allows the rotation start & end time to be customized.
 643    * @pre delaySeconds must be zero or greater.
 644    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 645    * @param [in] actor The actor to animate.
 646    * @param [in] angle The angle in degrees.
 647    * @param [in] axis The axis to rotate around
 648    * @param [in] alpha The alpha function to apply.
 649    * @param [in] delaySeconds The initial delay from the start of the animation.
 650    * @param [in] durationSeconds The duration of the rotation.
 651    */
 652   void RotateBy(Actor actor, Degree angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 653
 654   /**
 655    * @brief Rotate an actor around an arbitrary axis.
 656    *
 657    * This overload allows the rotation start & end time to be customized.
 658    * @pre delaySeconds must be zero or greater.
 659    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 660    * @param [in] actor The actor to animate.
 661    * @param [in] angle The angle in radians.
 662    * @param [in] axis The axis to rotate around
 663    * @param [in] alpha The alpha function to apply.
 664    * @param [in] delaySeconds The initial delay from the start of the animation.
 665    * @param [in] durationSeconds The duration of the rotation.
 666    */
 667   void RotateBy(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 668
 669   /**
 670    * @brief Rotate an actor to a target orientation.
 671    *
 672    * The default alpha function will be used.
 673    * The rotation will start & end when the animation begins & ends.
 674    * @param [in] actor The actor to animate.
 675    * @param [in] angle The target rotation angle in degrees.
 676    * @param [in] axis The target axis of rotation.
 677    */
 678   void RotateTo(Actor actor, Degree angle, Vector3 axis);
 679
 680   /**
 681    * @brief Rotate an actor to a target orientation.
 682    *
 683    * The default alpha function will be used.
 684    * The rotation will start & end when the animation begins & ends.
 685    * @param [in] actor The actor to animate.
 686    * @param [in] angle The target rotation angle in radians.
 687    * @param [in] axis The target axis of rotation.
 688    */
 689   void RotateTo(Actor actor, Radian angle, Vector3 axis);
 690
 691   /**
 692    * @brief Rotate an actor to a target orientation.
 693    *
 694    * The default alpha function will be used.
 695    * The rotation will start & end when the animation begins & ends.
 696    * @param [in] actor The actor to animate.
 697    * @param [in] orientation The target orientation.
 698    */
 699   void RotateTo(Actor actor, Quaternion orientation);
 700
 701   /**
 702    * @brief Rotate an actor to a target orientation.
 703    *
 704    * This overload allows the alpha function to be customized.
 705    * The rotation will start & end when the animation begins & ends.
 706    * @param [in] actor The actor to animate.
 707    * @param [in] angle The target rotation angle in degrees.
 708    * @param [in] axis The target axis of rotation.
 709    * @param [in] alpha The alpha function to apply.
 710    */
 711   void RotateTo(Actor actor, Degree angle, Vector3 axis, AlphaFunction alpha);
 712
 713   /**
 714    * @brief Rotate an actor to a target orientation.
 715    *
 716    * This overload allows the alpha function to be customized.
 717    * The rotation will start & end when the animation begins & ends.
 718    * @param [in] actor The actor to animate.
 719    * @param [in] angle The target rotation angle in radians.
 720    * @param [in] axis The target axis of rotation.
 721    * @param [in] alpha The alpha function to apply.
 722    */
 723   void RotateTo(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha);
 724
 725   /**
 726    * @brief Rotate an actor to a target orientation.
 727    *
 728    * This overload allows the alpha function to be customized.
 729    * The rotation will start & end when the animation begins & ends.
 730    * @param [in] actor The actor to animate.
 731    * @param [in] orientation The target orientation.
 732    * @param [in] alpha The alpha function to apply.
 733    */
 734   void RotateTo(Actor actor, Quaternion orientation, AlphaFunction alpha);
 735
 736   /**
 737    * @brief Rotate an actor to a target orientation.
 738    *
 739    * This overload allows the rotation start & end time to be customized.
 740    * @pre delaySeconds must be zero or greater.
 741    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 742    * @param [in] actor The actor to animate.
 743    * @param [in] angle The target rotation angle in degrees.
 744    * @param [in] axis The target axis of rotation.
 745    * @param [in] alpha The alpha function to apply.
 746    * @param [in] delaySeconds The initial delay from the start of the animation.
 747    * @param [in] durationSeconds The duration of the rotation.
 748    */
 749   void RotateTo(Actor actor, Degree angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 750
 751   /**
 752    * @brief Rotate an actor to a target orientation.
 753    *
 754    * This overload allows the rotation start & end time to be customized.
 755    * @pre delaySeconds must be zero or greater.
 756    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 757    * @param [in] actor The actor to animate.
 758    * @param [in] angle The target rotation angle in radians.
 759    * @param [in] axis The target axis of rotation.
 760    * @param [in] alpha The alpha function to apply.
 761    * @param [in] delaySeconds The initial delay from the start of the animation.
 762    * @param [in] durationSeconds The duration of the rotation.
 763    */
 764   void RotateTo(Actor actor, Radian angle, Vector3 axis, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 765
 766   /**
 767    * @brief Rotate an actor to a target orientation.
 768    *
 769    * This overload allows the rotation start & end time to be customized.
 770    * @pre delaySeconds must be zero or greater.
 771    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 772    * @param [in] actor The actor to animate.
 773    * @param [in] orientation The target orientation.
 774    * @param [in] alpha The alpha function to apply.
 775    * @param [in] delaySeconds The initial delay from the start of the animation.
 776    * @param [in] durationSeconds The duration of the rotation.
 777    */
 778   void RotateTo(Actor actor, Quaternion orientation, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 779
 780   /**
 781    * @brief Rotate an actor using a custom function.
 782    *
 783    * The animatorFunc will be called from a separate animation-thread; it should return quickly, to avoid performance degredation.
 784    * @pre delaySeconds must be zero or greater.
 785    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 786    * @param [in] actor The actor to animate.
 787    * @param [in] animatorFunc The function to call during the animation.
 788    * @param [in] alpha The alpha function to apply.
 789    * @param [in] delaySeconds The initial delay from the start of the animation.
 790    * @param [in] durationSeconds The duration of the rotation.
 791    */
 792   void Rotate(Actor actor, AnimatorFunctionQuaternion animatorFunc, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 793
 794   /**
 795    * @brief Scale an actor.
 796    *
 797    * The default alpha function will be used.
 798    * The scaling will start & end when the animation begins & ends.
 799    * @param [in] actor The actor to animate.
 800    * @param [in] x Scale factor in the X-direction.
 801    * @param [in] y Scale factor in the Y-direction.
 802    * @param [in] z Scale factor in the Z-direction.
 803    */
 804   void ScaleBy(Actor actor, float x, float y, float z);
 805
 806   /**
 807    * @brief Scale an actor.
 808    *
 809    * This overload allows the alpha function to be customized.
 810    * The scaling will start & end when the animation begins & ends.
 811    * @param [in] actor The actor to animate.
 812    * @param [in] scale The scale factor.
 813    * @param [in] alpha The alpha function to apply.
 814    */
 815   void ScaleBy(Actor actor, Vector3 scale, AlphaFunction alpha);
 816
 817   /**
 818    * @brief Scale an actor.
 819    *
 820    * This overload allows the scaling start & end time to be customized.
 821    * @pre delaySeconds must be zero or greater.
 822    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 823    * @param [in] actor The actor to animate.
 824    * @param [in] scale The scale factor.
 825    * @param [in] alpha The alpha function to apply.
 826    * @param [in] delaySeconds The initial delay from the start of the animation.
 827    * @param [in] durationSeconds The duration of the scaling.
 828    */
 829   void ScaleBy(Actor actor, Vector3 scale, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 830
 831   /**
 832    * @brief Scale an actor to a target scale factor.
 833    *
 834    * The default alpha function will be used.
 835    * The scaling will start & end when the animation begins & ends.
 836    * @param [in] actor The actor to animate.
 837    * @param [in] x Target scale-factor in the X-direction.
 838    * @param [in] y Target scale-factor in the Y-direction.
 839    * @param [in] z Target scale-factor in the Z-direction.
 840    */
 841   void ScaleTo(Actor actor, float x, float y, float z);
 842
 843   /**
 844    * @brief Scale an actor to a target scale factor.
 845    *
 846    * This overload allows the alpha function to be customized.
 847    * The scaling will start & end when the animation begins & ends.
 848    * @param [in] actor The actor to animate.
 849    * @param [in] scale The target scale factor.
 850    * @param [in] alpha The alpha function to apply.
 851    */
 852   void ScaleTo(Actor actor, Vector3 scale, AlphaFunction alpha);
 853
 854   /**
 855    * @brief Scale an actor to a target scale factor.
 856    *
 857    * This overload allows the scaling start & end time to be customized.
 858    * @pre delaySeconds must be zero or greater.
 859    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 860    * @param [in] actor The actor to animate.
 861    * @param [in] scale The target scale factor.
 862    * @param [in] alpha The alpha function to apply.
 863    * @param [in] delaySeconds The initial delay from the start of the animation.
 864    * @param [in] durationSeconds The duration of the scaling.
 865    */
 866   void ScaleTo(Actor actor, Vector3 scale, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 867
 868   /**
 869    * @brief Show an actor during the animation.
 870    *
 871    * @param [in] actor The actor to animate.
 872    * @param [in] delaySeconds The initial delay from the start of the animation.
 873    */
 874   void Show(Actor actor, float delaySeconds);
 875
 876   /**
 877    * @brief Hide an actor during the animation.
 878    *
 879    * @param [in] actor The actor to animate.
 880    * @param [in] delaySeconds The initial delay from the start of the animation.
 881    */
 882   void Hide(Actor actor, float delaySeconds);
 883
 884   /**
 885    * @brief Animate the opacity of an actor.
 886    *
 887    * The default alpha function will be used.
 888    * The effect will start & end when the animation begins & ends.
 889    * @param [in] actor The actor to animate.
 890    * @param [in] opacity The relative change in opacity.
 891    */
 892   void OpacityBy(Actor actor, float opacity);
 893
 894   /**
 895    * @brief Animate the opacity of an actor.
 896    *
 897    * This overload allows the alpha function to be customized.
 898    * The effect will start & end when the animation begins & ends.
 899    * @param [in] actor The actor to animate.
 900    * @param [in] opacity The relative change in opacity.
 901    * @param [in] alpha The alpha function to apply.
 902    */
 903   void OpacityBy(Actor actor, float opacity, AlphaFunction alpha);
 904
 905   /**
 906    * @brief Animate the opacity of an actor.
 907    *
 908    * This overload allows the animation start & end time to be customized.
 909    * @pre delaySeconds must be zero or greater.
 910    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 911    * @param [in] actor The actor to animate.
 912    * @param [in] opacity The relative change in opacity.
 913    * @param [in] alpha The alpha function to apply.
 914    * @param [in] delaySeconds The initial delay from the start of the animation.
 915    * @param [in] durationSeconds The duration of the opacity animation.
 916    */
 917   void OpacityBy(Actor actor, float opacity, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 918
 919   /**
 920    * @brief Animate an actor to a target opacity.
 921    *
 922    * The default alpha function will be used.
 923    * The effect will start & end when the animation begins & ends.
 924    * @param [in] actor The actor to animate.
 925    * @param [in] opacity The target opacity.
 926    */
 927   void OpacityTo(Actor actor, float opacity);
 928
 929   /**
 930    * @brief Animate an actor to a target opacity.
 931    *
 932    * This overload allows the alpha function to be customized.
 933    * The effect will start & end when the animation begins & ends.
 934    * @param [in] actor The actor to animate.
 935    * @param [in] opacity The target opacity.
 936    * @param [in] alpha The alpha function to apply.
 937    */
 938   void OpacityTo(Actor actor, float opacity, AlphaFunction alpha);
 939
 940   /**
 941    * @brief Animate an actor to a target opacity.
 942    *
 943    * This overload allows the animation start & end time to be customized.
 944    * @pre delaySeconds must be zero or greater.
 945    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 946    * @param [in] actor The actor to animate.
 947    * @param [in] opacity The target opacity.
 948    * @param [in] alpha The alpha function to apply.
 949    * @param [in] delaySeconds The initial delay from the start of the animation.
 950    * @param [in] durationSeconds The duration of the opacity animation.
 951    */
 952   void OpacityTo(Actor actor, float opacity, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 953
 954   /**
 955    * @brief Animate the color of an actor.
 956    *
 957    * The default alpha function will be used.
 958    * The effect will start & end when the animation begins & ends.
 959    * @param [in] actor The actor to animate.
 960    * @param [in] color The relative change in color.
 961    */
 962   void ColorBy(Actor actor, Vector4 color);
 963
 964   /**
 965    * @brief Animate the color of an actor.
 966    *
 967    * This overload allows the alpha function to be customized.
 968    * The effect will start & end when the animation begins & ends.
 969    * @param [in] actor The actor to animate.
 970    * @param [in] color The relative change in color.
 971    * @param [in] alpha The alpha function to apply.
 972    */
 973   void ColorBy(Actor actor, Vector4 color, AlphaFunction alpha);
 974
 975   /**
 976    * @brief Animate the color of an actor.
 977    *
 978    * This overload allows the animation start & end time to be customized.
 979    * @pre delaySeconds must be zero or greater.
 980    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
 981    * @param [in] actor The actor to animate.
 982    * @param [in] color The relative change in color.
 983    * @param [in] alpha The alpha function to apply.
 984    * @param [in] delaySeconds The initial delay from the start of the animation.
 985    * @param [in] durationSeconds The duration of the color animation.
 986    */
 987   void ColorBy(Actor actor, Vector4 color, AlphaFunction alpha, float delaySeconds, float durationSeconds);
 988
 989   /**
 990    * @brief Animate an actor to a target color.
 991    *
 992    * The default alpha function will be used.
 993    * The effect will start & end when the animation begins & ends.
 994    * @param [in] actor The actor to animate.
 995    * @param [in] color The target color.
 996    */
 997   void ColorTo(Actor actor, Vector4 color);
 998
 999   /**
1000    * @brief Animate an actor to a target color.
1001    *
1002    * This overload allows the alpha function to be customized.
1003    * The effect will start & end when the animation begins & ends.
1004    * @param [in] actor The actor to animate.
1005    * @param [in] color The target color.
1006    * @param [in] alpha The alpha function to apply.
1007    */
1008   void ColorTo(Actor actor, Vector4 color, AlphaFunction alpha);
1009
1010   /**
1011    * @brief Animate an actor to a target color.
1012    *
1013    * This overload allows the animation start & end time to be customized.
1014    * @pre delaySeconds must be zero or greater.
1015    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
1016    * @param [in] actor The actor to animate.
1017    * @param [in] color The target color.
1018    * @param [in] alpha The alpha function to apply.
1019    * @param [in] delaySeconds The initial delay from the start of the animation.
1020    * @param [in] durationSeconds The duration of the color animation.
1021    */
1022   void ColorTo(Actor actor, Vector4 color, AlphaFunction alpha, float delaySeconds, float durationSeconds);
1023
1024   /**
1025    * @brief Resize an actor.
1026    *
1027    * The default alpha function will be used.
1028    * The resizing will start & end when the animation begins & ends.
1029    * The depth defaults to the minimum of width & height.
1030    * @param [in] actor The actor to animate.
1031    * @param [in] width The target width.
1032    * @param [in] height The target height.
1033    */
1034   void Resize(Actor actor, float width, float height);
1035
1036   /**
1037    * @brief Resize an actor.
1038    *
1039    * This overload allows the alpha function to be customized.
1040    * The resizing will start & end when the animation begins & ends.
1041    * The depth defaults to the minimum of width & height.
1042    * @param [in] actor The actor to animate.
1043    * @param [in] width The target width.
1044    * @param [in] height The target height.
1045    * @param [in] alpha The alpha function to apply.
1046    */
1047   void Resize(Actor actor, float width, float height, AlphaFunction alpha);
1048
1049   /**
1050    * @brief Resize an actor.
1051    *
1052    * This overload allows the resizing start & end time to be customized.
1053    * The depth defaults to the minimum of width & height.
1054    * @pre delaySeconds must be zero or greater.
1055    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
1056    * @param [in] actor The actor to animate.
1057    * @param [in] width The target width.
1058    * @param [in] height The target height.
1059    * @param [in] alpha The alpha function to apply.
1060    * @param [in] delaySeconds The initial delay from the start of the animation.
1061    * @param [in] durationSeconds The duration of the resizing.
1062    */
1063   void Resize(Actor actor, float width, float height, AlphaFunction alpha, float delaySeconds, float durationSeconds);
1064
1065   /**
1066    * @brief Resize an actor.
1067    *
1068    * The default alpha function will be used.
1069    * The resizing will start & end when the animation begins & ends.
1070    * @param [in] actor The actor to animate.
1071    * @param [in] size The target size.
1072    */
1073   void Resize(Actor actor, Vector3 size);
1074
1075   /**
1076    * @brief Resize an actor.
1077    *
1078    * This overload allows the alpha function to be customized.
1079    * The resizing will start & end when the animation begins & ends.
1080    * @param [in] actor The actor to animate.
1081    * @param [in] size The target size.
1082    * @param [in] alpha The alpha function to apply.
1083    */
1084   void Resize(Actor actor, Vector3 size, AlphaFunction alpha);
1085
1086   /**
1087    * @brief Resize an actor.
1088    *
1089    * This overload allows the resizing start & end time to be customized.
1090    * @pre delaySeconds must be zero or greater.
1091    * @pre durationSeconds must be zero or greater; zero is useful when animating boolean values.
1092    * @param [in] actor The actor to animate.
1093    * @param [in] size The target size.
1094    * @param [in] alpha The alpha function to apply.
1095    * @param [in] delaySeconds The initial delay from the start of the animation.
1096    * @param [in] durationSeconds The duration of the resizing.
1097    */
1098   void Resize(Actor actor, Vector3 size, AlphaFunction alpha, float delaySeconds, float durationSeconds);
1099
1100 public: // Not intended for use by Application developers
1101
1102   /**
1103    * @brief This constructor is used by Dali New() methods
1104    * @param [in] animation A pointer to a newly allocated Dali resource
1105    */
1106   explicit DALI_INTERNAL Animation(Internal::Animation* animation);
1107
1108 private:
1109
1110   /**
1111    * @brief Animate a property using a custom function.
1112    *
1113    * @pre The property type is equal expectedType.
1114    * @param [in] target The target object/property to animate.
1115    * @param [in] targetType The expected type of the property.
1116    * @param [in] func The function to call during the animation.
1117    */
1118   void Animate( Property target,
1119                 Property::Type targetType,
1120                 AnyFunction func );
1121
1122   /**
1123    * @brief Animate a property using a custom function.
1124    *
1125    * @pre The property type is equal expectedType.
1126    * @param [in] target The target object/property to animate.
1127    * @param [in] targetType The expected type of the property.
1128    * @param [in] func The function to call during the animation.
1129    * @param [in] alpha The alpha function to apply.
1130    */
1131   void Animate( Property target,
1132                 Property::Type targetType,
1133                 AnyFunction func,
1134                 AlphaFunction alpha );
1135
1136   /**
1137    * @brief Animate a property using a custom function.
1138    *
1139    * @pre The property type is equal expectedType.
1140    * @param [in] target The target object/property to animate.
1141    * @param [in] targetType The expected type of the property.
1142    * @param [in] func The function to call during the animation.
1143    * @param [in] period The effect will occur during this time period.
1144    */
1145   void Animate( Property target,
1146                 Property::Type targetType,
1147                 AnyFunction func,
1148                 TimePeriod period );
1149
1150   /**
1151    * @brief Animate a property using a custom function.
1152    *
1153    * @pre The property type is equal expectedType.
1154    * @param [in] target The target object/property to animate.
1155    * @param [in] targetType The expected type of the property.
1156    * @param [in] func The function to call during the animation.
1157    * @param [in] alpha The alpha function to apply.
1158    * @param [in] period The effect will occur during this time period.
1159    */
1160   void Animate( Property target,
1161                 Property::Type targetType,
1162                 AnyFunction func,
1163                 AlphaFunction alpha,
1164                 TimePeriod period );
1165 };
1166
1167 } // namespace Dali
1168
1169 #endif // __DALI_ANIMATION_H__