image_cache_manager
image_cache_manager 模块提供图像缓存管理功能，用于管理图像缓存内存的申请、释放与回收。
Class Summary
OHOS::ImageCacheManager
图像缓存管理类，提供图像资源的加载、缓存与卸载能力
- 构造：无
-
成员函数：
接口名称 功能简述 GetInstance 获取 ImageCacheManager 单例实例 LoadAllInMultiRes 从打包资源文件或内存缓冲区加载全部图像 LoadPartialInMultiRes 从打包资源文件或内存缓冲区加载指定数量的图像 LoadOneInMultiRes 从已加载的多图像资源中按资源 ID 加载单张图像 UnloadOneInMultiRes 卸载指定资源 ID 的单张图像 UnloadPartialInMultiRes 卸载多个指定资源 ID 的图像 UnloadAllInMultiRes 卸载指定文件或缓冲区关联的全部图像 LoadSingleRes 加载单资源文件中的图像 UnloadSingleRes 卸载单资源文件中的图像 UpdateImageInfoIfNecessary 检查图像是否已释放，若已释放则重新加载，否则更新使用信息 TryToFreeImage 尝试释放图像缓存资源 Dump 输出图像缓存信息 EnterAod 进入 AOD（Always On Display）模式 ExitAod 退出 AOD 模式 IsInAod 查询当前是否处于 AOD 模式 -
使用包含头文件：
#include "image_cache_manager.h" - 声明头文件：
middleware/services/gui/uikit/proprietary/include/common/image_cache_manager.h - 公有运算符：无
- 继承关系：HeapBase
- 嵌套类型：无
- 模板形参：无
Functions
OHOS::ImageCacheManager
GetInstance
static ImageCacheManager& GetInstance()
功能说明
- 核心用途：获取 ImageCacheManager 的全局单例实例
- 设计目的：确保图像缓存管理器在整个进程中唯一存在，统一管理图像资源的加载与释放
- 使用场景：所有图像加载、卸载操作均需通过此单例实例调用
返回值
- 返回类型：
ImageCacheManager&
返回单例实例的引用
| 返回值 | 触发场景 |
|---|---|
| ImageCacheManager& | 成功获取单例实例引用 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
LoadAllInMultiRes
bool LoadAllInMultiRes(const std::string& file, FILE* userFP = nullptr, bool isLongTerm = false, int offset = 0)
功能说明
- 核心用途：从打包资源文件中一次性加载全部图像到缓存
- 设计目的：批量预加载图像资源，后续通过 LoadOneInMultiRes 按资源 ID 获取具体图像
- 使用场景：应用启动时预加载整个图像资源包，或页面切换前批量加载所需图像
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| file | const std::string& | 图像二进制资源文件路径，入参只读引用 | 有效的文件路径字符串 |
| userFP | FILE* | 外部已打开的文件指针，入参指针，可为 nullptr；不为 nullptr 时优先使用该指针 | nullptr 或有效的 FILE* |
| isLongTerm | bool | 是否将图像保持在长期缓存中 | false / true |
| offset | int | 多图像资源的起始偏移量 | ≥ 0 |
返回值
- 返回类型：
bool
返回加载结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 图像全部加载成功 |
| false(0) | 加载失败 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
LoadPartialInMultiRes
bool LoadPartialInMultiRes(const std::string& file, uint32_t startResId, uint32_t num, FILE* userFP = nullptr, bool isLongTerm = false, uint32_t offset = 0)
功能说明
- 核心用途：从打包资源文件中加载指定数量的图像到缓存
- 设计目的：按需加载部分图像资源，减少不必要的内存占用
- 使用场景：仅需使用资源包中部分图像时，指定起始资源 ID 和数量进行部分加载
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| file | const std::string& | 图像二进制资源文件路径，入参只读引用 | 有效的文件路径字符串 |
| startResId | uint32_t | 起始图像的资源 ID | 0 ~ 最大资源 ID |
| num | uint32_t | 需要加载的图像数量 | > 0 |
| userFP | FILE* | 外部已打开的文件指针，入参指针，可为 nullptr | nullptr 或有效的 FILE* |
| isLongTerm | bool | 是否将图像保持在长期缓存中 | false / true |
| offset | uint32_t | 多图像资源的起始偏移量 | ≥ 0 |
返回值
- 返回类型：
bool
返回加载结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 图像加载成功 |
| false(0) | 加载失败 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
LoadAllInMultiRes
bool LoadAllInMultiRes(uint8_t* buf)
功能说明
- 核心用途：从内存缓冲区中一次性加载全部图像到缓存
- 设计目的：支持从内存中直接加载图像资源，无需文件系统路径
- 使用场景：图像数据已存在于内存中时，直接从缓冲区加载全部图像
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| buf | uint8_t* | 内存中图像二进制数据的地址，入参指针 | 非 nullptr，指向有效的图像数据 |
返回值
- 返回类型：
bool
返回加载结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 图像全部加载成功 |
| false(0) | 加载失败 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
LoadPartialInMultiRes
bool LoadPartialInMultiRes(uint8_t* buf, uint32_t startResId, uint32_t num)
功能说明
- 核心用途：从内存缓冲区中加载指定数量的图像到缓存
- 设计目的：按需从内存缓冲区加载部分图像资源，减少内存占用
- 使用场景：图像数据已存在于内存中，仅需加载部分图像时使用
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| buf | uint8_t* | 内存中图像二进制数据的地址，入参指针 | 非 nullptr，指向有效的图像数据 |
| startResId | uint32_t | 起始图像的资源 ID | 0 ~ 最大资源 ID |
| num | uint32_t | 需要加载的图像数量 | > 0 |
返回值
- 返回类型：
bool
返回加载结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 图像加载成功 |
| false(0) | 加载失败 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
LoadOneInMultiRes
ImageInfo* LoadOneInMultiRes(uint32_t resId, const std::string& file, FILE* userFP = nullptr, bool isLongTerm = false, int offset = 0)
功能说明
- 核心用途：按资源 ID 从打包资源文件中加载单张图像，若已加载则直接返回缓存中的图像信息
- 设计目的：支持按需加载单个图像资源，已缓存时直接返回避免重复加载
- 使用场景：UI 组件需要显示某张图像时，通过资源 ID 按需获取
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| resId | uint32_t | 目标图像的资源 ID | 0 ~ 最大资源 ID |
| file | const std::string& | 图像二进制资源文件路径，入参只读引用 | 有效的文件路径字符串 |
| userFP | FILE* | 外部已打开的文件指针，入参指针，可为 nullptr | nullptr 或有效的 FILE* |
| isLongTerm | bool | 是否将图像保持在长期缓存中 | false / true |
| offset | int | 多图像资源的起始偏移量 | ≥ 0 |
返回值
- 返回类型：
ImageInfo*
返回图像信息指针
| 返回值 | 触发场景 |
|---|---|
| 非 nullptr | 成功加载并返回图像信息指针 |
| nullptr | 加载失败 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
LoadOneInMultiRes
ImageInfo* LoadOneInMultiRes(uint8_t* buf, uint32_t resId)
功能说明
- 核心用途：按资源 ID 从内存缓冲区中加载单张图像，若已加载则直接返回缓存中的图像信息
- 设计目的：支持从内存缓冲区按需加载单个图像资源
- 使用场景：图像数据已存在于内存中，需要获取指定资源 ID 的图像
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| buf | uint8_t* | 内存中图像二进制数据的地址，入参指针 | 非 nullptr，指向有效的图像数据 |
| resId | uint32_t | 目标图像的资源 ID | 0 ~ 最大资源 ID |
返回值
- 返回类型：
ImageInfo*
返回图像信息指针
| 返回值 | 触发场景 |
|---|---|
| 非 nullptr | 成功加载并返回图像信息指针 |
| nullptr | 加载失败 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
UnloadOneInMultiRes
bool UnloadOneInMultiRes(uint32_t resId, const std::string& file)
功能说明
- 核心用途：卸载指定文件中指定资源 ID 的单张图像
- 设计目的：释放不再使用的图像缓存资源，回收内存
- 使用场景：UI 组件不再需要某张图像时，卸载该图像以释放缓存
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| resId | uint32_t | 目标图像的资源 ID | 0 ~ 最大资源 ID |
| file | const std::string& | 图像资源文件路径，入参只读引用 | 有效的文件路径字符串 |
返回值
- 返回类型：
bool
返回卸载结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 卸载成功 |
| false(0) | 卸载失败 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
UnloadOneInMultiRes
bool UnloadOneInMultiRes(uint8_t* buf, uint32_t resId)
功能说明
- 核心用途：卸载指定缓冲区中指定资源 ID 的单张图像
- 设计目的：从内存缓冲区加载的图像缓存中释放指定资源
- 使用场景：从内存缓冲区加载的图像不再使用时，卸载该图像
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| buf | uint8_t* | 内存中图像二进制数据的地址，入参指针 | 非 nullptr，指向有效的图像数据 |
| resId | uint32_t | 目标图像的资源 ID | 0 ~ 最大资源 ID |
返回值
- 返回类型：
bool
返回卸载结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 卸载成功 |
| false(0) | 卸载失败 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
UnloadPartialInMultiRes
bool UnloadPartialInMultiRes(const uint32_t* resIdArray, uint32_t arrayLen, const std::string& file)
功能说明
- 核心用途：卸载指定文件中多个资源 ID 对应的图像
- 设计目的：批量释放多个不再使用的图像缓存资源
- 使用场景：页面退出时批量卸载该页面关联的多张图像
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| resIdArray | const uint32_t* | 资源 ID 数组，入参只读指针 | 非 nullptr |
| arrayLen | uint32_t | 资源 ID 数组的长度 | > 0 |
| file | const std::string& | 图像资源文件路径，入参只读引用 | 有效的文件路径字符串 |
返回值
- 返回类型：
bool
返回卸载结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 卸载成功 |
| false(0) | 卸载失败 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
UnloadPartialInMultiRes
bool UnloadPartialInMultiRes(uint8_t* buf, const uint32_t* resIdArray, uint32_t arrayLen)
功能说明
- 核心用途：卸载指定缓冲区中多个资源 ID 对应的图像
- 设计目的：批量释放从内存缓冲区加载的多个图像缓存资源
- 使用场景：从内存缓冲区加载的多个图像不再使用时，批量卸载
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| buf | uint8_t* | 内存中图像二进制数据的地址，入参指针 | 非 nullptr，指向有效的图像数据 |
| resIdArray | const uint32_t* | 资源 ID 数组，入参只读指针 | 非 nullptr |
| arrayLen | uint32_t | 资源 ID 数组的长度 | > 0 |
返回值
- 返回类型：
bool
返回卸载结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 卸载成功 |
| false(0) | 卸载失败 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
UnloadAllInMultiRes
bool UnloadAllInMultiRes(const std::string& file)
功能说明
- 核心用途：卸载指定文件关联的全部图像缓存
- 设计目的：一次性释放某个资源文件的所有图像缓存，回收内存
- 使用场景：应用退出某个功能模块时，卸载该模块关联的所有图像资源
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| file | const std::string& | 图像资源文件路径，入参只读引用 | 有效的文件路径字符串 |
返回值
- 返回类型：
bool
返回卸载结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 卸载成功 |
| false(0) | 卸载失败 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
UnloadAllInMultiRes
bool UnloadAllInMultiRes(uint8_t* buf)
功能说明
- 核心用途：卸载指定缓冲区关联的全部图像缓存
- 设计目的：一次性释放某个内存缓冲区的所有图像缓存
- 使用场景：从内存缓冲区加载的全部图像不再使用时，整体卸载
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| buf | uint8_t* | 内存中图像二进制数据的地址，入参指针 | 非 nullptr，指向有效的图像数据 |
返回值
- 返回类型：
bool
返回卸载结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 卸载成功 |
| false(0) | 卸载失败 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
LoadSingleRes
ImageInfo* LoadSingleRes(const std::string& file, bool isLongTerm = false)
功能说明
- 核心用途：加载单资源文件中的图像（二进制文件中仅包含一张图像）
- 设计目的：为仅包含单张图像的资源文件提供便捷的加载接口
- 使用场景：加载独立图像文件，如图标、背景图等单一资源
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| file | const std::string& | 图像资源文件路径，入参只读引用 | 有效的文件路径字符串 |
| isLongTerm | bool | 是否将图像保持在长期缓存中 | false / true |
返回值
- 返回类型：
ImageInfo*
返回图像信息指针
| 返回值 | 触发场景 |
|---|---|
| 非 nullptr | 成功加载并返回图像信息指针 |
| nullptr | 加载失败 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
UnloadSingleRes
bool UnloadSingleRes(const std::string& file)
功能说明
- 核心用途：卸载单资源文件中加载的图像
- 设计目的：释放单资源图像的缓存，回收内存
- 使用场景：单资源图像不再使用时，卸载该图像
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| file | const std::string& | 图像资源文件路径，入参只读引用 | 有效的文件路径字符串 |
返回值
- 返回类型：
bool
返回卸载结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 卸载成功 |
| false(0) | 卸载失败 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
UpdateImageInfoIfNecessary
void UpdateImageInfoIfNecessary(ImageInfo& info)
功能说明
- 核心用途：检查图像是否已被释放，若已释放则重新加载，否则更新使用信息
- 设计目的：在缓存淘汰机制下，确保正在使用的图像不会被错误释放
- 使用场景：UI 组件在绘制图像前调用，确保图像数据有效
入参
| 名称 | 参数类型 | 详细说明 | 约束取值范围 |
|---|---|---|---|
| info | ImageInfo& | 图像信息引用，入参引用，函数可能写入（重新加载或更新） | 有效的 ImageInfo 对象引用 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
TryToFreeImage
bool TryToFreeImage()
功能说明
- 核心用途：尝试释放短期缓存中的图像资源
- 设计目的：在内存紧张时主动回收短期缓存占用的内存空间
- 使用场景：系统内存不足时调用，尝试释放非长期持有的图像缓存
返回值
- 返回类型：
bool
返回释放结果
| 返回值 | 触发场景 |
|---|---|
| true(1) | 成功释放图像缓存 |
| false(0) | 无可释放的缓存或释放失败 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
Dump
void Dump()
功能说明
- 核心用途：输出当前图像缓存管理器的调试信息
- 设计目的：提供缓存状态的可观测能力，便于调试与性能分析
- 使用场景：开发调试阶段查看图像缓存加载情况与内存占用
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
EnterAod
void EnterAod()
功能说明
- 核心用途：进入 AOD（Always On Display）模式
- 设计目的：在 AOD 模式下对图像缓存进行特殊管理，记录 AOD 使用的图像文件
- 使用场景：设备进入常亮显示模式时调用
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
ExitAod
void ExitAod()
功能说明
- 核心用途：退出 AOD（Always On Display）模式
- 设计目的：恢复正常的图像缓存管理策略
- 使用场景：设备退出常亮显示模式时调用
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
IsInAod
bool IsInAod() const
功能说明
- 核心用途：查询当前图像缓存管理器是否处于 AOD 模式
- 设计目的：供上层组件判断当前缓存策略是否为 AOD 模式
- 使用场景：在加载或卸载图像前判断当前是否处于 AOD 模式，以决定缓存策略
返回值
- 返回类型：
bool
返回 AOD 模式状态
| 返回值 | 触发场景 |
|---|---|
| true(1) | 当前处于 AOD 模式 |
| false(0) | 当前未处于 AOD 模式 |
Kconfig 配置
| 配置项 | 说明 | 默认值 |
|---|---|---|
| ENABLE_IMAGE_PACKER | 启用图像打包缓存功能 | 1 |
Structures
ImageHeader
struct ImageHeader {
uint32_t colorMode : 8;
uint32_t version : 4;
uint32_t compressMode : 4;
uint32_t reserved : 16;
uint16_t width;
uint16_t height;
};
成员说明
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| colorMode | uint32_t : 8 | 图像颜色格式，用于匹配图像类型 |
| version | uint32_t : 4 | 图像版本号 |
| compressMode | uint32_t : 4 | 图像压缩模式 |
| reserved | uint32_t : 16 | 保留位 |
| width | uint16_t | 图像宽度（像素） |
| height | uint16_t | 图像高度（像素） |
ImageInfo
struct ImageInfo {
ImageHeader header;
uint32_t dataSize;
const uint8_t* data;
#if IMG_CACHE_MEMORY_CUSTOM || defined(VERSION_IOT)
const uint8_t* phyAddr;
void* cacheNode;
char file[MAX_IMG_PATH_LEN];
uint8_t fileLen;
uint32_t resId;
#endif
union {
uint32_t color;
void* userData;
};
bool isHdr;
};
成员说明
| 成员名称 | 数据类型 | 描述 |
|---|---|---|
| header | ImageHeader | 图像头节点信息 |
| dataSize | uint32_t | 图像数据大小（字节） |
| data | const uint8_t* | 像素颜色数据指针 |
| phyAddr | const uint8_t* | 物理地址（IMG_CACHE_MEMORY_CUSTOM 或 VERSION_IOT 宏启用时存在） |
| cacheNode | void* | ImageCacheManager LRU 逻辑使用的缓存节点指针（IMG_CACHE_MEMORY_CUSTOM 或 VERSION_IOT 宏启用时存在） |
| file | char[MAX_IMG_PATH_LEN] | 图像文件路径（IMG_CACHE_MEMORY_CUSTOM 或 VERSION_IOT 宏启用时存在，MAX_IMG_PATH_LEN = 128） |
| fileLen | uint8_t | 文件路径长度（IMG_CACHE_MEMORY_CUSTOM 或 VERSION_IOT 宏启用时存在） |
| resId | uint32_t | 资源 ID（IMG_CACHE_MEMORY_CUSTOM 或 VERSION_IOT 宏启用时存在） |
| color | uint32_t | Alpha 图像使用的颜色值（联合体成员） |
| userData | void* | 用户自定义数据指针（联合体成员） |
| isHdr | bool | 是否为 HDR 图像 |