ESP MMAP ASSETS
该模块主要用于打包资源(如图像、字体等),将其直接映射以供用户访问。同时,它内部也集成了丰富的图像预处理功能。
功能
- 添加导入文件类型
支持多种文件格式,如
.bin
、.jpg
、.ttf
等。
- 启用分片 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)
选项说明
通用选项
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_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 = 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
-
const char *partition_label
Type Definitions
-
typedef struct mmap_assets_t *mmap_assets_handle_t
Asset handle type, points to the asset.
Type of asset handle