Skip to content

MPP_EncoderContext

Jump to bottom
SweerItTer edited this page Feb 21, 2026 · 4 revisions

MppEncoderContext API 文档

概述

MppEncoderContext 是 utilsCore MPP 模块的核心类，提供 Rockchip MPP 编码器的完整上下文管理，包括初始化、配置、重配置等。

职责

  • MppCtx/MppApi/MppEncCfg 的 RAII 生命周期管理
  • 编码器的初始化、配置、重配置
  • 支持动态修改编码参数（分辨率、码率、FPS、编码格式等）
  • Ffmpeg 兼容性验证和自动修复

适用场景

  • 视频录制
  • 实时流编码
  • 图像压缩
  • 多格式编码

依赖关系

  • 依赖: Rockchip MPP 库
  • 被依赖: MppEncoderCore, JpegEncoder 等模块

类分析

MppEncoderContext 类

职责与用途

MppEncoderContext 是编码器上下文的封装类，提供：

  • 完整的 MPP 上下文生命周期管理
  • 40+ 个编码配置参数
  • 静态配置验证和修复方法
  • 预设配置生成器

设计模式

  • RAII: 自动管理 MPP 资源
  • Builder 模式: 通过 Config 结构体配置参数

CodingType 枚举

编码器类型定义。

enum class CodingType {
    H264 = MPP_VIDEO_CodingAVC,   // H.264 / AVC
    H265 = MPP_VIDEO_CodingHEVC,  // H.265 / HEVC
    VP8  = MPP_VIDEO_CodingVP8,   // VP8
    MJPEG= MPP_VIDEO_CodingMJPEG  // MJPEG
};

Config 配置结构体

编码器配置结构体，用于初始化和动态重置编码器参数。

基础编码参数

CodingType codec_type = CodingType::H264;  // 编码格式
int prep_width = 1920;                     // 输入图像宽度
int prep_height = 1080;                    // 输入图像高度
int rc_fps_out_num = 30;                   // 输出帧率
int rc_bps_target = 4 * 1024 * 1024;       // 目标码率(bps)
int rc_gop = 60;                           // GOP 长度

预处理参数

int prep_hor_stride = 0;                   // 水平 stride, 0 为自动对齐
int prep_ver_stride = 0;                   // 垂直 stride
MppFrameFormat prep_format = MPP_FMT_YUV420SP; // 输入像素格式, 默认 NV12
int prep_rotation = 0;                     // 旋转角度, 支持 0/90/180/270
bool prep_mirroring = false;               // 镜像

码率控制参数

int rc_mode = MPP_ENC_RC_MODE_VBR;         // CBR/VBR/FIXQP
int rc_bps_min = 0;                        // 最小码率, 0 为自动
int rc_bps_max = 0;                        // 最大码率
int rc_fps_in_num = 30;                    // 输入帧率
int rc_fps_in_denorm = 1;                  // 输入帧率分母
int rc_fps_out_denorm = 1;                 // 输出帧率分母
int rc_fps_in_flex = 0;                    // 输入帧率自适应
int rc_fps_out_flex = 0;                   // 输出帧率自适应
int rc_qp_init = -1;                       // 初始 QP, 仅 FIXQP 模式有效
int rc_qp_min_i  = 0;                      // I 帧最小 QP
int rc_qp_max_i  = 0;                      // I 帧最大 QP
int rc_qp_min    = 0;                      // P 帧最小 QP
int rc_qp_max    = 0;                      // P 帧最大 QP
int rc_qp_ip     = 2;                      // I/P帧QP差值

H.264/H.265 编码配置

int h264_profile = 77;                     // H.264 profile, 默认 baseline
int h264_level   = 30;                     // H.264 level
int hevc_profile = 1;                      // H.265 主 profile
int hevc_level   = 30;                     // H.265 level

JPEG 编码相关

int jpeg_q_factor = 90;                    // JPEG 默认质量因子, 推荐范围 70–95
int jpeg_qf_min   = 1;                     // JPEG 最低质量因子
int jpeg_qf_max   = 99;                    // JPEG 最高质量因子

SEI / header 输出控制

int sei_mode = MPP_ENC_SEI_MODE_ONE_FRAME; // SEI 插入模式
int header_mode = MPP_ENC_HEADER_MODE_EACH_IDR; // SPS/PPS 输出策略

高级参数

int split_mode = 0;                        // Slice 分割模式
int split_arg  = 0;                        // Slice 参数
int split_out  = 0;                        // Slice 输出

int roi_enable = 0;                        // 启用 ROI
int osd_enable = 0;                        // 启用 OSD
int osd_mode   = MPP_ENC_OSD_PLT_TYPE_DEFAULT; // OSD 模式

int user_data_enable = 0;                  // 是否写入 user-data SEI

int rc_force_idr_interval = 0;             // 0 = 不强制, >0 = 每 N 帧强制生成 I 帧

bool rc_low_delay = false;                 // 是否开启低延时模式

int rc_max_reenc_times = 1;                // 单帧最大重编码次数

int rc_super_mode = 0;                     // 超大帧处理策略: 0=无策略, 1=丢弃, 2=重编码
int rc_super_i_thd = 0;                    // 超大 I 帧阈值, 字节数
int rc_super_p_thd = 0;                    // 超大 P 帧阈值, 字节数

int rc_max_i_prop = 30;                    // 最大 I/P 比例
int rc_min_i_prop = 10;                    // 最小 I/P 比例
int rc_init_ip_ratio = 160;                // 初始 I/P 比例

bool hier_qp_enable = false;               // 是否启用 QP 分层
int hier_frame_num[4] = {0};               // 每层帧数, 层数最多 4
int hier_qp_delta[4] = {0};                // 每层 QP 相对第0层 P 帧的偏移

bool rc_debreath_en = false;               // 是否开启去呼吸效应
int rc_debreath_strength = 0;              // 去呼吸强度, [0,35]

int rc_drop_mode = 0;                      // 0=关闭, 1=正常丢帧, 2=pskip构造
int rc_drop_thd = 20;                      // 丢帧阈值
int rc_drop_gap = 1;                       // 最大允许连续丢帧数

int rc_stats_time = 3;                     // 瞬时码率统计时间, 单位秒

bool cabac_enable = false;                 // 是否启用 CABAC
int cabac_idc = 0;                         // CABAC 初始化 ID, 0~2
int rc_poc_type = 0;                       // pic_order_cnt_type
int rc_log2_max_poc_lsb = 0;               // log2_max_pic_order_cnt_lsb_minus4
int rc_log2_max_frm_num = 0;               // log2_max_frame_num_minus4

bool rc_prefix_mode = false;               // 是否在 SEI 前插入 prefix nal
int rc_base_layer_pid = 0;                 // 基准层优先级ID

int rc_color_range_override = -1;          // -1: 默认, 0: 未指定, 1: MPEG, 2: JPEG

void* user_ext = nullptr;                  // 用户自定义扩展指针

公共 API 方法

构造函数

explicit MppEncoderContext(const Config &cfg);
~MppEncoderContext();

参数说明:

  • cfg (输入): 用户定义的编码配置

返回值: 无

所有权归属:

  • MppEncoderContext 拥有 MppCtx, MppApi, MppEncCfg 的所有权

注意事项:

  1. 构造时会初始化 MPP 上下文
  2. 失败时抛出异常
  3. 析构时自动清理资源

使用例程:

MppEncoderContext::Config cfg;
cfg.codec_type = MppEncoderContext::CodingType::H264;
cfg.prep_width = 1920;
cfg.prep_height = 1080;
cfg.rc_fps_out_num = 30;
cfg.rc_bps_target = 4 * 1024 * 1024;

MppEncoderContext ctx(cfg);

resetConfig() - 重置配置

bool resetConfig(const Config &cfg);

参数说明:

  • cfg (输入): 新配置

返回值:

  • true: 重置成功
  • false: 重置失败

所有权归属:

  • 无所有权转移

注意事项:

  1. 会触发 MPP 内部重新配置编码参数
  2. 不会销毁 ctx
  3. 可以动态修改编码参数

使用例程:

MppEncoderContext ctx(cfg);

// 修改码率
cfg.rc_bps_target = 8 * 1024 * 1024;
ctx.resetConfig(cfg);

ctx() - 获取 MPP 上下文指针

MppCtx ctx() const;

参数说明: 无

返回值: MppCtx 指针

所有权归属:

  • 只读访问

注意事项:

  • 用于传递给 MppEncoderCore

api() - 获取 MPP API 接口

MppApi* api() const;

参数说明: 无

返回值: MppApi 指针

所有权归属:

  • 只读访问

注意事项:

  • 用于调用 MPP API

encCfg() - 获取 MPP 编码配置句柄

MppEncCfg encCfg() const;

参数说明: 无

返回值: MppEncCfg 句柄

所有权归属:

  • 只读访问

注意事项:

  • 用于传递给 MppEncoderCore

getmCfg() - 获取当前配置

const Config* getmCfg() const;

参数说明: 无

返回值: 当前配置指针

所有权归属:

  • 只读访问

注意事项:

  • 返回指向 mCurCfg 的指针

validateForFfmpeg() - 验证配置是否适合 ffmpeg 转换（静态方法）

static void validateForFfmpeg(const Config& cfg);

参数说明:

  • cfg (输入): 要验证的配置

返回值: 无

所有权归属:

  • 无所有权转移

注意事项:

  1. 检查关键参数以确保生成的视频流可以被 ffmpeg 正确转换为 MP4
  2. 如果配置有问题，会输出警告信息到 stderr
  3. 不修改配置

检查项:

  • 像素格式是否为 NV12 或 YUV420P
  • 色彩范围是否为 MPEG (1)
  • 编码类型是否为 H264 或 H265
  • H264 profile 是否为 Main (77) 或 High (100)

使用例程:

MppEncoderContext::Config cfg;
// ... 设置配置 ...

MppEncoderContext::validateForFfmpeg(cfg);
// 输出:
// [MppEncoderContext] WARNING: Format 24 may not be optimal for ffmpeg. Use MPP_FMT_YUV420SP (NV12).

fixForFfmpeg() - 自动修复配置以确保 ffmpeg 兼容性（静态方法）

static void fixForFfmpeg(Config& cfg);

参数说明:

  • cfg (输入/输出): 要修复的配置引用

返回值: 无

所有权归属:

  • 无所有权转移

注意事项:

  1. 自动设置关键参数以避免 ffmpeg 转换时的颜色问题
  2. 直接修改传入的 Config 引用
  3. 根据分辨率自动调整 level

修复项:

  • 强制 NV12 格式 (MPP_FMT_YUV420SP)
  • 强制 MPEG 色彩范围 (rc_color_range_override = 1)
  • 确保 H264/H265 编码类型
  • 设置合适的 H264 profile
  • 根据分辨率自动设置 level

使用例程:

MppEncoderContext::Config cfg;
cfg.codec_type = MppEncoderContext::CodingType::H264;
cfg.prep_width = 1920;
cfg.prep_height = 1080;

// 自动修复以获得最佳 ffmpeg 兼容性
MppEncoderContext::fixForFfmpeg(cfg);

// 使用修复后的配置
MppEncoderContext ctx(cfg);

DefaultConfigs 命名空间

预设配置生成器，提供常用场景的配置模板。

defconfig_video_recording() - 视频录制配置

inline static MppEncoderContext::Config defconfig_video_recording(
    int width, int height, int fps = 30, int bitrate_mbps = 4);

参数说明:

  • width (输入): 图像宽度
  • height (输入): 图像高度
  • fps (输入): 帧率
  • bitrate_mbps (输入): 码率，0 表示自动计算

返回值: 视频录制配置

使用例程:

auto cfg = DefaultConfigs::defconfig_video_recording(1920, 1080, 30, 8);
MppEncoderContext ctx(cfg);

createJpegConfig() - JPEG 编码器配置

inline static MppEncoderContext::Config createJpegConfig(
    uint32_t width, uint32_t height, MppFrameFormat format = MPP_FMT_YUV420SP, int quality = 8);

参数说明:

  • width (输入): 图像宽度
  • height (输入): 图像高度
  • format (输入): 像素格式
  • quality (输入): 质量因子 0-10

返回值: JPEG 编码器配置

使用例程:

auto cfg = DefaultConfigs::createJpegConfig(1920, 1080, MPP_FMT_YUV420SP, 8);
MppEncoderContext ctx(cfg);

defconfig_480p_video() - 480p 视频配置

inline static MppEncoderContext::Config defconfig_480p_video(int fps = 120);

使用例程:

auto cfg = DefaultConfigs::defconfig_480p_video(60);
MppEncoderContext ctx(cfg);

defconfig_720p_video() - 720p 视频配置

inline static MppEncoderContext::Config defconfig_720p_video(int fps = 60);

使用例程:

auto cfg = DefaultConfigs::defconfig_720p_video(60);
MppEncoderContext ctx(cfg);

defconfig_1080p_video() - 1080p 视频配置

inline static MppEncoderContext::Config defconfig_1080p_video(int fps = 60);

使用例程:

auto cfg = DefaultConfigs::defconfig_1080p_video(30);
MppEncoderContext ctx(cfg);

defconfig_4k_video() - 4K 视频配置

inline static MppEncoderContext::Config defconfig_4k_video(int fps = 30);

使用例程:

auto cfg = DefaultConfigs::defconfig_4k_video(30);
MppEncoderContext ctx(cfg);

defconfig_2k_video() - 2K 视频配置

inline static MppEncoderContext::Config defconfig_2k_video(int fps = 30);

使用例程:

auto cfg = DefaultConfigs::defconfig_2k_video(30);
MppEncoderContext ctx(cfg);

典型使用场景

场景 1: 基本使用

MppEncoderContext::Config cfg;
cfg.codec_type = MppEncoderContext::CodingType::H264;
cfg.prep_width = 1920;
cfg.prep_height = 1080;
cfg.rc_fps_out_num = 30;
cfg.rc_bps_target = 4 * 1024 * 1024;

MppEncoderContext ctx(cfg);

// 传递给 MppEncoderCore
auto encoder = std::make_shared<MppEncoderCore>(cfg, 0);

场景 2: 使用预设配置

auto cfg = DefaultConfigs::defconfig_1080p_video(30);
MppEncoderContext ctx(cfg);

场景 3: Ffmpeg 兼容性配置

auto cfg = DefaultConfigs::defconfig_video_recording(1920, 1080, 30, 8);

// 验证配置
MppEncoderContext::validateForFfmpeg(cfg);

// 自动修复
MppEncoderContext::fixForFfmpeg(cfg);

MppEncoderContext ctx(cfg);

场景 4: JPEG 编码

auto cfg = DefaultConfigs::createJpegConfig(1920, 1080, MPP_FMT_YUV420SP, 8);
MppEncoderContext ctx(cfg);

场景 5: 动态修改配置

auto cfg = DefaultConfigs::defconfig_1080p_video(30);
MppEncoderContext ctx(cfg);

// 修改码率
cfg.rc_bps_target = 8 * 1024 * 1024;
ctx.resetConfig(cfg);

注意事项

  1. 类名: 是 MppEncoderContext，不是 EncoderContext
  2. Config 字段: 有 40+ 个配置参数，大部分有合理的默认值
  3. RAII: 析构时自动清理 MPP 资源
  4. Ffmpeg 兼容: 使用 fixForFfmpeg() 自动修复配置
  5. 预设配置: 优先使用 DefaultConfigs 命名空间的预设配置
  6. 动态重配置: 使用 resetConfig() 动态修改参数
  7. 质量因子: JPEG quality 参数范围是 0-10（内部转换为 0-100）
  8. 码率计算: 在 defconfig_video_recording() 等预设配置中，当 bitrate_mbps > 0 时使用指定码率（bitrate_mbps * 1024 * 1024），当 bitrate_mbps <= 0 时使用 MPP 官方默认公式计算：width * height / 8 * (fps / 1)

相关文档

参考资料

主页

API 文档

DMA 模块

DRM 模块

NET 模块

V4L2 模块

V4L2Param 模块

RGA 模块

MPP 模块

Sys 模块

Mouse 模块

Utils 模块

Clone this wiki locally