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 animation 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 in lv_conf.h. 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 be assigned to the Lottie Widget. The animations are rendered in ARGB8888 format, therefore 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 of storing the JSON string, a hex array is stored for the following reasons:

to avoid escaping " character in the JSON file, and
some compilers don't support very long strings.

lvgl/scripts/filetohex.py can be used to convert a Lottie file to a hex array. E.g.:

./filetohex.py path/to/lottie.json --filter-character --null-terminate > out.txt

--filter-character filters out non-ASCII characters and --null-terminate makes sure that a trailing zero is appended to properly close the string.

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)

returns 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 events are emitted by Lottie Widgets.

Keys

No keys are processed by Lottie Widgets.

Example

Load a Lottie animation from an array

#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

#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*/

API

lv_lottie.h