feat(docs): reorganize docs (#7136)

docs/details/libs/arduino_esp_littlefs.rst

@@ -0,0 +1,23 @@
+.. _arduino_esp_littlefs:
+
+====================
+Arduino ESP littlefs
+====================
+
+LittleFS is a little fail-safe filesystem designed for microcontrollers and integrated in the Arduino framework 
+when used with ESP32 and ESP8266.
+
+Detailed introduction:
+
+- https://github.com/esp8266/Arduino 
+- https://github.com/espressif/arduino-esp32
+
+
+Usage
+-----
+
+Enable :c:macro:`LV_USE_FS_ARDUINO_ESP_LITTLEFS` and define a :c:macro:`LV_FS_ARDUINO_ESP_LITTLEFS_LETTER` in ``lv_conf.h``.
+
+
+API
+---

docs/details/libs/arduino_sd.rst

@@ -0,0 +1,24 @@
+.. _arduino_sd:
+
+==========
+Arduino SD
+==========
+
+Enables reading and writing on SD cards.
+Once an SD memory card is connected to the SPI interface of the Arduino or Genuino board you can create files
+and read/write on them. You can also move through directories on the SD card..
+
+Detailed introduction:
+
+- https://www.arduino.cc/reference/en/libraries/sd/
+
+
+Usage
+-----
+
+Enable :c:macro:`LV_USE_FS_ARDUINO_SD` and define a :c:macro:`LV_FS_ARDUINO_SD_LETTER` in ``lv_conf.h``.
+You will need to initialize the SD card before LVGL can use it (i.e. :cpp:expr:`SD.begin(0, SPI, 40000000)`).
+
+
+API
+---

docs/details/libs/barcode.rst

@@ -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 Widget 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_h`
+

docs/details/libs/bmp.rst

@@ -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-block:: 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 cannot be zoomed or rotated.
+
+.. _bmp_example:
+
+Example
+-------
+
+.. include:: ../../examples/libs/bmp/index.rst
+
+.. _bmp_api:
+
+API
+---
+

docs/details/libs/ffmpeg.rst

@@ -0,0 +1,52 @@
+.. _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-block:: 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
+---
+

docs/details/libs/freetype.rst

@@ -0,0 +1,121 @@
+.. _freetype:
+
+================
+FreeType support
+================
+
+Interface to FreeType library to generate font bitmap at 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-block:: 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`.
+
+The FreeType extension also supports colored bitmap glyphs such as emojis. Note
+that only bitmaps are supported at this time. Colored vector graphics cannot be
+rendered. An example on how to draw a colored bitmap glyph is shown below.
+
+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:
+
+Examples
+--------
+
+.. 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_h`
+
+:ref:`ftmodule_h`
+

docs/details/libs/fs.rst

@@ -0,0 +1,77 @@
+.. _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)
+- Arduino ESP LITTLEFS (a little fail-safe filesystem designed for Arduino ESP)
+- Arduino SD (allows for reading from and writing to SD cards)
+
+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"``.
+
+Working with common prefixes
+""""""""""""""""""""""""""""
+
+A **default driver letter** can be set by ``LV_FS_DEFAULT_DRIVE_LETTER``,
+which allows skipping the drive prefix in file paths.
+
+For example if ``LV_FS_DEFAULT_DRIVE_LETTER`` is set the ``'S'`` *"path/to/file.txt"* will mean *"S:path/to/file.txt"*.
+
+This feature is useful if you have only a single driver and don't want to bother with LVGL's driver layer in the file paths.
+It also helps to use a unified path with LVGL's file system and normal file systems.
+The original mechanism is not affected, so a path starting with drive letter will still work.
+
+The **working directory** can be set with ``LV_FS_..._PATH``. E.g.
+``"/home/joe/projects/"`` The actual file/directory paths will be
+appended to it, allowing to skip the common part.
+
+Caching
+"""""""
+
+:ref:`Cached reading <overview_file_system_cache>` 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-block:: 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
+***
+

docs/details/libs/gif.rst

@@ -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(widget, 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-block:: c
+
+   lv_gif_set_src(widget, "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_h`
+

docs/details/libs/index.rst

@@ -0,0 +1,28 @@
+.. _3rd_party_libraries:
+
+===================
+3rd-Party Libraries
+===================
+
+
+.. toctree::
+    :maxdepth: 1
+
+    arduino_esp_littlefs
+    arduino_sd
+    barcode
+    bmp
+    ffmpeg
+    freetype
+    fs
+    gif
+    lfs
+    libjpeg_turbo
+    libpng
+    lodepng
+    qrcode
+    rle
+    rlottie
+    svg
+    tiny_ttf
+    tjpgd

docs/details/libs/lfs.rst

@@ -0,0 +1,60 @@
+.. _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-block:: 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
+---
+
+

docs/details/libs/libjpeg_turbo.rst

@@ -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-block:: bash
+
+    sudo apt install libjpeg-turbo8-dev
+
+Add libjpeg-turbo to your project
+---------------------------------
+
+.. code-block:: 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:`lv_libjpeg_turbo_h`
+

docs/details/libs/libpng.rst

@@ -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-block:: bash
+
+    sudo apt install libpng-dev
+
+Add libpng to your project
+--------------------------
+
+.. code-block:: 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`
+

docs/details/libs/lodepng.rst

@@ -0,0 +1,51 @@
+.. _lodepng_rst:
+
+===============
+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_h`
+

docs/details/libs/qrcode.rst

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

docs/details/libs/rle.rst

@@ -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:: 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-block:: 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-block:: 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-block:: bash
+
+   ./script/LVGLImage.py --ofmt BIN --cf I8 --compress RLE cogwheel.png

docs/details/libs/rlottie.rst

@@ -0,0 +1,291 @@
+.. _rlottie:
+
+==============
+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>`__.
+
+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-block:: 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 Widget 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-block:: 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-block:: shell
+
+   ./filetohex.py path/to/lottie.json > out.txt
+
+To create an animation from raw data:
+
+.. code-block:: 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-block:: 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 cannot 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-block:: 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-block:: 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-block:: 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
+---

docs/details/libs/svg.rst

@@ -0,0 +1,47 @@
+.. _svg:
+
+==============
+SVG support
+==============
+
+Scalable Vector Graphics (SVG) Tiny 1.2 support in LVGL.
+
+Detailed introduction: https://www.w3.org/TR/SVGTiny12/
+
+Usage
+*****
+
+Enable :c:macro:`LV_USE_SVG` in ``lv_conf.h``.
+
+See the examples below.
+
+If you need support SVG animation attribute parsing,
+you can enable :c:macro:`LV_USE_SVG_ANIMATION` in ``lv_conf.h``.
+
+.. _svg_example:
+
+Example
+*******
+
+.. code:: c
+
+    lv_svg_node_t * svg_doc;
+    const char* svg_data = "<svg><rect x=\"0\" y=\"0\" width=\"100\" height=\"100\"/></svg>";
+
+    /* Create an SVG DOM tree*/
+    svg_doc = lv_svg_load_data(svg_data, svg_len);
+    ...
+
+    /* Draw SVG image*/
+    lv_draw_svg(layer, svg_doc);
+    ...
+
+    /* Release the DOM tree*/
+    lv_svg_node_delete(svg_doc);
+
+.. _svg_api:
+
+API
+***
+
+

docs/details/libs/tiny_ttf.rst

@@ -0,0 +1,55 @@
+.. _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 cache data for upto 256 glyphs elements to speed up rendering.
+This maximum can be changed by using
+:cpp:expr:`lv_tiny_ttf_create_data_ex(data, data_size, font_size, kerning, cache_size)`
+or :cpp:expr:`lv_tiny_ttf_create_file_ex(path, font_size, kerning, cache_size)` (when
+available). The cache size is indicated in number of entries. Kerning is whether to allow
+if supported, or disable.
+
+
+
+.. _tiny_ttf_example:
+
+Example
+-------
+
+.. include:: ../../examples/libs/tiny_ttf/index.rst
+
+.. _tiny_ttf_api:
+
+API
+---
+
+:ref:`stb_rect_pack_h`
+
+:ref:`stb_truetype_htcw_h`

docs/details/libs/tjpgd.rst

@@ -0,0 +1,67 @@
+.. _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-block:: 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_h`
+
+:ref:`tjpgd_h`
+
+:ref:`tjpgdcnf_h`