arch add small 3rd party libs to lvgl (#2569)

* move png, sjpg, bmp, gif, fs_if to extra/libs

* reorganize the examples

* update lv_conf_internal.h

* fix warnings

* add freetype

* remove unused assets

* add the new libs to build tests

* update the docs
This commit is contained in:
Gabor Kiss-Vamosi
2021-10-04 14:34:11 +02:00
committed by GitHub
parent b20a706112
commit 18f61c5f77
69 changed files with 17841 additions and 0 deletions

42
docs/libs/bmp.md Normal file
View File

@@ -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
```

39
docs/libs/freetype.md Normal file
View File

@@ -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
```

19
docs/libs/fs.md Normal file
View File

@@ -0,0 +1,19 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/libs/fs.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)
You still need to provide the drivers and libraries, this extensions provide only the bridge between FATFS, STDIO, POSIX 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.

48
docs/libs/gif.md Normal file
View File

@@ -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
```

21
docs/libs/index.md Normal file
View File

@@ -0,0 +1,21 @@
```eval_rst
.. include:: /header.rst
:github_url: |github_link_base|/libs/index.md
```
# 3rd party libraries
```eval_rst
.. toctree::
:maxdepth: 1
fs
bpm
jpg
png
gif
freetype
qrcode
```

31
docs/libs/png.md Normal file
View File

@@ -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

28
docs/libs/qrcode.md Normal file
View File

@@ -0,0 +1,28 @@
```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/littlevgl/lv_lib_qrcode.git) from GitHub
- Clone: git clone https://github.com/littlevgl/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

77
docs/libs/sjpg.md Normal file
View File

@@ -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