============= Image Sources

The images module supports images in any of 3 forms:

.. container:: tighter-table-3

+------------+------------------------------------------------------------------+
| Form       | Source                                                           |
+============+==================================================================+
| Variables_ | :cpp:type:`lv_image_dsc_t` object + data in ROM or RAM           |
+------------+------------------------------------------------------------------+
| Files_     | :ref:`file_system` path to file (e.g. JPG, PNG, BMP etc.)        |
+------------+------------------------------------------------------------------+
| Symbols_   | C strings starting with Unicode characters (e.g. icons) in UTF-8 |
+------------+------------------------------------------------------------------+

Image sources are set by calling one of the ..._set_src() functions. See code examples below.

.. _image_sources_variables:

Variables

In this context, a "variable" is a C symbol that is used in C code to refer to an object in either RAM or ROM.

Images stored as variables are comprised of an :cpp:struct:lv_image_dsc_t struct plus its data. The struct contains the following fields:

:header:

:magic:       Magic number (must be LV_IMAGE_HEADER_MAGIC)
:cf:          Color format. See :ref:`images_color_formats`.
:flags:       Image flags (any of the ``LV_IMAGE_FLAGS_...`` enumeration values).
:w:           Width in pixels (<= 2048)
:h:           Height in pixels (<= 2048)
:stride:      Number of bytes between the beginning of one row of pixels and the beginning of the next row
:reserved_2:  reserved for future use

:data_size: length of data in bytes :data: pointer to a byte array where the data of the image is stored (pixels and sometimes indexed color palettes [for indexed color formats]). When header.cf is one of the RAW formats, this can also contain the contents of a file loaded into RAM at run-time, or embedded in ROM (program space).

These are usually stored within a project as a C file generated by one of these two LVGL image converters:

LVGL Online Image Converter_
Offline converter in ./scripts/LVGLImage.py.

At this writing, the online converter supports these formats:

RGB565
RGB565A8
RGB888
XRGB8888
ARGB8888

The offline converter can convert an image into the above formats plus all the other supported color formats.

The generated C files are compiled and linked into the resulting executable like any other const data.

See :ref:adding images to your project for more details.

Example:

.. code-block:: c

LV_IMAGE_DECLARE(img_cogwheel_argb);
lv_obj_t * img = lv_image_create(lv_screen_active());
lv_image_set_src(img, &img_cogwheel_argb);

.. _image_sources_files:

Files

Files can be used as image sources by passing in the path string to the image file to the lv_<widget>_set_src() function as the src argument. The string must begin with a printable ASCII character (range [0x20-0x7F]). Example:

.. code-block:: c

lv_image_set_src(icon, "S:my_icon.png");

Images stored as files are normally not linked into the resulting executable, and must be read into RAM before being drawn. As a result, they are not as resource-friendly as images linked at compile time. However, they are easier to replace without needing to rebuild the main program.

Exceptions where there is no meaningful extra memory usage:

JPEG: Only a few pixels are read and drawn at once.
BMP: Pixels are transferred directly from the file to the draw buffer.
BIN: Pixels are transferred line-by-line to the draw buffer.

For the images module to deal with files you need to add a Driver for the target storage system to LVGL. See :ref:file_system for details.

.. _image_sources_symbols:

Symbols

Symbols that can be used as an image source are char * strings beginning with a Unicode character encoded in UTF-8, which will have a first-byte value >= 0x80. After that, these strings can contain any other characters, including additional Unicode characters. Such strings are passed as the image source like this:

.. code-block:: c

lv_image_set_src(icon, LV_SYMBOL_BATTERY_FULL);
/* or */
lv_image_set_src(icon, LV_SYMBOL_OK " Accept");

The file ./src/font/lv_symbol_def.h contains a wide variety of Unicode symbols you can use directly, or you can make your own. See :ref:font_adding_a_custom_symbol for details.

.. note::

Symbols are only implemented for :ref:`lv_image` Widgets.

Examples

See :ref:Using Images Examples <using_images_examples> for a number of examples of using image sources in these 3 forms.

API

.. API equals: lv_image_set_src