ESP MMAP ASSETS

[English]

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

功能

添加导入文件类型

支持多种文件格式，如 .bin、.jpg、.ttf 等。

多种访问模式

分区模式: 从 ESP32 分区访问资源（默认）
内存映射模式: 直接内存访问，性能最佳
文件系统模式: 从文件系统访问资源，用于开发和测试

启用分片 JPG

需要使用 SJPG 来解析。参见 LVGL SJPG。

启用分片 PNG

需要使用 esp_lv_decoder 来解析。参见组件 esp_lv_decoder。

设置分片高度

当开启 split 图片（ MMAP_SUPPORT_SJPG 、 MMAP_SUPPORT_SPNG 或 MMAP_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,
    IMPORT_INC_PATH,
    COPY_PREBUILT_BIN)

选项说明

通用选项

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

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

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

COPY_PREBUILT_BIN: 复制预生成的二进制文件到目标目录。此选项允许您使用外部生成的资产二进制文件，而不是从源文件构建。

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"
)

预构建二进制资源示例

spiffs_create_partition_assets(
   my_spiffs_partition
   "${ASSETS_DIR}"
   FLASH_IN_PROJECT
   COPY_PREBUILT_BIN "${ASSETS_DIR}/prebuilt.bin"
)

支持的图像格式

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 数据。

参考:

LVGL v8: 详细参考

LVGL v9: 详细参考

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_files 和 checksum，用来验证头文件和内存映射的二进制文件是否匹配，当然你也可以跳过此检验。

分区模式（默认）

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 = false,  // 使用分区模式
      .use_fs = false,       // 不使用文件系统
      .app_bin_check = true,
   }
};

ESP_ERROR_CHECK(mmap_assets_new(&config, &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,   // 启用内存映射
      .use_fs = false,       // 不使用文件系统
      .app_bin_check = true,
   }
};

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

文件系统模式

const mmap_assets_config_t config = {
   .partition_label = "/spiffs/assets.bin",  // 文件路径而不是分区名称
   .max_files = TOTAL_MMAP_FILES,
   .checksum = MMAP_CHECKSUM,
   .flags = {
      .mmap_enable = false,  // 禁用内存映射
      .use_fs = 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

components/display/tools/esp_mmap_assets/include/esp_mmap_assets.h

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.

size_t mmap_assets_copy_by_index(mmap_assets_handle_t handle, int index, void *dest_buffer, size_t size)

Copy asset data by index to a destination buffer (one-step operation).

This function combines get_mem and copy_mem operations into a single call. It retrieves the asset at the specified index and copies its data to the destination buffer.

参数

handle – [in] Asset instance handle.
index – [in] Index of the asset.
dest_buffer – [out] Pointer to the destination buffer where the asset data will be copied.
size – [in] Number of bytes to copy from the asset 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, or file path when use_fs is enabled

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 use_fs: Flag to use file system (partition_label as file path) instead of partition

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

提供有关此文档的反馈