概述
接口简介
本文档详细描述了DVPP(Digital Vision Pre-Processing)执行器对外提供的接口,接口描述包括:接口函数描述、接口调用说明、整体示例等,适合开发人员、测试人员。
- 当前版本调用CreateDvppApi、DvppCtl、DestroyDvppApi接口实现VPC功能有两种方式:
- 方式一,在DvppCtl接口中传入入参:DVPP_CTL_VPC_PROC命令字和VpcUserImageConfigure结构体的参数。推荐使用。
- 方式二,在DvppCtl接口中传入入参:DVPP_CTL_VPC_PROC命令字和resize_param_in_msg结构体的参数。对时延要求不高、处理的图片分辨率低、数量多的场景,可以在DvppCtl接口中传入入参:DVPP_CTL_CMDLIST_PROC和IMAGE_CONFIG结构体的参数。这种方式是为了兼容旧版本中的功能,后续版本会删除,不推荐使用。
- 当前版本实现VENC功能有两种方式:
- 方式一,调用CreateVenc、RunVenc、DestroyVenc接口实现VENC功能,推荐使用。
- 方式二,调用CreateDvppApi、DvppCtl、DestroyDvppApi接口实现VENC功能,在DvppCtl接口中传入入参:DVPP_CTL_VENC_PROC命令字和venc_in_msg结构体的参数,这种方式在为了兼容旧版本中的功能,后续版本会删除,不推荐使用。
接口列表
您可以在DDK(Device Development Kit)的安装目录下的“ddk/include/inc/dvpp/”目录下查看接口的头文件。若需要调用DVPP提供的接口,在代码中可以包含idvppapi.h、Venc.h、Vpc.h(定义数据类型的头文件,请参见VpcUserImageConfigure中的结构体)。
分类 |
接口 |
功能说明 |
定义接口的头文件 |
---|---|---|---|
实现VPC/JPEGE/JPEGD/PNGD功能 |
创建dvppapi实例,相当于获取DVPP执行器句柄,调用方可以使用申请到的dvppapi实例调用DvppCtl接口处理图片,可以跨函数调用,跨线程调用。 |
idvppapi.h |
|
使用CreateDvppApi接口创建的实例来调用DvppCtl接口,控制DVPP各模块执行,模块主要包括VPC(Vision Pre-processing Core)、JPEGE、JPEGD、PNGD等。 |
|||
销毁由CreateDvppApi接口创建的dvppapi实例,关闭DVPP执行器。 |
|||
获取JPEGD/JPEGE/PNGD模块的输出内存大小。 |
|||
实现VDEC功能 |
获取vdecapi实例,相当于vdec执行器句柄。调用方可以使用申请到的vdecapi实例调用CreateVdecApi接口进行视频解码,可以跨函数调用,跨线程调用。 |
idvppapi.h |
|
使用CreateVdecApi接口创建的实例调用VdecCtl接口,控制DVPP执行器进行视频解码。 |
|||
释放由CreateVdecApi接口创建的vdecapi实例,关闭VDEC执行器。 |
|||
实现VENC功能 |
获取VENC编码实例,相当于获取VENC执行器句柄。调用方可以使用申请到的VENC编码实例调用RunVenc接口进行图片编码。 |
Venc.h |
|
使用CreateVenc接口创建的实例调用RunVenc接口,控制DVPP执行器进行视频编码。 |
|||
释放由CreateVenc接口创建的VENC编码实例,关闭VENC执行器。 |
VPC功能
功能说明
VPC功能包括:
- 抠图,从输入图片中抠出需要用的图片区域。
- 缩放
- 针对不同分辨率的图像,VPC的处理方式可分为非8K缩放、8K缩放。
- 8K缩放,用于处理输入图像宽度在4096~8192范围内或高度在4096~8192范围内的图片。
- 非8K缩放,用于处理输入图像分辨率在32*6~4096*4096范围内的图片。
- 从是否抠多张图的维度,可分为单图裁剪缩放(支持非压缩格式和HFBC压缩格式)、一图多框裁剪缩放(支持非压缩格式和HFBC压缩格式)。
HFBC,是VDEC输出的一种压缩图像格式,使用这种方式压缩图像,VDEC的处理性能更优。
- 其它缩放方式,如:原图缩放、等比例缩放。
- 针对不同分辨率的图像,VPC的处理方式可分为非8K缩放、8K缩放。
- 叠加,从输入图片中抠出来的图,对抠出的图进行缩放后,放在用户输出图片的指定区域,输出图片可以是空白图片(由用户申请的空输出内存产生的),也可以是已有图片(由用户申请输出内存后将已有图片读入输出内存),只有当输出图片是已有图片时,才表示叠加。
- 拼接,从输入图片中抠多张图片,对抠出的图进行缩放后,放到输出图片的指定区域。
- 格式转换
- 将RGB格式/YUV422格式/YUV444格式的图片转为YUV420格式的图片。
- 图像灰度化,对输出图像数据只取Y分量的数据。
约束说明
- 针对不同分辨率的图像,VPC的处理方式包括8K缩放、非8K缩放,如下表所示。
输入图像分辨率
输入图像格式
输入图像宽stride*高stride对齐要求
VPC功能
输出图像分辨率
输出图像格式
输出图像宽stride*高stride对齐要求
宽度在4096~8192范围内或高度在4096~8192范围内(不包括4096)
YUV420SP(NV12、NV21)
2*2对齐
8K缩放
16*16~4096*4096
请参见表10-10处的outputFormat参数
2*2对齐
32*6~4096*4096(包括4096)
请参见表10-10处的inputFormat参数
- 宽stride的对齐:请参见表10-10处的widthStride参数
- 高stride是2对齐
非8K缩放
32*6~4096*4096
请参见表10-10处的outputFormat参数
16*2对齐
- 针对缩放功能,宽高缩放比例范围:[1/32, 16]。
- 对于8K缩放功能,支持缩放、支持YUV420SP NV12与YUV420SP NV21之间的格式转换、不支持抠图。
功能示意图
概念 |
描述 |
---|---|
宽stride |
指一行图像步长,表示输入图片对齐后的宽,RGB格式或YUV格式的宽stride计算方式不一样。宽stride最小为32,最大为4096 * 4(即宽是4096的argb格式的图像)。
|
高stride |
指图像在内存中的行数,表示输入图片对齐后的高。 取值为:输入图像的高对齐到2。高stride最小为6,最大为4096。 |
上/下/左/右偏移 |
通过配置上偏移、下偏移、左偏移、右偏移可以实现两个功能:指定抠图区域或贴图区域的位置;控制抠图或贴图区域的宽、高,右偏移-左偏移+1=宽,下偏移-上偏移+1=高。
|
抠图区域 |
指用户指定的需裁剪的图片区域。 抠图区域最小分辨率为10*6,最大分辨率为4096*4096。 |
贴图区域 |
指在输出图片中用户指定的区域,贴图区域最小分辨率为10*6,最大分辨率为4096*4096。 约束如下:
|
性能指标说明
- 对于非8K缩放,VPC性能由于涉及到抠图、缩放等不同的场景,当处理图片的过程中分辨率改变时,以大分辨率来计算性能。例如,对于缩放,缩放后图片的分辨率大于缩放前图片的分辨率,则以缩放后图片的分辨率来计算性能指标;对于抠图,贴图区域的分辨率大于抠图区域的分辨率,则以贴图区域的分辨率来计算性能指标。对于YUV420 SP格式的图片,典型场景性能指标参考如下:
场景举例
总帧率
1080p * n路(n<4,1路对应一个线程)
n*360fps
1080p * n路(n>=4,1路对应一个线程)
1440fps
4k * n路(n<4,1路对应一个线程)
n*90fps
4k * n路(n>=4,1路对应一个线程)
360fps
- 对于8K缩放,VPC性能与输出分辨率强相关,输出分辨率越大,处理耗时越久,性能越低,典型场景(输出分辨率为1080p、4k的场景,图片格式为YUV420 SP)性能指标参考如下:
场景举例
总帧率
1080p * n路(n=1,1路对应一个线程)
4fps
1080p * n路(n>=4,1路对应一个线程)
16fps
4k * n路(n=1,1路对应一个线程)
1fps
4k * n路(n>=4,1路对应一个线程)
4fps
参考说明
RBG、YUV格式图像的各分量排布示意图。示例:sp图像以yuv420sp为例,packed和rgb图像以argb图像为例。
JPEGE功能
功能及约束说明
JPEGE功能:实现编码生成.jpg图片。
- JPEGE支持以下格式输入:
- YUV422 packed(yuyv,yvyu,uyvy,vyuy)
- YUV420 Semi-planar(NV12,NV21)
- JPEGE支持的分辨率为:
最大分辨率:8192 * 8192,最小分辨率:32 * 32
- JPEGE输出格式为jpeg,只支持huffman编码,不支持算术编码,不支持渐进编码。
性能指标说明
场景举例 |
总帧率 |
---|---|
1080p * n路(n>=1) |
64fps |
4k * n路(n>=1) |
16fps |
JPEGD功能
功能说明
实现.jpg、.jpeg、.JPG、.JPEG图片的解码,对于硬件不支持的格式,会使用软件解码。
解码后,输出如下格式的图片:
jpeg(444) -> yuv444 / yuv420半平面V在前U在后。
jpeg(422) -> yuv422 / yuv420半平面V在前U在后。
jpeg(420) -> yuv420半平面V在前U在后。
jpeg(400) -> yuv420,uv数据采用0 x 80填充。
- JPEGD由于编程规范要求驼峰风格命名方式,原内核风格的入参和出参继续支持,同时提供新的驼峰风格参数供调用方使用,所以JPEGD暂时支持两套参数供用户使用,推荐使用驼峰风格参数。
- 若图片内EOI(End Of Image,标记代码为0XFFD9)之后,还有用户自定义的数据,则JPEGD在对图片进行解码时,会直接清零EOI之后的8字节数据,若用户需要保留这些自定义的数据,则将图片数据读入内存之后,需要提前备份这部分数据,再传给JPEGD处理。
若需要查看图片内EOI之后是否存在自定义数据,可以使用二进制查看工具打开图片查看,例如下图中的FFD9标记符之后就存在自定义数据。
约束说明
- 关于输入图片的约束:
- 最大分辨率:8192 * 8192,最小分辨率:32 * 32
- 只支持Huffman编码,码流的colorspace为YUV,码流的subsample为444/422/420/400;
- 不支持算术编码;
- 不支持渐进JPEG格式;
- 不支持JPEG2000格式;
- 关于硬件约束:
- 最多支持4张Huffman表,其中包括2 张DC(直流)表和2 张AC(交流)表;
- 最多支持3张量化表;
- 只支持8bit采样精度;
- 只支持对顺序式编码的图片进行解码;
- 只支持基于DCT(Discrete Cosine Transform)变换的JPEG 格式解码;
- 只支持一个SOS(Start of Scan)标志的图片解码。
- 关于软件约束:
- 支持3个SOS标志的图片解码;
- 支持mcu(Minimum Coded Unit)数据不足的异常图片解码。
性能指标说明
JPEGD性能指标是基于硬件解码的性能,JPEGD硬件解码不支持3个SOS的图片解码,对于硬件不支持的格式,会使用软件解码,软件解码性能参考为1080P*1路 15fps。
场景举例 |
总帧率 |
---|---|
1080p * 1路 |
128fps |
1080p * n路(n>=2) |
256fps |
4k * 1路 |
32fps |
4k * n路(n>=2) |
64fps |
PNGD功能
功能及约束说明
PNGD功能:实现PNG格式图片的硬件解码。
- PNGD支持以下两种输入格式:
RGBA、RGB
- PNGD输出格式为:
RGBA、RGB
- PNGD支持的分辨率
最大分辨率4096 * 4096,最小分辨率32 * 32。
性能指标说明
场景举例 |
总帧率 |
---|---|
1080p * 1路 |
4fps |
1080p * 2路 |
8fps |
1080p * 3路 |
12fps |
1080p * 4路 |
16fps |
1080p * 5路 |
20fps |
1080p * n路(n>= 6) |
24fps |
4k * 1路 |
1fps |
4k * 2路 |
2fps |
4k * 3路 |
3fps |
4k * 4路 |
4fps |
4k * 5路 |
5fps |
4k * n路(n>= 6) |
6fps |
VDEC功能
功能及约束说明
实现视频的解码。
- VDEC支持两种输入格式:
H264 bp/mp/hp level5.1 yuv420sp编码的码流。
H265 8/10bit level5.1 yuv420sp编码的码流。
- VDEC支持的分辨率
最大分辨率4096 * 4096,最小分辨率128 * 128。
- VDEC输出格式为:yuv420sp压缩后的HFBC数据。
HFBC,是VDEC输出的一种压缩图像格式,使用这种方式压缩图像,VDEC的处理性能更优。
- 若码流中有坏帧、缺帧等情况,解码器VDEC可能会丢帧。
- 仅支持对隔行扫描方式编码出来的8bit H264码流进行解码,隔行扫描方式编码出来的其它格式的码流,VDEC不支持解码。
- VDEC比较特殊,由于当前内部不是单例模式,所以其对外提供C接口函数与其他不同。
性能指标说明
场景举例 |
总帧率 |
---|---|
720p * n路(n>=2且n<=16) (隔行扫描方式编码出来的8bit H264码流) |
480fps |
720p * 1路 (隔行扫描方式编码出来的8bit H264码流) |
240fps |
1080p * n路(n>=2且n<=16) |
480fps |
1080p * 1路 |
240fps |
4k * n路(n>=2且n<=16) |
120fps |
4k * 1路 |
60fps |
如果用户使用Matrix模块编排应用的流程,那么在使用DVPP对多路(Channel)输入的视频流进行解码时,由于视频流中每帧的数据之间有关联关系,因此为保证同一个视频流中每帧数据的顺序,要求每个VDEC固定对应一路视频流,否则DVPP中的VDEC无法解码视频流。
- 多路视频流解码时,为保证视频流中每帧数据的顺序,可能存在多种实现方式,推荐使用以下配置:
- 在Graph配置文件中,在graphs配置段内,配置多个进行视频解码的Engine,一路视频流对应一个Engine。
- 在Graph配置文件中,在视频解码的engine配置段内,将thread_num配置为1,一个Engine对应一个线程。
- 关于Matrix的功能及其Graph配置文件的配置,请参见《 Matrix API参考》。
- 一个Graph(一个进程)最大可以对应16路的视频流。
- 如果在多路视频流解码时,在Graph配置文件中,仅配置一个视频解码的Engine,并将thread_num配置为n(n的值就是视频流channel的数量),在不同时刻,在Matrix中各路视频流可能会在不同的Thread处理,但是在DVPP中,一个VDEC需要固定一路视频流数据,一路视频流数据对应一个线程,这样可能导致VDEC解码时无法保证视频流中每帧数据的顺序,如图所示。图10-4 VDEC处理流程
VENC功能
VENC将编码分成实例化、编码、释放资源三小步。
功能及约束说明
实现YUV420/YVU420图片数据的编码。
- VENC支持以下格式输入:
YUV420 semi-planar NV12/NV21-8bit
- VENC支持的分辨率
最大分辨率1920 * 1920,最小分辨率128 * 128。
- VENC输出格式为:
H264 BP/MP/HP
H265 MP(仅支持Slice码流)
性能指标说明
场景举例 |
总帧率 |
---|---|
1080p * n路(一个进程对应一路) |
30fps |
注:其它分辨率可以等量估算。
关于输入输出内存的说明
关于HIAI_DMalloc/HIAI_DFree接口、HIAI_DVPP_DMalloc/HIAI_DVPP_DFree接口的说明,以及Graph配置文件(receive_memory_without_dvpp参数)的说明,请参见《Matrix API参考》。
功能模块 |
输入内存 |
输出内存 |
---|---|---|
VPC |
请使用Matrix提供的接口申请/释放内存:
|
请使用Matrix提供的接口申请/释放内存:
|
JPEGE和JPEGD |
请使用Matrix提供的接口申请/释放内存:
|
|
PNGD |
请使用Matrix提供的接口申请/释放内存:
|
由用户指定输出内存时,由用户自行释放内存 。请使用Matrix提供的接口申请/释放内存:
|
VDEC和VENC |
对内存无要求,支持调用malloc/free、new/delete等原生接口申请/释放内存,也支持调用Matrix提供的HIAI_DMalloc/HIAI_DFree接口、HIAI_DVPP_DMalloc/HIAI_DVPP_DFree接口申请/释放内存,还支持通过Matrix提供的receive_memory_without_dvpp参数控制内存是否给DVPP使用。 |
VDEC输出的HFBC格式数据直接作为VPC的输入。 VENC输出内存是DVPP内部管理,用户在使用时可以拷贝输出内存中的数据。 |