08 区域叠加应用

本章节介绍 GK7206 的区域叠加应用示例 —— sample_region。该应用演示了在 VPSS/VO/VENC 上叠加 overlay（OSD）/cover/mosaic/角标等功能。

应用源码位于 SDK 目录 sample/region/，是开发视频叠加相关应用的参考模板。

1 应用概述

1.1 功能特性

多种叠加目标：VPSS、VO、VENC
多种叠加类型：OVERLAYEX（字符叠加）、COVEREX（遮挡）、MOSAICEX（马赛克）、CORNER RECTEX（角标）
灵活配置：支持多种分辨率和位置配置

1.2 技术参数

参数	值
`index`	0~10（见下表）
`依赖`	index 0~3 需 VPSS（sensor），4~6 需 VO（面板），7~10 需 VENC

1.3 测试用例列表

index	目标	index	目标
0	VPSS OVERLAYEX	6	VO CORNER RECTEX
1	VPSS COVEREX	7	VENC OVERLAY
2	VPSS MOSAICEX	8	VENC COVER
3	VPSS CORNER RECTEX	9	VENC MOSAIC
4	VO OVERLAYEX	10	VENC CORNER RECT
5	VO COVEREX

1.4 目录结构

sample/region/
├── Makefile              # 构建脚本
└── sample_region.c       # 主程序

2 编译与部署

2.1 编译应用

# 进入 sample 目录
cd <SDK_PATH>/sample

# 编译 region 示例
make -C region clean && make -C region

2.2 部署到板端

# 挂载 SD 卡（推荐）
mkdir -p /sd_card
mount -t vfat /dev/mmcblk1p1 /sd_card

# 使用 SCP 传输到开发板
scp sample/region/sample_region root@<板端IP>:/sd_card/

2.3 运行应用

# 添加执行权限
chmod +x /sd_card/sample_region

# 进入 SD 卡目录
cd /sd_card

# 运行（index 7：VENC OSD，可拉 RTSP 看）
./sample_region 7

# 退出
按 e + 回车

2.4 预期输出

成功运行后（index 7），终端会输出类似以下信息：

sample_region running
region test index: 7
target: VENC
type: OVERLAY
...
rtsp://192.168.1.100:554/livestream/0

拉流后可以看到画面上有叠加的 OSD 文本。

3 内部执行逻辑详解

3.1 应用架构

本应用采用以下架构：

Sensor → VI → VPSS → REGION → VENC → RTSP 推流

3.2 REGION 初始化流程

// 步骤 1：系统初始化
sample_comm_sys_init(&sys_config);

// 步骤 2：ISP 初始化
sample_comm_isp_init();

// 步骤 3：VI 启动
sample_comm_vi_start(...);

// 步骤 4：VPSS 启动
sample_comm_vpss_start(...);

// 步骤 5：VENC 启动
sample_comm_venc_start(...);

// 步骤 6：REGION 初始化
xmedia_region_init();

// 步骤 7：配置 REGION 任务
switch(index) {
    case 7:  // VENC OVERLAY
        xmedia_region_attach_venc_chn(venc_chn, &region_attr);
        break;
    // ... 其他 case
}

// 步骤 8：绑定模块
xmedia_bind_vpss_to_venc(...);

4 关键编程要点

4.1 OVERLAYEX 配置

xmedia_region_attr_t region_attr;

region_attr.type = XMEDIA_REGION_TYPE_OVERLAYEX;
region_attr.rect.x = 10;
region_attr.rect.y = 10;
region_attr.rect.width = 200;
region_attr.rect.height = 30;
region_attr.color = 0xFFFFFF;  // 白色
strcpy(region_attr.text, "Hello Region");

4.2 COVEREX 配置

region_attr.type = XMEDIA_REGION_TYPE_COVEREX;
region_attr.rect.x = 100;
region_attr.rect.y = 100;
region_attr.rect.width = 200;
region_attr.rect.height = 200;
region_attr.color = 0xFF0000;  // 红色

4.3 MOSAICEX 配置

region_attr.type = XMEDIA_REGION_TYPE_MOSAICEX;
region_attr.rect.x = 150;
region_attr.rect.y = 150;
region_attr.rect.width = 100;
region_attr.rect.height = 100;
region_attr.mosaic_blk_size = 16;  // 马赛克块大小

5 常见问题排查

问题	可能原因	解决方案
叠加不显示	REGION 配置错误	检查 REGION 位置和颜色设置
VENC 叠加失败	VENC 通道未配置	检查 VENC 通道是否正确初始化
VO 叠加失败	无显示设备	使用 VENC 叠加或连接显示设备