feat(lottie): add ThorVG based lottie widget

lvgl · May 23, 2024 · 9c5ca0e · 9c5ca0e
1 parent f34ec4b
commit 9c5ca0e
Show file tree

Hide file tree

Showing 25 changed files with 805 additions and 5 deletions.
diff --git a/Kconfig b/Kconfig
@@ -943,6 +943,12 @@ menu "LVGL configuration"
 		config LV_USE_LIST
 			bool "List"
 			default y if !LV_CONF_MINIMAL
+		config LV_USE_LOTTIE
+			bool "Lottie"
+			default n
+			depends on LV_USE_VECTOR_GRAPHIC && (LV_USE_THORVG_INTERNAL || LV_USE_THORVG_EXTERNAL)
+			help
+				Enable Lottie animations. Requires LV_USE_VECTOR_GRAPHIC and LV_USE_THORVG_INTERNAL or LV_USE_THORVG_EXTERNAL.
 		config LV_USE_MENU
 			bool "Menu"
 			default y if !LV_CONF_MINIMAL
@@ -1176,7 +1182,7 @@ menu "LVGL configuration"
 
 		config LV_USE_RLOTTIE
 			bool "Lottie library"
-	
+
 		config LV_USE_THORVG
 			bool "ThorVG library"
 			choice

diff --git a/docs/libs/rlottie.rst b/docs/libs/rlottie.rst
@@ -1,8 +1,11 @@
 .. _rlottie:
 
-=============
-Lottie player
-=============
+==============
+Rlottie player
+==============
+
+.. warning::
+   Rlottie is deprecated. Consider using :ref:`lv_lottie` instead.
 
 Allows playing Lottie animations in LVGL. Taken from `lv_rlottie <https://github.com/ValentiWorkLearning/lv_rlottie>`__.
 
@@ -176,7 +179,7 @@ limitations:
 
 - Build the lottie animation to be sized for the intended size
 - it can scale/resize, but performance will be best when the base lottie size is as intended
-- Limit total number of frames, the longer the lottie animation is, 
+- Limit total number of frames, the longer the lottie animation is,
 the more memory it will consume for rendering (rlottie consumes IRAM for rendering)
 - Build the lottie animation for the intended frame rate
 - default lottie is 60fps, embedded LCDs likely won't go above 30fps

diff --git a/docs/widgets/lottie.rst b/docs/widgets/lottie.rst
@@ -0,0 +1,113 @@
+.. _lv_lottie:
+
+==================
+Lottie (lv_lottie)
+==================
+
+Overview
+********
+
+The Lottie widget is capable of parsing, rasterizing, and playing `Lottie animations <https://lottiefiles.com>`__.
+
+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/ <https://lottiefiles.com/>`__
+or you can create your own animations using for example Adobe After Effects.
+
+The Lottie widget is based on :ref:`lv_canvas` because in order to render the animation
+the user needs to provide a buffer where the current frame is stored.
+
+.. _lv_lottie_parts_and_styles:
+
+Parts and Styles
+****************
+
+-  :cpp:enumerator:`LV_PART_MAIN` The background of the Lottie animation. The typical background style properties apply but usually it is left transparent.
+
+.. _lv_lottie_usage:
+
+Usage
+*****
+
+Dependencies
+------------
+
+The Lottie widget uses the `ThorVG <https://github.com/thorvg/thorvg>`__ library which is `integrated into LVGL <https://github.com/lvgl/lvgl/tree/master/src/libs/thorvg>`__.
+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 :cpp:expr:`void lv_lottie_set_buffer(lottie, w, h, buf);`
+or :cpp:expr:`lv_lottie_set_draw_buf(lottie, draw_buf)`.
+
+When a draw buffer is used, it must be already initialized by the user with :cpp:expr:`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.:
+
+.. code:: shell
+
+   ./filetohex.py path/to/lottie.json > out.txt
+
+To create an animation from data use
+:cpp:enumerator:`lv_lottie_set_src_data(lottie, data, sizeof(data))`
+
+Lottie animations can be opened from JSON files by using :cpp:enumerator:`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.
+
+.. _lv_lottie_events:
+
+Events
+******
+
+No special events are sent by the Lottie widget.
+
+Learn more about :ref:`events`.
+
+.. _lv_lottie_keys:
+
+Keys
+****
+
+No keys are processed by the Lottie widget
+Learn more about :ref:`indev_keys`.
+
+.. _lv_lottie_example:
+
+Example
+*******
+
+.. include:: ../examples/widgets/lottie/index.rst
+
+.. _lv_lottie_api:
+
+API
+***
diff --git a/examples/widgets/lottie/index.rst b/examples/widgets/lottie/index.rst
@@ -0,0 +1,11 @@
+Load a Lottie animation from an array
+-------------------------------------
+
+.. lv_example:: libs/lottie/lv_example_lottie_1
+  :language: c
+
+Load a Lottie animation from file
+---------------------------------
+
+.. lv_example:: libs/lottie/lv_example_lottie_2
+  :language: c
diff --git a/examples/widgets/lottie/lv_example_lottie_1.c b/examples/widgets/lottie/lv_example_lottie_1.c
@@ -0,0 +1,43 @@
+#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 alignemnt/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*/
diff --git a/examples/widgets/lottie/lv_example_lottie_2.c b/examples/widgets/lottie/lv_example_lottie_2.c
@@ -0,0 +1,41 @@
+#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 alignemnt/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*/