Overview

Images can be embedded as variables within the application. Besides that, they can be loaded from external storage. This allows for greater flexibility, such as updating images without requiring application rebuilds.

Beginning with v0.28.0, external image file support has been implemented.

Configuration

Enable External Image Support

  1. Navigate to Project → Project Config...
  2. Enable Use External Image File
  3. Configure the Path Prefix
  4. Define decoder support in lv_conf.h:
#define LV_USE_FS_STDIO 1 // Enable file system support

#define LV_USE_PNG 1      // Enable PNG decoder
#define LV_USE_JPEG 1     // Enable JPEG decoder
#define LV_USE_BMP 1      // Enable BMP decoder

File System Driver Implementation

Implement and register a file system driver for file I/O operations.

A reference implementation for the simulator is provided, which can be adapted for custom implementations:

/* File system callbacks for LVGL */
static void *fs_open(lv_fs_drv_t *drv, const char *path, lv_fs_mode_t mode) {
  LV_UNUSED(drv);
  const char *flags = (mode == LV_FS_MODE_WR) ? "wb" : "rb";
  return fopen(path, flags);
}

static lv_fs_res_t fs_close(lv_fs_drv_t *drv, void *file) {
  LV_UNUSED(drv);
  fclose((FILE *)file);
  return LV_FS_RES_OK;
}

static lv_fs_res_t fs_read(lv_fs_drv_t *drv, void *file, void *buf,
                           uint32_t btr, uint32_t *br) {
  LV_UNUSED(drv);
  *br = fread(buf, 1, btr, (FILE *)file);
  return (*br > 0) ? LV_FS_RES_OK : LV_FS_RES_UNKNOWN;
}

static lv_fs_res_t fs_seek(lv_fs_drv_t *drv, void *file, uint32_t pos,
                           lv_fs_whence_t whence) {
  LV_UNUSED(drv);
  int origin = (whence == LV_FS_SEEK_SET)   ? SEEK_SET
               : (whence == LV_FS_SEEK_CUR) ? SEEK_CUR
                                            : SEEK_END;
  fseek((FILE *)file, pos, origin);
  return LV_FS_RES_OK;
}

static lv_fs_res_t fs_tell(lv_fs_drv_t *drv, void *file, uint32_t *pos) {
  LV_UNUSED(drv);
  *pos = ftell((FILE *)file);
  return LV_FS_RES_OK;
}

/* Register the file system */
void register_fs() {
  static lv_fs_drv_t fs_drv;
  lv_fs_drv_init(&fs_drv);
  fs_drv.letter = 'S'; // Drive letter
  fs_drv.open_cb = fs_open;
  fs_drv.close_cb = fs_close;
  fs_drv.read_cb = fs_read;
  fs_drv.seek_cb = fs_seek;
  fs_drv.tell_cb = fs_tell;
  lv_fs_drv_register(&fs_drv);
}

Register the file system by calling register_fs() in main():

int main() {
  ...
  register_fs();
  ...
}

Enable simulation by defining USE_SIMULATOR in lv_conf.h within the simulator folder:

#define USE_SIMULATOR

Important Considerations

Info

If image loading fails due to memory allocation issues, increase LV_MEM_SIZE in lv_conf.h:

#  define LV_MEM_SIZE    (? * 1024U * 1024U)          /*[bytes]*/

Warning

  • All images must be located in the configured Path Prefix directory on the target device
  • Image component dimensions must match the source image dimensions, as the original image will be displayed without scaling