resubmit the lvgl code

2022-01-18 16:38:38 +08:00
parent a5066f8a36
commit 65a3861ea7
879 changed files with 304372 additions and 1 deletions
@@ -0,0 +1,42 @@
+```eval_rst
+.. include:: /header.rst 
+:github_url: |github_link_base|/libs/bmp.md
+```
+
+# BMP decoder 
+
+This extension allows the use of BMP images in LVGL. 
+This implementation uses [bmp-decoder](https://github.com/caj-johnson/bmp-decoder) library.
+The pixel are read on demand (not the whole image is loaded) so using BMP images requires very little RAM. 
+
+If enabled in `lv_conf.h` by `LV_USE_BMP` LVGL will register a new image decoder automatically so BMP files can be directly used as image sources. For example:
+```
+lv_img_set_src(my_img, "S:path/to/picture.bmp");
+```
+
+Note that, a file system driver needs to registered to open images from files. Read more about it [here](https://docs.lvgl.io/master/overview/file-system.html) or just enable one in `lv_conf.h` with `LV_USE_FS_...` 
+
+## Limitations
+- Only BMP files are supported and BMP images as C array (`lv_img_dsc_t`) are not. It's because there is no practical differences between how the BMP files and LVGL's image format stores the image data. 
+- BMP files can be loaded only from file. If you want to store them in flash it's better to convert them to C array with [LVGL's image converter](https://lvgl.io/tools/imageconverter).
+- The BMP files color format needs to match with `LV_COLOR_DEPTH`. Use GIMP to save the image in the required format.
+  Both RGB888 and ARGB888 works with `LV_COLOR_DEPTH 32`
+- Palette is not supported.
+- Because not the whole image is read in can not be zoomed or rotated.
+
+
+## Example
+```eval_rst
+
+.. include:: ../../examples/libs/bmp/index.rst
+
+```
+
+## API
+
+```eval_rst
+
+.. doxygenfile:: lv_bmp.h
+  :project: lvgl
+
+```
@@ -0,0 +1,39 @@
+```eval_rst
+.. include:: /header.rst 
+:github_url: |github_link_base|/libs/bmp.md
+```
+
+# FreeType support
+Interface to [FreeType](https://www.freetype.org/) to generate font bitmaps run time.
+
+## Install FreeType
+- Download Freetype from [here](https://sourceforge.net/projects/freetype/files/)
+- `make`
+- `sudo make install`
+
+## Add FreeType to your project
+- Add include path: `/usr/include/freetype2` (for GCC: `-I/usr/include/freetype2 -L/usr/local/lib`)
+- Add library: `freetype` (for GCC: `-L/usr/local/lib -lfreetype`)
+
+## Usage
+
+Enable `LV_USE_FREETYPE` in `lv_conf.h`.
+
+See the examples below.
+
+Note that, the FreeType extension doesn't use LVGL's file system. 
+You can simply pass the path to the font as usual on your operating system or platform.
+
+## Learn more
+- FreeType [tutorial](https://www.freetype.org/freetype2/docs/tutorial/step1.html) 
+- LVGL's [font interface](https://docs.lvgl.io/v7/en/html/overview/font.html#add-a-new-font-engine)
+
+
+## API
+
+```eval_rst
+
+.. doxygenfile:: lv_freetype.h
+  :project: lvgl
+
+```
@@ -0,0 +1,20 @@
+```eval_rst
+.. include:: /header.rst 
+:github_url: |github_link_base|/libs/fsdrv.md
+```
+
+# File System Interfaces
+
+LVGL has a [File system](https://docs.lvgl.io/master/overview/file-system.html) module to provides an abstraction layer for various file system drivers.
+
+LVG has build in support for
+- [FATFS](http://elm-chan.org/fsw/ff/00index_e.html)
+- STDIO (Linux and Windows using C standard function .e.g fopen, fread)
+- POSIX (Linux and Windows using POSIX function .e.g open, read)
+- WIN32 (Windows using Win32 API function .e.g CreateFileA, ReadFile)
+
+You still need to provide the drivers and libraries, this extensions provide only the bridge between FATFS, STDIO, POSIX, WIN32 and LVGL.
+
+## Usage
+
+In `lv_conf.h` set a driver letter for one or more `LV_FS_USE_...` define(s). After that you can access files using that driver letter. Setting `'\0'` will disable use of that interface.  
@@ -0,0 +1,48 @@
+```eval_rst
+.. include:: /header.rst 
+:github_url: |github_link_base|/libs/gif.md
+```
+
+# GIF decoder
+Allow to use of GIF images in LVGL. Based on https://github.com/lecram/gifdec
+
+When enabled in `lv_conf.h` with `LV_USE_GIF` `lv_gif_create(parent)` can be used to create a gif widget.
+
+`lv_gif_set_src(obj, src)` works very similarly to `lv_img_set_src`. As source It also accepts images as variables (`lv_img_dsc_t`) or files.
+
+
+## Convert GIF files to C array
+To convert a GIF file to byte values array use [LVGL's online converter](https://lvgl.io/tools/imageconverter). Select "Raw" color format and "C array" Output format.
+ 
+
+## Use GIF images from file
+
+For example:
+```c
+lv_gif_set_src(obj, "S:path/to/example.gif");
+```
+
+Note that, a file system driver needs to regsitered to open images from files. Read more about it [here](https://docs.lvgl.io/master/overview/file-system.html) or just enable one in `lv_conf.h` with `LV_USE_FS_...` 
+
+
+## Memory requirements
+To decode and display a GIF animation the following amount of RAM is required:
+- `LV_COLOR_DEPTH 8`: 3 x image width x image height 
+- `LV_COLOR_DEPTH 16`: 4 x image width x image height 
+- `LV_COLOR_DEPTH 32`: 5 x image width x image height 
+
+## Example
+```eval_rst
+
+.. include:: ../../examples/libs/gif/index.rst
+
+```
+
+## API
+
+```eval_rst
+
+.. doxygenfile:: lv_gif.h
+  :project: lvgl
+
+```
@@ -0,0 +1,22 @@
+```eval_rst
+.. include:: /header.rst 
+:github_url: |github_link_base|/libs/index.md
+```
+# 3rd party libraries
+
+
+```eval_rst
+
+.. toctree::
+   :maxdepth: 1
+   
+   fsdrv
+   bmp
+   sjpg
+   png
+   gif
+   freetype
+   qrcode
+   rlottie
+```
+
@@ -0,0 +1,31 @@
+```eval_rst
+.. include:: /header.rst 
+:github_url: |github_link_base|/libs/png.md
+```
+
+# PNG decoder
+
+Allow the use of PNG images in LVGL. This implementation uses [lodepng](https://github.com/lvandeve/lodepng) library.
+
+If enabled in `lv_conf.h` by `LV_USE_PNG` LVGL will register a new image decoder automatically so PNG files can be directly used as any other image  sources.
+
+Note that, a file system driver needs to registered to open images from files. Read more about it [here](https://docs.lvgl.io/master/overview/file-system.html) or just enable one in `lv_conf.h` with `LV_USE_FS_...` 
+
+The whole PNG image is decoded so during decoding RAM equals to `image width x image height x 4` bytes are required.
+
+As it might take significant time to decode PNG images LVGL's [images caching](https://docs.lvgl.io/master/overview/image.html#image-caching) feature can be useful. 
+
+## Example
+```eval_rst
+
+.. include:: ../../examples/libs/png/index.rst
+
+```
+
+## API
+
+```eval_rst
+
+.. doxygenfile:: lv_png.h
+  :project: lvgl
+
@@ -0,0 +1,42 @@
+```eval_rst
+.. include:: /header.rst 
+:github_url: |github_link_base|/libs/qrcode.md
+```
+
+# QR code
+
+QR code generation with LVGL. Uses [QR-Code-generator](https://github.com/nayuki/QR-Code-generator) by [nayuki](https://github.com/nayuki).
+
+## Get started
+- Download or clone this repository
+  - [Download](https://github.com/lvgl/lv_lib_qrcode.git) from GitHub
+  - Clone: git clone https://github.com/lvgl/lv_lib_qrcode.git
+- Include the library: `#include "lv_lib_qrcode/lv_qrcode.h"`
+- Test with the following code:
+```c
+const char * data = "Hello world";
+
+/*Create a 100x100 QR code*/
+lv_obj_t * qr = lv_qrcode_create(lv_scr_act(), 100, lv_color_hex3(0x33f), lv_color_hex3(0xeef));
+
+/*Set data*/
+lv_qrcode_update(qr, data, strlen(data));
+```
+
+## Notes
+- QR codes with less data are smaller but they scaled by an integer numbers number to best fit to the given size
+
+
+## Example
+```eval_rst
+
+.. include:: ../../examples/libs/qrcode/index.rst
+
+```
+
+## API
+
+```eval_rst
+
+.. doxygenfile:: lv_qrcode.h
+  :project: lvgl
@@ -0,0 +1,86 @@
+```eval_rst
+.. include:: /header.rst
+:github_url: |github_link_base|/libs/rlottie.md
+```
+
+
+# Lottie player
+Allows to use Lottie animations in LVGL. Taken from this [base repository](https://github.com/ValentiWorkLearning/lv_rlottie)
+
+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.
+
+## Build Rlottie
+To build Samsung's Rlottie C++14-compatible compiler and optionally CMake 3.14 or higher is required.
+
+To build on desktop you can follow the instrutions from Rlottie's [README](https://github.com/Samsung/rlottie/blob/master/README.md). In the most basic case it looks like this:
+```
+mkdir rlottie_workdir
+cd rlottie_workdir
+git clone https://github.com/Samsung/rlottie.git
+mkdir build
+cd build
+cmake ../rlottie
+make -j
+sudo make install
+```
+
+And finally add the `-lrlottie` flag to your linker.
+
+On embedded systems you need to take care of integrating Rlottie to the given build system.
+
+
+## Usage
+
+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`.
+
+
+The `width` and `height` of the object be set in the *create* function and the animation will be scaled accordingly.
+
+### Use Rlottie from file
+
+To create a Lottie animation from file use:
+```c
+  lv_obj_t * lottie = lv_rlottie_create_from_file(parent, width, height, "path/to/lottie.json");
+```
+
+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.
+
+
+### Use Rlottie from raw string data
+
+`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:
+- avoid escaping `"` 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 raw data:
+
+```c
+extern const uint8_t lottie_data[];
+lv_obj_t* lottie = lv_rlottie_create_from_raw(parent, width, height, (const char *)lottie_data);
+```
+
+## Getting animations
+
+Lottie is standard and popular format so you can find many animation files on the web.
+For example: https://lottiefiles.com/
+
+You can also create your own animations with Adobe After Effects or similar software.
+
+## Example
+```eval_rst
+
+.. include:: ../../examples/libs/rlottie/index.rst
+
+```
+
+## API
+
+```eval_rst
+
+.. doxygenfile:: lv_rlottie.h
+  :project: lvgl
@@ -0,0 +1,77 @@
+```eval_rst
+.. include:: /header.rst 
+:github_url: |github_link_base|/libs/sjpg.md
+```
+
+# JPG decoder
+
+Allow the use of JPG images in LVGL. Besides that it also allows the use of a custom format, called Split JPG (SJPG), which can be decided in more optimal way on embedded systems.
+
+## Overview
+  - Supports both normal JPG and the custom SJPG formats.
+  - Decoding normal JPG consumes RAM with the size fo the whole uncompressed image (recommended only for devices with more RAM)
+  - SJPG is a custom format based on "normal" JPG and specially made for LVGL.
+  - SJPG is 'split-jpeg' which is a bundle of small jpeg fragments with an sjpg header.
+  - SJPG size will be almost comparable to the jpg file or might be a slightly larger.
+  - File read from file and c-array are implemented.
+  - SJPEG frame fragment cache enables fast fetching of lines if availble in cache.
+  - By default the sjpg image cache will be image width * 2 * 16 bytes (can be modified)
+  - Currently only 16 bit image format is supported (TODO)
+  - Only the required partion of the JPG and SJPG images are decoded, therefore they can't be zoomed or rotated.
+
+## Usage
+
+If enabled in `lv_conf.h` by `LV_USE_SJPG` LVGL will register a new image decoder automatically so JPG and SJPG files can be directly used as image sources. For example:
+```
+lv_img_set_src(my_img, "S:path/to/picture.jpg");
+```
+
+Note that, a file system driver needs to registered to open images from files. Read more about it [here](https://docs.lvgl.io/master/overview/file-system.html) or just enable one in `lv_conf.h` with `LV_USE_FS_...` 
+
+
+
+## Converter
+
+### Converting JPG to C array
+  - Use lvgl online tool https://lvgl.io/tools/imageconverter 
+  - Color format = RAW, output format = C Array
+  
+### Converting JPG to SJPG  
+python3 and the PIL library required. (PIL can be installed with `pip3 install pillow`)
+
+To create SJPG from JPG:
+- Copy the image to convert into `lvgl/scripts`
+- `cd lvgl/scripts`
+- `python3 jpg_to_sjpg.py image_to_convert.jpg`. It creates both a C files and an SJPG image.
+
+The expected result is:
+```sh
+Conversion started...
+
+Input:
+        image_to_convert.jpg
+        RES = 640 x 480
+
+Output:
+        Time taken = 1.66 sec
+        bin size = 77.1 KB
+        walpaper.sjpg           (bin file)
+        walpaper.c              (c array)
+
+All good!
+```
+
+
+## Example
+```eval_rst
+
+.. include:: ../../examples/libs/sjpg/index.rst
+
+```
+
+## API
+
+```eval_rst
+
+.. doxygenfile:: lv_sjpg.h
+  :project: lvgl