ESP MMAP ASSETS

[English]

该模块主要用于打包资源(如图像、字体等),将其直接映射以供用户访问。同时,它内部也集成了丰富的图像预处理功能。

功能

添加导入文件类型
  • 支持多种文件格式,如 .bin.jpg.ttf 等。

启用分片 JPG
  • 需要使用 SJPG 来解析。参见 LVGL SJPG

启用分片 PNG
  • 需要使用 esp_lv_decoder 来解析。参见组件 esp_lv_decoder

设置分片高度
  • 当开启 split 图片( MMAP_SUPPORT_SJPGMMAP_SUPPORT_SPNGMMAP_SUPPORT_SQOI)处理功能,可以灵活设置图片分割的高度。

支持 QOI
  • 支持将图像从 JPG、PNG 格式转换为 QOI。

  • 支持 split qoi,需要使用 esp_lv_decoder 来解析。

支持多分区
  • 使用 spiffs_create_partition_assets 挂载分区时,支持挂载多个分区,且为每个分区设置不同的处理逻辑。

支持 LVGL Image Converter
  • 通过开启 MMAP_SUPPORT_RAW 以及相关配置,可以将 JPG、PNG 转换为 Bin, 以便在 LVGL 中使用它们。

CMake 选项

支持以下选项。这些选项允许您配置图像处理的各个方面。

set(options
    FLASH_IN_PROJECT,
    FLASH_APPEND_APP,
    MMAP_SUPPORT_SJPG,
    MMAP_SUPPORT_SPNG,
    MMAP_SUPPORT_QOI,
    MMAP_SUPPORT_SQOI,
    MMAP_SUPPORT_RAW,
    MMAP_RAW_DITHER,
    MMAP_RAW_BGR_MODE)

set(one_value_args
    MMAP_FILE_SUPPORT_FORMAT,
    MMAP_SPLIT_HEIGHT,
    MMAP_RAW_FILE_FORMAT)

选项说明

通用选项

  • FLASH_IN_PROJECT: 用户可以选择在 idf.py flash 时自动将图像与应用程序二进制文件、分区表等一起烧录。

  • FLASH_APPEND_APP: 启用将二进制数据(bin)附加到应用程序二进制文件(app_bin)。

  • IMPORT_INC_PATH: 指定生成头文件的目标路径。默认与引用组件位置相同。

  • MMAP_FILE_SUPPORT_FORMAT: 指定支持的文件格式(例如,.png.jpg.ttf)。

  • MMAP_SPLIT_HEIGHT: 定义图像分割的高度以减少内存使用。依赖于:

    • MMAP_SUPPORT_SJPG

    • MMAP_SUPPORT_SPNG

    • MMAP_SUPPORT_SQOI

通用示例
spiffs_create_partition_assets(
   my_spiffs_partition
   my_folder
   FLASH_IN_PROJECT
   MMAP_FILE_SUPPORT_FORMAT ".jpg,.png,.ttf"
)

支持的图像格式

  • MMAP_SUPPORT_SJPG: 启用对 SJPG 格式的支持。

  • MMAP_SUPPORT_SPNG: 启用对 SPNG 格式的支持。

  • MMAP_SUPPORT_QOI: 启用对 QOI 格式的支持。

  • MMAP_SUPPORT_SQOI: 启用对 SQOI 格式的支持。依赖于:

    • MMAP_SUPPORT_QOI

图像分割示例
spiffs_create_partition_assets(
   my_spiffs_partition
   my_folder
   FLASH_IN_PROJECT
   MMAP_FILE_SUPPORT_FORMAT ".jpg"
   MMAP_SUPPORT_SJPG
   MMAP_SPLIT_HEIGHT 16
)

LVGL Bin 支持

  • MMAP_SUPPORT_RAW: 将图像转换为 LVGL 支持的 Binary 数据。

    参考:
  • MMAP_RAW_FILE_FORMAT: 指定 RAW 图像的文件格式。

    • LVGL v8: {true_color, true_color_alpha, true_color_chroma, indexed_1, indexed_2, indexed_4, indexed_8, alpha_1, alpha_2, alpha_4, alpha_8, raw, raw_alpha, raw_chroma}

    • LVGL v9: 未使用。

  • MMAP_RAW_COLOR_FORMAT: 指定 RAW 图像的颜色格式。

    • LVGL v8: {RGB332, RGB565, RGB565SWAP, RGB888}

    • LVGL v9: {L8, I1, I2, I4, I8, A1, A2, A4, A8, ARGB8888, XRGB8888, RGB565, RGB565A8, ARGB8565, RGB888, AUTO, RAW, RAW_ALPHA}

  • MMAP_RAW_DITHER: 启用 RAW 图像的 抖动

    • LVGL v8: 需要抖动。

    • LVGL v9: 未使用。

  • MMAP_RAW_BGR_MODE: 启用 RAW 图像的 BGR 模式

    • LVGL v8: 未使用。

    • LVGL v9: 未使用。

LVGL v9 示例
spiffs_create_partition_assets(
    .........
    MMAP_FILE_SUPPORT_FORMAT ".png"
    MMAP_SUPPORT_RAW
    MMAP_RAW_COLOR_FORMAT "ARGB8888"
)
LVGL v8 示例
spiffs_create_partition_assets(
    .........
    MMAP_FILE_SUPPORT_FORMAT ".png"
    MMAP_SUPPORT_RAW
    MMAP_RAW_FILE_FORMAT "true_color_alpha"
    MMAP_RAW_COLOR_FORMAT "RGB565SWAP"
)

应用示例

生成头文件 (mmap_generate_my_spiffs_partition.h)

该头文件自动生成,包含内存映射资源的基本定义。

#include "mmap_generate_my_spiffs_partition.h"

#define TOTAL_MMAP_FILES      2
#define MMAP_CHECKSUM         0xB043

enum MMAP_FILES {
   MMAP_JPG_JPG = 0,   /*!< jpg.jpg */
   MMAP_PNG_PNG = 1,   /*!< png.png */
};

创建资源句柄

资源初始化配置确保与 mmap_generate_my_spiffs_partition.h 一致。它设置了 max_fileschecksum,用来验证头文件和内存映射的二进制文件是否匹配,当然你也可以跳过此检验。

mmap_assets_handle_t asset_handle;

const mmap_assets_config_t config = {
   .partition_label = "my_spiffs_partition",
   .max_files = TOTAL_MMAP_FILES,
   .checksum = MMAP_CHECKSUM,
   .flags = {
         .mmap_enable = true,
         .app_bin_check = true,
     },
};

ESP_ERROR_CHECK(mmap_assets_new(&config, &asset_handle));

资源使用

可以使用 mmap_generate_my_spiffs_partition.h 中定义的枚举来获取资源信息。

const char *name = mmap_assets_get_name(asset_handle, MMAP_JPG_JPG);
const void *mem = mmap_assets_get_mem(asset_handle, MMAP_JPG_JPG);
int size = mmap_assets_get_size(asset_handle, MMAP_JPG_JPG);
int width = mmap_assets_get_width(asset_handle, MMAP_JPG_JPG);
int height = mmap_assets_get_height(asset_handle, MMAP_JPG_JPG);

ESP_LOGI(TAG, "Name:[%s], Mem:[%p], Size:[%d bytes], Width:[%d px], Height:[%d px]", name, mem, size, width, height);

API 参考

Header File

Functions

esp_err_t mmap_assets_new(const mmap_assets_config_t *config, mmap_assets_handle_t *ret_item)

Create a new asset instance.

参数
  • config[in] Pointer to the asset configuration structure.

  • ret_item[out] Pointer to the handle of the newly created asset instance.

返回

  • ESP_OK: Success

  • ESP_ERR_NO_MEM: Insufficient memory

  • ESP_ERR_NOT_FOUND: Can’t find partition

  • ESP_ERR_INVALID_SIZE: File num mismatch

  • ESP_ERR_INVALID_CRC: Checksum mismatch

esp_err_t mmap_assets_del(mmap_assets_handle_t handle)

Delete an asset instance.

参数

handle[in] Asset instance handle.

返回

  • ESP_OK: Success

  • ESP_ERR_INVALID_ARG: Invalid argument

const uint8_t *mmap_assets_get_mem(mmap_assets_handle_t handle, int index)

Get the memory of the asset at the specified index.

参数
  • handle[in] Asset instance handle.

  • index[in] Index of the asset.

返回

Pointer to the asset memory, or NULL if index is invalid.

size_t mmap_assets_copy_mem(mmap_assets_handle_t handle, size_t offset, void *dest_buffer, size_t size)

Copy a portion of an asset’s memory to a destination buffer.

参数
  • handle[in] Asset instance handle.

  • offset[in] Offset within the asset’s memory from which to start copying.

  • dest_buffer[out] Pointer to the destination buffer where the memory will be copied.

  • size[in] Number of bytes to copy from the asset’s memory to the destination buffer.

返回

The actual number of bytes copied, or 0 if the operation fails.

const char *mmap_assets_get_name(mmap_assets_handle_t handle, int index)

Get the name of the asset at the specified index.

参数
  • handle[in] Asset instance handle.

  • index[in] Index of the asset.

返回

Pointer to the asset name, or NULL if index is invalid.

int mmap_assets_get_size(mmap_assets_handle_t handle, int index)

Get the size of the asset at the specified index.

参数
  • handle[in] Asset instance handle.

  • index[in] Index of the asset.

返回

Size of the asset, or -1 if index is invalid.

int mmap_assets_get_width(mmap_assets_handle_t handle, int index)

Get the width of the asset at the specified index.

参数
  • handle[in] Asset instance handle.

  • index[in] Index of the asset.

返回

Width of the asset, or -1 if index is invalid.

int mmap_assets_get_height(mmap_assets_handle_t handle, int index)

Get the height of the asset at the specified index.

参数
  • handle[in] Asset instance handle.

  • index[in] Index of the asset.

返回

Height of the asset, or -1 if index is invalid.

int mmap_assets_get_stored_files(mmap_assets_handle_t handle)

Get the number of stored files in the memory-mapped asset.

This function returns the total number of assets stored in the memory-mapped file associated with the given handle. This can be useful for iterating over all assets or validating the file contents.

参数

handle[in] Asset instance handle. This handle is used to identify the memory-mapped file instance containing the assets.

返回

The number of stored assets. Returns the total count of assets if the handle is valid, otherwise returns 0.

Structures

struct mmap_assets_config_t

Asset configuration structure, contains the asset table and other configuration information.

Public Members

const char *partition_label

Label of the partition containing the assets

int max_files

Maximum number of assets supported

uint32_t checksum

Checksum of the asset table for integrity verification

unsigned int mmap_enable

Flag to indicate if memory-mapped I/O is enabled

unsigned int app_bin_check

Flag to enable app header and bin file consistency check

unsigned int full_check

Flag to enable self-consistency check

unsigned int metadata_check

Flag to enable metadata verification

unsigned int reserved

Reserved for future use

struct mmap_assets_config_t::[anonymous] flags

Configuration flags

Type Definitions

typedef struct mmap_assets_t *mmap_assets_handle_t

Asset handle type, points to the asset.

Type of asset handle