acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
rlottie.md (3771B)
      1 ```eval_rst
      2 .. include:: /header.rst
      3 :github_url: |github_link_base|/libs/rlottie.md
      4 ```
      5 
      6 
      7 # Lottie player
      8 Allows to use Lottie animations in LVGL. Taken from this [base repository](https://github.com/ValentiWorkLearning/lv_rlottie)
      9 
     10 LVGL provides the interface to [Samsung/rlottie](https://github.com/Samsung/rlottie) library's C API. That is the actual Lottie player is not part of LVGL, it needs to be built separately.
     11 
     12 ## Build Rlottie
     13 To build Samsung's Rlottie C++14-compatible compiler and optionally CMake 3.14 or higher is required.
     14 
     15 To build on desktop you can follow the instructions from Rlottie's [README](https://github.com/Samsung/rlottie/blob/master/README.md). In the most basic case it looks like this:
     16 ```
     17 mkdir rlottie_workdir
     18 cd rlottie_workdir
     19 git clone https://github.com/Samsung/rlottie.git
     20 mkdir build
     21 cd build
     22 cmake ../rlottie
     23 make -j
     24 sudo make install
     25 ```
     26 
     27 And finally add the `-lrlottie` flag to your linker.
     28 
     29 On embedded systems you need to take care of integrating Rlottie to the given build system.
     30 
     31 
     32 ## Usage
     33 
     34 You can use animation from files or raw data (text). In either case first you need to enable `LV_USE_RLOTTIE` in `lv_conf.h`.
     35 
     36 
     37 The `width` and `height` of the object be set in the *create* function and the animation will be scaled accordingly.
     38 
     39 ### Use Rlottie from file
     40 
     41 To create a Lottie animation from file use:
     42 ```c
     43   lv_obj_t * lottie = lv_rlottie_create_from_file(parent, width, height, "path/to/lottie.json");
     44 ```
     45 
     46 Note that, Rlottie uses the standard STDIO C file API, so you can use the path "normally" and no LVGL specific driver letter is required.
     47 
     48 
     49 ### Use Rlottie from raw string data
     50 
     51 `lv_example_rlottie_approve.c` contains an example animation in raw format. Instead storing the JSON string a hex array is stored for the following reasons:
     52 - avoid escaping `"` in the JSON file
     53 - some compilers don't support very long strings
     54 
     55 `lvgl/scripts/filetohex.py` can be used to convert a Lottie file a hex array. E.g.:
     56 ```
     57 ./filetohex.py path/to/lottie.json > out.txt
     58 ```
     59 
     60 To create an animation from raw data:
     61 
     62 ```c
     63 extern const uint8_t lottie_data[];
     64 lv_obj_t* lottie = lv_rlottie_create_from_raw(parent, width, height, (const char *)lottie_data);
     65 ```
     66 
     67 ## Getting animations
     68 
     69 Lottie is standard and popular format so you can find many animation files on the web.
     70 For example: https://lottiefiles.com/
     71 
     72 You can also create your own animations with Adobe After Effects or similar software.
     73 
     74 ## Controlling animations
     75 
     76 LVGL provides two functions to control the animation mode: `lv_rlottie_set_play_mode` and `lv_rlottie_set_current_frame`.
     77 You'll combine your intentions when calling the first method, like in these examples:
     78 ```c
     79 lv_obj_t * lottie = lv_rlottie_create_from_file(scr, 128, 128, "test.json");
     80 lv_obj_center(lottie);
     81 // Pause to a specific frame
     82 lv_rlottie_set_current_frame(lottie, 50);
     83 lv_rlottie_set_play_mode(lottie, LV_RLOTTIE_CTRL_PAUSE); // The specified frame will be displayed and then the animation will pause
     84 
     85 // Play backward and loop
     86 lv_rlottie_set_play_mode(lottie, LV_RLOTTIE_CTRL_PLAY | LV_RLOTTIE_CTRL_BACKWARD | LV_RLOTTIE_CTRL_LOOP);
     87 
     88 // Play forward once (no looping)
     89 lv_rlottie_set_play_mode(lottie, LV_RLOTTIE_CTRL_PLAY | LV_RLOTTIE_CTRL_FORWARD);
     90 ```
     91 
     92 The default animation mode is **play forward with loop**.
     93 
     94 If you don't enable looping, a `LV_EVENT_READY` is sent when the animation can not make more progress without looping.
     95 
     96 To get the number of frames in an animation or the current frame index, you can cast the `lv_obj_t` instance to a `lv_rlottie_t` instance and inspect the `current_frame` and `total_frames` members.
     97 
     98 ## Example
     99 ```eval_rst
    100 
    101 .. include:: ../../examples/libs/rlottie/index.rst
    102 
    103 ```
    104 
    105 ## API
    106 
    107 ```eval_rst
    108 
    109 .. doxygenfile:: lv_rlottie.h
    110   :project: lvgl