Image Sources
The images module supports images in any of 3 forms:
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:
| Field | Description |
|---|---|
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:
- 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 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.
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
How is this guide?
Last updated on