Tizen Native API
Functions | Typedefs
Ecore Animator
Ecore Main Loop

Ecore animators are a helper to simplify creating animations.

Creating an animation is as simple as saying for how long it should be run and having a callback that does the animation, something like this: 

 static Eina_Bool
 _do_animation(void *data, double pos)
 {
    evas_object_move(data, 100 * pos, 100 * pos);
    ... do some more animating ...
 }
 ...
 ecore_animator_timeline_add(2, _do_animation, my_evas_object);

In the sample above we create an animation to move my_evas_object from position (0,0) to (100,100) in 2 seconds.

If your animation runs for an unspecified amount of time you can use ecore_animator_add(), which is like using ecore_timer_add() with the interval being the framerate. Note that this has tangible benefits of creating a timer for each animation in terms of performance.

Functions

Ecore_Animator * ecore_animator_add (Ecore_Task_Cb func, const void *data)
 Adds an animator to call func at every animation tick during main loop execution.
Ecore_Animator * ecore_animator_timeline_add (double runtime, Ecore_Timeline_Cb func, const void *data)
 Adds an animator that runs for a limited time.
void * ecore_animator_del (Ecore_Animator *animator)
 Deletes the specified animator from the animator list.
void ecore_animator_freeze (Ecore_Animator *animator)
 Suspends the specified animator.
void ecore_animator_thaw (Ecore_Animator *animator)
 Restores execution of the specified animator.
void ecore_animator_frametime_set (double frametime)
 Sets the animator call interval in seconds.
double ecore_animator_frametime_get (void)
 Gets the animator call interval in seconds.
double ecore_animator_pos_map (double pos, Ecore_Pos_Map map, double v1, double v2)
 Maps an input position from 0.0 to 1.0 along a timeline to a position in a different curve.
void ecore_animator_source_set (Ecore_Animator_Source source)
 Sets the source of the animator ticks for the mainloop.
Ecore_Animator_Source ecore_animator_source_get (void)
 Gets the animator source currently set.
void ecore_animator_custom_source_tick_begin_callback_set (Ecore_Cb func, const void *data)
 Sets the function that begins a custom animator tick source.
void ecore_animator_custom_source_tick_end_callback_set (Ecore_Cb func, const void *data)
 Sets the function that ends a custom animator tick source.
void ecore_animator_custom_tick (void)
 Triggers a custom animator tick.

Typedefs

typedef struct _Ecore_Animator Ecore_Animator
 handle for ecore animator.
typedef enum _Ecore_Pos_Map Ecore_Pos_Map
 typedef to enum _Ecore_Pos_Map
typedef enum _Ecore_Animator_Source Ecore_Animator_Source
 typedef to enum _Ecore_Animator_Source
typedef Eina_Bool(* Ecore_Timeline_Cb )(void *data, double pos)
 The boolean type for a callback run for a task (animators with runtimes)

Enumeration Type Documentation

enum _Ecore_Animator_Source

Enumeration that defines the timing sources for animators.

Enumerator:
ECORE_ANIMATOR_SOURCE_TIMER 

The default system clock/timer based animator that ticks every "frametime" seconds

ECORE_ANIMATOR_SOURCE_CUSTOM 

A custom animator trigger which ticks when you call ecore_animator_trigger()

enum _Ecore_Pos_Map

Enumeration that defines the position mappings for the animation.

Enumerator:
ECORE_POS_MAP_LINEAR 

Linear 0.0 -> 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 being linear, 1.0 being normal accelerate, 2.0 being much more pronounced accelerate (squared), 3.0 being cubed, and so on

ECORE_POS_MAP_DECELERATE_FACTOR 

Start fast then slow down, v1 being a power factor, 0.0 being linear, 1.0 being normal decelerate, 2.0 being much more pronounced decelerate (squared), 3.0 being cubed, and so on

ECORE_POS_MAP_SINUSOIDAL_FACTOR 

Start slow, speed up then slow down at the end, v1 being a power factor, 0.0 being linear, 1.0 being normal sinusoidal, 2.0 being much more pronounced sinusoidal (squared), 3.0 being cubed, and so on

ECORE_POS_MAP_DIVISOR_INTERP 

Start at gradient * v1, interpolated via 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 decay factor of v1

ECORE_POS_MAP_SPRING 

Start at 0.0 then "wobble" like a spring with rest position 1.0, and wobble v2 times, with decay factor of v1

ECORE_POS_MAP_CUBIC_BEZIER 

Follow the cubic-bezier curve calculated with the points (x1, y1), (x2, y2)

Function Documentation

Ecore_Animator* ecore_animator_add ( Ecore_Task_Cb  func,
const void *  data 
)

Adds an animator to call func at every animation tick during main loop execution.

This function adds an animator and returns its handle on success, and NULL on failure. The function func is called every N seconds where N is the frametime interval set by ecore_animator_frametime_set(). The function is passed the data pointer as its parameter.

Since :
2.3.1
Remarks:
When the animator func is called, it must return a value of either 1 or 0. If it returns 1 (or ECORE_CALLBACK_RENEW), it is called again at the next tick, or if it returns 0 (or ECORE_CALLBACK_CANCEL) it is deleted automatically making any references/handles for it invalid.
The default frametime value is 1/30th of a second.
Parameters:
[in]funcThe function to call when it ticks off
[in]dataThe data to pass to the function
Returns:
A handle to the new animator
See also:
ecore_animator_timeline_add()
ecore_animator_frametime_set()
void ecore_animator_custom_source_tick_begin_callback_set ( Ecore_Cb  func,
const void *  data 
)

Sets the function that begins a custom animator tick source.

Since :
2.3.1
Remarks:
The Ecore Animator infrastructure handles tracking of whether animators are needed and which ones need to be called and when, but when the tick source is custom, you have to provide a tick source by calling ecore_animator_custom_tick() to indicate that a frame tick happened. In order to allow the source of ticks to be dynamically enabled or disabled as needed, func when set is called to enable the tick source to produce tick events that call ecore_animator_custom_tick(). If func is NULL then no function is called to begin custom ticking.
Parameters:
[in]funcThe function to call when ticking is to begin
[in]dataThe data passed to the tick begin function as its parameter
See also:
ecore_animator_source_set()
ecore_animator_custom_source_tick_end_callback_set()
ecore_animator_custom_tick()
void ecore_animator_custom_source_tick_end_callback_set ( Ecore_Cb  func,
const void *  data 
)

Sets the function that ends a custom animator tick source.

Since :
2.3.1
Remarks:
This function is a matching pair to the function set by ecore_animator_custom_source_tick_begin_callback_set() and is called when ticking is to stop. If func is NULL then no function is called to stop ticking. For more information see ecore_animator_custom_source_tick_begin_callback_set().
Parameters:
[in]funcThe function to call when ticking is to end
[in]dataThe data passed to the tick end function as its parameter
See also:
ecore_animator_source_set()
ecore_animator_custom_source_tick_begin_callback_set()
ecore_animator_custom_tick()
void ecore_animator_custom_tick ( void  )

Triggers a custom animator tick.

Since :
2.3.1
Remarks:
When animator source is set to ECORE_ANIMATOR_SOURCE_CUSTOM, then calling this function triggers a run of all animators currently registered with Ecore as this indicates that a "frame tick" happened. This does nothing if the animator source(set by ecore_animator_source_set()) is not set to ECORE_ANIMATOR_SOURCE_CUSTOM.
See also:
ecore_animator_source_set()
ecore_animator_custom_source_tick_begin_callback_set
ecore_animator_custom_source_tick_end_callback_set()()
void* ecore_animator_del ( Ecore_Animator *  animator)

Deletes the specified animator from the animator list.

This deletes the specified animator from the set of animators that are executed during main loop execution. This function returns the data parameter that is being passed to the callback on success, otherwise NULL on failure. After this call returns the specified animator object animator is invalid and should not be used again. It does not get called again after deletion.

Since :
2.3.1
Parameters:
[in]animatorThe animator to delete
Returns:
The data pointer set for the animator on add
double ecore_animator_frametime_get ( void  )

Gets the animator call interval in seconds.

This function retrieves the time in seconds between animator ticks.

Since :
2.3.1
Returns:
The time in seconds between animator ticks
See also:
ecore_animator_frametime_set()
void ecore_animator_frametime_set ( double  frametime)

Sets the animator call interval in seconds.

This function sets the time interval (in seconds) between animator ticks. At every tick the callback of every existing animator is called.

Since :
2.3.1
Remarks:
Too small a value may cause performance issues and too high a value may cause your animation to look "jerky".
The default frametime value is 1/30th of a second.
Parameters:
[in]frametimeThe time in seconds between animator ticks
void ecore_animator_freeze ( Ecore_Animator *  animator)

Suspends the specified animator.

Since :
2.3.1
Remarks:
The specified animator is temporarily removed from the set of animators that are executed during the main loop.
Freezing an animator doesn't freeze accounting of how long that animator has been running. Therefore if the animator is created with ecore_animator_timeline_add() the pos argument given to the callback increases as if the animator hadn't been frozen and the animator may have its execution halted if runtime elapses.
Parameters:
[in]animatorThe animator to delete
double ecore_animator_pos_map ( double  pos,
Ecore_Pos_Map  map,
double  v1,
double  v2 
)

Maps an input position from 0.0 to 1.0 along a timeline to a position in a different curve.

This takes an input position (0.0 to 1.0) and maps it to a new position (normally between 0.0 and 1.0, but it may go above/below 0.0 or 1.0 to show that it has "overshot" the mark) using some interpolation (mapping) algorithm.

Since :
2.3.1
Remarks:
This function is useful to create non-linear animations. It offers a variety of possible animation curves to be used:
  • ECORE_POS_MAP_LINEAR - Linear, returns pos.
  • 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 being linear, 1.0 being ECORE_POS_MAP_ACCELERATE, 2.0 being much more pronounced accelerate (squared), 3.0 being cubed, and so on.
  • ECORE_POS_MAP_DECELERATE_FACTOR - Start fast then slow down, v1 being a power factor, 0.0 being linear, 1.0 being ECORE_POS_MAP_DECELERATE, 2.0 being much more pronounced decelerate (squared), 3.0 being cubed, and so on.
  • ECORE_POS_MAP_SINUSOIDAL_FACTOR - Start slow, speed up then slow down at the end, v1 being a power factor, 0.0 being linear, 1.0 being ECORE_POS_MAP_SINUSOIDAL, 2.0 being much more pronounced sinusoidal (squared), 3.0 being cubed, and so on.
  • ECORE_POS_MAP_DIVISOR_INTERP - Start at gradient * v1, interpolated via 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 decay factor of v1.
  • ECORE_POS_MAP_SPRING - Start at 0.0 then "wobble" like a spring with rest position 1.0, and wobble v2 times, with decay factor of v1
When not listed v1 and v2 have no effect.
ecore-pos-map.png
Remarks:
One way to use this would be: 
 double pos; // input position in a timeline from 0.0 to 1.0
 double out; // output position after mapping
 int x1, y1, x2, y2; // x1 & y1 are start position, x2 & y2 are end position
 int x, y; // x & y are the calculated position

 out = ecore_animator_pos_map(pos, ECORE_POS_MAP_BOUNCE, 1.8, 7);
 x = (x1 * out) + (x2 * (1.0 - out));
 y = (y1 * out) + (y2 * (1.0 - out));
 move_my_object_to(myobject, x, y);
This makes an animation that bounces 7 diminish each time by a factor of 1.8.
Parameters:
[in]posThe input position to map
[in]mapThe mapping to use
[in]v1A parameter used by the mapping (pass 0.0 if not used)
[in]v2A parameter used by the mapping (pass 0.0 if not used)
Returns:
The mapped value
See also:
_Ecore_Pos_Map
Since (EFL) :
1.1.0
Ecore_Animator_Source ecore_animator_source_get ( void  )

Gets the animator source currently set.

This gets the current animator source.

Since :
2.3.1
Returns:
The current animator source
See also:
ecore_animator_source_set()
void ecore_animator_source_set ( Ecore_Animator_Source  source)

Sets the source of the animator ticks for the mainloop.

This sets the source of the animator ticks. When an animator is active the mainloop will "tick" over frame by frame calling all animators that are registered until none are left. The mainloop ticks at a given rate based on the animator source. The default source is the system clock timer source - ECORE_ANIMATOR_SOURCE_TIMER. This source uses the system clock to tick over every N seconds (specified by ecore_animator_frametime_set(), with the default being 1/30th of a second unless set otherwise). You can set a custom tick source by setting the source to ECORE_ANIMATOR_SOURCE_CUSTOM and then driving it yourself based on some input tick source (like another application via ipc, some vertical blanking interrupt and so on) using ecore_animator_custom_source_tick_begin_callback_set() and ecore_animator_custom_source_tick_end_callback_set() to set the functions that are called to start and stop the ticking source, which when gets a "tick" should call ecore_animator_custom_tick() to make the "tick" over 1 frame.

Since :
2.3.1
Parameters:
[in]sourceThe source of the animator ticks to use
void ecore_animator_thaw ( Ecore_Animator *  animator)

Restores execution of the specified animator.

Since :
2.3.1
Remarks:
The specified animator is put back in the set of animators that are executed during the main loop.
Parameters:
[in]animatorThe animator to delete
Ecore_Animator* ecore_animator_timeline_add ( double  runtime,
Ecore_Timeline_Cb  func,
const void *  data 
)

Adds an animator that runs for a limited time.

This function is just like ecore_animator_add() except that the animator only runs for a limited time specified in seconds by runtime. Once the runtime of the animator has elapsed (animator finished) it is automatically deleted. The callback function func can return ECORE_CALLBACK_RENEW to keep the animator running or ECORE_CALLBACK_CANCEL to stop it and have it deleted automatically at any time.

Since (EFL) :
1.1.0
Since :
2.3.1
Remarks:
The func is ALSO passed a position parameter that has a value from 0.0 to 1.0 to indicate where along the timeline (0.0 for start, 1.0 for end) is the animator run at. If the callback wishes not to have a linear transition it can "map" this value to one of the several curves and mappings via ecore_animator_pos_map().
The default frametime value is 1/30th of a second.
Parameters:
[in]runtimeThe time to run in seconds
[in]funcThe function to call when it ticks off
[in]dataThe data to pass to the function
Returns:
A handle to the new animator
See also:
ecore_animator_add()
ecore_animator_pos_map()