1 /**
2 * @file lv_anim.h
3 *
4 */
5
6 #ifndef LV_ANIM_H
7 #define LV_ANIM_H
8
9 #ifdef __cplusplus
10 extern "C" {
11 #endif
12
13 /*********************
14 * INCLUDES
15 *********************/
16 #include "../lv_conf_internal.h"
17
18 #include <stdint.h>
19 #include <stdbool.h>
20 #include <stddef.h>
21
22 /*********************
23 * DEFINES
24 *********************/
25
26 #define LV_ANIM_REPEAT_INFINITE 0xFFFF
27 #define LV_ANIM_PLAYTIME_INFINITE 0xFFFFFFFF
28
29 LV_EXPORT_CONST_INT(LV_ANIM_REPEAT_INFINITE);
30 LV_EXPORT_CONST_INT(LV_ANIM_PLAYTIME_INFINITE);
31
32 /**********************
33 * TYPEDEFS
34 **********************/
35
36 /** Can be used to indicate if animations are enabled or disabled in a case*/
37 typedef enum {
38 LV_ANIM_OFF,
39 LV_ANIM_ON,
40 } lv_anim_enable_t;
41
42 struct _lv_anim_t;
43 struct _lv_timer_t;
44
45 /** Get the current value during an animation*/
46 typedef int32_t (*lv_anim_path_cb_t)(const struct _lv_anim_t *);
47
48 /** Generic prototype of "animator" functions.
49 * First parameter is the variable to animate.
50 * Second parameter is the value to set.
51 * Compatible with `lv_xxx_set_yyy(obj, value)` functions
52 * The `x` in `_xcb_t` means it's not a fully generic prototype because
53 * it doesn't receive `lv_anim_t *` as its first argument*/
54 typedef void (*lv_anim_exec_xcb_t)(void *, int32_t);
55
56 /** Same as `lv_anim_exec_xcb_t` but receives `lv_anim_t *` as the first parameter.
57 * It's more consistent but less convenient. Might be used by binding generator functions.*/
58 typedef void (*lv_anim_custom_exec_cb_t)(struct _lv_anim_t *, int32_t);
59
60 /** Callback to call when the animation is ready*/
61 typedef void (*lv_anim_ready_cb_t)(struct _lv_anim_t *);
62
63 /** Callback to call when the animation really stars (considering `delay`)*/
64 typedef void (*lv_anim_start_cb_t)(struct _lv_anim_t *);
65
66 /** Callback used when the animation values are relative to get the current value*/
67 typedef int32_t (*lv_anim_get_value_cb_t)(struct _lv_anim_t *);
68
69 /** Callback used when the animation is deleted*/
70 typedef void (*lv_anim_deleted_cb_t)(struct _lv_anim_t *);
71
72 /** Describes an animation*/
73 typedef struct _lv_anim_t {
74 void * var; /**<Variable to animate*/
75 lv_anim_exec_xcb_t exec_cb; /**< Function to execute to animate*/
76 lv_anim_start_cb_t start_cb; /**< Call it when the animation is starts (considering `delay`)*/
77 lv_anim_ready_cb_t ready_cb; /**< Call it when the animation is ready*/
78 lv_anim_deleted_cb_t deleted_cb; /**< Call it when the animation is deleted*/
79 lv_anim_get_value_cb_t get_value_cb; /**< Get the current value in relative mode*/
80 #if LV_USE_USER_DATA
81 void * user_data; /**< Custom user data*/
82 #endif
83 lv_anim_path_cb_t path_cb; /**< Describe the path (curve) of animations*/
84 int32_t start_value; /**< Start value*/
85 int32_t current_value; /**< Current value*/
86 int32_t end_value; /**< End value*/
87 int32_t time; /**< Animation time in ms*/
88 int32_t act_time; /**< Current time in animation. Set to negative to make delay.*/
89 uint32_t playback_delay; /**< Wait before play back*/
90 uint32_t playback_time; /**< Duration of playback animation*/
91 uint32_t repeat_delay; /**< Wait before repeat*/
92 uint16_t repeat_cnt; /**< Repeat count for the animation*/
93 uint8_t early_apply : 1; /**< 1: Apply start value immediately even is there is `delay`*/
94
95 /*Animation system use these - user shouldn't set*/
96 uint8_t playback_now : 1; /**< Play back is in progress*/
97 uint8_t run_round : 1; /**< Indicates the animation has run in this round*/
98 uint8_t start_cb_called : 1; /**< Indicates that the `start_cb` was already called*/
99 } lv_anim_t;
100
101 /**********************
102 * GLOBAL PROTOTYPES
103 **********************/
104
105 /**
106 * Init. the animation module
107 */
108 void _lv_anim_core_init(void);
109
110 /**
111 * Initialize an animation variable.
112 * E.g.:
113 * lv_anim_t a;
114 * lv_anim_init(&a);
115 * lv_anim_set_...(&a);
116 * lv_anim_start(&a);
117 * @param a pointer to an `lv_anim_t` variable to initialize
118 */
119 void lv_anim_init(lv_anim_t * a);
120
121 /**
122 * Set a variable to animate
123 * @param a pointer to an initialized `lv_anim_t` variable
124 * @param var pointer to a variable to animate
125 */
lv_anim_set_var(lv_anim_t * a,void * var)126 static inline void lv_anim_set_var(lv_anim_t * a, void * var)
127 {
128 a->var = var;
129 }
130
131 /**
132 * Set a function to animate `var`
133 * @param a pointer to an initialized `lv_anim_t` variable
134 * @param exec_cb a function to execute during animation
135 * LVGL's built-in functions can be used.
136 * E.g. lv_obj_set_x
137 */
lv_anim_set_exec_cb(lv_anim_t * a,lv_anim_exec_xcb_t exec_cb)138 static inline void lv_anim_set_exec_cb(lv_anim_t * a, lv_anim_exec_xcb_t exec_cb)
139 {
140 a->exec_cb = exec_cb;
141 }
142
143 /**
144 * Set the duration of an animation
145 * @param a pointer to an initialized `lv_anim_t` variable
146 * @param duration duration of the animation in milliseconds
147 */
lv_anim_set_time(lv_anim_t * a,uint32_t duration)148 static inline void lv_anim_set_time(lv_anim_t * a, uint32_t duration)
149 {
150 a->time = duration;
151 }
152
153 /**
154 * Set a delay before starting the animation
155 * @param a pointer to an initialized `lv_anim_t` variable
156 * @param delay delay before the animation in milliseconds
157 */
lv_anim_set_delay(lv_anim_t * a,uint32_t delay)158 static inline void lv_anim_set_delay(lv_anim_t * a, uint32_t delay)
159 {
160 a->act_time = -(int32_t)(delay);
161 }
162
163 /**
164 * Set the start and end values of an animation
165 * @param a pointer to an initialized `lv_anim_t` variable
166 * @param start the start value
167 * @param end the end value
168 */
lv_anim_set_values(lv_anim_t * a,int32_t start,int32_t end)169 static inline void lv_anim_set_values(lv_anim_t * a, int32_t start, int32_t end)
170 {
171 a->start_value = start;
172 a->current_value = start;
173 a->end_value = end;
174 }
175
176 /**
177 * Similar to `lv_anim_set_exec_cb` but `lv_anim_custom_exec_cb_t` receives
178 * `lv_anim_t * ` as its first parameter instead of `void *`.
179 * This function might be used when LVGL is bound to other languages because
180 * it's more consistent to have `lv_anim_t *` as first parameter.
181 * The variable to animate can be stored in the animation's `user_data`
182 * @param a pointer to an initialized `lv_anim_t` variable
183 * @param exec_cb a function to execute.
184 */
lv_anim_set_custom_exec_cb(lv_anim_t * a,lv_anim_custom_exec_cb_t exec_cb)185 static inline void lv_anim_set_custom_exec_cb(lv_anim_t * a, lv_anim_custom_exec_cb_t exec_cb)
186 {
187 a->var = a;
188 a->exec_cb = (lv_anim_exec_xcb_t)exec_cb;
189 }
190
191 /**
192 * Set the path (curve) of the animation.
193 * @param a pointer to an initialized `lv_anim_t` variable
194 * @param path_cb a function to set the current value of the animation.
195 */
lv_anim_set_path_cb(lv_anim_t * a,lv_anim_path_cb_t path_cb)196 static inline void lv_anim_set_path_cb(lv_anim_t * a, lv_anim_path_cb_t path_cb)
197 {
198 a->path_cb = path_cb;
199 }
200
201 /**
202 * Set a function call when the animation really starts (considering `delay`)
203 * @param a pointer to an initialized `lv_anim_t` variable
204 * @param start_cb a function call when the animation starts
205 */
lv_anim_set_start_cb(lv_anim_t * a,lv_anim_start_cb_t start_cb)206 static inline void lv_anim_set_start_cb(lv_anim_t * a, lv_anim_start_cb_t start_cb)
207 {
208 a->start_cb = start_cb;
209 }
210
211 /**
212 * Set a function to use the current value of the variable and make start and end value
213 * relative to the returned current value.
214 * @param a pointer to an initialized `lv_anim_t` variable
215 * @param get_value_cb a function call when the animation starts
216 */
lv_anim_set_get_value_cb(lv_anim_t * a,lv_anim_get_value_cb_t get_value_cb)217 static inline void lv_anim_set_get_value_cb(lv_anim_t * a, lv_anim_get_value_cb_t get_value_cb)
218 {
219 a->get_value_cb = get_value_cb;
220 }
221
222 /**
223 * Set a function call when the animation is ready
224 * @param a pointer to an initialized `lv_anim_t` variable
225 * @param ready_cb a function call when the animation is ready
226 */
lv_anim_set_ready_cb(lv_anim_t * a,lv_anim_ready_cb_t ready_cb)227 static inline void lv_anim_set_ready_cb(lv_anim_t * a, lv_anim_ready_cb_t ready_cb)
228 {
229 a->ready_cb = ready_cb;
230 }
231
232 /**
233 * Set a function call when the animation is deleted.
234 * @param a pointer to an initialized `lv_anim_t` variable
235 * @param deleted_cb a function call when the animation is deleted
236 */
lv_anim_set_deleted_cb(lv_anim_t * a,lv_anim_deleted_cb_t deleted_cb)237 static inline void lv_anim_set_deleted_cb(lv_anim_t * a, lv_anim_deleted_cb_t deleted_cb)
238 {
239 a->deleted_cb = deleted_cb;
240 }
241
242 /**
243 * Make the animation to play back to when the forward direction is ready
244 * @param a pointer to an initialized `lv_anim_t` variable
245 * @param time the duration of the playback animation in milliseconds. 0: disable playback
246 */
lv_anim_set_playback_time(lv_anim_t * a,uint32_t time)247 static inline void lv_anim_set_playback_time(lv_anim_t * a, uint32_t time)
248 {
249 a->playback_time = time;
250 }
251
252 /**
253 * Make the animation to play back to when the forward direction is ready
254 * @param a pointer to an initialized `lv_anim_t` variable
255 * @param delay delay in milliseconds before starting the playback animation.
256 */
lv_anim_set_playback_delay(lv_anim_t * a,uint32_t delay)257 static inline void lv_anim_set_playback_delay(lv_anim_t * a, uint32_t delay)
258 {
259 a->playback_delay = delay;
260 }
261
262 /**
263 * Make the animation repeat itself.
264 * @param a pointer to an initialized `lv_anim_t` variable
265 * @param cnt repeat count or `LV_ANIM_REPEAT_INFINITE` for infinite repetition. 0: to disable repetition.
266 */
lv_anim_set_repeat_count(lv_anim_t * a,uint16_t cnt)267 static inline void lv_anim_set_repeat_count(lv_anim_t * a, uint16_t cnt)
268 {
269 a->repeat_cnt = cnt;
270 }
271
272 /**
273 * Set a delay before repeating the animation.
274 * @param a pointer to an initialized `lv_anim_t` variable
275 * @param delay delay in milliseconds before repeating the animation.
276 */
lv_anim_set_repeat_delay(lv_anim_t * a,uint32_t delay)277 static inline void lv_anim_set_repeat_delay(lv_anim_t * a, uint32_t delay)
278 {
279 a->repeat_delay = delay;
280 }
281
282 /**
283 * Set a whether the animation's should be applied immediately or only when the delay expired.
284 * @param a pointer to an initialized `lv_anim_t` variable
285 * @param en true: apply the start value immediately in `lv_anim_start`;
286 * false: apply the start value only when `delay` ms is elapsed and the animations really starts
287 */
lv_anim_set_early_apply(lv_anim_t * a,bool en)288 static inline void lv_anim_set_early_apply(lv_anim_t * a, bool en)
289 {
290 a->early_apply = en;
291 }
292
293 /**
294 * Set the custom user data field of the animation.
295 * @param a pointer to an initialized `lv_anim_t` variable
296 * @param user_data pointer to the new user_data.
297 */
298 #if LV_USE_USER_DATA
lv_anim_set_user_data(lv_anim_t * a,void * user_data)299 static inline void lv_anim_set_user_data(lv_anim_t * a, void * user_data)
300 {
301 a->user_data = user_data;
302 }
303 #endif
304
305 /**
306 * Create an animation
307 * @param a an initialized 'anim_t' variable. Not required after call.
308 * @return pointer to the created animation (different from the `a` parameter)
309 */
310 lv_anim_t * lv_anim_start(const lv_anim_t * a);
311
312 /**
313 * Get a delay before starting the animation
314 * @param a pointer to an initialized `lv_anim_t` variable
315 * @return delay before the animation in milliseconds
316 */
lv_anim_get_delay(lv_anim_t * a)317 static inline uint32_t lv_anim_get_delay(lv_anim_t * a)
318 {
319 return -a->act_time;
320 }
321
322 /**
323 * Get the time used to play the animation.
324 * @param a pointer to an animation.
325 * @return the play time in milliseconds.
326 */
327 uint32_t lv_anim_get_playtime(lv_anim_t * a);
328
329 /**
330 * Get the user_data field of the animation
331 * @param a pointer to an initialized `lv_anim_t` variable
332 * @return the pointer to the custom user_data of the animation
333 */
334 #if LV_USE_USER_DATA
lv_anim_get_user_data(lv_anim_t * a)335 static inline void * lv_anim_get_user_data(lv_anim_t * a)
336 {
337 return a->user_data;
338 }
339 #endif
340
341 /**
342 * Delete an animation of a variable with a given animator function
343 * @param var pointer to variable
344 * @param exec_cb a function pointer which is animating 'var',
345 * or NULL to ignore it and delete all the animations of 'var
346 * @return true: at least 1 animation is deleted, false: no animation is deleted
347 */
348 bool lv_anim_del(void * var, lv_anim_exec_xcb_t exec_cb);
349
350 /**
351 * Delete all the animations
352 */
353 void lv_anim_del_all(void);
354
355 /**
356 * Get the animation of a variable and its `exec_cb`.
357 * @param var pointer to variable
358 * @param exec_cb a function pointer which is animating 'var', or NULL to return first matching 'var'
359 * @return pointer to the animation.
360 */
361 lv_anim_t * lv_anim_get(void * var, lv_anim_exec_xcb_t exec_cb);
362
363 /**
364 * Get global animation refresher timer.
365 * @return pointer to the animation refresher timer.
366 */
367 struct _lv_timer_t * lv_anim_get_timer(void);
368
369 /**
370 * Delete an animation by getting the animated variable from `a`.
371 * Only animations with `exec_cb` will be deleted.
372 * This function exists because it's logical that all anim. functions receives an
373 * `lv_anim_t` as their first parameter. It's not practical in C but might make
374 * the API more consequent and makes easier to generate bindings.
375 * @param a pointer to an animation.
376 * @param exec_cb a function pointer which is animating 'var',
377 * or NULL to ignore it and delete all the animations of 'var
378 * @return true: at least 1 animation is deleted, false: no animation is deleted
379 */
lv_anim_custom_del(lv_anim_t * a,lv_anim_custom_exec_cb_t exec_cb)380 static inline bool lv_anim_custom_del(lv_anim_t * a, lv_anim_custom_exec_cb_t exec_cb)
381 {
382 return lv_anim_del(a ? a->var : NULL, (lv_anim_exec_xcb_t)exec_cb);
383 }
384
385 /**
386 * Get the animation of a variable and its `exec_cb`.
387 * This function exists because it's logical that all anim. functions receives an
388 * `lv_anim_t` as their first parameter. It's not practical in C but might make
389 * the API more consequent and makes easier to generate bindings.
390 * @param a pointer to an animation.
391 * @param exec_cb a function pointer which is animating 'var', or NULL to return first matching 'var'
392 * @return pointer to the animation.
393 */
lv_anim_custom_get(lv_anim_t * a,lv_anim_custom_exec_cb_t exec_cb)394 static inline lv_anim_t * lv_anim_custom_get(lv_anim_t * a, lv_anim_custom_exec_cb_t exec_cb)
395 {
396 return lv_anim_get(a ? a->var : NULL, (lv_anim_exec_xcb_t)exec_cb);
397 }
398
399 /**
400 * Get the number of currently running animations
401 * @return the number of running animations
402 */
403 uint16_t lv_anim_count_running(void);
404
405 /**
406 * Calculate the time of an animation with a given speed and the start and end values
407 * @param speed speed of animation in unit/sec
408 * @param start start value of the animation
409 * @param end end value of the animation
410 * @return the required time [ms] for the animation with the given parameters
411 */
412 uint32_t lv_anim_speed_to_time(uint32_t speed, int32_t start, int32_t end);
413
414 /**
415 * Manually refresh the state of the animations.
416 * Useful to make the animations running in a blocking process where
417 * `lv_timer_handler` can't run for a while.
418 * Shouldn't be used directly because it is called in `lv_refr_now()`.
419 */
420 void lv_anim_refr_now(void);
421
422 /**
423 * Calculate the current value of an animation applying linear characteristic
424 * @param a pointer to an animation
425 * @return the current value to set
426 */
427 int32_t lv_anim_path_linear(const lv_anim_t * a);
428
429 /**
430 * Calculate the current value of an animation slowing down the start phase
431 * @param a pointer to an animation
432 * @return the current value to set
433 */
434 int32_t lv_anim_path_ease_in(const lv_anim_t * a);
435
436 /**
437 * Calculate the current value of an animation slowing down the end phase
438 * @param a pointer to an animation
439 * @return the current value to set
440 */
441 int32_t lv_anim_path_ease_out(const lv_anim_t * a);
442
443 /**
444 * Calculate the current value of an animation applying an "S" characteristic (cosine)
445 * @param a pointer to an animation
446 * @return the current value to set
447 */
448 int32_t lv_anim_path_ease_in_out(const lv_anim_t * a);
449
450 /**
451 * Calculate the current value of an animation with overshoot at the end
452 * @param a pointer to an animation
453 * @return the current value to set
454 */
455 int32_t lv_anim_path_overshoot(const lv_anim_t * a);
456
457 /**
458 * Calculate the current value of an animation with 3 bounces
459 * @param a pointer to an animation
460 * @return the current value to set
461 */
462 int32_t lv_anim_path_bounce(const lv_anim_t * a);
463
464 /**
465 * Calculate the current value of an animation applying step characteristic.
466 * (Set end value on the end of the animation)
467 * @param a pointer to an animation
468 * @return the current value to set
469 */
470 int32_t lv_anim_path_step(const lv_anim_t * a);
471
472 /**********************
473 * GLOBAL VARIABLES
474 **********************/
475
476 /**********************
477 * MACROS
478 **********************/
479
480 #ifdef __cplusplus
481 } /*extern "C"*/
482 #endif
483
484 #endif /*LV_ANIM_H*/
485
