Video Effects SDK 编程指南

Video Effects SDK 编程指南

《Video Effects Programming Guide》（视频效果编程指南）提供有关 API 架构、可用效果、可用图像和 API 参考的信息。

本节提供有关 NVIDIA® Video Effects SDK 中效果的信息。要了解有关如何开始使用 Maxine 以及如何安装 SDK 的更多信息，请参阅《Video Effects SDK System Guide》（视频效果 SDK 系统指南）。

1.1. AI 绿幕滤镜

AI 绿幕滤镜将视频或静止图像分割为前景和背景区域。

支持以下操作模式：

• 质量模式，可提供最高质量的结果。
  • 图像的高度必须至少为 288 像素，宽度必须至少为 512 像素。
  • 此模式为默认模式。
• 性能模式，可提供最快的性能。
  • 可能会观察到一些质量下降。
  • 图像的高度必须至少为 288 像素，宽度必须至少为 512 像素。

为了获得最佳效果，图像文件的纵横比必须为 16:9。该滤镜适用于具有其他纵横比的图像。该滤镜的输入/输出如下：

• 输入应以 BGR 交错格式在 GPU 缓冲区中提供，其中每个像素都是 24 位无符号字符值，因此每个像素分量为 8 位。
• 滤镜的输出将写入 8 位（灰度）GPU 缓冲区。

有关可用于体验此效果的示例应用程序的更多信息，请参阅《Sample Applications Reference》（示例应用程序参考）。AI 绿幕滤镜通过执行以下操作序列来处理输入图像：

1. 滤镜根据滤镜的置信度对视频中的像素进行分类

   属于人的像素被归类为前景像素。

   所有其他像素都被归类为背景像素。

2. 对像素进行分类后，滤镜会生成一个与输入图像具有相同分辨率的 8 位 Alpha 蒙版。Alpha 值由滤镜对像素属于其分配类别的置信度决定。
   • 具有高前景置信度的像素被分配接近 255 的 Alpha 值。
   • 具有高背景置信度的像素被分配接近零的 Alpha 值。

下游进程可以将 AI 绿幕滤镜生成的 Alpha 蒙版与原始图像结合使用以生成效果。例如，可以将 24 位 BGR 输入图像与蒙版结合使用，以创建具有 Alpha 通道的 32 位图像。Alpha 值可以通过以下方式之一确定：

• 可以在该过程中应用阈值，以强制背景像素的 Alpha 通道为 0，前景像素的 Alpha 通道为 255。
• 可以维护原始 Alpha 值，以基于置信度创建半透明效果。

然后可以将 32 位图像合成到三级图像上，以生成原始图像的背景像素被三级图像的背景像素替换的图像。

1.2. 背景模糊滤镜

背景模糊滤镜使用分割蒙版和输入图像在输入图像的背景区域中产生模糊效果。

强度值允许您通过选择 [0-1] 范围内的值来更改应用的模糊滤镜的强度，默认值为 0.5。强度值可以使用 NVVFX_SetF32 函数设置。该值使用与 AI 绿幕滤镜相同的输入、AI 绿幕滤镜或其他来源的分割蒙版输出以及输出缓冲区。背景模糊滤镜通过完成以下过程来处理输入图像：

1. 滤镜使用分割蒙版来查找要应用模糊滤镜的感兴趣区域。
2. 输入与模糊图像合成以产生背景模糊效果。

以下是使用背景模糊滤镜的要求：

• 输入必须是 24 位 BGR 输入图像，因此每个像素分量为 8 位。

  数据类型为 UINT8，值范围为 [0, 255]。

• 分割蒙版必须是 8 位分割蒙版。

  数据类型为 UINT8，值范围为 [0, 255]。

• 输出是 24 位 BGR 图像，数据类型为 UINT8。

1.3. 伪影减少滤镜

此滤镜可减少编码器伪影，例如来自低比特率视频的块状伪影、振铃伪影、蚊子噪声，同时保留原始视频的细节。编码器伪影减少已针对 H.264 编码器进行了优化。

以下是两种操作模式：

• 模式 0 可消除较小的伪影，更好地保留低梯度信息，并且适用于较高比特率的视频。
• 模式 1 更适合较低比特率的视频。

滤镜的输入/输出如下：

• 输入应以 BGR 平面格式在 GPU 缓冲区中提供，其中每个像素分量都是 32 位浮点值。
• 滤镜的输出是与输入图像大小相同的 GPU 缓冲区，采用 BGR 平面格式，其中每个像素分量都是 32 位浮点值。

1.4. 超分辨率滤镜

超分辨率滤镜在保留内容的同时，提高了低分辨率视频的分辨率，增强了细节并锐化了输出。

此滤镜在保留内容的同时，增强了低分辨率视频的分辨率，并增强了细节并锐化了输出。模式 0 适用于升级具有编码伪影的有损内容，模式 1 适用于无损视频：

• 模式 0 增强较少，消除更多编码伪影，并且适用于较低质量的视频。
• 模式 1 增强更多，并且适用于较高质量的无损视频。

滤镜的输入/输出如下：

• 输入应以 BGR 平面格式在 GPU 缓冲区中提供，其中每个像素分量都是 32 位浮点值。
• 滤镜的输出是 BGR 平面格式的 GPU 缓冲区，其中每个像素分量都是 32 位浮点值。

下表说明了用于 ArtifactReduction 和 SuperRes 效果的输入视频的比例和分辨率支持。

1.5. 放大滤镜

这是一种非常快速且轻量级的方法，用于放大输入视频。

它还提供锐化参数来锐化生成的输出。此功能可以选择与编码器伪影减少功能流水线连接，以增强比例，同时减少视频伪影。放大支持任何输入分辨率，并且可以放大 4/3 倍、1.5 倍、2 倍、3 倍或 4 倍。输出分辨率值必须为整数，并且宽度比率必须与高度比率完全相等。放大滤镜提供介于 0.0 和 1.0 之间的浮点强度值。这表示增强参数：

• 强度 0 表示不增强，仅放大。
• 强度 1 表示最大增强。
• 默认值为 0.4。

滤镜的输入/输出如下：

• 输入应以 RGBA 块状/交错格式在 GPU 缓冲区中提供，其中每个像素为 32 位，因此每个像素分量为 8 位。
• 滤镜的输出是 RGBA 块状/交错格式的 GPU 缓冲区，其中每个像素为 32 位，因此每个像素分量为 8 位。

以下是一些一般建议：

• 如果无编码伪影的视频需要快速分辨率增加，请使用放大。
• 如果视频没有编码伪影，要增加分辨率，请使用超分辨率模式 1 以获得更大的增强效果。
• 如果视频的编码伪影较少，要消除伪影，请仅使用伪影减少模式 0。
• 如果视频的编码伪影较多，要消除伪影，请仅使用伪影减少模式 1。
• 要增加具有编码伪影的视频的分辨率：
  • 对于轻微伪影，请使用超分辨率模式 0。
  • 否则，请使用伪影减少，然后使用超分辨率模式 1。

以下示例应用程序是为这些滤镜提供的：

• VideoEffectsApp：此应用程序分别运行每个伪影减少、超分辨率、放大效果，并且当您想要将滤镜应用于输入视频时应使用此应用程序。
• UpscalePipelineApp：此应用程序运行伪影减少，然后放大的流水线。

  当您想要一个执行伪影减少和比例增强的快速应用程序时，可以使用此应用程序。

  这两个应用程序都支持在Scale and Resolution Support for Input Videos（输入视频的比例和分辨率支持）表（在The Super Resolution Filter（超分辨率滤镜）中）中指定的分辨率范围内的输入视频。

1.6. 网络摄像头降噪滤镜

网络摄像头降噪滤镜可消除网络摄像头视频中的噪声，同时保留细节。

强度值允许您通过选择值 0 或 1 来更改应用降噪滤镜的强度，默认值为 0。以下是有关这些值的一些其他信息：

• 强度值 0 对应于弱效果，它更强调纹理保留。
• 强度值 1 对应于强效果，它更强调噪声消除。

您可以使用 NVVFX_SetF32 函数设置强度值。滤镜的输入/输出如下：

• 输入应以 BGR 平面格式在 GPU 缓冲区中提供，其中每个像素分量都是 32 位浮点值。
• 滤镜的输出是 BGR 平面格式的 GPU 缓冲区，其中每个像素分量都是 32 位浮点值。

网络摄像头降噪滤镜可以应用于视频和图像，但为了获得更好的降噪效果，我们建议您仅在视频上应用此滤镜。

此滤镜支持 80p-1080p 分辨率范围内的输入图像/视频。

本节提供有关 Video Effects API 架构的信息。

2.1. 使用视频效果滤镜

要使用视频效果滤镜，您需要创建滤镜，设置滤镜的各种属性，然后加载、运行和销毁滤镜。

2.1.1. 创建视频效果滤镜

以下是有关如何创建视频效果滤镜的信息。

调用 NvVFX_CreateEffect() 函数，指定以下信息作为参数

• NvVFX_EffectSelector 类型。有关更多信息，请参阅 NvVFX_EffectSelector。
• 用于存储新创建的视频效果滤镜句柄的位置。

NvVFX_CreateEffect() 函数创建视频效果滤镜实例的句柄，以用于进一步的 API 调用。

此示例创建 AI 绿幕视频效果滤镜。

            

            
NvCV_Status vfxErr = NvVFX_CreateEffect(NVVFX_FX_GREEN_SCREEN, &effectHandle);
        

2.1.2. 设置模型文件夹的路径

视频效果滤镜需要神经网络模型来转换输入静止图像或视频图像。您必须设置包含描述滤镜要使用的模型的文件所在的文件夹的路径。

调用 NvVFX_SetString() 函数，指定以下信息作为参数：

• 在Creating a Video Effect Filter（创建视频效果滤镜）中说明的已创建的滤镜句柄。
• 选择器字符串 NVVFX_MODEL_DIRECTORY。
• 指示模型文件夹路径的 null 终止字符串。

此示例将模型文件夹的路径设置为 C:\Users\vfxuser\Documents\vfx\models。

            

            
const char* modelDir="C:\Users\vfxuser\Documents\vfx\models";
...
vfxErr = NvVFX_SetString(effectHandle, NVVFX_MODEL_DIRECTORY, modelDir);
        

2.1.3. 设置 CUDA 流

视频效果滤镜需要 CUDA 流才能运行。有关 CUDA 流的信息，请参阅《NVIDIA CUDA Toolkit Documentation》（NVIDIA CUDA 工具包文档）。

1. 通过调用以下函数之一初始化 CUDA 流。
   • CUDA Runtime API 函数 cudaStreamCreate()。
   • 使用 NvVFX_CudaStreamCreate() 函数以避免与 NVIDIA CUDA 工具包库链接。
2. 调用 NvVFX_SetCudaStream() 函数，提供以下信息作为参数：
   • 在Creating a Video Effect Filter（创建视频效果滤镜）中说明的已创建的滤镜句柄。
   • 选择器字符串 NVVFX_CUDA_STREAM。
   • 您在上一步中创建的 CUDA 流。

   此示例设置通过调用 NvVFX_CudaStreamCreate() 函数创建的 CUDA 流。

   复制

   已复制！

               
   
               
   CUstream stream;
   ...
   vfxErr = NvVFX_CudaStreamCreate (&stream);
   ...
   vfxErr = NvVFX_SetCudaStream(effectHandle, NVVFX_CUDA_STREAM, stream);
           

   
   

2.1.4. 创建和设置状态变量

2.1.4.1. 对于网络摄像头降噪

网络摄像头降噪使用状态变量来跟踪输入视频流以消除时间噪声。

SDK 用户负责完成以下任务：

• 创建状态变量。
  1. 通过使用 NVVFX_STATE_SIZE 选择器字符串调用 NvVFX_GetU32() 来查询状态变量的大小。
     复制

     已复制！

                 
     
                 
     unsigned int stateSizeInBytes;
     vfxErr =  NvVFX_GetU32(effectHandle, NVVFX_STATE_SIZE, &stateSizeInBytes);
             

     
     
  2. 通过使用 cudaMalloc() 在 GPU 中为状态变量分配必要的空间。
     复制

     已复制！

                 
     
                 
     void* state[1];
     cudaMalloc(&state[0], stateSizeInBytes);
             

     
     
  3. 通过使用 cudaMemset() 将状态变量初始化为 0。
     复制

     已复制！

                 
     
                 
     cudaMemset(state[0], 0, stateSizeInByte);
             

     
     
• 将状态变量传递给 SDK。

  要将状态变量传递给 SDK，请将 NVVFX_STATE 选择器字符串与 NvVFX_SetObject() 一起使用。

  复制

  已复制！

              
  
              
  vfxErr = NvVFX_SetObject(effectHandle, NVVFX_STATE, (void*)state);
          

  
  

• 释放状态变量内存。

  初始化和设置状态变量后，可以在图像或视频上运行滤镜。状态变量完成原始输入的处理后，您可以将该变量与另一个图像/视频一起重复使用。

2.1.4.2. 对于 AI 绿幕

AI 绿幕滤镜使用状态变量来跟踪输入视频流，以保持时间一致性，并且 SDK 提供 NvVFX_StateObjectHandle 来表示状态变量的句柄。

SDK 用户负责完成以下任务：

• 创建状态变量。
  1. 通过使用 NvCV_Status 选择器字符串调用 NvVFX_AllocateState 来查询状态变量的大小。该函数完成以下步骤：
     1. 分配状态变量。
     2. 重置状态变量。
     3. 在 SDK 用户可以存储以进行额外处理的第二个参数中分配句柄。
     复制

     已复制！

                 
     
                 
     NvVFX_StateObjectHandle stateObjectHandle;
     vfxErr =  NvVFX_AllocateState(effectHandle, &stateObjectHandle);
             

     
     

• 将状态变量传递给 SDK。

  要将状态变量传递给 SDK，请将 NVVFX_STATE 选择器字符串与 NvVFX_SetStateObjectHandleArray 函数一起使用。

  复制

  已复制！

              
  
              
  vfxErr =  NvVFX_SetObject(effectHandle, NVVFX_STATE, &stateObjectHandle);
          

  
  

• 为另一个输入视频流重复使用状态变量。

  初始化和设置状态变量后，可以在图像或视频上运行滤镜。状态变量完成原始输入的处理后，您可以将该变量与另一个图像/视频一起重复使用。

  但是，在将其用于新输入之前，请通过调用 NvVFX_ResetState 函数来重置状态变量。它返回 NvCV_Status。

  复制

  已复制！

              
  
              
  vfxErr = NvVFX_ResetState(effectHandle, stateObjectHandle);
          

  
  

• 当状态变量不再使用时，通过调用 NvVFX_DeallocateState 函数来释放状态变量。

  vfxErr = NvVFX_DeallocateState(effectHandle, stateObjectHandle);

2.1.5. 设置输入和输出图像缓冲区

每个滤镜都将 GPU NvCVImage 结构作为输入，并在 GPU NvCVImage 结构中生成结果。有关 NvCVImage 的更多信息，请参阅《NvCVImage API Guide》（NvCVImage API 指南）。这些图像是滤镜接受的 GPU 缓冲区。应用程序通过将输入和输出缓冲区设置为必需参数来为滤镜提供它们。

视频效果滤镜要求输入以 GPU 缓冲区形式提供。如果原始缓冲区的类型为 CPU/GPU 或采用平面格式，则必须按照Transferring Images Between CPU and GPU Buffers（在 CPU 和 GPU 缓冲区之间传输图像）中的说明进行转换。以下是当前使用的格式列表：

• AI 绿幕：BGRu8 块状 --> Au8
• 背景模糊：BGRu8 块状 + Au8 块状 --> BGRu8 块状
• 放大：RGBAu8 块状 --> RGBAu8 块状
• 伪影减少：BGRf32 平面归一化 --> BGRf32 平面归一化
• 超分辨率：BGRf32 平面归一化 --> BGRf32 平面归一化
• 传输：任何 --> 任何
• 降噪：BGRf32 平面归一化 --> BGRf32 平面归一化

对于每个图像缓冲区，调用 NvVFX_SetImage() 函数，并指定以下信息作为参数：

• 在Creating a Video Effect Filter（创建视频效果滤镜）中说明的已创建的滤镜句柄。
• 表示您要创建的缓冲区类型的选择器字符串
• 对于输入图像缓冲区，请使用 NVVFX_INPUT_IMAGE。
• 对于输出（蒙版）图像缓冲区，请使用 NVVFX_OUTPUT_IMAGE。
• 为输入或输出图像创建的 NvCVImage 对象的地址。
• 对于背景模糊，请使用 NVVFX_INPUT_IMAGE_1 传递第二个输入，即分割蒙版。

此示例创建输入图像缓冲区。

            

            
NvCVImage srcGpuImage;
...
vfxErr = NvCVImage_Alloc(&srcGpuImage, 960, 540, NVCV_BGR, NVCV_U8, NVCV_CHUNKY, NVCV_GPU, 1)
...
vfxErr = NvVFX_SetImage(effectHandle, NVVFX_INPUT_IMAGE, &srcGpuImage);
        

此示例创建输出图像缓冲区。

            

            
NvCVImage srcGpuImage;
...
vfxErr = NvCVImage_Alloc(&dstGpuImage, 960, 540, NVCV_A, NVCV_U8, NVCV_CHUNKY, NVCV_GPU, 1))
...
vfxErr = NvVFX_SetImage(effectHandle, NVVFX_OUTPUT_IMAGE, &dstGpuImage);
        

2.1.6. 设置和获取视频效果滤镜的其他参数

在加载和运行视频效果滤镜之前，设置滤镜所需的任何其他参数。Video Effects SDK 提供用于此目的的类型安全设置访问器函数。如果您需要具有设置访问器函数的参数的值，请使用相应的 get 访问器函数。

以下是当前使用的格式列表：

• 在Creating a Video Effect Filter（创建视频效果滤镜）中说明的已创建的滤镜句柄。
• 您要访问的参数的选择器字符串。
• 您要设置的值或指向要存储要获取的值的位置的指针。

此示例将 AI 绿幕滤镜的模式设置为最快性能。

            

            
vfxErr = NvVFX_SetU32(effectHandle, NVVFX_MODE, 1);
        

2.1.6.1. 示例：设置 AI 绿幕的滤镜模式

以下是 AI 绿幕滤镜的任务示例。

AI 绿幕滤镜支持以下操作模式：

• 质量模式，可提供最高质量的结果（默认）。
• 性能模式，可提供最快的性能。

调用 NvVFX_SetU32() 函数，指定以下信息作为参数：

• 在Creating a Video Effect Filter（创建视频效果滤镜）中说明的已创建的滤镜句柄。
• 选择器字符串 NVVFX_MODE。
• 表示您想要的操作模式的整数：
  • 0：质量模式
  • 1：性能模式

此示例将模式设置为性能。

            

            
vfxErr = NvVFX_SetU32 (effectHandle, NVVFX_MODE, 1);
        

2.1.6.2. 示例：为 AI 绿幕启用 CUDA 图优化

AI 绿幕滤镜支持 CUDA 图优化，可以通过为 NVVFX_CUDA_GRAPH 设置正确的值来启用该优化。

调用 NvVFX_SetU32() 函数并指定以下信息作为参数：

• 已创建的滤镜句柄（有关更多信息，请参阅Creating a Video Effect Filter（创建视频效果滤镜））。
• NVVFX_CUDA_GRAPH 选择器字符串。
• 以下整数表示优化状态：
  • 0: 关闭
  • 1: 开启

在调用 NvVFX_Load() 方法之前调用以下 set 方法，将初始化 AI 绿幕效果

            

            
vfxErr = NvVFX_SetU32 (effectHandle, NVVFX_CUDA_GRAPH, 1);
        

• 如果启用了 CUDA 图形优化，则首次调用 NVVFX_RUN() 将初始化优化。

  在图形初始化期间，如果发生错误，将返回 NVCV_ERR_CUDA 错误代码。

• 如果在初始化之后调用 set 方法，则 NvVFX_Run() 调用将返回 NVCV_ERR_INITIALIZATION 错误代码。

启用 CUDA 图形优化可以减少内核启动开销，并可能提高整体性能。为了验证性能提升，我们建议开发人员通过在 关闭 和 开启 状态之间切换来测试其应用程序的 CUDA 图形优化效果。

2.1.6.3. 示例：优化 AI 绿幕的内存分配

AI 绿幕滤镜适用于任何宽度和高度的图像，但分辨率的提高将导致滤镜分配必要的 GPU 内存。

AI 绿幕滤镜支持 NVVFX_MAX_INPUT_WIDTH 和 NVVFX_MAX_INPUT_HEIGHT 参数，这些参数可以在 NvVFX_RUN() 期间优化内存分配。

调用 NvVFX_SetU32() 函数并指定以下信息作为参数

在Creating a Video Effect Filter（创建视频效果滤镜）中说明的已创建的滤镜句柄。

选择器字符串 NVVFX_MAX_INPUT_WIDTH 和 NVVFX_MAX_INPUT_HEIGHT。

宽度和高度的整数值，例如 1920、1080。

            

            
vfxErr = NvVFX_SetU32 (effectHandle, NVVFX_MAX_INPUT_WIDTH , 1920);
vfxErr = NvVFX_SetU32 (effectHandle, NVVFX_MAX_INPUT_HEIGHT , 1080);
        

上述 set 方法必须在 NvVFX_Load() 方法之前调用，该方法初始化 AIGS 效果。

在通过上述参数选择器字符串设置的值范围内，滤镜将不会分配额外的内存。

2.1.7. NVIDIA 视频特效 SDK 访问器函数摘要

下表提供了有关 SDK 访问器函数的详细信息。

2.1.8. 获取有关滤镜及其参数的信息

以下是关于如何获取有关滤镜及其参数的信息。

要获取有关滤镜及其参数的信息，请调用 NvVFX_GetString() 函数，并指定 NvVFX_ParameterSelector 类型定义的 NVVFX_INFO 类型。

            

            
NvCV_Status NvVFX_GetString(
  NvVFX_Handle obj,
  NVVFX_INFO,
  const char **str
);
        

2.1.9. 获取所有可用特效的列表

以下是关于如何获取可用特效列表的信息。

要获取可用特效的列表，请调用 NvVFX_GetString() 函数，并为 NvVFX_Handle 对象句柄指定 NULL。

            

            
NvCV_Status NvVFX_GetString(NULL, NVVFX_INFO, const char **str);
        

2.2. 加载视频特效滤镜

加载滤镜会选择和加载特效模型，并验证为滤镜设置的参数。

要加载视频特效滤镜，请调用 NvVFX_Load() 函数，并指定在创建视频特效滤镜中说明的已创建的滤镜句柄。

            

            
vfxErr = NvVFX_Load(effectHandle);
        

2.3. 运行视频特效滤镜

加载视频特效滤镜后，运行滤镜以应用所需的效果。运行滤镜时，将读取输入 GPU 缓冲区的内容，应用视频特效滤镜，并将输出写入输出 GPU 缓冲区。

要运行视频特效滤镜，请调用 NvVFX_Run() 函数。在调用 NvVFX_Run() 函数时，传递以下信息作为参数：

• 在Creating a Video Effect Filter（创建视频效果滤镜）中说明的已创建的滤镜句柄。
• 一个整数值，用于指定滤镜是以异步方式还是同步方式运行：
  • 1：滤镜以异步方式运行。
  • 0：滤镜以同步方式运行。

此示例以异步方式运行视频特效滤镜，并调用 NvCVImage_Transfer() 函数将输出复制到 CPU 缓冲区。

            

            
vfxErr = NvVFX_Run(effectHandle, 1);
vfxErr = NvCVImage_Transfer()
        

2.4. 销毁视频特效滤镜

当不再需要视频特效滤镜时，销毁它以释放为滤镜分配的资源和内存。

要销毁视频特效滤镜，请调用 NvVFX_DestroyEffect() 函数，并指定在创建视频特效滤镜中说明的已创建的滤镜句柄。

            

            
NvVFX_DestroyEffect(effectHandle);
        

您可以使用视频特效 SDK 来使应用程序能够将特效滤镜应用于视频。视频特效 API 是面向对象的，但除了 C++ 之外，C 也可以访问它。

2.5. 在 GPU 或 CPU 缓冲区上处理图像帧

特效滤镜接受图像缓冲区作为 NvCVImage 对象。图像缓冲区可以是 CPU 或 GPU 缓冲区，但出于性能原因，特效滤镜需要 GPU 缓冲区。视频特效 SDK 提供了用于将图像表示形式转换为 NvCVImage 以及在 CPU 和 GPU 缓冲区之间传输图像的函数。

有关 NvCVImage 的更多信息，请参阅 NvCVImage API 指南。本节概述了视频特效 SDK 最常用的函数。

2.5.1. 将图像表示形式转换为 NvCVImage 对象

视频特效 SDK 提供了用于将 OpenCV 图像和其他图像表示形式转换为 NvCVImage 对象的函数。每个函数都在现有缓冲区周围放置一个包装器。当调用包装器的析构函数时，包装器会阻止缓冲区被释放。

2.5.1.1. 将 OpenCV 图像转换为 NvCVImage 对象

以下是关于如何将 OpenCV 图像转换为 NvCVImage 对象的信息。

• 要为 OpenCV 图像创建 NvCVImage 对象包装器，请使用 NVWrapperForCVMat() 函数。
  复制

  已复制！

              
  
              
  //Allocate source and destination OpenCV images
  cv::Mat srcCVImg(   );
  cv::Mat dstCVImg(...);
   
  // Declare source and destination NvCVImage objects
  NvCVImage srcCPUImg;
  NvCVImage dstCPUImg;
   
  NVWrapperForCVMat(&srcCVImg, &srcCPUImg);
  NVWrapperForCVMat(&dstCVImg, &dstCPUImg);
          

  
  
• 要为 NvCVImage 对象创建 OpenCV 图像包装器，请使用 CVWrapperForNvCVImage() 函数。
  复制

  已复制！

              
  
              
  // Allocate source and destination NvCVImage objects
  NvCVImage srcCPUImg(...);
  NvCVImage dstCPUImg(...);
   
  //Declare source and destination OpenCV images
  cv::Mat srcCVImg;
  cv::Mat dstCVImg;
   
  CVWrapperForNvCVImage (&srcCPUImg, &srcCVImg);
  CVWrapperForNvCVImage (&dstCPUImg, &dstCVImg);
          

  
  

2.5.1.2. 将 GPU 或 CPU 缓冲区上的图像帧转换为 NvCVImage 对象

以下是关于如何将 CPU 或 GPU 缓冲区上的图像帧转换为 NvCVImage 对象的信息。

调用 NvCVImage_Init() 函数，在现有缓冲区 (srcPixelBuffer) 周围放置一个包装器。

            

            
NvCVImage src_gpu;
vfxErr = NvCVImage_Init(&src_gpu, 640, 480, 1920, srcPixelBuffer, NVCV_BGR, NVCV_U8, NVCV_INTERLEAVED, NVCV_GPU);
 
NvCVImage src_cpu;
vfxErr = NvCVImage_Init(&src_cpu, 640, 480, 1920, srcPixelBuffer, NVCV_BGR, NVCV_U8, NVCV_INTERLEAVED, NVCV_CPU);
        

2.5.1.3. 将来自 NvDecoder 的解码帧转换为 NvCVImage 对象

以下是关于将来自 NvDecoder 的解码帧转换为 NvCVImage 对象的信息。

调用 NvCVImage_Transfer() 函数，将 NvDecoder 提供的解码帧从解码像素格式转换为视频特效 SDK 功能所需的格式。以下示例显示了从 NV12 转换为 BGRA 像素格式的解码帧。

            

            
vCVImage decoded_frame, BGRA_frame, stagingBuffer;
NvDecoder dec;
 
//Initialize decoder...
//Assuming dec.GetOutputFormat() == cudaVideoSurfaceFormat_NV12
 
//Initialize memory for decoded frame
NvCVImage_Init(&decoded_frame, dec.GetWidth(), dec.GetHeight(), dec.GetDeviceFramePitch(), NULL, NVCV_YUV420, NVCV_U8, NVCV_NV12, NVCV_GPU, 1);
decoded_frame.colorSpace = NVCV_709 | NVCV_VIDEO_RANGE | NVCV_CHROMA_ COSITED;
 
//Allocate memory for BGRA frame
NvCVImage_Alloc(&BGRA_frame, dec.GetWidth(), dec.GetHeight(), NVCV_BGRA, NVCV_U8, NVCV_CHUNKY, NVCV_GPU, 1);
 
decoded_frame.pixels = (void*)dec.GetFrame();
 
//Convert from decoded frame format(NV12) to desired format(BGRA)
NvCVImage_Transfer(&decoded_frame, &BGRA_frame, 1.f, stream, & stagingBuffer);
        

2.5.1.4. 将 NvCVImage 对象转换为可由 NvEncoder 编码的缓冲区

以下是关于如何使用 NvEncoder 将 NvCVImage 对象转换为缓冲区的信息。

要将 NvCVImage 转换为在通过 NvEncoder 编码期间使用的像素格式，如果需要，请调用 NvCVImage_Transfer() 函数。以下示例显示了以 BGRA 像素格式编码的帧。

            

            
//BGRA frame is 4-channel, u8 buffer residing on the GPU
NvCVImage BGRA_frame;
NvCVImage_Alloc(&BGRA_frame, dec.GetWidth(), dec.GetHeight(), NVCV_BGRA, NVCV_U8, NVCV_CHUNKY, NVCV_GPU, 1);
 
//Initialize encoder with a BGRA output pixel format
using NvEncCudaPtr = std::unique_ptr<NvEncoderCuda, std::function<void(NvEncoderCuda*)>>;
NvEncCudaPtr pEnc(new NvEncoderCuda(cuContext, dec.GetWidth(), dec.GetHeight(), NV_ENC_BUFFER_FORMAT_ARGB));
pEnc->CreateEncoder(&initializeParams);
//...
 
std::vector<std::vector<uint8_t>> vPacket;
//Get the address of the next input frame from the encoder
const NvEncInputFrame* encoderInputFrame = pEnc->GetNextInputFrame();
 
//Copy the pixel data from BGRA_frame into the input frame address obtained above
NvEncoderCuda::CopyToDeviceFrame(cuContext,
                        BGRA_frame.pixels,
                        BGRA_frame.pitch,
                        (CUdeviceptr)encoderInputFrame->inputPtr,
                        encoderInputFrame->pitch,
                        pEnc->GetEncodeWidth(),
                        pEnc->GetEncodeHeight(),
                        CU_MEMORYTYPE_DEVICE,
                        encoderInputFrame->bufferFormat,
                        encoderInputFrame->chromaOffsets,
                        encoderInputFrame->numChromaPlanes);
pEnc->EncodeFrame(vPacket);
        

2.5.2. 分配 NvCVImage 对象缓冲区

您可以使用 NvCVImage 分配构造函数或图像函数来分配 NvCVImage 对象的缓冲区。在这两种选项中，当图像超出范围时，缓冲区都会被析构函数自动释放。

2.5.2.1. 使用 NvCVImage 分配构造函数来分配缓冲区

NvCVImage 分配构造函数创建一个已分配内存并已初始化的对象。有关更多信息，请参阅 分配构造函数。
分配构造函数的最后三个可选参数确定生成的 NvCVImage 对象的属性：

• 像素组织形式决定了蓝色、绿色和红色是在单独的平面中还是交错排列。
• 内存类型决定了缓冲区驻留在 GPU 还是 CPU 上。
• 字节对齐方式决定了连续扫描线之间的间隙。

以下示例显示了如何使用分配构造函数的最后三个可选参数来确定 NvCVImage 对象的属性。

• 此示例创建一个对象，而不设置分配构造函数的最后三个可选参数。在此对象中，蓝色、绿色和红色分量在每个像素中交错排列，缓冲区驻留在 CPU 上，字节对齐方式为默认对齐方式。
  复制

  已复制！

              
  
              
  NvCVImage cpuSrc(
    srcWidth,
    srcHeight,
    NVCV_BGR,
    NVCV_U8
  );
          

  
  
• 此示例创建一个对象，其像素组织形式、内存类型和字节对齐方式与上一个示例相同，通过显式设置最后三个可选参数来实现。与上一个示例一样，蓝色、绿色和红色分量在每个像素中交错排列，缓冲区驻留在 CPU 上，字节对齐方式为默认对齐方式，即针对最大性能进行了优化。
  复制

  已复制！

              
  
              
  NvCVImage src(
    srcWidth,
    srcHeight,
    NVCV_BGR,
    NVCV_U8,
    NVCV_INTERLEAVED,
    NVCV_CPU,
    0
  );
          

  
  
• 此示例创建一个对象，其中蓝色、绿色和红色分量在单独的平面中，缓冲区驻留在 GPU 上，字节对齐方式确保在一条扫描线和下一条扫描线之间不存在间隙。
  复制

  已复制！

              
  
              
  NvCVImage gpuSrc(
    srcWidth,
    srcHeight,
    NVCV_BGR,
    NVCV_U8,
    NVCV_PLANAR,
    NVCV_GPU,
    1
  );
          

  
  

2.5.2.2. 使用图像函数来分配缓冲区

通过声明一个空图像，您可以延迟缓冲区分配。

1. 声明一个空的 NvCVImage 对象。
   复制

   已复制！

               
   
               
   NvCVImage xfr;
           

   
   
2. 为图像分配或重新分配缓冲区。
   • 要分配缓冲区，请调用 NvCVImage_Alloc() 函数。

     当图像是状态结构的一部分时，请以这种方式分配缓冲区，在这种情况下，您稍后才能知道图像的大小。

   • 要重新分配缓冲区，请调用 NvCVImage_Realloc()。

     此函数检查是否已分配缓冲区，并在释放缓冲区并调用 NvCVImage_Alloc() 之前，如果缓冲区足够大，则会重塑缓冲区。

2.5.3. 在 CPU 和 GPU 缓冲区之间传输图像

如果输入和输出图像缓冲区的内存类型不同，则应用程序可以在 CPU 和 GPU 缓冲区之间传输图像。

2.5.3.1. 将输入图像从 CPU 缓冲区传输到 GPU 缓冲区

以下是关于如何将输入图像从 CPU 缓冲区传输到 GPU 缓冲区的信息。

要将图像从 CPU 传输到 GPU 缓冲区并进行转换，给定以下代码

            

            
NvCVImage srcCpuImg(width, height, NVCV_RGB, NVCV_U8, NVCV_INTERLEAVED,
                    NVCV_CPU, 1);
NvCVImage dstGpuImg(width, height, NVCV_BGR, NVCV_F32, NVCV_PLANAR,
                    NVCV_GPU, 1);
        

1. 通过以下方式之一创建 NvCVImage 对象以用作暂存 GPU 缓冲区：
   • 为了避免在视频管道中分配内存，请在初始化阶段创建一个 GPU 缓冲区，其尺寸和格式与 CPU 图像相同。
     复制

     已复制！

                 
     
                 
     NvCVImage stageImg(srcCpuImg.width, srcCpuImg.height,
               srcCpuImg.pixelFormat, srcCpuImg.componentType,
               srcCpuImg.planar, NVCV_GPU);
             

     
     
   • 为了简化应用程序程序代码，您可以在初始化阶段声明一个空的暂存缓冲区。
     复制

     已复制！

                 
     
                 
     NvCVImage stageImg;
             

     
     

   将根据需要（如果需要）分配或重新分配大小合适的缓冲区。

2. 调用 NvCVImage_Transfer() 函数，以通过暂存 GPU 缓冲区将源 CPU 缓冲区内容复制到最终 GPU 缓冲区。
   复制

   已复制！

               
   
               
   // Transfer the image from the CPU to the GPU, perhaps with conversion.
   NvCVImage_Transfer(&srcCpuImg, &dstGpuImg, 1.0f, stream, &stageImg);
           

   
   

   无论图像大小如何，相同的暂存缓冲区都可以在不同上下文中的多个 NvCVImage_Transfer 调用中重复使用，并且如果它是持久性的，则可以避免缓冲区分配。

2.5.3.2. 将输出图像从 GPU 缓冲区传输到 CPU 缓冲区

以下是关于如何将输出图像从 GPU 缓冲区传输到 CPU 缓冲区的信息。

要将图像从 GPU 传输到 CPU 缓冲区并进行转换，给定以下代码

            

            
NvCVImage srcGpuImg(width, height, NVCV_BGR, NVCV_F32, NVCV_PLANAR,
                    NVCV_GPU, 1);
NvCVImage dstCpuImg(width, height, NVCV_BGR, NVCV_U8, NVCV_INTERLEAVED,
                    NVCV_CPU, 1);
        

1. 通过以下方式之一创建 NvCVImage 对象以用作暂存 GPU 缓冲区：
   • 为了避免在视频管道中分配内存，请在初始化阶段创建一个 GPU 缓冲区，其尺寸和格式与 CPU 图像相同。
     复制

     已复制！

                 
     
                 
     NvCVImage stageImg(dstCpuImg.width, dstCpuImg.height,
     dstCPUImg.pixelFormat, dstCPUImg.componentType,
     dstCPUImg.planar, NVCV_GPU);
             

     
     
   • 为了简化应用程序程序代码，您可以在初始化阶段声明一个空的暂存缓冲区。
     复制

     已复制！

                 
     
                 
     NvCVImage stageImg;
             

     
     

   将根据需要（如果需要）分配或重新分配大小合适的缓冲区。

   有关 NvCVImage 的更多信息，请参阅 NvCVImage API 指南。

2. 调用 NvCVImage_Transfer() 函数，以通过暂存 GPU 缓冲区将 GPU 缓冲区内容复制到目标 CPU 缓冲区。
   复制

   已复制！

               
   
               
   // Retrieve the image from the GPU to CPU, perhaps with conversion.
   NvCVImage_Transfer(&srcGpuImg, &dstCpuImg, 1.0f, stream, &stageImg);
           

   
   

如果暂存缓冲区是持久性的，则可以在 NvCVImage_Transfer 中重复使用相同的暂存缓冲区，而无需重新分配。

本节提供有关使用多个 GPU、默认行为以及如何为任务选择 GPU 的信息。

3.1. 使用多个 GPU

使用视频特效 SDK 开发的应用程序可以与多个 GPU 一起使用。

默认情况下，SDK 根据当前选定 GPU 的功能来确定要使用的 GPU：如果当前选定的 GPU 支持视频特效 SDK，则 SDK 使用它。否则，SDK 将选择最佳 GPU。您可以使用 NVIDIA CUDA 工具包函数 cudaSetDevice(int whichGPU) 和 cudaGetDevice(int *whichGPU) 以及视频特效 Set 函数 NvVFX_SetS32(NULL, NVVFX_GPU, whichGPU) 来控制在多 GPU 环境中使用哪个 GPU。Set() 调用旨在仅在创建任何特效之前对视频特效 SDK 调用一次。在一个 GPU 上分配的图像不能透明地传递到另一个 GPU，因此您必须确保所有视频特效都使用相同的 GPU。

            

            
NvCV_Status err;
int chosenGPU = 0; // or whatever GPU you want to use
err = NvVFX_SetS32(NULL, NVVFX_GPU, chosenGPU);
if (NVCV_SUCCESS != err) {
	printf(“Error choosing GPU %d: %s\n”, chosenGPU,
        	NvCV_GetErrorStringFromCode(err));
}
cudaSetDevice(chosenGPU);
NvCVImage *dst = new NvCVImage(…);
NvVFX_Handle eff;
err = NvVFX_API NvVFX_CreateEffect(code, &eff);
err = NvVFX_API NvVFX_SetImage(eff, NVVFX_OUTPUT_IMAGE, dst);
…
err = NvVFX_API NvVFX_Load(eff);
err = NvVFX_API NvVFX_Run(eff, true);
// switch GPU for other task, then switch back for next frame
        

缓冲区需要在选定的 GPU 上分配，因此在 GPU 上分配图像之前，请调用 cudaSetDevice()。神经网络需要在选定的 GPU 上加载，因此在调用 NvVFX_Load() 之前，请将此 GPU 设置为当前设备。

要在调用 NvVFX_Run() 之前使用缓冲区和模型，GPU 设备需要是当前的。先前调用 NvVFX_SetS32(NULL, NVVFX_GPU, whichGPU) 有助于强制执行此要求。

出于性能考虑，切换到适当的 GPU 是应用程序的责任。

3.2. 多 GPU 环境中的默认行为

NvVFX_Load() 函数在内部调用 cudaGetDevice() 以识别当前选定的 GPU。
然后，该函数检查当前选定 GPU（默认值为 0）的计算能力，以确定 GPU 架构是否支持视频特效 SDK：

• 如果是，NvVFX_Load() 将使用该 GPU。
• 如果否，NvVFX_Load() 将搜索支持视频特效 SDK 的最强大的 GPU，并调用 cudaSetDevice() 将该 GPU 设置为当前 GPU。

如果您不要求应用程序在多 GPU 环境中使用特定的 GPU，则默认行为应已足够。

3.3. 在多 GPU 环境中选择用于视频特效处理的 GPU

您的应用程序可能旨在仅使用多 GPU 环境中的特定 GPU 来执行应用视频特效滤镜的任务。

在这种情况下，请确保视频特效 SDK 不会覆盖您为应用视频特效滤镜而选择的 GPU。

            

            
// Initialization
cudaGetDevice(&beforeGPU);
vfxErr = NvVFX_Load(eff);
if (NVCV_SUCCESS != vfxErr) { printf("Cannot load VFX: %s\n",
   NvCV_GetErrorStringFromCode(vfxErr)); exit(-1); }
cudaGetDevice(&vfxGPU);
if (beforeGPU != vfxGPU) {
  printf("GPU #%d cannot run VFX, so GPU #%d was chosen instead\n",
	beforeGPU, vfxGPU);
}
vfxErr = NvVFX_SetImage() ...
...
        

3.4. 为不同任务选择不同的 GPU

您的应用程序可能旨在在多 GPU 环境中执行多项任务，例如，渲染游戏和应用视频特效滤镜。在这种情况下，请在调用 NvVFX_Load() 之前，为每项任务选择最佳 GPU。

1. 调用 cudaGetDeviceCount() 以确定环境中的 GPU 数量。
   复制

   已复制！

               
   
               
   // Get the number of GPUs
   cuErr = cudaGetDeviceCount(&deviceCount);
           

   
   
2. 获取每个 GPU 的属性，并通过为循环中的每个 GPU 执行以下操作来确定它是否是每项任务的最佳 GPU。
   1. 调用 cudaSetDevice() 以设置当前 GPU。
   2. 调用 cudaGetDeviceProperties() 或最好是 cudaDeviceGetAttribute () 以获取当前 GPU 的属性。
   3. 在您的应用程序中使用自定义代码来分析 cudaGetDeviceProperties() 或 cudaDeviceGetAttribute() 检索到的属性，以确定 GPU 是否是每项特定任务的最佳 GPU。

   此示例使用计算能力来确定是否应分析 GPU 的属性，以确定 GPU 是否是应用视频特效滤镜的最佳 GPU。仅当计算能力为 7.5、8.6 或 8.9 时才分析 GPU 的属性。此值表示分别基于 NVIDIA Turing、NVIDIA Ampere 或 NVIDIA Ada 架构的 GPU。

   复制

   已复制！

               
   
               
   // Loop through the GPUs to get the properties of each GPU and
   //determine if it is the best GPU for each task based on the
   //properties obtained.
   for (int dev = 0; dev < deviceCount; ++dev) {
     cudaSetDevice(dev);
     cudaGetDeviceProperties(&deviceProp, dev);
     if (DeviceIsBestForVFX(&deviceProp))  gpuVFX = dev;
     if (DeviceIsBestForGame(&deviceProp)) gpuGame = dev;
     ...
     }
     cudaSetDevice(gpuVFX);
     vfxErr = NvVFX_Set...; // set parameters
     vfxErr = NvVFX_Load(eff);
           

   
   

3. 在执行应用程序任务的循环中，在执行任务之前为每项任务选择最佳 GPU。
   1. 调用 cudaSetDevice() 以选择任务的 GPU。
   2. 进行执行任务所需的所有函数调用。

   通过这种方式，您只需为每项任务选择一次最佳 GPU，而无需为每个函数调用设置 GPU。

   此示例选择最佳 GPU 来渲染游戏，并使用自定义代码来渲染游戏。然后，它选择最佳 GPU 来应用视频特效滤镜，然后再调用 NvCVImage_Transfer() 和 NvVFX_Run() 函数来应用滤镜。此步骤避免了为每个视频特效 SDK API 调用保存和恢复 GPU 的需要。

   复制

   已复制！

               
   
               
   // Select the best GPU for each task and perform the task.
   while (!done) {
     ...
     cudaSetDevice(gpuGame);
     RenderGame();
     cudaSetDevice(gpuVFX);
     vfxErr = NvCVImage_Transfer(&srcCPU, &srcGPU, 1.0f, stream, &tmpGPU);
     vfxErr = NvVFX_Run(eff, 1);
     vfxErr = NvCVImage_Transfer(&dstGPU, &dstCPU, 1.0f, stream, &tmpGPU);
     ...
   }
           

   
   

3.5. 使用多实例 GPU（仅限 Linux）

使用视频特效 SDK 开发的应用程序可以部署在受支持设备（例如 NVIDIA DGX™ A100）上的多实例 GPU (MIG) 上。MIG 允许您将设备划分为多个 GPU 实例，最多七个，每个实例都有单独的流式多处理器、单独的 GPU 内存切片以及通往内存的单独路径。此过程确保一个分区上的应用程序的大量资源使用不会影响在其他分区上运行的应用程序的性能。

要在 MIG 分区上运行应用程序，您无需在应用程序中调用任何其他 SDK API。您可以在应用程序调用期间指定要用于执行的 MIG 实例。您可以使用以下选项之一选择 MIG 实例：

• 使用 CUDA_VISIBLE_DEVICES 环境变量的裸机方法。
• 通过使用 NVIDIA Container Toolkit 的容器方法。

  MIG 仅在 Linux 上受支持。

有关使用 MIG 的更多信息，请参阅 NVIDIA 多实例 GPU 用户指南。

当以连续批次提交多个图像时，某些视频特效具有更高的性能。所有视频特效都可以处理批次，无论它们是否具有专门调整的模型。

提交批次与提交图像的不同之处在于：

• 分配批量缓冲区。
• 选择批量模型。
• 设置批量图像。
• 为 NvVFX_Run() 设置批次大小。

4.1. 什么是批次？

在视频特效 SDK 中，批次是包含多个具有相同结构的图像的连续缓冲区。对于某些特效，此过程可以产生比单独提交图像更高的吞吐量。

批次由第一个图像的 NvCVImage 描述符和一个单独的批次大小参数表示，该参数在您运行以下命令时设置

NvVFX_SetU32(effect, NVVFX_BATCH_SIZE, batchSize);

每次调用 NvVFX_Run() 时都会对该值进行采样，这允许批次大小随每次 NvVFX_Run() 调用而更改。

4.2. 批次实用程序

以下是关于可用批次实用程序的一些信息。

BatchUtilities.cpp 中的以下实用程序函数可帮助您处理图像批次：

• AllocateBatchBuffer() 可用于为一批图像分配缓冲区。
• NthImage() 可用于在批量缓冲区中设置第 n 个图像的视图。
• ComputeImageBytes() 可用于确定每个图像的字节数，以便将像素指针从一个图像移动到下一个图像。
• TransferToNthImage() 可以轻松调用 NvCVImage_Transfer() 来设置批次中的一个图像。
• TransferFromNthImage() 可以轻松调用 NvCVImage_Transfer() 以将批次中的一个图像复制到常规图像。
• TransferToBatchImage() 将多个图像从不同位置传输到批量图像。
• TransferFromBatchImage() 可用于将批次中的图像检索到不同位置的不同图像中。
• TransferBatchImage() 将批次中的所有图像传输到另一个兼容的图像批次。

最后三个函数也可以通过重复调用 Nth 图像 API 来完成，但源代码说明了访问批次中图像的另一种方法。

4.3. 批量缓冲区的分配

要分配批量缓冲区，请调用 AllocateBatchBuffer() 函数，该函数将分配一个比原型图像高 N 倍的图像。

此函数的主要目的是提供存储，然后在 NvCVImage 超出范围或调用其析构函数时处理掉此存储。

您可以使用自己的方法来分配批量图像的存储。 AllocateBatchBuffer() 产生的图像仅用于簿记，从不用于任何视频特效 API。

4.4. 选择批量模型

视频特效 SDK 包含多个运行时引擎，这些引擎不仅实现了特效，还经过调整以充分利用特定的 GPU 架构，并且经过优化以同时处理多个输入。

这些多个输入（也称为批次）以及经过优化以同时处理 N 个图像的引擎称为 Batch-N 模型。GPU 架构上的特效可能具有 1 个、2 个或更多个批量模型。

除了效率之外，提交给视频特效的图像批次大小与批量模型的 [最大] 批次大小无关。当图像批次大小是模型批次大小的整数倍时，效率最高。例如，batch-4 模型在传递大小为 4、8、12 等的图像批次时效率最高，尽管您也可以以 3、5、10 甚至 1 的批次大小来馈送模型。

所有特效都附带一个针对单个图像优化的模型，即 batch-1 模型。某些特效可能具有其他模型，可以同时有效地处理大量图像批次。如果您的应用程序可以利用这些较大批次的更高效率，则可以在加载之前指定所需的批量模型。

默认情况下，当调用 NvVFX_Load() 时，会加载 batch-1 模型。要选择另一个模型，请调用

            

            
NvVFX_SetU32(effect, NVVFX_MODEL_BATCH, modelBatch);
        

您可以在其中指定模型批次大小，然后调用

            

            
NvVFX_Load(effect);
        

如果具有您想要的批次大小的模型可用，则返回 NVCV_SUCCESS。否则，将进行适当的替换，并返回 NVCV_ERR_MODELSUBSTITUTION 状态。尽管这可能不是您想要的结果，但会加载针对您指定的批次大小的最有效的批量模型。

随后可以通过运行以下命令查询加载的模型的批次大小

            

            
NvVFX_GetU32(effect, NVVFX_MODEL_BATCH, &modelBatch);
        

要查找可用的模型批次大小，请查询 INFO 字符串。

            

            
NvVFX_GetString(effect, NVVFX_INFO, &infoStr);
        

在编程上，您可以重复调用以下命令并增加大小，直到返回的大小小于请求的大小

            

            
NvVFX_SetU32(effect, NVVFX_MODEL_BATCH, modelBatch);
NvVFX_Load(effect);
NvVFX_GetU32(effect, NVVFX_MODEL_BATCH, &modelBatch);
        

由 NvVFX_GetU32() 返回的值与可用的模型批大小相同。此信息在运行时启动时可能很有用，以最大限度提高吞吐量并最大限度地减少延迟。

NvCV_Load() 是一个重量级操作（秒级），因此我们建议您在服务在线时避免重复调用。上面的代码示例仅是在启动期间或季度性调整期间用于离线查询目的的建议。

4.5. 设置批量图像

以下是关于如何设置批量图像的一些信息。

API 仅获取批次中第一张图像的图像描述符。以下示例分配了 src 和 dst 批处理缓冲区，并通过每个批处理缓冲区中第一张图像的视图设置了输入和输出。

            

            
NvCVImage srcBatch, dstBatch, nthSrc, nthDst;
AllocateBatchBuffer(&srcBatch, batchSize, srcWidth, srcHeight,
                  	...);
AllocateBatchBuffer(&dstBatch, batchSize, dstWidth, dstHeight,
                   	...);
NthImage(0, srcHeight, &srcBatch, &nthSrc);
NthImage(0, dstHeight, &dstBatch, &nthDst);
NvVFX_SetImage(effect, NVVFX_INPUT_IMAGE,  &nthSrc);
NvVFX_SetImage(effect, NVVFX_OUTPUT_IMAGE, &nthDst);
        

由于图像描述符被复制到 Video Effects SDK 中，因此可以简化为以下形式

            

            
NvCVImage srcBatch, dstBatch, nth;
AllocateBatchBuffer(&srcBatch, batchSize, srcWidth, srcHeight,
                    	...);
AllocateBatchBuffer(&dstBatch, batchSize, dstWidth, dstHeight,
                    	...);
NvVFX_SetImage(effect, NVVFX_INPUT_IMAGE,
               	NthImage(0, srcHeight, &srcBatch, &nth));
NvVFX_SetImage(effect, NVVFX_OUTPUT_IMAGE,
               	NthImage(0, dstHeight, &dstBatch, &nth));
        

批次中的其他图像通过将像素指针按每张图像的大小前进进行计算。

设置批量图像的另一个方面是确定如何设置像素值。可以通过调用 NthImage() 函数来访问批次中的每张图像

NthImage(n, imageHeight, &batchImage, &nthImage);

然后，您可以对最近初始化的 nthImage 视图使用与其他 NvCVImages 相同的技术。正如之前建议的那样，NthImage() 只是 NvCVImage_InitView() 的一个薄包装器，可以替代使用。BatchUtilities.cpp 中的 NvVFX_Transfer() 函数可用于将像素复制到批次和从批次复制像素。

4.6. 为 NvVFX_Run() 设置批大小

以下是关于如何为 NvVFX_Run 设置批大小的一些信息。

默认情况下，NvVFX_ Run() 处理的批大小为 1。在调用 NvVFX_Run() 处理任何其他大小的批次之前，请在调用 NvVFX_Run() 之前调用此函数

NvVFX_SetU32(effect, NVVFX_BATCH_SIZE, batchSize);

如前所述，MODEL_BATCH 和 BATCH_SIZE 之间没有关联，除非当 BATCH_SIZE 是 MODEL_BATCH 的整数倍时性能最高。提交批次中的所有图像都将被处理。

4.7. 使用状态变量时进行批处理

本节提供有关使用状态变量进行批处理的信息。

4.7.1. 对于网络摄像头降噪

网络摄像头降噪滤波器使用状态变量来跟踪输入视频流以消除时间噪声。然而，批量输入 srcBatch 可以包含来自多个视频的帧，数量和顺序任意。

当您使用网络摄像头降噪时，在 NvVFX_Run() 之前，您需要完成一些额外的步骤，以提供有关批次中图像的排序和视频源的信息。此过程允许正确跟踪每个输入视频流。

由于一个状态变量跟踪一个视频流，因此您需要

1. 在您的应用程序中，每个视频流创建一个状态变量。

   如果您有 N 个输入视频流，则需要创建 N 个状态变量

   复制

   已复制！

               
   
               
   void* arrayOfStates[N] = {nullptr};
    
   cudaMalloc(&arrayOfStates[0], stateSizeInBytes);  
   cudaMemset(arrayOfStates[0], 0, stateSizeInByte);
   . . .
   . . .
   cudaMalloc(&arrayOfStates[N-1], stateSizeInBytes);
   cudaMemset(arrayOfStates[N-1], 0, stateSizeInByte);
           

   
   

2. 创建一个数组 batchOfStates，以保存一批状态变量的内存地址。

   此数组的大小将等于批大小。

   注意

   批次的大小不必等于输入视频流的数量，并且批次可以包含来自不同视频流的帧，顺序任意。一个批次也可以包含来自同一视频流的多个帧，但它们必须在批次中按时间顺序排列。

   
   

   此数组保存状态变量的地址，顺序与批量输入 srcBatch 中图像的视频源相对应。如果批次中的第 n 个图像来自第 m 个视频流，则此数组中的第 n 个元素将保存第 m 个状态变量的地址。

   例如，假设批大小为 6，并且批量输入 srcBatch 按此顺序包含来自输入流 #N-1、输入流 #q、输入流 #q、输入流 #1、输入流 #p、输入流 #0 的帧。您需要将相应状态变量的地址复制到 batchOfStates 中，并使用 NvVFX_SetObject 将此数组传递给 SDK

   复制

   已复制！

               
   
               
   void* batchOfStates[] = {arrayOfStates[N-1], arrayOfStates[q],
    arrayOfStates[q], arrayOfStates[1],
    arrayOfStates[p], arrayOfStates[0]};
   vfxErr = NvVFX_SetObject(effectHandle, NVVFX_STATE, (void*)batchOfStates);
           

   
   

   根据批大小和/或批次中图像源的顺序是否发生变化，batchOfStates 的大小和内容可以更改，并在每次 NvVFX_Run() 之前使用 NvVFX_SetObject 进行设置。

4.7.1.1. 示例代码

以下是关于 SDK 中示例代码的一些信息。

示例代码位于以下文件中：

• BatchEffectApp.cpp，它提供了功能性示例代码，并包含图像文件列表以及将这些文件作为批次处理的代码。
• BatchDenoiseEffectApp.cpp，它提供了功能性示例代码，用于将批处理与网络摄像头降噪结合使用。

  该代码接受多个视频文件作为输入，并以用户指定大小的批次处理来自输入视频的帧。

4.7.2. AI 绿幕批处理

为了保持时间一致性，AI 绿幕滤波器使用状态变量来跟踪输入视频流。

批量输入 srcBatch 可以包含来自多个视频的帧，数量和顺序任意。但是，当您创建批量输入时，必须满足以下约束条件：

• 批量输入不应包含来自同一视频流的多个帧。
• 来自同一视频流的帧必须按时间顺序在单独的批次中传递。

当您使用 AI 绿幕滤波器时，为了提供有关批次中图像的排序和视频源的信息，在 之前NvVFX_Run()，您需要完成一些额外的步骤。此过程允许正确跟踪每个输入视频流。

通过调用 NvVFX_SetU32() 并使用 NVVFX_MAX_NUMBER_STREAMS 选择器字符串，设置并发输入视频流的最大数量。

            

            
vfxErr = NvVFX_SetU32(effectHandle, NVVFX_MAX_NUMBER_STREAMS, numberOfInputVideoStreams);
        

此设置方法必须在初始化效果的 NvVFX_Load() 方法之前调用。

一个状态变量跟踪一个视频流，因此您需要完成以下步骤

1. 在您的应用程序中，每个视频流创建一个状态变量。如果您有 N 个输入视频流，则需要创建 N 个状态变量。
   复制

   已复制！

               
   
               
   NvVFX_StateObjectHandle stateObjectHandle;
   vfxErr =  NvVFX_AllocateState(effectHandle, &stateObjectHandle);
           

   
   
2. SDK 用户可以通过调用 NvVFX_GetU32 函数和 NVVFX_STATE_COUNT 参数选择器来查询活动状态变量的数量。活动状态变量的数量将分配给提供的参数。
   复制

   已复制！

               
   
               
   vfxErr =  NvVFX_GetU32(effectHandle, NVVFX_STATE_COUNT,
   &numActiveStateVariables);
           

   
   
3. 创建一个数组 batchOfStates，以保存一批状态变量的内存地址。

   此数组的大小将等于批大小。

   注意

   批次的大小应小于或等于输入视频流的数量，因为每个流的批次中只能有一个帧。由于每个批次中视频流的数量不同，因此批次中帧的数量可能因批次而异。

   一个批次可以包含来自不同视频流的帧，顺序任意。

   
   

   此数组保存状态变量的地址，顺序与 srcBatch 中图像的视频源相对应。如果批次中的第 n 个图像来自第 m 个视频流，则此数组中的第 n 个元素将保存第m 个状态变量的地址。

   例如，如果批大小为 5，并且 srcBatch 按此顺序包含来自输入流 #N-1、输入流 #q、输入流 #1、输入流 #p、输入流 #0 的帧。您需要将相应状态变量的地址复制到 batchOfStates 中，并使用 NvVFX_SetObject 将此数组传递给 SDK

   复制

   已复制！

               
   
               
   NvVFX_StateObjectHandle batchOfStates[] = {arrayOfStates[N-1],
                     arrayOfStates[q], arrayOfStates[1],
               	arrayOfStates[p], arrayOfStates[0]};
   vfxErr = NvVFX_SetStateObjectHandleArray(effectHandle, NVVFX_STATE, batchOfStates);
           

   
   

   根据批大小和/或批次中图像源的顺序是否发生变化，batchOfStates 的大小和内容可以更改，并在每次 NvVFX_Run() 之前使用 NvVFX_SetStateObjectHandleArray 函数进行设置。

4.7.2.1. 示例代码

示例代码位于 BatchAigsEffectApp.cpp 文件中，此文件提供了功能性示例代码，允许您将批处理与 AI 绿幕结合使用。

该代码接受多个视频文件作为输入，并以等于视频文件数量的批次处理来自输入视频的帧。

本节提供有关 Video Effects SDK 中 API 的信息。

5.1. 结构体

本节提供有关 Video Effects SDK 中结构体的信息。

Video Effects SDK 中的结构体在以下头文件中定义：

• nvVideoEffects.h
• nvCVImage.h

5.1.1. NvVFX_Handle

以下是关于 NvVFX_Handle 结构体的详细信息。

            

            
typedef struct NvVFX_Object NvVFX_Object, *NvVFX_Handle;
        

此结构体表示与视频效果滤波器的每个实例关联的不透明句柄。它是指向 nvwarpObject 类型不透明对象的指针。大多数视频效果函数调用都包含此句柄作为第一个参数。

定义于 nvVideoEffects.h 中。

5.1.2. NvVFX_Object

以下是关于 NvVFX_Object 结构体的详细信息。

            

            
struct NvVFX_Object;
        

这是指向应用程序分配的不透明数据结构的指针，需要在效果销毁后由应用程序处置。它始终由其指针引用，该指针是 NvVFX_Handle。

定义于：nvVideoEffects.h。

5.1.3. NvVFX_StateObjectHandle

以下是关于 NvVFX_StateObjectHandle 结构体的详细信息。

            

            
typedef struct NvVFX_StateObjectHandleBase *NvVFX_StateObjectHandle;
        

此指针表示与 SDK 效果使用的状态变量的每个实例关联的不透明句柄。NvVFX_AllocateState、NvVFX_DeallocateState、NvVFX_ResetState 和 NvVFX_SetStateObjectHandleArray 函数调用都包含此句柄作为参数。

定义于：nvVideoEffects.h.。

5.1.4. NvVFX_StateObjectHandleBase

以下是关于 NvVFX_StateObjectHandleBase 结构体的详细信息。

            

            
struct NvVFX_StateObjectHandleBase;
        

此结构体表示 SDK 使用的状态变量。

定义于：nvVideoEffects.h.。

5.1.5. NvCVImage

以下是关于 NvCVImage 结构体的详细信息。有关更多信息，请参阅 NvCVImage API 指南。

            

            
typedef struct NvCVImage {
  unsigned int          	width;
  unsigned int          	height;
  unsigned int          	pitch;
  NvCVImage_PixelFormat     pixelFormat;
  NvCVImage_ComponentType   componentType;
  unsigned char         	pixelBytes;
  unsigned char       	componentBytes;
  unsigned char         	numComponents;
  unsigned char         	planar;
  unsigned char         	gpuMem;
  unsigned char         	colorspace;
  unsigned char         	reserved[2];
  void                  	*pixels;
  void                  	*deletePtr;
  void                  	(*deleteProc)(void *p);
  unsigned long long    	bufferBytes;
 
} NvCVImage;
        

成员

width

类型：unsigned int

图像的宽度，以像素为单位。

height

类型：unsigned int

图像的高度，以像素为单位。

pitch

类型：unsigned int

像素之间的垂直字节步幅。

pixelFormat

类型：NvCVImage_PixelFormat

图像中像素的格式。

componentType

类型：NvCVImage_ComponentType

用于表示图像每个分量的数据类型。

pixelBytes

类型：unsigned char

块状像素中的字节数。

componentBytes

类型：unsigned char

每个像素分量中的字节数。

numComponents

类型：unsigned char

每个像素中的分量数。

planar

类型：unsigned char

指定图像中像素的组织方式。

• 0：块状
• 1：平面

gpuMem

类型：unsigned char

指定存储图像数据缓冲区的内存类型。不同类型的内存具有不同的地址空间。

• 0：CPU 内存
• 1：CUDA 内存
• 2：pinned CPU 内存

colorspace

类型：unsigned char

指定 YUV 色彩空间类型的逻辑 OR 组，例如

复制

已复制！

            

            
my422.colorspace = NVCV_709 | NVCV_VIDEO_RANGE | NVCV_CHROMA_COSITED;
        

有关类型定义的更多信息，请参阅 YUV 色彩空间。

始终为 420、422 或 444 YUV 图像设置色彩空间。默认色彩空间为 NVCV_601 | NVCV_VIDEO_RANGE | NVCV_CHROMA_COSITED。

reserved

类型：unsigned char[2]

保留用于填充和未来功能。将此参数设置为 0。

pixels

类型：void

指向图像中像素 (0,0) 的指针。

deletePtr

类型：void

要删除的缓冲区内存（可以为 NULL）。

deleteProc

类型：void

要调用的函数，而不是 free()，以删除像素缓冲区。要调用 free()，请将此参数设置为 NULL。图像分配器对 CPU 缓冲区使用 free()，对 GPU 缓冲区使用 cudaFree()。

bufferBytes

类型：unsigned long long

通过像素可用的最大内存量（以字节为单位）。

备注

此结构体定义了图像缓冲区中图像的属性，该图像缓冲区作为效果滤波器的输入提供。可以使用 setter 函数设置成员，如 NvCVImage API 指南中所述。

定义于：nvCVImage.h。

5.2. 枚举

NVIDIA Video Effects SDK 中的枚举，与像素组织和图像分量数据类型相关，在 nvCVImage.h 头文件中定义。有关更多信息，请参阅 NvCVImage API 指南。

5.3. 类型定义

Video Effects SDK 类型定义为视频效果滤波器和视频效果滤波器的参数提供选择器字符串。

5.3.1. NvVFX_EffectSelector

此类型定义为各种类型的视频效果滤波器提供选择器字符串。

            

            
typedef const char* NvVFX_EffectSelector;
        

NVVFX_FX_TRANSFER "Transfer"

图像传输效果。

此效果以效果的形式提供与 NvCVImage_Transfer() 函数相同的功能。此效果对于匹配效果管线中的格式尤其有用。

NVVFX_FX_GREEN_SCREEN "Green Screen"

AI 绿幕滤波器。

NVVFX_FX_BGBLUR “BackgroundBlur”

背景模糊滤波器。

NVVFX_FX_ARTIFACT_REDUCTION "Artifact Reduction"

基于 AI 的伪影减少

NVVFX_FX_SUPER_RES "Super Res"

基于 AI 的超分辨率

NVVFX_FX_SR_UPSCALE "Upscale"

基于 AI 的快速视频放大器

NVVFX_FX_ARTIFACT_REMOVAL "remove_artifacts"

伪影去除滤波器。

NVVFX_FX_SUPER_RES "super_res_V0"

超分辨率滤波器。

NVVFX_FX_DENOISING "Denoising"

网络摄像头降噪滤波器。

5.3.2. NvVFX_ParameterSelector

此定义类型为视频效果滤波器的参数提供选择器字符串。

            

            
typedef const char* NvVFX_ParameterSelector;
        

NVVFX_INPUT_IMAGE_0 "SrcImage0"

将用作效果输入的 NvCVImage 结构体。

由于没有效果采用多个输入图像，因此此选择器等效于 NVVFX_INPUT_IMAGE。

NVVFX_OUTPUT_IMAGE_0 "DstImage0"

将用作效果输出的 NvCVImage 结构体。

由于没有效果具有多个输出图像，因此此选择器等效于 NVVFX_OUTPUT_IMAGE。

NVVFX_MODEL_DIRECTORY "ModelDir"

包含将用于转换的模型文件的文件夹路径。

NVVFX_CUDA_STREAM "CudaStream"

运行视频效果滤波器的 CUDA 流。

NVVFX_CUDA_GRAPH “CudaGraph”

启用 CUDA 图优化。

NVVFX_INFO "Info"

获取有关视频效果滤波器及其参数的信息。

NVVFX_MAX_INPUT_WIDTH "MaxInputWidth"

支持的最大输入宽度。

NVVFX_MAX_INPUT_HEIGHT "MaxInputHeight"

支持的最大输入高度。

NVVFX_MAX_NUMBER_STREAMS "MaxNumberStreams"

并发输入流的最大数量。

NVVFX_SCALE "Scale"

缩放因子。这用于在传输期间缩放图像的值，以匹配效果管线中的格式。

NVVFX_STRENGTH "Strength"

使用此参数的滤波器的强度。强度越高，效果越强。

NVVFX_STRENGTH_LEVELS "StrengthLevels"

区间 [0, 1] 中唯一强度级别的数量。目前，这仅适用于网络摄像头降噪滤波器，设置为 2，这意味着两个强度级别为 0 或 1。

NVVFX_MODE "Mode"

AI 绿幕、伪影分辨率和超分辨率滤波器的模式。

• 0：质量模式
• 1：性能模式

NVVFX_TEMPORAL "Temporal"

应用时间滤波。

NVVFX_GPU "GPU"

要使用的首选 GPU。这是一个可选参数。

NVVFX_BATCH_SIZE "BatchSize"

提供给滤波器的输入批次的大小。默认值为 1。

NVVFX_MODEL_BATCH "ModelBatch"

要使用的首选批处理模型，该模型针对批大小为 1 或 8 进行了调整。这仅适用于 AI 绿幕滤波器。

NVVFX_STATE "State"

状态变量数组。

NVVFX_STATE_SIZE "StateSize"

存储状态变量所需的字节数。

NVVFX_STATE_COUNT "NumStateObjects"

活动状态对象句柄的数量。

5.4. 视频效果函数

视频效果函数在 nvVideoEffects.h 头文件中定义。视频效果 API 是面向对象的，但 C 和 C++ 都可以访问。

5.4.1. NvVFX_CreateEffect

以下是关于 NvVFX_CreateEffect 函数的详细信息。

            

            
NvCV_Status NvVFX_CreateEffect(
  NvVFX_EffectSelector code,
..NvVFX_Handle *obj
);
        

参数

code [in]

类型：NvVFX_EffectSelector

要创建的视频效果滤波器类型的选择字符串。有关允许的选择字符串的更多信息，请参阅 NvVFX_EffectSelector。

obj [out]

类型：NvVFX_Handle *

用于存储新创建的视频效果滤波器实例句柄的位置。

返回值

NVCV_SUCCESS 成功时

备注

此函数创建指定类型的视频效果滤波器实例。该函数将视频效果滤波器实例的句柄写入 out obj 参数。

5.4.2. NvVFX_CudaStreamCreate

以下是关于 NvVFX_CudaStreamCreate 函数的详细信息。

            

            
NvCV_Status NvVFX_CudaStreamCreate(
  CUstream *stream
);
        

参数

stream [out]

类型：CUstream *

用于存储新分配的 CUDA 流的位置。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_CUDA_VALUE 如果 CUDA 参数不在其可接受的范围内。

备注

此函数创建 CUDA 流。它是 CUDA 运行时 API 函数 cudaStreamCreate() 的包装器，您可以使用它来避免与 NVIDIA CUDA Toolkit 库链接。此函数和 cudaStreamCreate() 是等效且可互换的。

5.4.3. NvVFX_CudaStreamDestroy

以下是关于 NvVFX_CudaStreamDestroy 函数的详细信息。

            

            
void NvVFX_CudaStreamDestroy(
  CUstream stream
);
        

参数

stream [in]

类型：CUstream

要销毁的 CUDA 流。

返回值

不返回值。

备注

此函数销毁 CUDA 流。它是 CUDA 运行时 API 函数 cudaStreamDestroy() 的包装器，您可以使用它来避免与 NVIDIA CUDA Toolkit 库链接。此函数和 cudaStreamDestroy() 是等效且可互换的。

5.4.4. NvVFX_DestroyEffect

以下是关于 NvVFX_DestroyEffect 函数的详细信息。

            

            
void NvVFX_DestroyEffect(
  NvVFX_Handle obj
);
        

参数

obj [in]

类型：NvVFX_Handle

要销毁的视频效果滤波器实例的句柄。

返回值

不返回值。

备注

此函数销毁具有指定句柄的视频效果滤波器实例，并释放为其分配的资源和内存。

5.4.5. NvVFX_GetCudaStream

以下是关于 NvVFX_GetCudaStream 函数的详细信息。

            

            
NvCV_Status NvVFX_GetCudaStream(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  CUstream *stream
);
        

参数

obj

类型：NvVFX_Handle

您要从中获取 CUDA 流的视频效果滤波器实例的句柄。

paramName

类型：NvVFX_ParameterSelector

NVVFX_CUDA_STREAM 选择器字符串。任何其他选择器字符串都会返回错误。

stream

类型：CUstream *

指向将在其中写入检索到的 CUDA 流的 CUDA 流的指针。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数获取指定的视频效果滤波器将在其中运行的 CUDA 流，并将检索到的 CUDA 流写入参数 stream 指定的位置。

5.4.6. NvCV_GetErrorStringFromCode

以下是关于 NvCV_GetErrorStringFromCode 函数的详细信息。

            

            
NvCV_GetErrorStringFromCode(NvCV_Status code);
        

参数

code

类型：NvCV_Status

要获取错误字符串的 NvCV_Status 代码。

返回值

与指定的错误代码对应的错误字符串。

备注

此函数获取与 code 参数指定的状态代码对应的错误字符串。

5.4.7. NvVFX_GetF32

以下是关于 NvVFX_GetF32 函数的详细信息。

            

            
NvCV_Status NvVFX_GetF32(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  float *val
);
        

参数

obj

类型：NvVFX_Handle

您要从中获取指定的 32 位浮点参数的视频效果滤波器实例的句柄。

paramName

类型：NvVFX_ParameterSelector

NVVFX_SCALE 或 NVVFX_STRENGTH 选择器字符串。任何不相关的选择器字符串都会返回错误。

val

类型：float *

指向将在其中写入检索到的值的浮点数的指针。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数获取指定视频效果滤波器的指定单精度（32 位）浮点参数的值，并将检索到的值写入 val 参数指定的位置。

5.4.8. NvVFX_GetF64

以下是关于 NvVFX_GetF64 函数的详细信息。

            

            
NvVFX_Status NvVFX_GetF64(
NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  double *val
);
        

参数

obj

类型：NvVFX_Handle

您要从中获取指定的 64 位浮点参数的视频效果滤波器实例的句柄。

paramName

类型：NvVFX_ParameterSelector

您要获取的 64 位浮点参数的选择器字符串。

val

类型：double *

指向将在其中写入检索到的值的双精度浮点数的指针。

返回值

• NVCV_SUCCESS 成功时。
• NVVFX_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• NVVFX_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数获取指定视频效果滤波器的指定双精度（64 位）浮点参数的值，并将检索到的值写入 val 参数指定的位置。

5.4.9. NvVFX_GetImage

以下是关于 NvVFX_GetImage 函数的详细信息。

            

            
NvCV_Status NvVFX_GetImage(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  NvCVImage *im
);
        

参数

obj

类型：NvVFX_Handle

您要从中获取指定的图像缓冲区的视频效果滤波器实例的句柄。

paramName

类型：NvVFX_ParameterSelector

您要获取的图像缓冲区的以下选择器字符串之一：

• NVVFX_INPUT_IMAGE_0
• NVVFX_INPUT_IMAGE
• NVVFX_OUTPUT_IMAGE_0
• NVVFX_OUTPUT_IMAGE

任何其他选择器字符串都会返回错误。

im

类型：NvCVImage *

指向空 NvCVImage 结构的指针，其中将写入请求的图像的视图。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数获取指定视频效果滤波器的指定输入或输出图像描述符，并将其写入 im 参数指定的位置。检索到的图像描述符是先前调用 NvVFX_SetImage() 中提供的描述符的副本。如果之前没有使用相同的选择器调用 NvVFX_SetImage()，则 im 指定的位置将填充零。当提供的 NvCVImage 对象超出范围时，缓冲区不会被释放。

5.4.10. NvVFX_GetObject

以下是关于 NvVFX_GetObject 函数的详细信息。

            

            
NvVFX_Status NvVFX_GetObject(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  void **ptr
);
        

参数

obj

类型：NvVFX_Handle

您要从中获取指定的对象的视频效果滤波器实例的句柄。

paramName

类型：NvVFX_ParameterSelector

您要获取的对象参数的选择器字符串。

ptr

类型：void **

指向将在其中写入检索到的对象的对象地址的指针。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数获取指定视频效果滤波器的指定对象，并将检索到的对象写入 ptr 参数指定的位置。

5.4.11. NvVFX_GetS32

以下是关于 NvVFX_GetS32 函数的详细信息。

            

            
NvVFX_Status NvVFX_GetS32(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  int *val
);
        

参数

obj

类型：NvVFX_Handle

您要从中获取指定的 32 位有符号整数参数的视频效果滤波器实例的句柄。

paramName

类型：NvVFX_ParameterSelector

您要获取的 32 位有符号整数参数的选择器字符串。

val

类型：int *

指向将在其中写入检索到的值的 32 位有符号整数的指针。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数获取指定视频效果滤波器的指定 32 位有符号整数参数的值，并将检索到的值写入 val 参数指定的位置。

5.4.12. NvVFX_GetString

以下是关于 NvVFX_GetString 函数的详细信息。

            

            
NvCV_Status NvVFX_GetString(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  const char **str
);
        

参数

obj

类型：NvVFX_Handle

要从中获取指定字符串参数的视频效果滤镜实例的句柄。要获取可用效果的列表，请将 obj 参数设置为 NULL，并将 paramName 参数设置为 NVVFX_INFO。

paramName

类型：NvVFX_ParameterSelector

您要获取的字符串参数的以下选择器字符串之一：

• NVVFX_INFO
• NVVFX_MODEL_DIRECTORY

任何其他选择器字符串都会返回错误。

str

类型：const char **

将存储请求的字符串指针的地址。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数获取指定视频效果滤镜的指定字符串参数的值或相关信息，并将检索到的字符串写入 str 参数指定的位置。

5.4.13. NvVFX_GetU32

以下是有关 NvVFX_GetU32 函数的详细信息。

            

            
NvCV_Status NvVFX_GetU32(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector
  paramName,
  unsigned int *val
);
        

参数

obj

类型：NvVFX_Handle

要从中获取指定 32 位无符号整数参数的视频效果滤镜实例的句柄。

paramName

类型：NvVFX_ParameterSelector

NVVFX_MODE 或 NVVFX_STRENGTH 或 NVVFX_TEMPORAL 或 NVVFX_GPU 或 NVVFX_BATCH_SIZE 或 NVVFX_MODEL_BATCH 选择器字符串。任何不相关的选择器字符串都会返回错误。

val

类型：unsigned int *

指向将写入检索值的 32 位无符号整数的指针。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数获取指定视频效果滤镜的指定 32 位无符号整数参数的值，并将检索到的值写入 val 参数指定的位置。

5.4.14. NvVFX_GetU64

以下是有关 NvVFX_GetU64 函数的详细信息。

            

            
NvVFX_Status NvVFX_GetU64(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  unsigned long long *val
);
        

参数

obj

类型：NvVFX_Handle

要从中获取指定 64 位无符号整数参数的视频效果滤镜实例的句柄。

paramName

类型：NvVFX_ParameterSelector

您要获取的 64 位无符号整数参数的选择器字符串。

val

类型：unsigned long long *

指向将写入检索值的 64 位无符号整数的指针。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数获取指定视频效果滤镜的指定 64 位无符号整数参数的值，并将检索到的值写入 val 参数指定的位置。

5.4.15. NvVFX_Load

以下是有关 NvVFX_Load 函数的详细信息。

            

            
NvCV_Status NvVFX_Load(
  NvVFX_Handle obj
);
        

参数

obj [in]

类型：NvVFX_Handle

要加载的视频效果滤镜实例的句柄。

返回值

NVCV_SUCCESS 成功时

备注

此函数加载指定的视频效果滤镜并验证为该滤镜设置的参数。

5.4.16. NvVFX_Run

以下是有关 NvVFX_Run 函数的详细信息。

            

            
NvCV_Status NvVFX_Run(
  NvVFX_Handle obj,
  int async
);
        

参数

obj [in]

类型：NvVFX_Handle

将要运行的视频效果滤镜实例的句柄。

async [in]

一个整数值，用于指定滤镜是以异步方式还是同步方式运行。

以下是这些值：

• 1：滤镜以异步方式运行。
• 0：滤镜以同步方式运行。

返回值

NVCV_SUCCESS 成功时

备注

此函数通过读取输入 GPU 缓冲区的内容、应用视频效果滤镜并将输出写入输出 GPU 缓冲区来运行指定的视频效果滤镜。

5.4.17. NvVFX_SetCudaStream

以下是有关 NvVFX_SetCudaStream 函数的详细信息。

            

            
NvCV_Status NvVFX_SetCudaStream(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  CUstream stream
);
        

参数

obj

类型：NvVFX_Handle

您要为其设置 CUDA 流的视频效果滤镜实例的句柄。

paramName

类型：NvVFX_ParameterSelector

NVVFX_CUDA_STREAM 选择器字符串。任何其他选择器字符串都会返回错误。

stream

类型：CUstream

将为其设置参数的 CUDA 流。

返回值

• NVCV_SUCCESS，如果成功。
• NVCV_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数将指定的视频效果滤镜将在其中运行的 CUDA 流设置为参数流。

5.4.18. NvVFX_AllocateState

以下是有关 NvVFX_AllocateState 函数的详细信息。

            

            
NvCV_Status NvVFX_AllocateState(
  NvVFX_Handle obj,
  NvVFX_StateObjectHandle *handle
);
        

参数

obj

类型：NvVFX_Handle

要从中创建状态变量的视频效果滤镜实例的句柄。

handle

类型：NvVFX_StateObjectHandle

这是 SDK 用于返回状态变量句柄的指针。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数分配一个状态变量，并返回指定视频效果滤镜的句柄。

5.4.19. NvVFX_DeallocateState

以下是有关 NvVFX_DeallocateState 函数的详细信息。

            

            
NvCV_Status NvVFX_DeallocateState(
  NvVFX_Handle obj,
  NvVFX_StateObjectHandle handle
);
        

参数

obj

类型：NvVFX_Handle

要从中创建状态变量的视频效果滤镜实例的句柄。

handle

类型：NvVFX_StateObjectHandle

这是 SDK 用于返回状态变量句柄的指针。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。
• 当提供的句柄不是由滤镜实例分配的时，返回 NVCV_ERR_OBJECTNOTFOUND。

备注

此函数释放一个状态变量。

5.4.20. NvVFX_ResetState

以下是有关 NvVFX_ResetState 函数的详细信息。

            

            
NvCV_Status NvVFX_ResetState(
  NvVFX_Handle obj,
  NvVFX_StateObjectHandle handle
);
        

参数

obj

类型：NvVFX_Handle

拥有第二个参数表示的状态变量的视频效果滤镜实例的句柄。

handle

类型：NvVFX_StateObjectHandle

这是状态变量的句柄。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。
• 当提供的句柄不是由滤镜实例分配的时，返回 NVCV_ERR_OBJECTNOTFOUND。

备注

此函数重置一个状态变量。

5.4.21. NvVFX_SetF32

以下是有关 NvVFX_SetF32 函数的详细信息。

            

            
NvCV_Status NvVFX_SetF32(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  float val
);
        

参数

obj

类型：NvVFX_Handle

您要为其设置指定 32 位浮点参数的视频效果滤镜实例的句柄。

paramName

类型：NvVFX_ParameterSelector

NVVFX_SCALE 或 NVVFX_STRENGTH 选择器字符串。任何不相关的选择器字符串都会返回错误。

val

类型：float

将为其设置参数的浮点数。

返回值

• NVCV_SUCCESS 成功时。
• 当 obj 参数指定的视频效果滤镜实例无法解析 paramName 参数指定的选择器字符串或选择器字符串指定的参数数据类型时，返回 NVCV_ERR_SELECTOR。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数将指定视频效果滤镜的指定单精度（32 位）浮点参数设置为 val 参数。

5.4.22. NvVFX_SetF64

以下是有关 NvVFX_SetF64 函数的详细信息。

            

            
NvVFX_Status NvVFX_SetF64(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  double val
);
        

参数

obj

类型：NvVFX_Handle

您要为其设置指定 64 位浮点参数的视频效果滤镜实例的句柄。

paramName

类型：NvVFX_ParameterSelector

您要设置的 64 位浮点参数的选择器字符串。

val

类型：double

将为其设置参数的双精度浮点数。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数将指定视频效果滤镜的指定双精度（64 位）浮点参数设置为 val 参数。

5.4.23. NvVFX_SetImage

以下是有关 NvVFX_SetImage 函数的详细信息。

            

            
NvCV_Status NvVFX_SetImage(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  NvCVImage *im
);
        

参数

obj

类型：NvVFX_Handle

您要为其设置指定图像缓冲区的视频效果滤镜实例的句柄。

paramName

类型：NvVFX_ParameterSelector

您要设置的图像缓冲区的以下选择器字符串之一：

• NVVFX_INPUT_IMAGE_0
• NVVFX_INPUT_IMAGE
• NVVFX_OUTPUT_IMAGE_0
• NVVFX_OUTPUT_IMAGE

任何其他选择器字符串都会返回错误。

im

类型：NvCVImage *

指向将为其设置参数的 NvCVImage 对象的指针。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数将指定视频效果滤镜的指定输入或输出图像缓冲区设置为 im 参数。

5.4.24. NvVFX_SetObject

以下是有关 NvVFX_SetObject 函数的详细信息。

            

            
NvVFX_Status NvVFX_SetObject(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  void *ptr
);
        

参数

obj

类型：NvVFX_Handle

您要为其设置指定对象的视频效果滤镜实例的句柄。

paramName

类型：NvVFX_ParameterSelector

您要设置的对象参数的选择器字符串。

ptr

类型：void *

指向将为其设置对象参数的对象的指针。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数将指定视频效果滤镜的指定对象设置为 ptr 参数。

5.4.25. NvVFX_SetStateObjectHandleArray

以下是有关 NvVFX_SetStateObjectHandleArray 函数的详细信息。

            

            
NvVFX_Status NvVFX_SetStateObjectHandleArray(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  NvVFX_StateObjectHandle* handle
);
        

参数

obj

类型：NvVFX_Handle

视频效果滤镜实例的句柄。

paramname

类型：NvVFX_ParameterSelector

您要设置的对象参数的选择器字符串：NVVFX_STATE。

类型：NvVFX_StateObjectHandle

指向状态对象数组的指针。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• 当提供了意外的 NULL 指针时，返回 NVCV_ERR_OBJECTNOTFOUND。

备注

此函数将指定视频效果滤镜的指定对象设置为句柄参数。

5.4.26. NvVFX_SetS32

以下是有关 NvVFX_SetS32 函数的详细信息。

            

            
NvVFX_Status NvVFX_SetS32(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  int val
);
        

参数

obj

类型：NvVFX_Handle

您要为其设置指定 32 位有符号整数参数的视频效果滤镜实例的句柄。

paramName

类型：NvVFX_ParameterSelector

您要设置的 32 位有符号整数参数的选择器字符串。

val

类型：int

将为其设置参数的 32 位有符号整数。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数将指定视频效果的指定 32 位有符号整数参数的值设置为 val 参数。

5.4.27. NvVFX_SetString

以下是有关 NvVFX_SetString 函数的详细信息。

            

            
NvCV_Status NvVFX_SetString(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  const char *str
);
        

参数

obj

类型：NvVFX_Handle

您要为其设置指定字符串参数的视频效果滤镜实例的句柄。

paramName

类型：NvVFX_ParameterSelector

NVVFX_MODEL_DIRECTORY 选择器字符串。任何其他选择器字符串都会返回错误。

str

类型：const char *

指向您要为其设置参数的字符串的指针。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数将指定视频效果滤镜的指定字符串参数的值设置为 str 参数。

5.4.28. NvVFX_SetU32

以下是有关 NvVFX_SetU32 函数的详细信息。

            

            
NvCV_Status NvVFX_SetU32(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  unsigned int val
);
        

参数

obj

类型：NvVFX_Handle

您要为其设置指定 32 位无符号整数参数的视频效果滤镜实例的句柄。

paramName

类型：NvVFX_ParameterSelector

NVVFX_MODE 或 NVVFX_STRENGTH 或 NVVFX_TEMPORAL 或 NVVFX_GPU 或 NVVFX_BATCH_SIZE 或 NVVFX_MODEL_BATCH 选择器字符串。任何不相关的选择器字符串都会返回错误。

val

类型：unsigned int

您要为其设置参数的 32 位无符号整数。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数将指定视频效果滤镜的指定 32 位无符号整数参数的值设置为 val 参数。

5.4.29. NvVFX_SetU64

以下是有关 NvVFX_SetU64 函数的详细信息。

            

            
NvVFX_Status NvVFX_SetU64(
  NvVFX_Handle obj,
  NvVFX_ParameterSelector paramName,
  unsigned long long val
);
        

参数

obj

类型：NvVFX_Handle

您要为其设置指定 64 位无符号整数参数的视频效果滤镜实例的句柄。

paramName

类型：NvVFX_ParameterSelector

您要设置的 64 位无符号整数参数的选择器字符串。

val

类型：unsigned long long

您要为其设置参数的 64 位无符号整数。

返回值

• NVCV_SUCCESS 成功时。
• NVCV_ERR_SELECTOR 当 obj 参数指定的视频效果滤波器实例无法解析 paramName 参数指定的选择器字符串，或选择器字符串指定的参数数据类型时。
• NVCV_ERR_PARAMETER 当提供了意外的 NULL 指针时。

备注

此函数将指定视频效果滤镜的指定 64 位无符号整数参数的值设置为 val 参数。

5.5. 返回值

NvCV_Status 枚举定义了视频效果函数可能返回的以下值，以指示错误或成功。

NVCV_SUCCESS = 0

成功执行。

NVCV_ERR_GENERAL

通用错误代码，指示函数由于未指定的原因而执行失败。

NVCV_ERR_UNIMPLEMENTED

请求的功能未实现。

NVCV_ERR_MEMORY

请求的操作需要的内存超出可用内存。

NVCV_ERR_EFFECT

已提供无效的效果句柄。

NVCV_ERR_SELECTOR

指定的选择器对此效果滤镜无效。

NVCV_ERR_BUFFER

未指定图像缓冲区。

NVCV_ERR_PARAMETER

为此效果和选择器字符串组合提供了无效的参数值。

NVCV_ERR_MISMATCH

某些参数（例如，图像格式或图像尺寸）未正确匹配。

NVCV_ERR_PIXELFORMAT

不支持指定的像素格式。

NVCV_ERR_MODEL

加载 TRT 模型时发生错误。

NVCV_ERR_LIBRARY

加载动态库时出错。

NVCV_ERR_INITIALIZATION

效果未正确初始化。

NVCV_ERR_FILE

找不到指定的文件。

NVCV_ERR_FEATURENOTFOUND

找不到请求的功能。

NVCV_ERR_MISSINGINPUT

未设置必需的参数。

NVCV_ERR_RESOLUTION

不支持指定的图像分辨率。

NVCV_ERR_UNSUPPORTEDGPU

不支持 GPU。

NVCV_ERR_WRONGGPU

当前 GPU 不是所选的 GPU。

NVCV_ERR_UNSUPPORTEDDRIVER

当前安装的图形驱动程序不受支持。

NVCV_ERR_MODELDEPENDENCIES

没有与此系统匹配的具有依赖项的模型。

NVCV_ERR_PARSE

读取文件时出现了解析或语法错误。

NVCV_ERR_MODELSUBSTITUTION

指定的模型不存在并且已被替换。

NVCV_ERR_READ

读取文件时发生错误。

NVCV_ERR_WRITE

写入文件时发生错误。

NVCV_ERR_PARAMREADONLY

选定的参数为只读。

NVCV_ERR_TRT_ENQUEUE

TensorRT 入队失败。

NVCV_ERR_TRT_BINDINGS

意外的 TensorRT 绑定。

NVCV_ERR_TRT_CONTEXT

创建 TensorRT 上下文时发生错误。

NVCV_ERR_TRT_INFER

创建推理引擎时出现问题。

NVCV_ERR_TRT_ENGINE

反序列化推理运行时引擎时出现问题。

NVCV_ERR_NPP

NPP 库中发生错误。

NVCV_ERR_CONFIG

对于指定的参数配置，不存在合适的模型。

NVCV_ERR_TOOSMALL

提供的参数或缓冲区不够大。

NVCV_ERR_TOOBIG

提供的参数太大。

NVCV_ERR_WRONGSIZE

提供的参数大小不是预期的大小。

NVCV_ERR_OBJECTNOTFOUND

找不到指定的对象。

NVCV_ERR_SINGULAR

遇到了数学奇点。

NVCV_ERR_NOTHINGRENDERED

在指定的区域中未渲染任何内容。

NVCV_ERR_OPENGL

发生了 OpenGL 错误。

NVCV_ERR_DIRECT3D

发生了 Direct3D 错误。

NVCV_ERR_CUDA_MEMORY

请求的操作需要的 CUDA 内存超出可用内存。

NVCV_ERR_CUDA_VALUE

CUDA 参数不在其可接受的范围内。

NVCV_ERR_CUDA_PITCH

CUDA pitch 不在其可接受的范围内。

NVCV_ERR_CUDA_INIT

无法初始化 CUDA 驱动程序和运行时。

NVCV_ERR_CUDA_LAUNCH

CUDA 内核启动失败。

NVCV_ERR_CUDA_KERNEL

没有适用于该设备的合适内核映像。

NVCV_ERR_CUDA_DRIVER

安装的 NVIDIA CUDA 驱动程序比 CUDA 运行时库旧。

NVCV_ERR_CUDA_UNSUPPORTED

当前系统或设备不支持 CUDA 操作。

NVCV_ERR_CUDA_ILLEGAL_ADDRESS

CUDA 尝试加载或存储无效的内存地址。

NVCV_ERR_CUDA

发生了未指定的 CUDA 错误。

还有许多其他与 CUDA 相关的错误未在此处列出。但是，NvCV_GetErrorStringFromCode() 函数会将错误代码转换为字符串，以帮助您进行调试。

声明

本文档仅供参考，不得视为对产品的特定功能、条件或质量的保证。NVIDIA Corporation（“NVIDIA”）不对本文档中包含的信息的准确性或完整性做出任何明示或暗示的陈述或保证，并且对本文档中包含的任何错误不承担任何责任。NVIDIA 对因使用此类信息而造成的后果或使用，或因其使用而可能导致的侵犯第三方专利或其他权利的行为不承担任何责任。本文档不承诺开发、发布或交付任何材料（在下文中定义）、代码或功能。

NVIDIA 保留随时修改、增强、改进本文档以及对其进行任何其他更改的权利，恕不另行通知。

客户在下订单之前应获取最新的相关信息，并应验证此类信息是否为最新且完整。

NVIDIA 产品的销售受 NVIDIA 在订单确认时提供的标准销售条款和条件（“销售条款”）的约束，除非 NVIDIA 和客户的授权代表签署的单独销售协议另有约定（“销售条款”）。NVIDIA 在此明确反对将任何客户通用条款和条件应用于购买本文档中引用的 NVIDIA 产品。本文档未直接或间接形成任何合同义务。

NVIDIA 产品并非设计、授权或保证适用于医疗、军事、航空、航天或生命维持设备，也不适用于 NVIDIA 产品的故障或失灵可能合理预期会导致人身伤害、死亡或财产或环境损害的应用。对于在任何此类设备或应用中包含和/或使用 NVIDIA 产品，NVIDIA 不承担任何责任，因此，此类包含和/或使用由客户自行承担风险。

NVIDIA 不保证或声明基于本文档的产品将适用于任何特定用途。NVIDIA 不一定会执行每个产品的所有参数的测试。客户全权负责评估和确定本文档中包含的任何信息的适用性，确保产品适合并满足客户计划的应用，并为应用执行必要的测试，以避免应用或产品的默认设置。客户产品设计中的缺陷可能会影响 NVIDIA 产品的质量和可靠性，并可能导致超出本文档中包含的额外或不同的条件和/或要求。NVIDIA 对可能基于或归因于以下原因的任何默认设置、损坏、成本或问题不承担任何责任：（i）以任何违反本文档的方式使用 NVIDIA 产品，或（ii）客户产品设计。

本文档未授予 NVIDIA 专利权、版权或其他 NVIDIA 知识产权下的任何明示或暗示的许可。NVIDIA 发布的有关第三方产品或服务的信息不构成 NVIDIA 授予使用此类产品或服务的许可，也不构成对其的保证或认可。使用此类信息可能需要获得第三方专利或其他知识产权下的第三方许可，或获得 NVIDIA 专利或其他 NVIDIA 知识产权下的 NVIDIA 许可。

只有在 NVIDIA 事先书面批准的情况下，才允许复制本文档中的信息，复制时不得进行更改，且必须完全遵守所有适用的出口法律和法规，并且附带所有相关的条件、限制和声明。

本文档和所有 NVIDIA 设计规范、参考板、文件、图纸、诊断程序、列表和其他文档（统称为“材料”，单独称为“材料”）均按“原样”提供。NVIDIA 不对材料做出任何明示、暗示、法定或其他形式的保证，并且明确声明不承担所有关于不侵权、适销性和特定用途适用性的暗示保证。在法律未禁止的范围内，在任何情况下，NVIDIA 均不对因使用本文档而引起的任何损害（包括但不限于任何直接、间接、特殊、偶然、惩罚性或后果性损害，无论因何种原因造成，也无论责任理论如何）承担任何责任，即使 NVIDIA 已被告知可能发生此类损害。尽管客户可能因任何原因而遭受任何损害，但 NVIDIA 对本文所述产品的客户的累计总责任应根据产品的销售条款进行限制。

VESA DisplayPort

DisplayPort 和 DisplayPort Compliance Logo、DisplayPort Compliance Logo for Dual-mode Sources 以及 DisplayPort Compliance Logo for Active Cables 是视频电子标准协会在美国和其他国家/地区拥有的商标。

HDMI

HDMI、HDMI 标志和 High-Definition Multimedia Interface 是 HDMI Licensing LLC 的商标或注册商标。

OpenCL

OpenCL 是 Apple Inc. 的商标，已获得 Khronos Group Inc. 的许可使用。

商标

NVIDIA、NVIDIA 标志以及 cuBLAS、CUDA、CUDA Toolkit、cuDNN、DALI、DIGITS、DGX、DGX-1、DGX-2、DGX Station、DLProf、GPU、JetPack、Jetson、Kepler、Maxwell、NCCL、Nsight Compute、Nsight Systems、NVCaffe、NVIDIA Ampere GPU 架构、NVIDIA Deep Learning SDK、NVIDIA Developer Program、NVIDIA GPU Cloud、NVLink、NVSHMEM、PerfWorks、Pascal、SDK Manager、T4、Tegra、TensorRT、TensorRT Inference Server、Tesla、TF-TRT、Triton Inference Server、Turing 和 Volta 是 NVIDIA Corporation 在美国和其他国家/地区的商标和/或注册商标。其他公司和产品名称可能是与其关联的各自公司的商标。