region 快速入门
1. 概述与作用
本样例将介绍如何在VI（chn）、VPSS（grp、chn）、VENC（chn）上叠加不同类型的区域，达到显示位图、色块、线框、线条的效果。
它通过在 VI、VPSS、VENC 三个不同媒体模块上 attach 各类区域（OVERLAY / COVER / COVEREX / CORNER_RECT / CORNER_RECTEX / LINEEX），覆盖位图叠加、纯色遮挡、检测框、画线等用法。每个 case 启动一条 VI→VPSS→VENC 的 H.265 编码链路，attach 区域后再通过 rgn_sample_pause() 等待用户回车，回车后销毁区域并停止通路运行，便可在 VENC 输出的 H.265 流中观察叠加效果。
2. 执行准备
在编译本样例之前，请参照Hi3516CV610环境搭建指南和快速上手指南完成编译环境的搭建。
2.1 编译
进入样例目录执行 make 即可完成编译：
编译成功之后，在当前目录下会生成一个sample_region的可执行文件，可以放社区支持的开发板上运行。
2.2 加载 KO
ko加载脚本位于 output/mpp/ko/load_ko，有两个脚本，load3516cv610_20s和load3516cv610_20s_debug。区别为load3516cv610_20s_debug脚本会打开 logmpp_show=1（日志记录）、proc_show=1（proc信息打印），并将 mem_process_isolation 置为 0（不启用进程间mmz隔离）。
由于当前版本不支持进程间mmz隔离，因此需要在load3516cv610_20s脚本中将 mem_process_isolation 置为 0或者使用load3516cv610_20s_debug脚本，此处以load3516cv610_20s_debug脚本为例，20s内存大小为128MB，默认分配为 32MB OS、96MB MMZ，加载命令为：
可以通过-h命令查看具体用法：
./load3516cv610_20s_debug -h
Usage: ./load3516cv610_20s_debug [-option] [-sensor0~1]
options:
-i insert modules
-r remove modules
-a remove modules first, then insert modules
-sensor0~1 sensor_name config sensor type [default: hy006_3814_0011]
-mmz_start config MMZ start addr [default: 0x42000000]
-mmz_size config MMZ mem size [unit: M, default: 96M]
-ir_auto config ir_auto enable [default: 0]
-profile config sys_profile [default: 0]
-h help information
Available sensors:hy006_3814_0011 bt1120/bt656/bt601
for example: ./load3516cv610_20s_debug -i -sensor0 hy006_3814_0011 -sensor1 hy006_3814_0011 -mmz_start 0x42000000 -mmz_size 96M -ir_auto 1
如果需要调整os和mmz的大小，需要参考《内存布局调整指南》对内存大小进行调整。
如果是使用社区默认提供的镜像，这些ko已经打包到文件系统中，烧录到单板上后位于
/ko目录下，在系统启动后会自动加载这些ko。
2.3 运行时依赖
在运行样例前，需要提前准备：
- 指定运行时依赖的so库路径
MPP样例依赖的so库位于soc/libs/musl下，需要将该目录下的so库拷贝到开发板上（或将这些so库所在的目录挂载到开发板上），并指定运行时依赖库的环境变量，假设这些so库位于/mnt/libs/，执行如下命令：
```shell
export LD_LIBRARY_PATH=/mnt/libs/:$LD_LIBRARY_PATH
```
如果是使用社区默认提供的镜像，这些so库已经打包到文件系统中，烧录到单板上后位于
/usr/lib目录下，该目录是系统默认搜索目录，不需要执行export LD_LIBRARY_PATH命令去指定。
- 启动MPP服务
当前MPP媒体模块处于用户态，通过一个独立进程提供相关接口的调用服务，该进程位于samples/mpp/sdk_server下，执行如下命令即可生成sdk_server可执行文件：
```shell
cd samples/mpp/sdk_server && make
```
在单板上执行./sdk_server &即可启动MPP服务。
- sdk_server同样依赖
soc/libs/musl下的so库，因此也需要参照上述export LD_LIBRARY_PATH指定路径；- 如果是使用社区默认提供的镜像，sdk_server进程已经打包到文件系统中，烧录到单板上后位于
/usr/bin目录下，并在系统启动时会自动启动sdk_server。
- 样例运行时候需要的资源文件
对于本样例，为samples/mpp/region/res/mm.bmp，需要将res目录放置于本样例运行的同目录下。
2.4 运行样例
可以执行./sample_region -h查看用法。
3. 支持的 Case 列表
调用语法为 ./sample_region <index>，index 为单数字 0–7。具体含义如下。
| index | 说明 |
|---|---|
| 0 | VI COVEREX — 在 VI chn 0 挂 3 个 OT_RGN_COVEREX（默认 OT_VI_OFFLINE_VPSS_OFFLINE wrap 模式（具体概念参考VI模块文档）） |
| 1 | VENC OVERLAY — 在 VENC chn 0 挂 8 个 OT_RGN_OVERLAY，载入 ./res/mm.bmp 位图；切到 OT_VI_ONLINE_VPSS_ONLINE |
| 2 | VPSS GRP COVER — VPSS group 0 挂 1 个 OT_RGN_COVER（dev 级 attach） |
| 3 | VPSS CHN COVER — VPSS chn 0 挂 2 个 OT_RGN_COVER |
| 4 | VPSS CHN CORNER_RECT — VPSS chn 0 挂 2 个 OT_RGN_CORNER_RECT |
| 5 | VPSS CHN CORNER_RECTEX — 2 个 OT_RGN_CORNER_RECTEX，禁用 VPSS wrap |
| 6 | VPSS CHN LINEEX — 4 个 OT_RGN_LINEEX，禁用 VPSS wrap |
| 7 | VENC OVERLAY DRAW LINE — 8 个 OT_RGN_OVERLAY 在 VENC chn 0，sample_comm_set_osd_drawline(OT_TRUE)；画 8 条 OSD 线（thick=8，color=1/2/3），用 set_bit_map 或 get_canvas 两种方式 |
3.1 case 0 - VI COVEREX
本case实现在VI的码流上显示1个实心矩形，1个空心矩形，1个空心四边形，如图1所示。
应用场景为在VI的输出码流上操作：
- 对画面的某块区域进行遮挡时，可以对指定区域叠加纯色块。
- 重点突出画面的某块区域或某个目标，可以使用空心框圈出来。例如人脸识别时，有一线框框住人脸。
调用命令
输出文件
H.265 编码流：stream_chn0.h265。该路径由 VENC 通用机制写入（实现位于 common/sample_comm_venc.c:2497-2509）。
控制台日志
启动时打印当前 case 名与 attach 信息；rgn_sample_pause() 等待用户回车（提示按回车继续）。回车后拆除并打印绿色 program exit normally! 或红色 program exit abnormally!。
正确性判断
满足以下三点视为通过：
- 控制台无
Error:/failed行。 stream_chn0.h265存在且非空，ffplay stream_chn0.h265或 VLC 可正常播放。- 显示一个空心四边形，一个纯色矩形，一个空心矩形
如 stream_chn0.h265 缺失，常见原因为未在 region/ 目录启动、VENC 通道启动失败、 sensor 未出图。
软件配置流程
- 创建 COVEREX 区域，参考接口
ss_mpi_rgn_create - 设置 COVEREX 相关属性（坐标、大小、形状），参考接口
ss_mpi_rgn_attach_to_chn中的属性ss_rgn_chn_attr - 将 COVEREX 绑定到 VI chn上，参考接口
ss_mpi_rgn_attach_to_chn - 将 COVEREX 从 VI chn 上解绑，参考接口
ss_mpi_rgn_detach_from_chn - 销毁 COVEREX，参考接口
ss_mpi_rgn_destroy
数据流
COVEREX的数据流图如图2所示。
3.2 case 1 - VENC OVERLAY
本case实现在VENC的码流上显示8个位图。这8个位图的原图是同一个，通过转换为不同像素格式进行呈现。像素格式分别为 ARGB1555、ARGB4444、CLUT2、CLUT4、CLUT2_2X2、CLUT4_2X2、CLUT2_4X4、CLUT4_4X4。
位图使用
- SDK包提供了根据不同像素格式将BMP图转化为相应内存形式的方法，具体可参考如下文件：samples/mpp/common/loadbmp.c
- 只有将位图转化为内存形式后，才能对位图进行叠加、更新等相应的操作
- 位图更新的方法有两种，通过调用相应接口来实现：
set_bmp或get_canvas+update_canvas。其中要实现局部更新，只能使用接口get_canvas+update_canvas
效果呈现
本case应用场景为在VENC的码流上操作：
- 可以在画面上显示中文、英文、数字，例如在每一帧画面显示时间戳，1秒或10秒更新一次。
- 可以对叠加在画面上的图片进行整体或局部更新，对于特定像素格式的图片，还可以分别设置图片的前景和后景的透明度，以达到需要的显示效果。
调用命令
输出文件
H.265 编码流：stream_chn0.h265。该路径由 VENC 通用机制写入（实现位于 common/sample_comm_venc.c:2497-2509）。
控制台日志
启动时打印当前 case 名与 attach 信息；rgn_sample_pause() 等待用户回车（提示按回车继续）。回车后拆除并打印绿色 program exit normally! 或红色 program exit abnormally!。
正确性判断
满足以下三点视为通过：
- 控制台无
Error:/failed行。 stream_chn0.h265存在且非空，ffplay stream_chn0.h265或 VLC 可正常播放。- 显示八个不同像素格式的 mm.bmp 位图
如 stream_chn0.h265 缺失，常见原因为未在 region/ 目录启动、VENC 通道启动失败、 sensor 未出图。位图载入失败时优先检查 ./res/mm.bmp 是否存在、样例的执行目录是否正确。
软件配置流程
- 创建 OVERLAY 区域，参考接口
ss_mpi_rgn_create（overlay的像素格式、背景色、大小等属性也在此接口设置） - 设置 OVERLAY 属性，参考接口
ss_mpi_rgn_attach_to_chn中的属性ss_rgn_chn_attr - 将 OVERLAY 绑定到 VENC chn 上，参考接口
ss_mpi_rgn_attach_to_chn - 将位图读入内存，参考 sample 中的
region_mst_load_bmp - 将位图载入 OVERLAY，参考接口
ss_mpi_rgn_set_bmp/ss_mpi_rgn_get_canvas_info+ss_mpi_rgn_update_canvas - 将 OVERLAY 从 VENC chn 上解绑，参考接口
ss_mpi_rgn_detach_from_chn - 销毁 OVERLAY，参考接口
ss_mpi_rgn_destroy
数据流
OVERLAY的数据流图如图3所示。
3.3 case 2 - VPSS GRP COVER
本case实现在VPSS GRP的码流上叠加一个COVER，实现遮挡效果，如图4所示。
应用场景为：在VPSS GRP的码流上操作，VPSS的一个GRP能够对接多个chn，也就是多个chn能同时出一样的码流，这就是VPSS GRP的一出多。如果希望多个chn上的码流在相同位置增加遮挡效果，可直接在 GRP上叠加 COVER。而无需对每一个chn进行同样的操作。
调用命令
输出文件
H.265 编码流：stream_chn0.h265。该路径由 VENC 通用机制写入（实现位于 common/sample_comm_venc.c:2497-2509）。
控制台日志
启动时打印当前 case 名与 attach 信息；rgn_sample_pause() 等待用户回车（提示按回车继续）。回车后拆除并打印绿色 program exit normally! 或红色 program exit abnormally!。
正确性判断
满足以下三点视为通过：
- 控制台无
Error:/failed行。 stream_chn0.h265存在且非空，ffplay stream_chn0.h265或 VLC 可正常播放。- 显示一个纯色矩形
如 stream_chn0.h265 缺失，常见原因为未在 region/ 目录启动、VENC 通道启动失败、 sensor 未出图。
软件配置流程
- 创建 COVER 区域，参考接口
ss_mpi_rgn_create - 设置 COVER 相关属性（坐标、大小、形状），参考接口
ss_mpi_rgn_attach_to_dev中的属性ss_rgn_chn_attr - 将 COVER 绑定到 VPSS grp 上，参考接口
ss_mpi_rgn_attach_to_dev - 将 COVER 从 VPSS grp 上解绑，参考接口
ss_mpi_rgn_detach_from_dev - 销毁 COVER，参考接口
ss_mpi_rgn_destroy
数据流
GRP COVER数据流图如图5所示。
3.4 case 3 - VPSS CHN COVER
本case实现在VPSS chn的码流上叠加一个实心COVER，一个空心COVER，效果如图6所示。
应用场景：在VPSS chn的码流上操作，如果VPSS的一个grp只对接一个chn，那么无论在grp上还是在chn的码流上实现遮挡功能，都一样。但是如果是一个grp对接多个chn，而且想分别在每个chn的码流上实现位置、大小不同的遮挡效果，那么只能分别对每个chn进行叠加自定义的COVER。
调用命令
输出文件
H.265 编码流：stream_chn0.h265。该路径由 VENC 通用机制写入（实现位于 common/sample_comm_venc.c:2497-2509）。
控制台日志
启动时打印当前 case 名与 attach 信息；rgn_sample_pause() 等待用户回车（提示按回车继续）。回车后拆除并打印绿色 program exit normally! 或红色 program exit abnormally!。
正确性判断
满足以下三点视为通过：
- 控制台无
Error:/failed行。 stream_chn0.h265存在且非空，ffplay stream_chn0.h265或 VLC 可正常播放。- 显示一个纯色矩形，一个空心矩形
如 stream_chn0.h265 缺失，常见原因为未在 region/ 目录启动、VENC 通道启动失败、 sensor 未出图。
软件配置流程
- 创建 COVER 区域，参考接口
ss_mpi_rgn_create - 设置 COVER 相关属性（坐标、大小、形状），参考接口
ss_mpi_rgn_attach_to_chn中的属性ss_rgn_chn_attr - 将 COVER 绑定到 VPSS chn 上，参考接口
ss_mpi_rgn_attach_to_chn - 将 COVER 从 VPSS chn 上解绑，参考接口
ss_mpi_rgn_detach_from_chn - 销毁 COVER，参考接口
ss_mpi_rgn_destroy
数据流
COVER数据流图如图7所示。
3.5 case 4 - VPSS CHN CORNER_RECT
本case实现在VPSS chn的码流上叠加一个CORNER_RECT，实现使用角框对画面中某个区域进行标记的效果。如图8所示。
应用场景：在VPSS chn的码流上操作，如果需要在码流上专门突出某个目标或某块区域，可以使用角框或线框对其进行标记。例如人脸识别。
调用命令
输出文件
H.265 编码流：stream_chn0.h265。该路径由 VENC 通用机制写入（实现位于 common/sample_comm_venc.c:2497-2509）。
控制台日志
启动时打印当前 case 名与 attach 信息；rgn_sample_pause() 等待用户回车（提示按回车继续）。回车后拆除并打印绿色 program exit normally! 或红色 program exit abnormally!。
正确性判断
满足以下三点视为通过：
- 控制台无
Error:/failed行。 stream_chn0.h265存在且非空，ffplay stream_chn0.h265或 VLC 可正常播放。- 显示一个角框，一个线框
如 stream_chn0.h265 缺失，常见原因为未在 region/ 目录启动、VENC 通道启动失败、 sensor 未出图。
软件配置流程
- 创建
CORNER_RECT区域，参考接口ss_mpi_rgn_create - 设置
CORNER_RECT相关属性（坐标、大小、形状），参考接口ss_mpi_rgn_attach_to_chn中的属性ss_rgn_chn_attr - 将
CORNER_RECT绑定到 VPSS chn 上，参考接口ss_mpi_rgn_attach_to_chn - 将
CORNER_RECT从 VPSS chn 上解绑，参考接口ss_mpi_rgn_detach_from_chn - 销毁
CORNER_RECT，参考接口ss_mpi_rgn_destroy
数据流
CORNER_RECT数据流图如图9所示。
3.6 case 5 - VPSS CHN CORNER_RECTEX
本case实现在VPSS chn的码流上叠加一个CORNER_RECTEX，实现使用角框对画面中某个区域进行标记的效果。如图10所示。
应用场景：在VPSS chn的码流上操作，如果需要在码流上需要专门突出某个目标或某块区域，可以使用角框或线框对其进行标记，例如人脸识别。
调用命令
输出文件
H.265 编码流：stream_chn0.h265。该路径由 VENC 通用机制写入（实现位于 common/sample_comm_venc.c:2497-2509）。
控制台日志
启动时打印当前 case 名与 attach 信息；rgn_sample_pause() 等待用户回车（提示按回车继续）。回车后拆除并打印绿色 program exit normally! 或红色 program exit abnormally!。
正确性判断
满足以下三点视为通过：
- 控制台无
Error:/failed行。 stream_chn0.h265存在且非空，ffplay stream_chn0.h265或 VLC 可正常播放。- 显示一个角框，一个线框
如 stream_chn0.h265 缺失，常见原因为未在 region/ 目录启动、VENC 通道启动失败、 sensor 未出图。
软件配置流程
- 创建
CORNER_RECTEX区域，参考接口ss_mpi_rgn_create - 设置
CORNER_RECTEX相关属性（坐标、大小、形状），参考接口ss_mpi_rgn_attach_to_chn中的属性ss_rgn_chn_attr - 将
CORNER_RECTEX绑定到 VPSS chn 上，参考接口ss_mpi_rgn_attach_to_chn - 将
CORNER_RECTEX从 VPSS chn 上解绑，参考接口ss_mpi_rgn_detach_from_chn - 销毁
CORNER_RECTEX，参考接口ss_mpi_rgn_destroy
数据流
CORNER_RECTEX数据流图如图11所示。
3.7 case 6 - VPSS CHN LINEEX
本case实现在VPSS chn的码流上叠加4条长度不同的直线段。效果如图12所示。
应用场景：VPSS chn的码流上操作，在码流上实现画直线段的功能。根据自身需求，能够通过多次画线来实现任意多边形的效果。但线段数量有限制，具体可查看《MPP 媒体处理软件 V6.0 开发参考》“区域管理”章节。
调用命令
输出文件
H.265 编码流：stream_chn0.h265。该路径由 VENC 通用机制写入（实现位于 common/sample_comm_venc.c:2497-2509）。
控制台日志
启动时打印当前 case 名与 attach 信息；rgn_sample_pause() 等待用户回车（提示按回车继续）。回车后拆除并打印绿色 program exit normally! 或红色 program exit abnormally!。
正确性判断
满足以下三点视为通过：
- 控制台无
Error:/failed行。 stream_chn0.h265存在且非空，ffplay stream_chn0.h265或 VLC 可正常播放。- 显示 4 条线段
如 stream_chn0.h265 缺失，常见原因为未在 region/ 目录启动、VENC 通道启动失败、 sensor 未出图。
软件配置流程
- 创建 LINEEX 区域，参考接口
ss_mpi_rgn_create - 设置 LINEEX 相关属性（坐标、大小、形状），参考接口
ss_mpi_rgn_attach_to_chn中的属性ss_rgn_chn_attr - 将 LINEEX 绑定到 VPSS chn 上，参考接口
ss_mpi_rgn_attach_to_chn - 将 LINEEX 从 VPSS chn 上解绑，参考接口
ss_mpi_rgn_detach_from_chn - 销毁 LINEEX ，参考接口
ss_mpi_rgn_destroy
数据流
LINEEX数据流图如图13所示。
3.8 case 7 - VENC OVERLAY DRAW LINE
本case实现分别创建像素格式为 ARGB1555、ARGB4444、CLUT2、CLUT4、CLUT2_2X2、CLUT4_2X2、CLUT2_4X4、CLUT4_4X4，背景色透明的 OVERLAY 区域，叠加到码流上，在各个 OVERLAY 上画多条直线段。效果如图14所示。
应用场景：在VENC的码流上操作，并实现画直线段的功能，而且没有数量的限制。可用在人脸识别数量较多的场景，弥补COVER、CORNER_RECT数量不够用的情况。
调用命令
输出文件
H.265 编码流：stream_chn0.h265。该路径由 VENC 通用机制写入（实现位于 common/sample_comm_venc.c:2497-2509）。
控制台日志
启动时打印当前 case 名与 attach 信息；rgn_sample_pause() 等待用户回车（提示按回车继续）。回车后拆除并打印绿色 program exit normally! 或红色 program exit abnormally!。
正确性判断
满足以下三点视为通过：
- 控制台无
Error:/failed行。 stream_chn0.h265存在且非空，ffplay stream_chn0.h265或 VLC 可正常播放。- 显示由八个不同像素格式的OSD通过画线形成的不规则图形
如 stream_chn0.h265 缺失，常见原因为未在 region/ 目录启动、VENC 通道启动失败、 sensor 未出图。位图载入失败时优先检查 ./res/mm.bmp 是否存在、样例的执行目录是否正确。
软件配置流程
- 创建 OVERLAY 区域，参考接口
ss_mpi_rgn_create（overlay的像素格式、背景色、大小等属性也在此接口设置） - 设置 OVERLAY 属性，参考接口
ss_mpi_rgn_attach_to_chn中的属性ss_rgn_chn_attr - 将 OVERLAY 绑定到 VENC chn 上，参考接口
ss_mpi_rgn_attach_to_chn - 将位图读入内存，参考 sample 中的
region_mst_load_bmp - 将位图载入 OVERLAY，参考接口
ss_mpi_rgn_set_bmp/ss_mpi_rgn_get_canvas_info+ss_mpi_rgn_update_canvas - 分别在各个 OVERLAY 上画直线段，参考 sample 中的
sample_region_do_osd_drawline - 将 OVERLAY 从 VENC chn 上解绑，参考接口
ss_mpi_rgn_detach_from_chn - 销毁 OVERLAY，参考接口
ss_mpi_rgn_destroy
数据流
OVERLAY DRAW LINE数据流图如图15所示。
