JLBmpConvertKit 位图转换

JLBmpConvertKit 是杰理 SDK 中的图像转换库（xcframework 二进制框架），用于将 iOS 端图片缩放并转换为杰理芯片（如 AC701N/AC707N 带屏设备）可识别的位图数据格式，供屏幕保护程序、表盘等画面下发使用。

Purpose and Scope

本页介绍 JLBmpConvertKit 位图转换库的集成方式、公开 API、转换流程与使用场景。JLBmpConvertKit 以预编译的 JLBmpConvertKit.xcframework 形式随仓库分发，源码不在此仓库内；本页内容基于仓库中的框架元信息、官方文档（docs/html/Development/function.html）以及 Demo 工程的实际调用代码整理。

本页边界：

覆盖：框架的目录形态与架构、Xcode 集成、JLBmpConvert / JLBmpConvertOption / JLImageConvertResult 等公开类型、位图转换流程、屏幕保护程序下发场景。
不覆盖：转换结果通过蓝牙下发的具体协议（属于 JL_BLEKit / JL_AdvParse 能力）、表盘处理库（JLDialUnit）、其他工具库（JLLogHelper 等）——这些内容请参见各自目录页。

Overview

带屏幕的杰理蓝牙设备（如 AC701N、AC707N 芯片的耳机/音箱充电仓、手表等）通常以自定义的位图/色深格式存储画面，而不是标准 PNG/JPG。App 需要把 UIImage 或图片文件先缩放到设备屏幕分辨率，再按设备芯片支持的像素格式（如 JLBmpConvertType701N_RBG）逐像素转换，最后通过蓝牙协议把二进制数据传给设备。

JLBmpConvertKit 正是为这一环节设计的工具库，它把"缩放 + 格式转换"封装为两个核心类方法，Demo 中与 request701nscreensav、request707nscreensav 等屏幕保护请求配合使用。

在仓库中的定位：

libs/JLBmpConvertKit.xcframework/：框架本体（含多平台切片，见 Info.plist）。
Demo 通过 #import <JLBmpConvertKit/JLBmpConvertKit.h> 引入，并在 JLPiHome.xcodeproj 中作为 Embed Frameworks 打入产物（见 project.pbxproj）。

Architecture

flowchart TD
    subgraph sg_App["iOS App (Demo)"]
        PCH["JieLiAppHeader.pch<br/>#import &lt;JLBmpConvertKit/JLBmpConvertKit.h&gt;"]
        OCHelper["OCHelper.m<br/>旧 C API 封装占位"]
        ScreenSaver["屏幕保护设置界面<br/>request701n/707nScreenSav"]
    end

    subgraph sg_Kit["JLBmpConvertKit.xcframework"]
        JLBmpConvert["JLBmpConvert<br/>+ resizeImage:andResizeTo:<br/>+ convert:ImageData:"]
        Option["JLBmpConvertOption<br/>convertType"]
        Result["JLImageConvertResult<br/>转换结果"]
    end

    subgraph sg_BLE["JL_BLEKit / 传输层"]
        Manager["JL_ManagerM"]
        Device["杰理带屏设备<br/>AC701N / AC707N"]
    end

    PCH --> ScreenSaver
    ScreenSaver --> JLBmpConvert
    JLBmpConvert --> Option
    JLBmpConvert --> Result
    Result --> Manager
    Manager -->|"BLE 数据下发"| Device
    OCHelper -.->|"旧版 C 接口注释"| JLBmpConvert

架构说明：App 在需要下发屏幕画面时，先取目标图片（targetImage）调用 JLBmpConvert 的类方法完成缩放与格式转换，得到 JLImageConvertResult；随后由 JL_ManagerM 等蓝牙管理对象把转换后的数据发送给设备。JLBmpConvertOption 决定输出格式（如 701N 的 RBG 排列），是转换行为的关键配置。OCHelper 中保留了对旧版 C 函数（br28_btm_to_res_path_with_alpha、br23_btm_to_res_path）的注释占位，说明该库在历史上以 C 函数形式提供过同类能力，现已被 Objective-C 类 API 取代。

库结构与集成方式

框架形态

JLBmpConvertKit 以 XCFramework 形式分发，位于 libs/JLBmpConvertKit.xcframework/。其 Info.plist 声明了多个平台切片（SupportedArchitectures 与 SupportedPlatform 成对出现），二进制入口统一为 JLBmpConvertKit.framework/JLBmpConvertKit，见 Info.plist。这意味着同一个目录可同时包含 iOS 设备、模拟器等切片，由 Xcode 在构建时自动选择，无需手动管理 arm64/x86_64 的胖二进制。

<key>BinaryPath</key>
<string>JLBmpConvertKit.framework/JLBmpConvertKit</string>
<key>LibraryIdentifier</key>
...
<key>LibraryPath</key>
<string>JLBmpConvertKit.framework</string>
<key>SupportedArchitectures</key>
...

Source: Info.plist

头文件引入

Demo 在预编译头文件 JieLiAppHeader.pch 中全局导入该库，工程内任意文件无需再单独 import：

#import <JLBmpConvertKit/JLBmpConvertKit.h>
#import <JLLogHelper/JLLogHelper.h>

Sources:
JieLiAppHeader.pch（第 55 行另有重复导入，见 L55）
OCHelper.m

工程嵌入

JLPiHome.xcodeproj/project.pbxproj 中将 JLBmpConvertKit.xcframework 加入 Embed Frameworks 构建阶段并签名拷贝，保证 App 运行时能动态加载框架：

63F75006AF9DF05B6EE6E398 /* JLBmpConvertKit.xcframework in Embed Frameworks */ = {isa = PBXBuildFile; fileRef = 4967D33E5A43EB9CF156BA15 /* JLBmpConvertKit.xcframework */; settings = {ATTRIBUTES = (CodeSignOnCopy, ); }; };

Source: project.pbxproj

核心 API 与转换流程

公开类型

依据官方文档（docs/html/Development/function.html）与 Demo 调用，库对外暴露以下类型：

类型	角色
`JLBmpConvert`	转换入口，提供两个类方法：`resizeImage:andResizeTo:`（缩放）与 `convert:ImageData:`（格式转换）
`JLBmpConvertOption`	转换选项，核心属性 `convertType` 指定输出格式（如 `JLBmpConvertType701N_RBG`）
`JLBmpConvertType701N_RBG`	枚举值，表示按 AC701N 芯片的 RBG 像素排列输出
`JLImageConvertResult`	转换结果对象，携带可下发设备的位图数据

Source: function.html

转换流程

sequenceDiagram
    participant VC as 设置界面(屏幕保护)
    participant CV as JLBmpConvert
    participant OP as JLBmpConvertOption
    participant RS as JLImageConvertResult
    participant BLE as JL_ManagerM / 蓝牙链路

    VC->>CV: resizeImage:targetImage andResizeTo:size
    CV-->>VC: NSData imgData(缩放后的图像数据)
    VC->>OP: alloc/init + 设置 convertType
    VC->>CV: convert:option ImageData:imgData
    CV-->>RS: JLImageConvertResult
    VC->>BLE: 传输转换结果(屏幕保护数据)
    BLE-->>Device: BLE 分包下发

流程要点：

缩放：resizeImage:andResizeTo: 把源图（如全屏截图或相册图）缩放到设备屏幕尺寸 size，返回 NSData。此步骤保证后续逐像素转换的尺寸与设备显示分辨率一致，避免设备端缩放导致花屏。
配置：创建 JLBmpConvertOption 并设置 convertType，按芯片型号选择像素格式。文档示例固定使用 JLBmpConvertType701N_RBG（701N 芯片）。
转换：convert:ImageData: 将缩放后的数据转换为目标格式，返回 JLImageConvertResult。
下发：App 取得结果后调用蓝牙管理对象开始传输（文档示例注释为"开始传输屏幕保护程序"），最终由设备端刷新屏幕画面。

这个"两段式"设计的意图在于把与设备相关的格式知识收敛在库内：App 只需关心图片来源与目标尺寸，不需要了解 701N/707N 的像素排列、位深、字节对齐等细节；同时 resizeImage 与 convert 分离，便于复用缩放结果做不同格式的转换尝试。

Usage Examples

基本用法：转换图片并下发（官方文档示例）

以下片段来自官方文档 docs/html/Development/function.html 的屏幕保护设置示例：先缩放，再按 701N 格式转换，随后开始传输：

NSData *imgData = [JLBmpConvert resizeImage:targetImage andResizeTo:size];
JLBmpConvertOption *option = [[JLBmpConvertOption alloc] init];
option.convertType = JLBmpConvertType701N_RBG;
JLImageConvertResult *result = [JLBmpConvert convert:option ImageData:imgData];
//开始传输屏幕保护程序

Source: function.html

说明：

targetImage 为待转换的源图对象，size 为目标尺寸（CGSize，通常取自设备屏幕信息）。
JLBmpConvertType701N_RBG 表明输出面向 AC701N 芯片、像素按 RBG 排列；不同芯片（如 707N）可能使用其他枚举值。
转换得到的 JLImageConvertResult 在文档中的同一段落内紧接"开始传输屏幕保护程序"，即结果对象随后被蓝牙模块消费。

历史 C API 参考（OCHelper 占位注释）

SDKTestHelper 的 OCHelper.m 保留了旧版 C 函数调用方式的注释，可帮助理解库的能力演进（旧接口直接把 BMP 文件路径转为资源 bin 路径，新接口改为面向 NSData 的 Objective-C 类方法）：

+(void)handleBr28Bmp:(NSString *)path size:(CGSize) size binPath:(NSString *)binPath{
    //    br28_btm_to_res_path_with_alpha((char*)[path UTF8String], size.width, size.height, (char*)[binPath UTF8String]);
}

+(void)handleBr23mp:(NSString *)bmpPath size:(CGSize) size binPath:(NSString *)binPath{
    //    br23_btm_to_res_path((char*)[bmpPath UTF8String], size.width, size.height, (char*)[binPath UTF8String]);
}

Source: OCHelper.m

从中可以看出：

旧接口按芯片系列分函数：br28_btm_to_res_path_with_alpha（BR28 系列，带 alpha）、br23_btm_to_res_path（BR23 系列）。
参数形态为 (bmpPath, width, height, binPath)：输入 BMP 文件路径与宽高，输出资源 bin 文件路径；新 API 则以内存中的 NSData 为输入输出，更适合在 App 内直接流转而不落盘。
两个旧函数在 Demo 中均被注释禁用，说明新框架已替代该 C 接口，集成时应使用 JLBmpConvert 类方法。

Configuration Options

JLBmpConvertOption 是转换行为的唯一配置载体。仓库可验证的配置项如下：

选项	类型	默认值	说明
`convertType`	`JLBmpConvertType`（枚举）	无（文档示例显式赋值）	指定输出像素格式，示例使用 `JLBmpConvertType701N_RBG`，面向 AC701N 芯片 RBG 像素排列

注：JLBmpConvertOption 为闭源框架中的类型，仓库内仅能验证 convertType 属性的用法；若存在位深、抖动、是否保留 alpha 等其他配置项，需以框架头文件 JLBmpConvertKit.h 为准。源码实现细节未包含在本仓库中。

API Reference

以下 API 依据官方文档与 Demo 调用整理。JLBmpConvertKit 为闭源框架，方法签名以仓库可验证的调用形式为准。

`+ (NSData )resizeImage:(UIImage )image andResizeTo:(CGSize)size`

将源图缩放到目标尺寸，返回缩放后的图像数据。

Parameters:

image（UIImage *）：源图片对象（文档示例变量名为 targetImage）。
size（CGSize）：目标尺寸，通常为设备屏幕分辨率。

Returns: NSData * — 缩放后的图像数据，作为后续 convert:ImageData: 的输入。

设计意图： 先统一尺寸再做像素格式转换，避免在设备端缩放带来的性能与花屏问题，同时让 convert 的实现只需面对固定尺寸。

`+ (JLImageConvertResult )convert:(JLBmpConvertOption )option ImageData:(NSData *)imgData`

按选项指定的像素格式将缩放后的图像数据转换为设备可用的位图。

Parameters:

option（JLBmpConvertOption *）：转换选项，至少需设置 convertType。
imgData（NSData *）：resizeImage:andResizeTo: 的输出数据。

Returns: JLImageConvertResult * — 转换结果对象，携带可下发设备的位图数据。

Throws: 未在仓库文档中记载显式异常；转换失败时应通过结果对象的状态字段或空值判断（框架闭源，具体字段需查头文件）。

`JLBmpConvertOption`

属性 convertType：JLBmpConvertType 枚举，决定输出格式；文档示例值为 JLBmpConvertType701N_RBG。

`JLImageConvertResult`

转换结果对象；具体字段（数据、长度、状态等）未在仓库源码中暴露，需参考框架头文件。

Failure Modes, Edge Cases & Concurrency

基于仓库可见证据，以下边界情况需要集成方注意：

格式不匹配：convertType 必须与目标芯片匹配（示例为 701N 的 JLBmpConvertType701N_RBG）。若向 707N 等不同芯片设备下发错误格式数据，可能出现花屏或画面异常；Demo 中 701N 与 707N 分别通过 request701nscreensav / request707nscreensav 发起，格式选择应与设备型号一致。
尺寸约束：resizeImage:andResizeTo: 的 size 应使用设备屏幕真实分辨率（CGSize 像素值）。缩放结果与设备分辨率不一致时，设备端可能拒绝或显示异常。
闭源限制：框架为二进制分发，convert 的失败路径（如内存不足、非法数据）与并发安全未在仓库中记载。建议在主线程之外做耗时的缩放/转换，并在主线程回调用结果刷新 UI；若结果为空应视为转换失败并提示用户。
旧接口兼容：br28_btm_to_res_path_with_alpha / br23_btm_to_res_path 为历史 C 函数，Demo 中已注释；新代码不应依赖这些符号。

Performance & Operational Notes

耗时操作：位图逐像素转换属于 CPU 密集操作，图片越大耗时越长。对于全屏截图级别的屏幕保护图（如 240×240 或更高分辨率），应避免在主线程同步执行，以免卡顿 ANR（可放入后台队列并在完成回调中切回主线程）。
内存：resizeImage:andResizeTo: 返回 NSData，大图缩放中间态会占用内存；转换完成后及时释放 imgData 与 result。
一次转换、多次下发：resizeImage 与 convert 分离的设计允许同一张源图针对不同设备/格式做多次转换尝试时复用缩放结果，减少重复计算。

Extension Points

新增芯片格式：框架以 JLBmpConvertType 枚举扩展输出格式（示例 JLBmpConvertType701N_RBG 表明按芯片+像素排列命名）。若接入新型号芯片，需框架新增枚举值；应用层只通过 option.convertType 选择，无需改动调用结构。
上层封装：可在 App 内以 JLBmpConvert 为基础封装"取图 → 缩放 → 转换 → 下发"的完整工具类（类似 OCHelper 的角色），把 size 获取（通过 request701nscreensav 等接口）与 convertType 选择集中管理。
产物集成：XCFramework 切片结构支持后续在 libs/JLBmpConvertKit.xcframework 中增补新平台切片，工程构建时自动选择。

JLBmpConvertKit.xcframework Info.plist — 框架切片元信息
function.html（屏幕保护/图像转换章节） — 官方 API 示例
OCHelper.m — Demo 中对旧 C 接口的封装占位
JieLiAppHeader.pch — 头文件引入示例
README.md（SDK 库清单） — JLBmpConvertKit 在 SDK 目录中的定位
相关能力页：屏幕保护下发协议见 JL_BLEKit 相关目录；表盘画面处理见 JLDialUnit 目录。