{{page>index}}
---------
===== Animators =====

Animators are a specific type of timer, specially designed for on-screen
animation purposes:

   * The time interval is usually known when they are created.
   * They are called at each screen refresh and their interval can vary. The interval can depend on the system load, the target power consumption, and other factors. The exact interval is not relevant.

To implement animators, Ecore provides the Ecore animator subsystem.

=== Table of Contents ===

  * [[#Forever-running_Animator|Forever-running Animator]]
  * [[#Specific-duration_Animator|Specific-duration Animator]]
  * [[#To_create_and_destroy_the_animator|To create and destroy the animator]]
    * [[#To_create_the_animator|To create the animator]]
    * [[#To_destroy_the_animator|To destroy the animator]]
  * [[#To_manage_the_animator|To manage the animator]]
    * [[#To_pause_the_currently_running_animator|To pause the currently running animator]]
    * [[#To_query_Ecore_for_the_interval_between_2_animator_calls|To query Ecore for the interval between 2 animator calls]]
    * [[#To_change_the_interval|To change the interval]]

=== Related Info ===

  * [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/group__Ecore__Animator__Group.html|Ecore Animator functions API]]
  * [[https://build.enlightenment.org/job/nightly_efl_gcc_x86_64/lastSuccessfulBuild/artifact/doc/html/tutorial_ecore_animator.html|Ecore Animator Example]]

==== Forever-running Animator ====

To create an animation that runs for an indefinite time:

<code c>
Eina_Bool my_anim_cb(void *data)
{
   static int count = 0;
   count++;
   if (count &lt; 5)
      return ECORE_CALLBACK_RENEW;

   return ECORE_CALLBACK_CANCEL;
}
ecore_animator_add(my_anim_cb, my_data);
</code>

This example looks the same as the one using an Ecore timer. The
''ecore_animator_add()'' function takes the callback function and data to pass
to it, and returns an ''Ecore_Animator'' object. The function is called at a
system-defined interval until it returns ''ECORE_CALLBACK_CANCEL'' instead of
''ECORE_CALLBACK_RENEW''.

==== Specific-duration Animator ====

An animator callback for an animator running a specific time has a different
prototype than the forever running animator.

This callback function receives both data and a position which represents the
current time among the full timeline, 0 meaning the beginning of the
animation, and 1 meaning the end of the animation, returning
''ECORE_CALLBACK_CANCEL'' to abort, or ''ECORE_CALLBACK_RENEW'' to continue.

==== To create and destroy the animator ====

== To create the animator ==

Use the ''ecore_animator_timeline_add()'' function. The first parameter
specifies the animator duration, the second parameter is the callback
function, and the third parameter is the data to pass to the callback. The
data parameter is optional.

<code c>
Eina_Bool my_anim_cb(void *data, double position)
{
   if (position < .5)
      return ECORE_CALLBACK_RENEW;

   return ECORE_CALLBACK_CANCEL;
}
ecore_animator_timeline_add(5., my_anim_cb, my_data);
</code>

In this example, the animator is specified to run for five seconds. The
function returns ''ECORE_CALLBACK_CANCEL'' as soon as the position among the
timeline passes half of the duration, 2.5 seconds.

Ecore can generate a virtual position from the original one using
''ecore_animator_pos_map(position, map, v1, v2)''. Several maps are available:

    * ''ECORE_POS_MAP_LINEAR'': linear from 0.0 to 1.0.
    * ''ECORE_POS_MAP_ACCELERATE'': start slow, then speed up.
    * ''ECORE_POS_MAP_DECELERATE'': start fast, then slow down.
    * ''ECORE_POS_MAP_SINUSOIDAL'': start slow, speed up, then slow down at the end.
    * ''ECORE_POS_MAP_ACCELERATE_FACTOR'': start slow, then speed up, v1 being a power factor: 0.0 is linear, 1.0 is standard acceleration, 2.0 is a much more pronounced acceleration (squared), and 3.0 is cubed.
    * ''ECORE_POS_MAP_DECELERATE_FACTOR'': start fast, then slow down, v1 being a power factor: 0.0 is linear, 1.0 is standard deceleration, 2.0 is a much more pronounced deceleration (squared), and 3.0 is cubed.
    * ''ECORE_POS_MAP_SINUSOIDAL_FACTOR'': start slow, speed up, then slow down at the end, v1 being a power factor: 0.0 is linear, 1.0 is a standard sinusoidal, 2.0 is a much more pronounced sinusoidal (squared), and 3.0 is cubed.
    * ''ECORE_POS_MAP_DIVISOR_INTERP'': start at gradient * v1, interpolated with the power of v2 curve.
    * ''ECORE_POS_MAP_BOUNCE'': start at 0.0, then drop like a ball bouncing to the ground at 1.0, and bounce v2 times, with a decay factor of v1.
    * ''ECORE_POS_MAP_SPRING'': start at 0.0, then wobble like a spring to the rest position 1.0, and wobble v2 times, with a decay factor of v1.

{{ :mainloop_pos_map_all.png }}

== To destroy the animator ==

Use the ''ecore_animator_del()'' function. The animator to destroy must be
running, that is, it has not returned a ''false'' value. If the animator is
not running, the function cannot be called.


==== To manage the animator ====

== To pause the currently running animator ==

Use the ''ecore_animator_freeze()'' function. Note that time continues ticking
even if the animator is frozen, and that resuming the animation using the
''ecore_animator_thaw()'' function does not actually resume, if the full
runtime has been passed in the meanwhile.

== To query Ecore for the interval between 2 animator calls ==

Use the ''ecore_animator_frametime_get()'' function.

== To change the interval ==

Use the ''ecore_animator_frametime_set(interval)'' function. Note that too
small a value causes performance and power consumption issues, and too high a
value makes the animation jerky.

------
{{page>index}}