ESP MMAP ASSETS

[English]

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

功能

添加导入文件类型

支持多种文件格式，如 .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 options

用户可以选择将图像与应用程序二进制文件、分区表等一起自动刷写到设备上，通过在 idf.py flash 时指定 FLASH_IN_PROJECT。例如：

/* partitions.csv
 * -----------------------------------------------------------------------
 * | Name                | Type | SubType | Offset | Size  | Flags     |
 * --------------------------------------------------------
 * | my_spiffs_partition | data | spiffs  |        | 6000K |           |
 * -----------------------------------------------------------------------
 */
 spiffs_create_partition_assets(
     my_spiffs_partition
     my_folder
     FLASH_IN_PROJECT
     MMAP_FILE_SUPPORT_FORMAT ".png")

组件还支持以下选项，这些选项允许您在编译时，启用对图像的各种预处理。

set(options FLASH_IN_PROJECT,           // Defines storage type (flash in project)
             MMAP_SUPPORT_SJPG,         // Enable support for SJPG format
             MMAP_SUPPORT_SPNG,         // Enable support for SPNG format
             MMAP_SUPPORT_QOI,          // Enable support for QOI format
             MMAP_SUPPORT_SQOI,         // Enable support for SQOI format
             MMAP_SUPPORT_RAW,          // Enable support for RAW format (LVGL conversion only)
             MMAP_RAW_DITHER,           // Enable dithering for RAW images (LVGL conversion only)
             MMAP_RAW_BGR_MODE)         // Enable BGR mode for RAW images (LVGL conversion only)

 set(one_value_args MMAP_FILE_SUPPORT_FORMAT,    // Specify supported file format (e.g., .png, .jpg)
                MMAP_SPLIT_HEIGHT,               // Define the height for image splitting
                MMAP_RAW_FILE_FORMAT)            // Specify the file format for RAW images (LVGL conversion only)

应用示例

生成头文件 (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

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.

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

提供有关此文档的反馈