MPP_JpegEncoder

JpegEncoder API 文档

概述

JpegEncoder 是 utilsCore MPP 模块的核心类，提供 Rockchip MPP JPEG 编码功能，支持直接从 DMA-BUF 捕获并保存为 JPEG 文件。

职责

• JPEG 图像编码
• 支持从 DMA-BUF 捕获
• 自动文件命名
• 质量控制

适用场景

• 图像快照
• 图像保存
• 视频帧捕获

依赖关系

• 依赖: Rockchip MPP 库
• 依赖: MppEncoderContext
• 依赖: DmaBuffer

---

类分析

JpegEncoder 类

职责与用途

JpegEncoder 是 JPEG 编码器的封装类，提供：

• JPEG 编码初始化
• 从 DMA-BUF 捕获并编码
• 自动文件命名和保存
• 编码参数配置

设计模式

• RAII: 自动管理 MPP 资源

---

Config 配置结构体

结构体定义

struct Config {
    uint32_t width;
    uint32_t height;
    MppFrameFormat format = MPP_FMT_YUV420SP;
    int quality = 8;  // 0-10, 值越大质量越高
    std::string save_dir;
    
    // 转换为 MPP 配置
    MppEncoderContext::Config toMppConfig() const {
        return DefaultConfigs::createJpegConfig(
            width, height, format, quality
        );
    }
};

字段说明

字段	类型	默认值	说明
width	uint32_t	-	图像宽度（像素）
height	uint32_t	-	图像高度（像素）
format	MppFrameFormat	MPP_FMT_YUV420SP	输入格式
quality	int	8	JPEG 质量（0-10，值越大质量越高）
save_dir	std::string	-	保存目录

方法

toMppConfig() - 转换为 MPP 配置

MppEncoderContext::Config toMppConfig() const;

返回值: MppEncoderContext 配置

---

公共 API 方法

构造函数

explicit JpegEncoder(const Config& cfg);
~JpegEncoder() = default;

参数说明:

• cfg (输入): 编码配置

返回值: 无

所有权归属:

• JpegEncoder 拥有 MPP 资源的所有权

注意事项:

1. 构造时会初始化 MPP 编码器
2. 失败时 initialized_ 会设置为 false
3. 析构时自动清理 MPP 资源

使用例程:

JpegEncoder::Config cfg;
cfg.width = 1920;
cfg.height = 1080;
cfg.format = MPP_FMT_YUV420SP;
cfg.quality = 8;
cfg.save_dir = "/tmp/jpeg";

JpegEncoder encoder(cfg);

---

resetConfig() - 重新配置

bool resetConfig(const Config& cfg);

参数说明:

• cfg (输入): 新的编码配置

返回值:

• true: 成功
• false: 失败

所有权归属:

• 无所有权转移

注意事项:

1. 重新初始化编码器
2. 会重置所有配置
3. 失败时不会改变原有配置

使用例程:

JpegEncoder encoder(cfg);

// 重新配置
JpegEncoder::Config new_cfg;
new_cfg.width = 1280;
new_cfg.height = 720;
new_cfg.format = MPP_FMT_YUV420SP;
new_cfg.quality = 10;
new_cfg.save_dir = "/tmp/jpeg";

if (encoder.resetConfig(new_cfg)) {
    printf("Reset config success\n");
} else {
    printf("Reset config failed\n");
}

---

captureFromDmabuf() - 从 DMA-BUF 捕获

bool captureFromDmabuf(const DmaBufferPtr dmabuf);

参数说明:

• dmabuf (输入): DMA-BUF 指针

返回值:

• true: 成功
• false: 失败

所有权归属:

• JpegEncoder 不持有 DMA-BUF 的所有权

注意事项:

1. 从 DMA-BUF 获取图像数据
2. 自动编码为 JPEG
3. 自动生成文件名并保存
4. 文件保存在 save_dir 目录中

使用例程:

JpegEncoder encoder(cfg);

// 从 DMA-BUF 捕获
if (encoder.captureFromDmabuf(dma_buffer)) {
    printf("Capture success\n");
} else {
    printf("Capture failed\n");
}

---

私有 API 方法

encodeToFile() - 编码到文件

bool encodeToFile(MppFrame frame, const std::string& filepath);

参数说明:

• frame (输入): MPP 帧
• filepath (输入): 文件路径

返回值:

• true: 成功
• false: 失败

说明: 编码 MPP 帧并保存为 JPEG 文件

---

generateFilename() - 生成文件名

std::string generateFilename();

返回值: 生成的文件名

说明: 生成唯一的 JPEG 文件名

---

编码流程

编码流程图

1. 初始化编码器
   ↓
2. 从 DMA-BUF 获取图像
   ↓
3. 生成文件名
   ↓
4. 编码为 JPEG
   ↓
5. 保存到文件

数据流

DMA-BUF → JpegEncoder → MPP 编码 → JPEG 文件

---

线程安全说明

同步机制

• 状态管理: 使用 std::atomic_bool 保护初始化状态
• MPP 操作: MPP 编码器本身是线程安全的

线程安全建议

• 每个线程应该有自己的 JpegEncoder 实例
• 不要共享 JpegEncoder 实例

---

典型使用场景

场景 1: 基本使用

JpegEncoder::Config cfg;
cfg.width = 1920;
cfg.height = 1080;
cfg.format = MPP_FMT_YUV420SP;
cfg.quality = 8;
cfg.save_dir = "/tmp/jpeg";

JpegEncoder encoder(cfg);

// 从 DMA-BUF 捕获
encoder.captureFromDmabuf(dma_buffer);

场景 2: 快照功能

JpegEncoder encoder(cfg);

// 按键触发快照
button.onPress([&]() {
    encoder.captureFromDmabuf(current_frame);
    printf("Snapshot saved\n");
});

场景 3: 定时捕获

JpegEncoder encoder(cfg);

// 每秒捕获一次
std::thread([&]() {
    while (running) {
        encoder.captureFromDmabuf(current_frame);
        sleep(1);
    }
}).detach();

场景 4: 重新配置

JpegEncoder encoder(cfg);

// 重新配置
JpegEncoder::Config new_cfg;
new_cfg.width = 1280;
new_cfg.height = 720;
new_cfg.format = MPP_FMT_YUV420SP;
new_cfg.quality = 10;
new_cfg.save_dir = "/tmp/jpeg_hd";

encoder.resetConfig(new_cfg);

场景 5: 质量控制

// 低质量
JpegEncoder::Config cfg;
cfg.width = 1920;
cfg.height = 1080;
cfg.quality = 3;
cfg.save_dir = "/tmp/jpeg_low";

// 高质量
JpegEncoder::Config cfg;
cfg.width = 1920;
cfg.height = 1080;
cfg.quality = 10;
cfg.save_dir = "/tmp/jpeg_high";

---

注意事项

1. 格式匹配: 输入格式必须与配置一致
2. 质量范围: 质量值必须在 0-10 范围内，值越大质量越高
3. 保存目录: save_dir 必须存在且有写权限
4. DMA-BUF: DMA-BUF 必须包含有效的图像数据
5. 线程安全: 每个线程应该有自己的实例
6. 错误处理: 检查返回值
7. 文件名: 文件名自动生成，格式为 timestamp.jpg

---

相关文档

• EncoderContext - 编码器上下文
• EncoderCore - 编码器核心
• StreamWriter - 流写入器
• DmaBuffer - DMA 缓冲区
• MPP 模块总览

---

参考资料

• Rockchip MPP
• JPEG 标准
• RK3568 MPP Guide