Update LVGL to v9.1.0
This commit is contained in:
jacqueline
@@ -0,0 +1,50 @@
|
||||
.. _barcode:
|
||||
|
||||
=======
|
||||
Barcode
|
||||
=======
|
||||
|
||||
Barcode generation with LVGL. Uses
|
||||
`code128 <https://github.com/fhunleth/code128>`__ by
|
||||
`fhunleth <https://github.com/fhunleth>`__.
|
||||
|
||||
.. _barcode_usage:
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Enable :c:macro:`LV_USE_BARCODE` in ``lv_conf.h``.
|
||||
|
||||
Use :cpp:func:`lv_barcode_create` to create a barcode object, and use
|
||||
:cpp:func:`lv_barcode_update` to generate a barcode.
|
||||
|
||||
Call :cpp:func:`lv_barcode_set_scale` to adjust scaling,
|
||||
call :cpp:func:`lv_barcode_set_dark_color` and :cpp:func:`lv_barcode_set_light_color`
|
||||
adjust color, call :cpp:func:`lv_barcode_set_direction` will set
|
||||
direction to display, and call :cpp:func:`lv_barcode_update` again to regenerate
|
||||
the barcode.
|
||||
|
||||
Notes
|
||||
-----
|
||||
|
||||
- It is best not to manually set the width of the barcode, because when
|
||||
the width of the object is lower than the width of the barcode, the
|
||||
display will be incomplete due to truncation.
|
||||
- The scale adjustment can only be an integer multiple, for example,
|
||||
:cpp:expr:`lv_barcode_set_scale(barcode, 2)` means 2x scaling.
|
||||
- The direction adjustment can be :cpp:enumerator:`LV_DIR_HOR` or :cpp:enumerator:`LV_DIR_VER`
|
||||
|
||||
.. _barcode_example:
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. include:: ../examples/libs/barcode/index.rst
|
||||
|
||||
.. _barcode_api:
|
||||
|
||||
API
|
||||
---
|
||||
|
||||
:ref:`code128`
|
||||
|
||||
@@ -1,38 +0,0 @@
|
||||
|
||||
# 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 pixels 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,54 @@
|
||||
.. _bmp:
|
||||
|
||||
===========
|
||||
BMP decoder
|
||||
===========
|
||||
|
||||
This extension allows the use of BMP images in LVGL.
|
||||
|
||||
Library source: https://github.com/caj-johnson/bmp-decoder
|
||||
|
||||
The pixels 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 :c:macro:`LV_USE_BMP` LVGL will register a new
|
||||
image decoder automatically so BMP files can be directly used as image
|
||||
sources. For example:
|
||||
|
||||
.. code:: c
|
||||
|
||||
lv_image_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 :ref:`overview_file_system` or just
|
||||
enable one in ``lv_conf.h`` with ``LV_USE_FS_...``
|
||||
|
||||
.. _bmp_limitations:
|
||||
|
||||
Limitations
|
||||
-----------
|
||||
|
||||
- Only BMP files are supported and BMP images as C array
|
||||
(:c:struct:`lv_image_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 :c:macro:`LV_COLOR_DEPTH`.
|
||||
Use GIMP to save the image in the required format. Both RGB888 and
|
||||
ARGB888 works with :c:macro:`LV_COLOR_DEPTH` ``32``
|
||||
- Palette is not supported.
|
||||
- Because not the whole image is read in can not be zoomed or rotated.
|
||||
|
||||
.. _bmp_example:
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. include:: ../examples/libs/bmp/index.rst
|
||||
|
||||
.. _bmp_api:
|
||||
|
||||
API
|
||||
---
|
||||
|
||||
@@ -1,37 +0,0 @@
|
||||
|
||||
# FFmpeg support
|
||||
[FFmpeg](https://www.ffmpeg.org/) A complete, cross-platform solution to record, convert and stream audio and video.
|
||||
|
||||
## Install FFmpeg
|
||||
- Download FFmpeg from [here](https://www.ffmpeg.org/download.html)
|
||||
- `./configure --disable-all --disable-autodetect --disable-podpages --disable-asm --enable-avcodec --enable-avformat --enable-decoders --enable-encoders --enable-demuxers --enable-parsers --enable-protocol='file' --enable-swscale --enable-zlib`
|
||||
- `make`
|
||||
- `sudo make install`
|
||||
|
||||
## Add FFmpeg to your project
|
||||
- Add library: `FFmpeg` (for GCC: `-lavformat -lavcodec -lavutil -lswscale -lm -lz -lpthread`)
|
||||
|
||||
## Usage
|
||||
|
||||
Enable `LV_USE_FFMPEG` in `lv_conf.h`.
|
||||
|
||||
See the examples below.
|
||||
|
||||
Note that, the FFmpeg extension doesn't use LVGL's file system.
|
||||
You can simply pass the path to the image or video as usual on your operating system or platform.
|
||||
|
||||
## Example
|
||||
```eval_rst
|
||||
|
||||
.. include:: ../../examples/libs/ffmpeg/index.rst
|
||||
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
```eval_rst
|
||||
|
||||
.. doxygenfile:: lv_ffmpeg.h
|
||||
:project: lvgl
|
||||
|
||||
```
|
||||
@@ -0,0 +1,51 @@
|
||||
.. _ffmpeg:
|
||||
|
||||
==============
|
||||
FFmpeg support
|
||||
==============
|
||||
|
||||
A complete, cross-platform solution to record, convert and stream audio and video.
|
||||
|
||||
Detailed introduction: https://www.ffmpeg.org
|
||||
|
||||
Install FFmpeg
|
||||
--------------
|
||||
|
||||
Download first FFmpeg from `here <https://www.ffmpeg.org/download.html>`__, then install it:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
./configure --disable-all --disable-autodetect --disable-podpages --disable-asm --enable-avcodec --enable-avformat --enable-decoders --enable-encoders --enable-demuxers --enable-parsers --enable-protocol='file' --enable-swscale --enable-zlib
|
||||
make
|
||||
sudo make install
|
||||
|
||||
Add FFmpeg to your project
|
||||
--------------------------
|
||||
|
||||
- Add library: ``FFmpeg`` (for GCC: ``-lavformat -lavcodec -lavutil -lswscale -lm -lz -lpthread``)
|
||||
|
||||
.. _ffmpeg_usage:
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Enable :c:macro:`LV_USE_FFMPEG` in ``lv_conf.h``.
|
||||
|
||||
See the examples below.
|
||||
|
||||
:Note: FFmpeg extension doesn't use LVGL's file system. You can
|
||||
simply pass the path to the image or video as usual on your operating
|
||||
system or platform.
|
||||
|
||||
.. _ffmpeg_example:
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. include:: ../examples/libs/ffmpeg/index.rst
|
||||
|
||||
.. _ffmpeg_api:
|
||||
|
||||
API
|
||||
---
|
||||
|
||||
@@ -1,51 +0,0 @@
|
||||
|
||||
# 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`.
|
||||
|
||||
To cache the glyphs from the opened fonts, set `LV_FREETYPE_CACHE_SIZE >= 0` and then use the following macros for detailed configuration:
|
||||
1. `LV_FREETYPE_CACHE_SIZE`:maximum memory(bytes) used to cache font bitmap, outline, character maps, etc. 0 means use the system default value, less than 0 means disable cache. Note: that this value does not account for managed FT_Face and FT_Size objects.
|
||||
1. `LV_FREETYPE_CACHE_FT_FACES`:maximum number of opened FT_Face objects managed by this cache instance.0 means use the system default value. Only useful when LV_FREETYPE_CACHE_SIZE >= 0.
|
||||
1. `LV_FREETYPE_CACHE_FT_SIZES`:maximum number of opened FT_Size objects managed by this cache instance. 0 means use the system default value. Only useful when LV_FREETYPE_CACHE_SIZE >= 0.
|
||||
|
||||
When you are sure that all the used font sizes will not be greater than 256, you can enable `LV_FREETYPE_SBIT_CACHE`, which is much more memory efficient for small bitmaps.
|
||||
|
||||
You can use `lv_ft_font_init()` to create FreeType fonts. It returns `true` to indicate success, at the same time, the `font` member of `lv_ft_info_t` will be filled with a pointer to an LVGL font, and you can use it like any LVGL font.
|
||||
|
||||
Font style supports bold and italic, you can use the following macros to set:
|
||||
1. `FT_FONT_STYLE_NORMAL`:default style.
|
||||
1. `FT_FONT_STYLE_ITALIC`:Italic style
|
||||
1. `FT_FONT_STYLE_BOLD`:bold style
|
||||
|
||||
They can be combined.eg:`FT_FONT_STYLE_BOLD | FT_FONT_STYLE_ITALIC`.
|
||||
|
||||
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.
|
||||
|
||||
## Example
|
||||
```eval_rst
|
||||
.. include:: ../../examples/libs/freetype/index.rst
|
||||
```
|
||||
|
||||
|
||||
## 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,117 @@
|
||||
.. _freetype:
|
||||
|
||||
================
|
||||
FreeType support
|
||||
================
|
||||
|
||||
Interface to FreeType library to generate font bitmaps run time.
|
||||
|
||||
Detailed introduction: https://www.freetype.org
|
||||
|
||||
Add FreeType to your project
|
||||
----------------------------
|
||||
|
||||
First, Download FreeType from `here <https://sourceforge.net/projects/freetype/files/>`__.
|
||||
|
||||
There are two ways to use FreeType:
|
||||
|
||||
For UNIX
|
||||
~~~~~~~~
|
||||
|
||||
For UNIX systems, it is recommended to use the way of compiling and installing libraries.
|
||||
|
||||
- Enter the FreeType source code directory
|
||||
- ``make``
|
||||
- ``sudo make install``
|
||||
- Add include path: ``/usr/include/freetype2`` (for GCC: ``-I/usr/include/freetype2 -L/usr/local/lib``)
|
||||
- Link library: ``freetype`` (for GCC: ``-L/usr/local/lib -lfreetype``)
|
||||
|
||||
For Embedded Devices
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
For embedded devices, it is more recommended to use the FreeType
|
||||
configuration file provided by LVGL, which only includes the most
|
||||
commonly used functions, which is very meaningful for saving limited
|
||||
FLASH space.
|
||||
|
||||
- Copy the FreeType source code to your project directory.
|
||||
- Refer to the following ``Makefile`` for configuration:
|
||||
|
||||
.. code:: make
|
||||
|
||||
# FreeType custom configuration header file
|
||||
CFLAGS += -DFT2_BUILD_LIBRARY
|
||||
CFLAGS += -DFT_CONFIG_MODULES_H=<lvgl/src/libs/freetype/ftmodule.h>
|
||||
CFLAGS += -DFT_CONFIG_OPTIONS_H=<lvgl/src/libs/freetype/ftoption.h>
|
||||
|
||||
# FreeType include path
|
||||
CFLAGS += -Ifreetype/include
|
||||
|
||||
# FreeType C source file
|
||||
FT_CSRCS += freetype/src/base/ftbase.c
|
||||
FT_CSRCS += freetype/src/base/ftbitmap.c
|
||||
FT_CSRCS += freetype/src/base/ftdebug.c
|
||||
FT_CSRCS += freetype/src/base/ftglyph.c
|
||||
FT_CSRCS += freetype/src/base/ftinit.c
|
||||
FT_CSRCS += freetype/src/cache/ftcache.c
|
||||
FT_CSRCS += freetype/src/gzip/ftgzip.c
|
||||
FT_CSRCS += freetype/src/sfnt/sfnt.c
|
||||
FT_CSRCS += freetype/src/smooth/smooth.c
|
||||
FT_CSRCS += freetype/src/truetype/truetype.c
|
||||
CSRCS += $(FT_CSRCS)
|
||||
|
||||
.. _freetype_usage:
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Enable :c:macro:`LV_USE_FREETYPE` in ``lv_conf.h``.
|
||||
|
||||
Cache configuration:
|
||||
|
||||
- :c:macro:`LV_FREETYPE_CACHE_FT_GLYPH_CNT` Maximum number of cached glyphs., etc.
|
||||
|
||||
By default, 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.
|
||||
|
||||
If you want FreeType to use lvgl's memory allocation and file system
|
||||
interface, you can enable :c:macro:`LV_FREETYPE_USE_LVGL_PORT` in
|
||||
``lv_conf.h``, convenient for unified management.
|
||||
|
||||
The font style supports *Italic* and **Bold** fonts processed by
|
||||
software, and can be set with reference to the following values:
|
||||
|
||||
- :cpp:enumerator:`LV_FREETYPE_FONT_STYLE_NORMAL`: Default style.
|
||||
- :cpp:enumerator:`LV_FREETYPE_FONT_STYLE_ITALIC`: Italic style.
|
||||
- :cpp:enumerator:`LV_FREETYPE_FONT_STYLE_BOLD`: Bold style.
|
||||
|
||||
They can be combined.eg:
|
||||
:cpp:expr:`LV_FREETYPE_FONT_STYLE_BOLD | LV_FREETYPE_FONT_STYLE_ITALIC`.
|
||||
|
||||
Use the :cpp:func:`lv_freetype_font_create` function to create a font. To
|
||||
delete a font, use :cpp:func:`lv_freetype_font_delete`. For more detailed usage,
|
||||
please refer to example code.
|
||||
|
||||
.. _freetype_example:
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. include:: ../examples/libs/freetype/index.rst
|
||||
|
||||
Learn more
|
||||
----------
|
||||
|
||||
- FreeType`tutorial <https://www.freetype.org/freetype2/docs/tutorial/step1.html>`__
|
||||
- LVGL's :ref:`add_font`
|
||||
|
||||
.. _freetype_api:
|
||||
|
||||
API
|
||||
---
|
||||
|
||||
:ref:`ftoption`
|
||||
|
||||
:ref:`ftmodule`
|
||||
|
||||
@@ -0,0 +1,60 @@
|
||||
.. _libs_filesystem:
|
||||
|
||||
======================
|
||||
File System Interfaces
|
||||
======================
|
||||
|
||||
LVGL has a :ref:`overview_file_system` module
|
||||
to provide an abstraction layer for various file system drivers.
|
||||
|
||||
LVG has built 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``)
|
||||
- MEMFS (read a file from a memory buffer)
|
||||
- LITTLEFS (a little fail-safe filesystem designed for microcontrollers)
|
||||
|
||||
You still need to provide the drivers and libraries, this extension
|
||||
provides only the bridge between FATFS, STDIO, POSIX, WIN32 and LVGL.
|
||||
|
||||
.. _libs_filesystem_usage:
|
||||
|
||||
Usage
|
||||
*****
|
||||
|
||||
In ``lv_conf.h`` enable ``LV_USE_FS_...`` and assign an upper cased
|
||||
letter to ``LV_FS_..._LETTER`` (e.g. ``'S'``). After that you can access
|
||||
files using that driver letter. E.g. ``"S:path/to/file.txt"``.
|
||||
|
||||
The work directory can be set with ``LV_FS_..._PATH``. E.g.
|
||||
``"/home/joe/projects/"`` The actual file/directory paths will be
|
||||
appended to it.
|
||||
|
||||
Cached reading is also supported if ``LV_FS_..._CACHE_SIZE`` is set to
|
||||
not ``0`` value. :cpp:func:`lv_fs_read` caches this size of data to lower the
|
||||
number of actual reads from the storage.
|
||||
|
||||
To use the memory-mapped file emulation an ``lv_fs_path_ex_t`` object must be
|
||||
created and initialized. This object can be passed to :cpp:func:`lv_fs_open` as
|
||||
the file name:
|
||||
|
||||
.. code:: c
|
||||
|
||||
lv_fs_path_ex_t mempath;
|
||||
lv_fs_file_t file;
|
||||
uint8_t *buffer;
|
||||
uint32_t size;
|
||||
|
||||
/*Initialize buffer*/
|
||||
...
|
||||
|
||||
lv_fs_make_path_from_buffer(&mempath, LV_FS_MEMFS_LETTER, (void*)buffer, size);
|
||||
lv_fs_res_t res = lv_fs_open(&file, (const char *)&mempath, LV_FS_MODE_RD);
|
||||
|
||||
.. _libs_filesystem_api:
|
||||
|
||||
API
|
||||
***
|
||||
|
||||
@@ -1,21 +0,0 @@
|
||||
|
||||
# File System Interfaces
|
||||
|
||||
LVGL has a [File system](https://docs.lvgl.io/master/overview/file-system.html) module to provide an abstraction layer for various file system drivers.
|
||||
|
||||
LVG has built 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 extension provides only the bridge between FATFS, STDIO, POSIX, WIN32 and LVGL.
|
||||
|
||||
## Usage
|
||||
|
||||
In `lv_conf.h` enable `LV_USE_FS_...` and assign an upper cased letter to `LV_FS_..._LETTER` (e.g. `'S'`).
|
||||
After that you can access files using that driver letter. E.g. `"S:path/to/file.txt"`.
|
||||
|
||||
The work directory can be set with `LV_FS_..._PATH`. E.g. `"/home/joe/projects/"` The actual file/directory paths will be appended to it.
|
||||
|
||||
Cached reading is also supported if `LV_FS_..._CACHE_SIZE` is set to not `0` value. `lv_fs_read` caches this size of data to lower the number of actual reads from the storage.
|
||||
@@ -1,39 +0,0 @@
|
||||
|
||||
# GIF decoder
|
||||
Allow using 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 be 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_...`
|
||||
|
||||
|
||||
## 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,61 @@
|
||||
.. _gif:
|
||||
|
||||
===========
|
||||
GIF decoder
|
||||
===========
|
||||
|
||||
Allow using GIF images in LVGL.
|
||||
|
||||
Detailed introduction: https://github.com/lecram/gifdec
|
||||
|
||||
When enabled in ``lv_conf.h`` with :c:macro:`LV_USE_GIF`
|
||||
:cpp:expr:`lv_gif_create(parent)` can be used to create a gif widget.
|
||||
|
||||
:cpp:expr:`lv_gif_set_src(obj, src)` works very similarly to :cpp:func:`lv_image_set_src`.
|
||||
As source, it also accepts images as variables (:c:struct:`lv_image_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:
|
||||
|
||||
.. code:: c
|
||||
|
||||
lv_gif_set_src(obj, "S:path/to/example.gif");
|
||||
|
||||
Note that, a file system driver needs to be registered to open images
|
||||
from files. Read more about it :ref:`overview_file_system` 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:
|
||||
|
||||
- :c:macro:`LV_COLOR_DEPTH` ``8``: 3 x image width x image height
|
||||
- :c:macro:`LV_COLOR_DEPTH` ``16``: 4 x image width x image height
|
||||
- :c:macro:`LV_COLOR_DEPTH` ``32``: 5 x image width x image height
|
||||
|
||||
.. _gif_example:
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. include:: ../examples/libs/gif/index.rst
|
||||
|
||||
.. _gif_api:
|
||||
|
||||
API
|
||||
---
|
||||
|
||||
:ref:`gifdec`
|
||||
|
||||
@@ -1,19 +0,0 @@
|
||||
# 3rd party libraries
|
||||
|
||||
|
||||
```eval_rst
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
fsdrv
|
||||
bmp
|
||||
sjpg
|
||||
png
|
||||
gif
|
||||
freetype
|
||||
qrcode
|
||||
rlottie
|
||||
ffmpeg
|
||||
```
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
.. _3rd_party_libraries:
|
||||
|
||||
===================
|
||||
3rd party libraries
|
||||
===================
|
||||
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
fs
|
||||
bmp
|
||||
tjpgd
|
||||
libjpeg_turbo
|
||||
lodepng
|
||||
libpng
|
||||
gif
|
||||
freetype
|
||||
tiny_ttf
|
||||
qrcode
|
||||
barcode
|
||||
rlottie
|
||||
ffmpeg
|
||||
rle
|
||||
lfs
|
||||
@@ -0,0 +1,59 @@
|
||||
.. _lfs:
|
||||
|
||||
==============
|
||||
littlefs
|
||||
==============
|
||||
|
||||
littlefs is a little fail-safe filesystem designed for microcontrollers.
|
||||
|
||||
Detailed introduction: https://github.com/littlefs-project/littlefs
|
||||
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Enable :c:macro:`LV_USE_FS_LITTLEFS` and define a :c:macro`LV_FS_LITTLEFS_LETTER` in ``lv_conf.h``.
|
||||
|
||||
When enabled :c:macro:`lv_littlefs_set_handler` can be used to set up a mount point.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. code:: c
|
||||
#include "lfs.h"
|
||||
|
||||
// configuration of the filesystem is provided by this struct
|
||||
const struct lfs_config cfg = {
|
||||
// block device operations
|
||||
.read = user_provided_block_device_read,
|
||||
.prog = user_provided_block_device_prog,
|
||||
.erase = user_provided_block_device_erase,
|
||||
.sync = user_provided_block_device_sync,
|
||||
|
||||
// block device configuration
|
||||
.read_size = 16,
|
||||
.prog_size = 16,
|
||||
.block_size = 4096,
|
||||
.block_count = 128,
|
||||
.cache_size = 16,
|
||||
.lookahead_size = 16,
|
||||
.block_cycles = 500,
|
||||
};
|
||||
|
||||
// mount the filesystem
|
||||
int err = lfs_mount(&lfs, &cfg);
|
||||
|
||||
// reformat if we can't mount the filesystem
|
||||
// this should only happen on the first boot
|
||||
if (err) {
|
||||
lfs_format(&lfs, &cfg);
|
||||
lfs_mount(&lfs, &cfg);
|
||||
}
|
||||
|
||||
lv_littlefs_set_handler(&lfs);
|
||||
|
||||
|
||||
API
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
.. _libjpeg:
|
||||
|
||||
=====================
|
||||
libjpeg-turbo decoder
|
||||
=====================
|
||||
|
||||
**libjpeg-turbo** is a JPEG image codec that uses SIMD instructions to accelerate baseline JPEG compression and decompression on x86,
|
||||
x86-64, Arm, PowerPC, and MIPS systems, as well as progressive JPEG compression on x86, x86-64, and Arm systems.
|
||||
|
||||
Detailed introduction: https://libjpeg-turbo.org
|
||||
|
||||
Library source: https://github.com/libjpeg-turbo/libjpeg-turbo
|
||||
|
||||
.. _libjpeg_install:
|
||||
|
||||
Install
|
||||
-------
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo apt install libjpeg-turbo8-dev
|
||||
|
||||
Add libjpeg-turbo to your project
|
||||
---------------------------------
|
||||
|
||||
.. code:: cmake
|
||||
|
||||
find_package(JPEG REQUIRED)
|
||||
include_directories(${JPEG_INCLUDE_DIR})
|
||||
target_link_libraries(${PROJECT_NAME} PRIVATE ${JPEG_LIBRARIES})
|
||||
|
||||
.. _libjpeg_usage:
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Enable :c:macro:`LV_USE_LIBJPEG_TURBO` in ``lv_conf.h``.
|
||||
|
||||
See the examples below.
|
||||
It should be noted that each image of this decoder needs to consume ``image width x image height x 3`` bytes of RAM,
|
||||
and it needs to be combined with the :ref:`overview_image_caching` feature to ensure that the memory usage is within a reasonable range.
|
||||
|
||||
.. _libjpeg_example:
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. include:: ../examples/libs/libjpeg_turbo/index.rst
|
||||
|
||||
.. _libjpeg_api:
|
||||
|
||||
API
|
||||
---
|
||||
|
||||
:ref:`libjpeg_turbo`
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
.. _libpng:
|
||||
|
||||
==============
|
||||
libpng decoder
|
||||
==============
|
||||
|
||||
libpng is the official PNG reference library. It supports almost all PNG features, is extensible, and has been extensively tested for over 28 years.
|
||||
|
||||
Detailed introduction: http://www.libpng.org/pub/png/libpng.html
|
||||
|
||||
Install
|
||||
-------
|
||||
|
||||
.. code:: bash
|
||||
|
||||
sudo apt install libpng-dev
|
||||
|
||||
Add libpng to your project
|
||||
--------------------------
|
||||
|
||||
.. code:: cmake
|
||||
|
||||
find_package(PNG REQUIRED)
|
||||
include_directories(${PNG_INCLUDE_DIR})
|
||||
target_link_libraries(${PROJECT_NAME} PRIVATE ${PNG_LIBRARIES})
|
||||
|
||||
.. _libpng_usage:
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Enable :c:macro:`LV_USE_LIBPNG` in ``lv_conf.h``.
|
||||
|
||||
See the examples below.
|
||||
It should be noted that each image of this decoder needs to consume ``width x height x 4`` bytes of RAM,
|
||||
and it needs to be combined with the :ref:`overview_image_caching` feature to ensure that the memory usage is within a reasonable range.
|
||||
The decoded image is stored in RGBA pixel format.
|
||||
|
||||
.. _libpng_example:
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. include:: ../examples/libs/libpng/index.rst
|
||||
|
||||
.. _libpng_api:
|
||||
|
||||
API
|
||||
---
|
||||
|
||||
:ref:`libpng`
|
||||
|
||||
@@ -0,0 +1,50 @@
|
||||
.. _lodepng:
|
||||
|
||||
===============
|
||||
LodePNG decoder
|
||||
===============
|
||||
|
||||
Allow the use of PNG images in LVGL.
|
||||
|
||||
Detailed introduction: https://github.com/lvandeve/lodepng
|
||||
|
||||
If enabled in ``lv_conf.h`` by :c:macro:`LV_USE_LODEPNG` LVGL will register a new
|
||||
image decoder automatically so PNG files can be directly used as any
|
||||
other image sources.
|
||||
|
||||
:Note: a file system driver needs to be registered to open images from
|
||||
files. Read more about it :ref:`overview_file_system` or just
|
||||
enable one in ``lv_conf.h`` with ``LV_USE_FS_...``
|
||||
|
||||
The whole PNG image is decoded, so ``width x height x 4`` bytes free RAM space is required.
|
||||
The decoded image is stored in RGBA pixel format.
|
||||
|
||||
As it might take significant time to decode PNG images LVGL's :ref:`overview_image_caching` feature can be useful.
|
||||
|
||||
Compress PNG files
|
||||
------------------
|
||||
|
||||
PNG file format supports True color (24/32 bit), and 8-bit palette colors.
|
||||
Usually cliparts, drawings, icons and simple graphics are stored in PNG format,
|
||||
that do not use the whole color space, so it is possible to compress further
|
||||
the image by using 8-bit palette colors, instead of 24/32 bit True color format.
|
||||
Because embedded devices have limited (flash) storage, it is recommended
|
||||
to compress images.
|
||||
|
||||
One option is to use a free online PNG compressor site,
|
||||
for example Compress PNG: https://compresspng.com/
|
||||
|
||||
.. _lodepng_example:
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. include:: ../examples/libs/lodepng/index.rst
|
||||
|
||||
.. _lodepng_api:
|
||||
|
||||
API
|
||||
---
|
||||
|
||||
:ref:`lodepng`
|
||||
|
||||
@@ -1,27 +0,0 @@
|
||||
|
||||
# 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
|
||||
|
||||
@@ -1,38 +0,0 @@
|
||||
|
||||
# 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 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,45 @@
|
||||
.. _qrcode:
|
||||
|
||||
=======
|
||||
QR code
|
||||
=======
|
||||
|
||||
QR code generation with LVGL. Uses
|
||||
`QR-Code-generator <https://github.com/nayuki/QR-Code-generator>`__ by
|
||||
`nayuki <https://github.com/nayuki>`__.
|
||||
|
||||
.. _qrcode_usage:
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Enable :c:macro:`LV_USE_QRCODE` in ``lv_conf.h``.
|
||||
|
||||
Use :cpp:func:`lv_qrcode_create` to create a qrcode object, and use
|
||||
:cpp:func:`lv_qrcode_update` to generate a QR code.
|
||||
|
||||
If you need to re-modify the size and color, use
|
||||
:cpp:func:`lv_qrcode_set_size` and :cpp:func:`lv_qrcode_set_dark_color` or
|
||||
:cpp:func:`lv_qrcode_set_light_color`, and
|
||||
call :cpp:func:`lv_qrcode_update` again to regenerate the QR code.
|
||||
|
||||
Notes
|
||||
-----
|
||||
|
||||
- QR codes with less data are smaller, but they scaled by an integer
|
||||
number to best fit to the given size.
|
||||
|
||||
.. _qrcode_example:
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. include:: ../examples/libs/qrcode/index.rst
|
||||
|
||||
.. _qrcode_api:
|
||||
|
||||
API
|
||||
---
|
||||
|
||||
:ref:`qrcodegen`
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 11 KiB |
@@ -0,0 +1,86 @@
|
||||
.. _rle:
|
||||
|
||||
============
|
||||
RLE Compress
|
||||
============
|
||||
|
||||
LVGL provides a custom RLE compression method. It can be used to reduce binary
|
||||
image size. The RLE compression is a lossless compression method.
|
||||
|
||||
The LVGL's built-in binary image decoder supports RLE compressed images.
|
||||
The decoder supports both variable and file as image sources. The original
|
||||
binary data is directly decoded to RAM
|
||||
|
||||
Benefits
|
||||
--------
|
||||
|
||||
Based on test result from a watch project. Most of the images can be compressed
|
||||
to save more than 70% space as show in below statistic. It shows the file count
|
||||
of every compress level. For rare conditions, RLE compress may increase the file
|
||||
size if there's no large repetition in data.
|
||||
|
||||
.. image:: /libs/rle-compress-statistics.png
|
||||
:alt: RLE compress statistics from a watch project
|
||||
:align: center
|
||||
|
||||
|
||||
Theory
|
||||
------
|
||||
|
||||
The RLE algorithm is a simple compression algorithm that is based on the fact that
|
||||
the for many pixels, the color is the same. The algorithm simply counts how many
|
||||
repeated data are there and store the count value and the color value.
|
||||
If the coming pixels are not repeated, it stores the non-repeat count value and
|
||||
original color value. For more details, the script used to compress the image
|
||||
can be found from ``lvgl/script/LVGLImage.py``.
|
||||
|
||||
.. code:: python
|
||||
|
||||
def rle_compress(self, data: bytearray, blksize: int, threshold=16):
|
||||
index = 0
|
||||
data_len = len(data)
|
||||
compressed_data = []
|
||||
while index < data_len:
|
||||
memview = memoryview(data)
|
||||
repeat_cnt = self.get_repeat_count(
|
||||
memview[index:], blksize)
|
||||
if repeat_cnt == 0:
|
||||
# done
|
||||
break
|
||||
elif repeat_cnt < threshold:
|
||||
nonrepeat_cnt = self.get_nonrepeat_count(
|
||||
memview[index:], blksize, threshold)
|
||||
ctrl_byte = uint8_t(nonrepeat_cnt | 0x80)
|
||||
compressed_data.append(ctrl_byte)
|
||||
compressed_data.append(
|
||||
memview[index: index + nonrepeat_cnt*blksize])
|
||||
index += nonrepeat_cnt * blksize
|
||||
else:
|
||||
ctrl_byte = uint8_t(repeat_cnt)
|
||||
compressed_data.append(ctrl_byte)
|
||||
compressed_data.append(memview[index: index + blksize])
|
||||
index += repeat_cnt * blksize
|
||||
|
||||
return b"".join(compressed_data)
|
||||
|
||||
.. _rle_usage:
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
To use the RLE Decoder, enable it in ``lv_conf.h`` configuration file by setting :c:macro:`LV_USE_RLE` to `1`.
|
||||
The RLE image can be used same as other images.
|
||||
|
||||
.. code:: c
|
||||
|
||||
lv_image_set_src(img, "path/to/image.rle");
|
||||
|
||||
Generate RLE compressed binary images
|
||||
-------------------------------------
|
||||
|
||||
The image can be directly generated using script ``lvgl/script/LVGLImage.py``
|
||||
|
||||
|
||||
.. code:: bash
|
||||
|
||||
./script/LVGLImage.py --ofmt BIN --cf I8 --compress RLE cogwheel.png
|
||||
@@ -1,106 +0,0 @@
|
||||
|
||||
|
||||
# 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 instructions 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.
|
||||
|
||||
## Controlling animations
|
||||
|
||||
LVGL provides two functions to control the animation mode: `lv_rlottie_set_play_mode` and `lv_rlottie_set_current_frame`.
|
||||
You'll combine your intentions when calling the first method, like in these examples:
|
||||
```c
|
||||
lv_obj_t * lottie = lv_rlottie_create_from_file(scr, 128, 128, "test.json");
|
||||
lv_obj_center(lottie);
|
||||
// Pause to a specific frame
|
||||
lv_rlottie_set_current_frame(lottie, 50);
|
||||
lv_rlottie_set_play_mode(lottie, LV_RLOTTIE_CTRL_PAUSE); // The specified frame will be displayed and then the animation will pause
|
||||
|
||||
// Play backward and loop
|
||||
lv_rlottie_set_play_mode(lottie, LV_RLOTTIE_CTRL_PLAY | LV_RLOTTIE_CTRL_BACKWARD | LV_RLOTTIE_CTRL_LOOP);
|
||||
|
||||
// Play forward once (no looping)
|
||||
lv_rlottie_set_play_mode(lottie, LV_RLOTTIE_CTRL_PLAY | LV_RLOTTIE_CTRL_FORWARD);
|
||||
```
|
||||
|
||||
The default animation mode is **play forward with loop**.
|
||||
|
||||
If you don't enable looping, a `LV_EVENT_READY` is sent when the animation can not make more progress without looping.
|
||||
|
||||
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.
|
||||
|
||||
## Example
|
||||
```eval_rst
|
||||
|
||||
.. include:: ../../examples/libs/rlottie/index.rst
|
||||
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
```eval_rst
|
||||
|
||||
.. doxygenfile:: lv_rlottie.h
|
||||
:project: lvgl
|
||||
@@ -0,0 +1,288 @@
|
||||
.. _rlottie:
|
||||
|
||||
=============
|
||||
Lottie player
|
||||
=============
|
||||
|
||||
Allows playing Lottie animations in LVGL. Taken from `lv_rlottie <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 instructions from Rlottie's
|
||||
`README <https://github.com/Samsung/rlottie/blob/master/README.md>`__.
|
||||
|
||||
In the most basic case it looks like this:
|
||||
|
||||
.. code:: shell
|
||||
|
||||
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.
|
||||
|
||||
ESP-IDF example at bottom
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. _rlottie_usage:
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
You can use animation from files or raw data (text). In either case
|
||||
first you need to enable :c:macro:`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:
|
||||
|
||||
.. code:: 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 ``"`` 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 raw data:
|
||||
|
||||
.. code:: 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.
|
||||
|
||||
Controlling animations
|
||||
----------------------
|
||||
|
||||
LVGL provides two functions to control the animation mode:
|
||||
:cpp:func:`lv_rlottie_set_play_mode` and :cpp:func:`lv_rlottie_set_current_frame`.
|
||||
You'll combine your intentions when calling the first method, like in
|
||||
these examples:
|
||||
|
||||
.. code:: c
|
||||
|
||||
lv_obj_t * lottie = lv_rlottie_create_from_file(scr, 128, 128, "test.json");
|
||||
lv_obj_center(lottie);
|
||||
// Pause to a specific frame
|
||||
lv_rlottie_set_current_frame(lottie, 50);
|
||||
lv_rlottie_set_play_mode(lottie, LV_RLOTTIE_CTRL_PAUSE); // The specified frame will be displayed and then the animation will pause
|
||||
|
||||
// Play backward and loop
|
||||
lv_rlottie_set_play_mode(lottie, LV_RLOTTIE_CTRL_PLAY | LV_RLOTTIE_CTRL_BACKWARD | LV_RLOTTIE_CTRL_LOOP);
|
||||
|
||||
// Play forward once (no looping)
|
||||
lv_rlottie_set_play_mode(lottie, LV_RLOTTIE_CTRL_PLAY | LV_RLOTTIE_CTRL_FORWARD);
|
||||
|
||||
The default animation mode is **play forward with loop**.
|
||||
|
||||
If you don't enable looping, a :cpp:enumerator:`LV_EVENT_READY` is sent when the
|
||||
animation can not make more progress without looping.
|
||||
|
||||
To get the number of frames in an animation or the current frame index,
|
||||
you can cast the :c:struct:`lv_obj_t` instance to a :c:struct:`lv_rlottie_t` instance
|
||||
and inspect the ``current_frame`` and ``total_frames`` members.
|
||||
|
||||
ESP-IDF Example
|
||||
---------------
|
||||
|
||||
Background
|
||||
~~~~~~~~~~
|
||||
|
||||
Rlottie can be expensive to render on embedded hardware. Lottie
|
||||
animations tend to use a large amount of CPU time and can use large
|
||||
portions of RAM. This will vary from lottie to lottie but in general for
|
||||
best performance:
|
||||
|
||||
- Limit total # of frames in the animation
|
||||
- Where possible, try to avoid bezier type animations
|
||||
- Limit animation render size
|
||||
|
||||
If your ESP32 chip does not have SPIRAM you will face severe limitations
|
||||
in render size.
|
||||
|
||||
To give a better idea on this, lets assume you want to render a 240x320
|
||||
lottie animation.
|
||||
|
||||
In order to pass initialization of the lv_rlottie_t object, you need
|
||||
240x320x32/8 (307k) available memory. The latest ESP32-S3 has 256kb RAM
|
||||
available for this (before freeRtos and any other initialization starts
|
||||
taking chunks out). So while you can probably start to render a 50x50
|
||||
animation without SPIRAM, PSRAM is highly recommended.
|
||||
|
||||
Additionally, while you might be able to pass initialization of the
|
||||
lv_rlottie_t object, as rlottie renders frame to frame, this consumes
|
||||
additional memory. A 30 frame animation that plays over 1 second
|
||||
probably has minimal issues, but a 300 frame animation playing over 10
|
||||
seconds could very easily crash due to lack of memory as rlottie
|
||||
renders, depending on the complexity of the animation.
|
||||
|
||||
Rlottie will not compile for the IDF using the ``-02`` compiler option at
|
||||
this time.
|
||||
|
||||
For stability in lottie animations, I found that they run best in the
|
||||
IDF when enabling :c:macro:`LV_MEM_CUSTOM` (using ``stdlib.h``)
|
||||
|
||||
For all its faults, when running right-sized animations, they provide a
|
||||
wonderful utility to LVGL on embedded LCDs and can look really good when
|
||||
done properly.
|
||||
|
||||
When picking/designing a lottie animation consider the following
|
||||
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,
|
||||
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
|
||||
|
||||
IDF Setup
|
||||
~~~~~~~~~
|
||||
|
||||
Where the LVGL simulator uses the installed rlottie lib, the IDF works
|
||||
best when using rlottie as a submodule under the components directory.
|
||||
|
||||
.. code:: shell
|
||||
|
||||
cd 'your/project/directory'
|
||||
git add submodule
|
||||
git add submodule https://github.com/Samsung/rlottie.git ./components/rlottie/rlottie
|
||||
git submodule update --init --recursive
|
||||
|
||||
Now, Rlottie is available as a component in the IDF, but it requires
|
||||
some additional changes and a CMakeLists file to tell the IDF how to
|
||||
compile.
|
||||
|
||||
Rlottie patch file
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Rlottie relies on a dynamic linking for an image loader lib. This needs
|
||||
to be disabled as the IDF doesn't play nice with dynamic linking.
|
||||
|
||||
A patch file is available in lvgl under:
|
||||
``/env_support/esp/rlottie/0001-changes-to-compile-with-esp-idf.patch``
|
||||
|
||||
Apply the patch file to your rlottie submodule.
|
||||
|
||||
CMakeLists for IDF
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
An example CMakeLists file has been provided at
|
||||
``/env_support/esp/rlottie/CMakeLists.txt``
|
||||
|
||||
Copy this CMakeLists file to
|
||||
``'your-project-directory'/components/rlottie/``
|
||||
|
||||
In addition to the component CMakeLists file, you'll also need to tell
|
||||
your project level CMakeLists in your IDF project to require rlottie:
|
||||
|
||||
.. code:: console
|
||||
|
||||
REQUIRES "lvgl" "rlottie"
|
||||
|
||||
From here, you should be able to use lv_rlottie objects in your ESP-IDF
|
||||
project as any other widget in LVGL ESP examples. Please remember that
|
||||
these animations can be highly resource constrained and this does not
|
||||
guarantee that every animation will work.
|
||||
|
||||
Additional Rlottie considerations in ESP-IDF
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
While unnecessary, removing the ``rlottie/rlottie/example`` folder can remove
|
||||
many un-needed files for this embedded LVGL application
|
||||
|
||||
From here, you can use the relevant LVGL lv_rlottie functions to create
|
||||
lottie animations in LVGL on embedded hardware!
|
||||
|
||||
Please note, that while lottie animations are capable of running on many
|
||||
ESP chips, below is recommended for best performance.
|
||||
|
||||
- ESP32-S3-WROOM-1-N16R8
|
||||
|
||||
- 16mb quad spi flash
|
||||
- 8mb octal spi PSRAM
|
||||
|
||||
- IDF4.4 or higher
|
||||
|
||||
The Esp-box devkit meets this spec and
|
||||
https://github.com/espressif/esp-box is a great starting point to adding
|
||||
lottie animations.
|
||||
|
||||
You will need to enable :c:macro:`LV_USE_RLOTTIE` through **idf.py** menuconfig under
|
||||
LVGL component settings.
|
||||
|
||||
Additional changes to make use of SPIRAM
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
:cpp:expr:`lv_alloc/realloc` do not make use of SPIRAM. Given the high memory usage
|
||||
of lottie animations, it is recommended to shift as much out of internal
|
||||
DRAM into SPIRAM as possible. In order to do so, SPIRAM will need to be
|
||||
enabled in the menuconfig options for your given espressif chip.
|
||||
|
||||
There may be a better solution for this, but for the moment the
|
||||
recommendation is to make local modifications to the lvgl component in
|
||||
your espressif project. This is as simple as swapping
|
||||
:cpp:expr:`lv_alloc/lv_realloc` calls in `lv_rlottie.c`` with :cpp:expr:`heap_caps_malloc` (for
|
||||
IDF) with the appropriate :cpp:expr:`MALLOC_CAP` call - for SPIRAM usage this is
|
||||
:cpp:expr:`MALLOC_CAP_SPIRAM`.
|
||||
|
||||
.. code:: c
|
||||
|
||||
rlottie->allocated_buf = heap_caps_malloc(allocated_buf_size+1, MALLOC_CAP_SPIRAM);
|
||||
|
||||
.. _rlottie_example:
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. include:: ../examples/libs/rlottie/index.rst
|
||||
|
||||
.. _rlottie_api:
|
||||
|
||||
API
|
||||
---
|
||||
@@ -1,73 +0,0 @@
|
||||
|
||||
# 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 decoded 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 available 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
|
||||
@@ -0,0 +1,52 @@
|
||||
.. _tiny_ttf:
|
||||
|
||||
====================
|
||||
Tiny TTF font engine
|
||||
====================
|
||||
|
||||
.. _tiny_ttf_usage:
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
Allow using TrueType fonts in LVGL.
|
||||
|
||||
Detailed introduction: https://github.com/nothings/stb
|
||||
|
||||
When enabled in ``lv_conf.h`` with :c:macro:`LV_USE_TINY_TTF`
|
||||
:cpp:expr:`lv_tiny_ttf_create_data(data, data_size, font_size)` can be used to
|
||||
create a TTF font instance at the specified line height. You can then
|
||||
use that font anywhere :c:struct:`lv_font_t` is accepted.
|
||||
|
||||
By default, the TTF or OTF file must be embedded as an array, either in
|
||||
a header, or loaded into RAM in order to function.
|
||||
|
||||
However, if :c:macro:`LV_TINY_TTF_FILE_SUPPORT` is enabled,
|
||||
:cpp:expr:`lv_tiny_ttf_create_file(path, font_size)` will also be available,
|
||||
allowing tiny_ttf to stream from a file. The file must remain open the
|
||||
entire time the font is being used.
|
||||
|
||||
After a font is created, you can change the font size in pixels by using
|
||||
:cpp:expr:`lv_tiny_ttf_set_size(font, font_size)`.
|
||||
|
||||
By default, a font will use up to 4KB of cache to speed up rendering
|
||||
glyphs. This maximum can be changed by using
|
||||
:cpp:expr:`lv_tiny_ttf_create_data_ex(data, data_size, font_size, cache_size)`
|
||||
or :cpp:expr:`lv_tiny_ttf_create_file_ex(path, font_size, cache_size)` (when
|
||||
available). The cache size is indicated in bytes.
|
||||
|
||||
.. _tiny_ttf_example:
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. include:: ../examples/libs/tiny_ttf/index.rst
|
||||
|
||||
.. _tiny_ttf_api:
|
||||
|
||||
API
|
||||
---
|
||||
|
||||
:ref:`stb_rect_pack`
|
||||
|
||||
:ref:`stb_truetype_htcw`
|
||||
@@ -0,0 +1,66 @@
|
||||
.. _tjpgd:
|
||||
|
||||
================================
|
||||
Tiny JPEG Decompressor (TJpgDec)
|
||||
================================
|
||||
|
||||
Allow the use of JPEG (JPG) images in LVGL.
|
||||
|
||||
Detailed introduction: `TJpgDec <http://elm-chan.org/fsw/tjpgd/>`__
|
||||
|
||||
.. _tjpgd_overview:
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
- JPEG is decoded in 8x8 tiles.
|
||||
- Only baseline JPEG files are supported (no progressive JPEG support).
|
||||
- Read from file and C array are implemented.
|
||||
- Only the required portions of the JPEG images are decoded,
|
||||
therefore they can't be zoomed or rotated.
|
||||
|
||||
.. _tjpgd_usage:
|
||||
|
||||
Usage
|
||||
-----
|
||||
|
||||
If enabled in ``lv_conf.h`` by :c:macro:`LV_USE_TJPGD` LVGL will register a new
|
||||
image decoder automatically so JPEG files can be used directly
|
||||
as image sources.
|
||||
|
||||
For example:
|
||||
|
||||
.. code:: c
|
||||
|
||||
lv_image_set_src(my_img, "S:path/to/picture.jpg");
|
||||
|
||||
:Note: a file system driver needs to be registered to open images from
|
||||
files. Read more about :ref:`overview_file_system` or just
|
||||
enable one in ``lv_conf.h`` with ``LV_USE_FS_...`` config.
|
||||
|
||||
Converter
|
||||
---------
|
||||
|
||||
Converting JPEG to C array
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- Use lvgl online tool https://lvgl.io/tools/imageconverter
|
||||
- Color format = RAW, output format = C Array
|
||||
|
||||
.. _tjpgd_example:
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
.. include:: ../examples/libs/tjpgd/index.rst
|
||||
|
||||
.. _tjpgd_api:
|
||||
|
||||
API
|
||||
---
|
||||
|
||||
:ref:`lv_tjpgd`
|
||||
|
||||
:ref:`tjpgd`
|
||||
|
||||
:ref:`tjpgdcnf`
|
||||
Reference in New Issue
Block a user