Use a Video Effect Filter#

Using a video effect filter involves creating the filter, setting up various properties of the filter, and then loading, running, and destroying the filter.

Creating a Video Effect Filter#

Call the NvVFX_CreateEffect() function, specifying the following information as parameters:

  • The NvVFX_EffectSelector type. Refer to NvVFX_EffectSelector for more information.

  • The location in which to store the handle to the newly created video effect filter.

The NvVFX_CreateEffect() function creates a handle to the video effect filter instance for use in further API calls.

To create an instance of the AI green screen feature type, at the top of your source file, include the feature header file:

#include "nvVFXGreenScreen.h"

To create the video effect filter instance:

NvCV_Status vfxErr = NvVFX_CreateEffect(NVVFX_FX_GREEN_SCREEN, &effectHandle);

Each NvVFX_EffectSelector identifier is defined under the respective feature header, e.g. nvVFXGreenScreen.h. Please make sure that the requested feature is installed so that the SDK has access to both feature libraries and required model files.

Note that during NvVFX_CreateEffect, the SDK will load the feature library from the location <vfx-sdk>/features/<feature>/<bin/lib>. Without a feature installation, the call to this API function will return an error code.

Please refer to the installation guide for instructions on how to install features.

Setting the Path to the Model Folder#

A video effect filter requires a neural network model for transforming the input still or video image. You must set the path to the folder that contains the files that describe the model to be used by the filter.

Call the NvVFX_SetString() function, specifying the following information as parameters:

  • The filter handle that was created as explained in Creating a Video Effect Filter.

  • The selector string NVVFX_MODEL_DIRECTORY.

  • A null-terminated string that indicates the path to the model folder.

This example sets the path to the model folder to C:\Users\vfxuser\Documents\vfx\models:

const char* modelDir="C:\Users\vfxuser\Documents\vfx\models";

...

vfxErr = NvVFX_SetString(effectHandle, NVVFX_MODEL_DIRECTORY, modelDir);

Setting Up the CUDA Stream#

A video effect filter requires an NVIDIA CUDA® stream in which to run. For information about CUDA streams, refer to the NVIDIA CUDA Toolkit Documentation.

  1. Initialize a CUDA stream by calling one of the following functions.

    • The CUDA Runtime API function cudaStreamCreate().

    • The NvVFX_CudaStreamCreate() function to avoid linking with the NVIDIA CUDA Toolkit libraries.

  2. Call the NvVFX_SetCudaStream() function, providing the following information as parameters:

    • The filter handle that was created as explained in Creating a Video Effect Filter.

    • The selector string NVVFX_CUDA_STREAM.

    • The CUDA stream that you created in the previous step.

This example sets up a CUDA stream that was created by calling the NvVFX_CudaStreamCreate() function.