Lottie (lv_lottie)
Overview
The Lottie widget is capable of parsing, rasterizing, and playing Lottie animations.
The Lottie animations are vector based animation. Think of it as the modern combination of SVG and GIF.
The animations can be downloaded from various sources, such as https://lottiefiles.com/ or you can create your own animations using for example Adobe After Effects.
The Lottie widget is based on Canvas (lv_canvas) because in order to render the animation the user needs to provide a buffer where the current frame is stored.
Parts and Styles
LV_PART_MAIN
The background of the Lottie animation. The typical background style properties apply but usually it is left transparent.
Usage
Dependencies
The Lottie widget uses the ThorVG library which is integrated into LVGL.
In order to use Lottie animations LV_USE_THORVG_INTERNAL
(to use the built-in ThorVG) or
LV_USE_THORVG_EXTERNAL
(to link it externally) needs to enabled. For vector graphics in general
LV_USE_VECTOR_GRAPHIC
also needs to be enabled.
As ThorVG is written in C++, when using LV_USE_THORVG_INTERNAL
be sure that you
can compile the cpp files.
Set a buffer
In order to render the animation a buffer needs to assign to the Lottie widget.
The animations are rendered in ARGB8888 format, therefor the buffer's size should be equal to
target_width x target_height x 4
bytes.
To keep the buffer size and the animation size consistent, the size of the widget (i.e. the size of the animation) is set to the dimensions of the buffer internally.
The buffer can be set with either lv_lottie_set_buffer(lottie, w, h, buf) or lv_lottie_set_draw_buf(lottie, draw_buf).
When a draw buffer is used, it must be already initialized by the user with LV_COLOR_FORMAT_ARGB8888
color format.
Set a source
lv_example_lottie_approve.c
contains an example animation. Instead storing the JSON string, a hex array is stored for the
following reasons:
- avoid escaping "
character in the JSON file
- some compilers don't support very long strings
lvgl/scripts/filetohex.py
can be used to convert a Lottie file a hex
array. E.g.:
./filetohex.py path/to/lottie.json > out.txt
To create an animation from data use lv_lottie_set_src_data(lottie, data, sizeof(data))
Lottie animations can be opened from JSON files by using lv_lottie_set_src_file(lottie, "path/to/file.json"). Note that the Lottie loader doesn't support LVGL's File System interface but a "normal path" should be used without a driver letter.
Get the animation
lv_anim_t * a = lv_lottie_get_anim(lottie)
return the LVGL animation which controls the
Lottie animation. By default it is running infinitely at 60FPS however the LVGL animation
can be freely adjusted.
Events
No Keys are processed by Lottie Widgets.
Further Reading
Learn more about Base-Widget Events emitted by all Widgets.
Learn more about Events.
Keys
No keys are processed by Lottie Widgets.
Further Reading
Learn more about Keys.
Example
Load a Lottie animation from an array
C code
View on GitHub#include "../../lv_examples.h"
#if LV_BUILD_EXAMPLES
#if LV_USE_LOTTIE
/**
* Load an lottie animation from data
*/
void lv_example_lottie_1(void)
{
extern const uint8_t lv_example_lottie_approve[];
extern const size_t lv_example_lottie_approve_size;
lv_obj_t * lottie = lv_lottie_create(lv_screen_active());
lv_lottie_set_src_data(lottie, lv_example_lottie_approve, lv_example_lottie_approve_size);
#if LV_DRAW_BUF_ALIGN == 4 && LV_DRAW_BUF_STRIDE_ALIGN == 1
/*If there are no special requirements, just declare a buffer
x4 because the Lottie is rendered in ARGB8888 format*/
static uint8_t buf[64 * 64 * 4];
lv_lottie_set_buffer(lottie, 64, 64, buf);
#else
/*For GPUs and special alignment/strid setting use a draw_buf instead*/
LV_DRAW_BUF_DEFINE(draw_buf, 64, 64, LV_COLOR_FORMAT_ARGB8888);
lv_lottie_set_draw_buf(lottie, &draw_buf);
#endif
lv_obj_center(lottie);
}
#else
void lv_example_lottie_1(void)
{
/*fallback for online examples*/
lv_obj_t * label = lv_label_create(lv_screen_active());
lv_label_set_text(label, "Lottie cannot be previewed online");
lv_obj_center(label);
}
#endif /*LV_USE_LOTTIE*/
#endif /*LV_BUILD_EXAMPLES*/
Load a Lottie animation from file
C code
View on GitHub#include "../../lv_examples.h"
#if LV_BUILD_EXAMPLES
#if LV_USE_LOTTIE
/**
* Load an lottie animation from file
*/
void lv_example_lottie_2(void)
{
lv_obj_t * lottie = lv_lottie_create(lv_screen_active());
lv_lottie_set_src_file(lottie, "lvgl/examples/widgets/lottie/lv_example_lottie_approve.json");
#if LV_DRAW_BUF_ALIGN == 4 && LV_DRAW_BUF_STRIDE_ALIGN == 1
/*If there are no special requirements, just declare a buffer
x4 because the Lottie is rendered in ARGB8888 format*/
static uint8_t buf[64 * 64 * 4];
lv_lottie_set_buffer(lottie, 64, 64, buf);
#else
/*For GPUs and special alignment/strid setting use a draw_buf instead*/
LV_DRAW_BUF_DEFINE(draw_buf, 64, 64, LV_COLOR_FORMAT_ARGB8888);
lv_lottie_set_draw_buf(lottie, &draw_buf);
#endif
lv_obj_center(lottie);
}
#else
void lv_example_lottie_2(void)
{
/*fallback for online examples*/
lv_obj_t * label = lv_label_create(lv_screen_active());
lv_label_set_text(label, "Lottie cannot be previewed online");
lv_obj_center(label);
}
#endif /*LV_USE_LOTTIE*/
#endif /*LV_BUILD_EXAMPLES*/