API GUIDE / JPEGD / Middleware

G32S10 JPEGD Middleware 接口

Middleware 层接口:输入 JPEG 和输出 buffer 在 im_jpegd_decode() 返回前必须保持有效。

1. 公开数据类型

1.1 im_jpegd_frame_t

字段类型说明
jpeg_addrconst void *完整 JPEG 文件地址,包含 SOI 和所有头
jpeg_sizeuint32_t完整 JPEG 文件大小
dst_y_addrvoid *输出 Y 或 packed RAW 基地址
dst_uv_addrvoid *NV12 UV 地址;NULL 使用紧凑布局
dst_buf_sizeuint32_t输出 buffer 可写容量
widthuint32_t成功解码后填写的图像宽度
heightuint32_t成功解码后填写的图像高度
output_sizeuint32_t成功解码后填写的 RAW 字节数

输入 JPEG 和输出 buffer 在 im_jpegd_decode() 返回前必须保持有效。

2. 默认值和必填字段

2.1 frame 必填字段

调用 im_jpegd_decode() 前必须填写:

  • jpeg_addr

  • jpeg_size

  • dst_y_addr

  • dst_buf_size

NV12 时可以填写 dst_uv_addr,也可以留 NULL 使用紧凑布局。

3. 初始化和反初始化

3.1 im_jpegd_init()

error_code_t im_jpegd_init(uint32_t timeout_ms);

流程:

  1. 检查内部状态必须为 UNINITIALIZED。

  2. 申请并使能 IRQ_JPEG_DEC。

  3. 使用 HAL 默认配置初始化 JPEGD。

  4. 注册 MID frame-event callback。

  5. 保存 frame-end 等待超时,进入 INITIALIZED。

timeout_ms == 0 时使用内部默认值 1000 ms。

该超时只控制 MID 等待 frame-end 的时间,不使用 job.runtime.timeout_ms。

返回:

返回值原因
IM_OK初始化成功
IM_ERR_BUSY会话已存在
其他错误IRQ 或 HAL 初始化失败

IRQ 初始化成功但 HAL 初始化失败时,IRQ 会被关闭。

4. 解码流程

error_code_t im_jpegd_decode(const im_jpegd_job_t *job,
                             im_jpegd_frame_t *frame);

4.1 输入检查

以下任一条件成立时返回 IM_ERR_INVALID_PARAM:

  • job == NULL

  • frame == NULL

  • frame->jpeg_addr == NULL

  • frame->jpeg_size == 0

  • frame->dst_y_addr == NULL

  • frame->dst_buf_size == 0

之后再检查会话状态:

  • UNINITIALIZED:IM_ERR_NOT_READY

  • RUNNING:IM_ERR_BUSY

5. 输出格式、尺寸和 buffer

5.1 对齐、stride 和输出大小

格式MCU 宽/高stride输出大小
Y8/8ALIGN_UP(width, 8)stride * ALIGN_UP(height, 8)
NV1216/16ALIGN_UP(width, 16)stride * ALIGN_UP(height, 16) * 3 / 2
YUYV16/8ALIGN_UP(width, 16) * 2stride * ALIGN_UP(height, 8)

当前 JPEGD HAL 的其他主要限制:

项当前限制
解码宽高8-1920 / 8-1440
dst_y_addr / UV 地址非空且至少 16-byte 对齐
out_formatNV12、YUYV 或单 Y
QT/Huffman 表指针全部非空
reset_cycle0-15
restart_mcu_num启用 restart 时必须大于 0 且小于等于 MCU 总数

dst_buf_size 必须覆盖 HAL 计算出的完整输出大小,否则 HAL 在启动前或取结果 时返回 IM_ERR_NO_SPACE。

6. 错误处理和自动恢复

6.1 没有公开 reset 接口

JPEGD MID 当前没有 im_jpegd_reset()。活跃解码失败后的复位由im_jpegd_decode() 内部自动完成。需要彻底重建时使用im_jpegd_deinit() + im_jpegd_init()。

7. 典型用法

7.1 先解析头以计算输出容量

im_jpegd_header_parse_result_t parsed;
uint32_t stride;
uint32_t lines;
uint32_t output_size;

ret = im_jpegd_parse_header(jpeg_data, jpeg_size, &parsed);
if (ret != IM_OK) {
    return ret;
}

stride = ALIGN_UP(parsed.param.width, 16U);
lines = ALIGN_UP(parsed.param.height, 16U);
output_size = stride * lines * 3U / 2U;

im_jpegd_decode() 内部会再次解析头部,因此预解析只适合用于分配输出 buffer 或提前校验,不是完成解码的必要步骤。

7.2 设置时钟

ret = im_jpegd_init(0U);
if (ret != IM_OK) {
    return ret;
}

ret = im_jpegd_set_clk_rate(200000000U);
if (ret == IM_OK) {
    actual_hz = im_jpegd_get_clk_rate();
}