Image Sources

The images module supports images in any of 3 forms:

Form

Source

Variables

lv_image_dsc_t object + data in ROM or RAM

Files

File System (lv_fs_drv) 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.

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

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 Adding Images to Your Project for more details.

Example:

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

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:

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 File System (lv_fs_drv) for details.

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:

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 Adding a Custom Symbol for details.

Note

Symbols are only implemented for Image (lv_image) Widgets.

Examples

See Using Images Examples for a number of examples of using image sources in these 3 forms.

API