.. include:: /include/substitutions.txt .. include:: /include/external_links.txt .. include:: /include/custom_roles.txt .. _lz4:

================= LZ4 Decompression

LVGL provides the extremely fast LZ4 decompression method found in the LZ4 repository <https://github.com/lz4/lz4>__ on GitHub. It can be used to reduce binary image size. The LZ4 compression is a lossless compression method.

The LVGL's built-in binary image decoder supports LZ4-compressed images. The decoder supports both variable and file as image sources. The original binary data is directly decoded to RAM.

Which Library

If :c:macro:LV_USE_LZ4_INTERNAL is enabled in lv_conf.h, LVGL's internal copy of the LZ4 decompression algorithm is used (./src/libs/lz4/lz4.c).

If :c:macro:LV_USE_LZ4_EXTERNAL is enabled, the LVGL project is assumed to be compiled and linked with an external LZ4 library that provides the :cpp:func:LZ4_decompress_safe function.

One of them must be enabled to use LZ4 decompression.

Benefits

LZ4 is best at compressing data where compression and decompression speed is a priority over compression ratio, making it ideal for applications like real-time data processing.

.. image:: /_static/images/lz4-compress-statistics.png :alt: LZ4 compress statistics from lz4.org :align: center

.. _lz4_usage:

Usage

To use the LZ4 Decoder, enable it in lv_conf.h configuration file by setting either :c:macro:LV_USE_LZ4_INTERNAL or :c:macro:LV_USE_LZ4_EXTERNAL to 1. LZ4 images can then be used in the same way as other images.

.. code-block:: c

lv_image_set_src(img, "path/to/cogwheel.bin");

Generating LZ4 Compressed Binary Images

An LZ4 image binary can be directly generated from another image using script lvgl/scripts/LVGLImage.py.

.. code-block:: bash

./scripts/LVGLImage.py --ofmt BIN --cf I8 --compress LZ4 cogwheel.png

This will decompress cogwheel.png, and then re-compress it using LZ4 and write the output to ./output/cogwheel.bin.