函数：dvpp_free
总体说明
多版本接口差异
- 本手册中媒体数据处理V1版本与媒体数据处理V2版本的接口功能范围相同，都是描述处理媒体数据的接口，用于实现抠图、图片缩放、格式转换等功能，但两套接口不能混用。
- 建议使用V2版本中的接口，保证后续版本接口功能以及业务的连续演进。
- V1版本中的接口是为了兼容旧版本，保证使用该部分接口的用户能继续使用，后续版本不再演进。
功能说明
本章节介绍媒体数据处理V1版本（DVPP，Digital Vision Pre-Processing）的功能，如表1所示。
表1 功能说明
| 功能 | 说明 |
|---|---|
| VPC（Vision Preprocessing Core） | 负责图像处理功能，支持对图片做抠图、缩放、格式转换等操作，详细描述请参见功能说明。 |
| JPEGD（JPEG Decoder） | 负责完成图像解码功能，将.jpg、.jpeg、.JPG、.JPEG图片解码成YUV格式图片，详细描述请参见功能及约束说明。 |
| JPEGE（JPEG Encoder） | 负责完成图像编码功能，将YUV格式图片编码成.jpg图片，详细描述请参见功能及约束说明。 |
| VDEC（Video Decoder） | 负责视频解码，详细描述请参见功能及约束说明。 |
| VENC（Video Encoder） | 负责视频编码，详细描述请参见功能及约束说明。 |
| PNGD（PNG decoder） | 负责PNG格式图片的解码，详细描述请参见功能及约束说明。 |
功能支持度说明
昇腾AI处理器对媒体数据处理V1版本各功能的支持度如表2所示。
表2 功能支持度说明
| 昇腾AI处理器 | VPC | JPEGD | JPEGE | PNGD | VDEC | VENC |
|---|---|---|---|---|---|---|
| Atlas 200/500 A2推理产品 | √ | √ | √ | √ | √ | √ |
整体约束说明
使用本章中介绍的接口，有以下注意点：
-
关于异步接口：
对于本章介绍的异步接口，调用接口成功仅表示任务下发成功，不表示任务执行成功，对于有依赖的接口，为确保能按序执行任务，建议用户在多个接口中指定同一个stream，因为同一个stream中的任务按接口调用顺序执行。
在调用异步口对图片进行解码、抠图、缩放等操作时，如果任务之间有依赖，一定要调用acl.rt.synchronize_stream接口确保在同一个Stream中的任务按序执行。
从性能角度考虑，建议一个stream上下发多个异步媒体数据处理任务后，执行一次acl.rt.synchronize_stream接口。
调用异步接口后，不能马上释放资源，需调用同步等待接口（例如，acl.rt.synchronize_stream）确保Device侧任务执行完成后才能释放。
-
关于内存申请/释放：
- 实现媒体数据处理的VPC、JPEGD、JPEGE等功能前，若需要申请Device上的内存存放输入或输出数据，需调用acl.media.dvpp_malloc申请内存、调用acl.media.dvpp_free接口释放内存。
- 调用1申请出来的内存可以满足媒体数据处理的要求，也可以在其它任务中使用，例如，从性能角度，为了减少拷贝，媒体数据处理的输出作为模型推理的输入，实现内存复用。
- 但由于媒体数据处理访问的地址空间有限，为确保媒体数据处理时内存足够，除媒体数据处理功能外的其它功能（例如，模型加载），建议调用内存管理章节下的acl.rt.malloc接口、或acl.rt.malloc_host接口、或acl.rt.malloc_cached接口申请内存。
-
关于通道的要求：
实现媒体数据处理的各功能前，必须调用接口创建对应功能的通道，创建通道的接口请参见通道创建与释放。通道的创建与销毁会涉及资源的申请与释放，反复创建与销毁通道会影响业务性能，因此建议根据实际场景管理通道，例如，如果有持续VPC图片处理，则创建VPC的通道后，等到所有VPC功能调用完成后，再销毁该VPC通道。
通道数量多，会影响Device的CPU占用率和内存占用，通道数量建议参考各功能章节下的的性能指标的路数。
在Atlas 200/500 A2推理产品上，各功能的通道数有一定的限制，VPC的通道数最多128，JPEGD的通道数最多128，VDEC的通道数最多128，JPEGE的通道数最多128，VENC的通道数最多128，PNGD的通道数最多128。创建通道的接口请参见通道创建与释放。
:::note 说明 **对于Atlas 200/500 A2推理产品，**昇腾虚拟化实例（Ascend Virtual Instance）场景下，如果通道总数不为整数，则向下取整：
- VPC通道总数最多128。
- VDEC通道 = ( 被分配的VDEC硬件单元 / VDEC硬件单元 ) * 128，如果通道总数不为整数，则向下取整。JPEGD的通道数不随算力影响，但JPEGD+VDEC的总通道数最大128。
- VENC通道 = ( 被分配的VENC硬件单元 / VENC硬件单元 ) * 128，如果通道总数不为整数，则向下取整。JPEGE的通道数不随算力影响，但JPEGE+VENC的总通道数最大128。 :::
父主题： 媒体数据处理V1
基本概念
表1 关键概念列表
| 概念 | 描述 |
|---|---|
| 宽stride（widthStride） | 指一行图像跨距，表示输入/输出图片对齐后的宽，RGB格式和YUV格式的宽stride计算方式不一样。 各功能对宽stride的要求不同，请参见对应功能的约束说明： - VPC功能，请参见图片格式、宽高对齐、内存约束。 - JPEGD功能，请参见功能及约束说明。 - JPEGE功能，请参见功能及约束说明。 - PNGD功能，请参见功能及约束说明。 - VDEC功能，请参见功能及约束说明。 - VENC功能，请参见功能及约束说明。 |
| 高stride（heightStride） | 指图像在内存中的行数，表示输入/输出图片对齐后的高。 各功能对高stride的要求不同，请参见对应功能的约束说明： - VPC功能，请参见图片格式、宽高对齐、内存约束。 - JPEGD功能，请参见功能及约束说明。 - JPEGE功能，请参见功能及约束说明。 - PNGD功能，请参见功能及约束说明。 - VDEC功能，请参见功能及约束说明。 - VENC功能，请参见功能及约束说明。 |
| 上/下/左/右偏移 | 通过配置上偏移、下偏移、左偏移、右偏移可以实现两个功能：指定抠图区域或贴图区域的位置，控制抠图或贴图区域的宽、高，右偏移-左偏移+1=宽，下偏移-上偏移+1=高。 Atlas 200/500 A2推理产品请参见图1。 |
| 抠图区域 | 指用户指定的需抠出的图片区域。 抠图区域最小分辨率为10*6，最大分辨率为4096*4096。 抠图区域的约束，请参见抠图、贴图约束。 |
| 贴图区域 | 指在输出图片中用户指定的区域，贴图区域最小分辨率为10*6，最大分辨率为4096*4096。 贴图区域的约束，请参见抠图、贴图约束。 |
| 非8K | 非8K表示10*6 - YUV400、YUV420SP、YUV422SP、YUV444SP：系数为1。 - YUV422packed：系数为2。 - YUV444packed、RGB888：系数为3。 - ARGB8888：系数为4。 |
| 8K | 8K表示宽或高在4096~8192（不包括4096）范围内的输入图片。 |
父主题： 媒体数据处理V1
函数：dvpp_malloc
| C函数原型 | aclError acldvppMalloc(void **devPtr, size_t size) |
|---|---|
| Python函数 | dev_ptr, ret = acl.media.dvpp_malloc(size) |
| 函数功能 | 该接口主要用于分配内存给Device侧媒体数据处理时使用，申请的大页内存满足数据处理的要求（例如，内存首地址128对齐），同步接口。 |
| 输入说明 | size：int，申请内存的大小，单位Byte。 |
| 返回值说明 | dev_ptr：int，Device上已分配内存的指针地址。 ret：int，错误码。 - 返回0表示成功。 - 返回其它值表示失败。 |
| 约束说明 | - 调用该接口申请内存后，如果内存不使用，需及时调用acl.media.dvpp_free接口释放内存。 - 频繁调用acl.media.dvpp_malloc接口申请内存、调用acl.media.dvpp_free接口释放内存，会损耗性能，建议用户提前做内存预先分配或二次管理，避免频繁申请/释放内存。 - 调用acl.media.dvpp_malloc接口申请内存时，会对用户输入的size按向上对齐成32整数倍后，再多加32字节。 - 媒体数据处理的输出作为模型推理的输入时，若用户使用本接口申请大块内存并自行划分、管理内存时，每段内存需同时满足以下要求： - 内存大小向上对齐成32整数倍+32字节（m=ALIGN_UP[len,32]+32字节）。 - 内存起始地址需满足128字节对齐（ALIGN_UP[m,128]）。（说明：len表示某段内存的大小，ALIGN_UP[len,k]表示向上按k字节对齐：((len-1)/k+1)*k。） - 调用该接口申请大页内存失败，仅表示系统内的大页内存不够。 |
| 参考资源 | 接口调用流程及示例，参见媒体数据处理V1。 |
父主题： 内存申请与释放
函数：dvpp_free
| C函数原型 | aclError acldvppFree(void *devPtr) |
|---|---|
| Python函数 | ret = acl.media.dvpp_free(dev_ptr) |
| 函数功能 | 释放通过acl.media.dvpp_malloc接口申请的内存，同步接口。 |
| 输入说明 | dev_ptr：int，待释放内存的指针地址。 |
| 返回值说明 | ret：int，错误码。 - 返回0表示成功。 - 返回其它值表示失败。 |
| 约束说明 | 无 |
| 参考资源 | 接口调用流程及示例，参见媒体数据处理V1。 |
父主题： 内存申请与释放
函数：dvpp_create_channel
| C函数原型 | aclError acldvppCreateChannel(acldvppChannelDesc *channelDesc) |
|---|---|
| Python函数 | ret = acl.media.dvpp_create_channel(dvpp_channel_desc) |
| 函数功能 | 创建图片数据处理的通道，同一个通道可以重复使用，销毁后不再可用，同步接口。 |
| 输入说明 | dvpp_channel_desc：int，指定通道描述信息。调用acl.media.dvpp_create_channel_desc接口创建该输入数据。 |
| 返回值说明 | ret：int，错误码。 - 返回0表示成功。 - 返回其它值表示失败。 |
| 约束说明 | - 通道为非线程安全，即不同线程要求创建不同的通道。 - 同一个通道不能同时在多个Stream中并发使用。 - acl.media.dvpp_create_channel接口内部调用1次acl.rt.create_stream接口创建了1个Stream，该Stream用于创建通道的任务，创建通道的任务结束后，该Stream资源自动释放。 用户在创建通道时，acl.rt.create_stream接口的约束需要遵循，例如Stream的数量等。 |
| 参考资源 | 接口调用流程与示例，参见媒体数据处理V1。 |
父主题： VPC/JPEGD/JPEGE/PNGD图片处理通道
函数：dvpp_destroy_channel
| C函数原型 | aclError acldvppDestroyChannel(acldvppChannelDesc *channelDesc) |
|---|---|
| Python函数 | ret = acl.media.dvpp_destroy_channel(dvpp_channel_desc) |
| 函数功能 | 销毁图片数据处理的通道，只能销毁通过acl.media.dvpp_create_channel接口创建的通道，同步接口。 |
| 输入说明 | dvpp_channel_desc：int，指定通道描述信息。与调用acl.media.dvpp_create_channel接口创建通道时指定的dvpp_channel_desc保持一致。 |
| 返回值说明 | ret：int，错误码。 - 返回0表示成功。 - 返回其它值表示失败。 |
| 约束说明 | 如果在调用acl.media.dvpp_destroy_channel接口销毁通道前，已调用acl.media.dvpp_destroy_channel_desc接口销毁了通道描述信息，那么在调用acl.media.dvpp_destroy_channel接口销毁通道时会报错。 |
| 参考资源 | 接口调用流程及示例，参见媒体数据处理V1。 |
父主题： VPC/JPEGD/JPEGE/PNGD图片处理通道
函数：vdec_create_channel
| C函数原型 | aclError aclvdecCreateChannel(aclvdecChannelDesc *channelDesc) |
|---|---|
| Python函数 | ret = acl.media.vdec_create_channel(vdec_channel_desc) |
| 函数功能 | 创建视频数据处理的通道，同一个通道可以重复使用，销毁后不再可用，同步接口。 |
| 输入说明 | vdec_channel_desc：int，vdec通道描述地址对象, 指定通道描述信息。 调用acl.media.vdec_create_channel_desc接口创建vdec_channel_desc类型的数据，调用acl.media.vdec_set_channel_desc系列接口设置通道描述信息的属性。 |
| 返回值说明 | ret：int，错误码。 - 返回0表示成功。 - 返回其它值表示失败。 |
| 约束说明 | - 通道为非线程安全，即不同线程要求创建不同的通道。 - 通道数的限制，请参见总体说明。 - acl.media.vdec_create_channel接口内部封装了acl.rt.create_stream接口和acl.rt.subscribe_report： - 调用2次acl.rt.create_stream接口创建了2个Stream，一个Stream用于视频码流解码任务，另一个用于回调函数的处理。这些Stream资源只有在调用acl.media.vdec_destroy_channel接口销毁通道后才能自动释放。 - 调用acl.rt.subscribe_report接口指定处理Stream上回调函数的线程，回调函数和线程是由用户调用acl.media.vdec_set_channel_desc系列接口时指定的。 用户在实现VDEC功能时，无需再单独调用acl.rt.create_stream接口、acl.rt.subscribe_report接口，但acl.rt.create_stream接口、acl.rt.subscribe_report接口的约束需要遵循，例如Stream的数量、处理Stream上回调函数的线程数量等。 |
| 参考资源 | 接口调用流程及示例，参见媒体数据处理V1。 |
父主题： VDEC视频解码通道
在线提单