Video Effects Functions#

The Video Effects functions are defined in the nvVideoEffects.h header file. The Video Effects API is object-oriented but is accessible to C and C++.

NvVFX_CreateEffect#

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

Parameters#

code [in]

Type: NvVFX_EffectSelector

The selection string for the type of video effect filter to be created. Refer to NvVFX_EffectSelector for more information about the allowed selection strings.

obj [out]

Type: NvVFX_Handle *

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

Return Value#

  • NVCV_SUCCESS on success.

Remarks#

This function creates an instance of the specified type of video effect filter. The function writes a handle to the video effect filter instance to the out parameter obj.

NvVFX_CudaStreamCreate#

NvCV_Status NvVFX_CudaStreamCreate(
  CUstream *stream
);

Parameters#

stream [out]

Type: CUstream *

The location in which to store the newly allocated CUDA stream.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_CUDA_VALUE if a CUDA parameter is not within its acceptable range.

Remarks#

This function creates a CUDA stream. It is a wrapper for the CUDA Runtime API function cudaStreamCreate() that you can use to avoid linking with the NVIDIA CUDA Toolkit libraries. This function and cudaStreamCreate() are equivalent and interchangeable.

NvVFX_CudaStreamDestroy#

void NvVFX_CudaStreamDestroy(
  CUstream stream
);

Parameters#

stream [in]

Type: CUstream

The CUDA stream to destroy.

Return Value#

Does not return a value.

Remarks#

This function destroys a CUDA stream. It is a wrapper for the CUDA Runtime API function cudaStreamDestroy() that you can use to avoid linking with the NVIDIA CUDA Toolkit libraries. This function and cudaStreamDestroy() are equivalent and interchangeable.

NvVFX_DestroyEffect#

void NvVFX_DestroyEffect(
  NvVFX_Handle obj
);

Parameters#

obj [in]

Type: NvVFX_Handle

The handle to the video effect filter instance to be destroyed.

Return Value#

Does not return a value.

Remarks#

This function destroys the video effect filter instance with the specified handle and frees resources and memory that were allocated for it.

NvVFX_GetCudaStream#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance from which you want to get the CUDA stream.

paramName

Type: NvVFX_ParameterSelector

The NVVFX_CUDA_STREAM selector string. Any other selector string returns an error.

stream

Type: CUstream *

Pointer to the CUDA stream where the CUDA stream will be written.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that the selector string specifies.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function gets the CUDA stream in which the specified video effect filter will run and writes the retrieved CUDA stream to the location that was specified by the parameter stream.

NvCV_GetErrorStringFromCode#

NvCV_GetErrorStringFromCode(NvCV_Status code);

Parameters#

code

Type: NvCV_Status

The NvCV_Status code for which to get an error string.

Return Value#

The error string that corresponds to the specified error code.

Remarks#

This function gets the error string that corresponds to the status code that was specified by the parameter code.

NvVFX_GetF32#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance from which you want to get the specified 32-bit floating-point parameter.

paramName

Type: NvVFX_ParameterSelector

The NVVFX_SCALE or NVVFX_STRENGTH selector strings. Any irrelevant selector strings return an error.

val

Type: float *

Pointer to the floating-point number where the value that was retrieved will be written.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function gets the value of the specified single-precision (32-bit) floating-point parameter for the specified video effect filter and writes the value that was retrieved to the location that was specified by the val parameter.

NvVFX_GetF64#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance from which you want to get the specified 64-bit floating-point parameter.

paramName

Type: NvVFX_ParameterSelector

The selector string for the 64-bit floating-point parameter that you want to get.

val

Type: double *

Pointer to the double-precision floating-point number where the value that was retrieved will be written.

Return Value#

  • NVCV_SUCCESS on success.

  • NVVFX_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVVFX_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function gets the value of the specified double-precision (64-bit) floating-point parameter for the specified video effect filter and writes the value that was retrieved to the location that was specified by the val parameter.

NvVFX_GetImage#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance from which you want to get the specified image buffer.

paramName

Type: NvVFX_ParameterSelector

One of the following selector strings for the image buffer that you want to get:

  • NVVFX_INPUT_IMAGE_0

  • NVVFX_INPUT_IMAGE

  • NVVFX_OUTPUT_IMAGE_0

  • NVVFX_OUTPUT_IMAGE

Any other selector string returns an error.

im

Type: NvCVImage *

Pointer to an empty NvCVImage structure where a view of the requested image is to be written.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function gets the specified input or output image descriptor for the specified video effect filter and writes it to the location that was specified by the im parameter. The retrieved image descriptor is a copy of the descriptor that was supplied in an earlier call to NvVFX_SetImage(). If NvVFX_SetImage() has not been called previously with the same selector, the location that was specified by im is filled with zeros. The buffer is not deallocated when the supplied NvCVImage object goes out of scope.

NvVFX_GetObject#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance from which you want to get the specified object.

paramName

Type: NvVFX_ParameterSelector

The selector string for the object parameter that you want to get.

ptr

Type: void **

Pointer to the address of the object where the retrieved object will be written.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function gets the specified object for the specified video effect filter and writes the retrieved object to the location that was specified by the ptr parameter.

NvVFX_GetS32#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance from which you want to get the specified 32-bit signed integer parameter.

paramName

Type: NvVFX_ParameterSelector

The selector string for the 32-bit signed integer parameter that you want to get.

val

Type: int *

Pointer to the 32-bit signed integer where the value retrieved will be written.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function gets the value of the specified 32-bit signed integer parameter for the specified video effect filter and writes the value that was retrieved to the location that was specified by the val parameter.

NvVFX_GetString#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance from which you want to get the specified character string parameter. To get a list of the available effects, set the obj parameter to NULL and the paramName parameter to NVVFX_INFO.

paramName

Type: NvVFX_ParameterSelector

One of the following selector strings for the character string parameter that you want to get:

  • NVVFX_INFO

  • NVVFX_MODEL_DIRECTORY

Any other selector string returns an error.

str

Type: const char **

The address where the requested character string pointer will be stored.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function gets the value of the specified character string parameter for, or information about, the specified video effect filter and writes the string that was retrieved to the location that was specified by the str parameter.

NvVFX_GetU32#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance from which you want to get the specified 32-bit unsigned integer parameter.

paramName

Type: NvVFX_ParameterSelector

The NVVFX_MODE, NVVFX_STRENGTH, NVVFX_TEMPORAL, NVVFX_GPU, NVVFX_BATCH_SIZE, or NVVFX_MODEL_BATCH selector strings. Any irrelevant selector strings return an error.

val

Type: unsigned int *

Pointer to the 32-bit unsigned integer where the value retrieved is to be written.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function gets the value of the specified 32-bit unsigned integer parameter for the specified video effect filter and writes the value that was retrieved to the location that was specified by the val parameter.

NvVFX_GetU64#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance from which you want to get the specified 64-bit unsigned integer parameter.

paramName

Type: NvVFX_ParameterSelector

The selector string for the 64-bit unsigned integer parameter that you want to get.

val

Type: unsigned long long *

Pointer to the 64-bit unsigned integer where the value retrieved is to be written.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function gets the value of the specified 64-bit unsigned integer parameter for the specified video effect filter and writes the value retrieved to the location specified by the val parameter.

NvVFX_Load#

NvCV_Status NvVFX_Load(
  NvVFX_Handle obj
);

Parameters#

obj [in]

Type: NvVFX_Handle

The handle to the video effect filter instance to load.

Return Value#

NVCV_SUCCESS on success.

Remarks#

This function loads the specified video effect filter and validates the parameters that are set for the filter.

NvVFX_Run#

NvCV_Status NvVFX_Run(
  NvVFX_Handle obj,
  int async
);

Parameters#

obj [in]

Type: NvVFX_Handle

The handle to the video effect filter instance that will be run.

async [in]

An integer value that specifies whether the filter will run asynchronously or synchronously:

  • 1: The filter runs asynchronously.

  • 0: The filter runs synchronously.

Return Value#

NVCV_SUCCESS on success.

Remarks#

This function runs the specified video effect filter by reading the contents of the input GPU buffer, applying the video effect filter, and writing the output to the output GPU buffer.

NvVFX_SetCudaStream#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance for which you want to set the CUDA stream.

paramName

Type: NvVFX_ParameterSelector

The NVVFX_CUDA_STREAM selector string. Any other selector string returns an error.

stream

Type: CUstream

The CUDA stream to which the parameter will be set.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function sets the CUDA stream in which the specified video effect filter will run to the parameter stream.

NvVFX_AllocateState#

NvCV_Status NvVFX_AllocateState(
  NvVFX_Handle obj,
  NvVFX_StateObjectHandle \*handle
);

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance for which you want to create a state variable.

handle

Type: NvVFX_StateObjectHandle

This is a pointer that the SDK uses to return the handle to the state variable.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function allocates a state variable and returns the handle for a specified video effect filter.

NvVFX_DeallocateState#

NvCV_Status NvVFX_DeallocateState(
  NvVFX_Handle obj,
  NvVFX_StateObjectHandle handle
);

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance that owns the state variable that is represented by the second parameter.

handle

Type: NvVFX_StateObjectHandle

This is a handle to a state variable.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

  • NVCV_ERR_OBJECTNOTFOUND when the supplied handle was not allocated by the filter instance.

Remarks#

This function deallocates a state variable.

NvVFX_ResetState#

NvCV_Status NvVFX_ResetState(
  NvVFX_Handle obj,
  NvVFX_StateObjectHandle handle
);

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance that owns the state variable that is represented by the second parameter.

handle

Type: NvVFX_StateObjectHandle

This is a handle to a state variable.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

  • NVCV_ERR_OBJECTNOTFOUND when the supplied handle was not allocated by the filter instance.

Remarks#

This function resets a state variable.

NvVFX_SetF32#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance for which you want to set the specified 32-bit floating-point parameter.

paramName

Type: NvVFX_ParameterSelector

The NVVFX_SC``ALE or NVVFX_STRENGTH selector strings. Any irrelevant selector strings return an error.

val

Type: float

The floating-point number to which the parameter will be set.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function sets the specified single-precision (32-bit) floating-point parameter for the specified video effect filter to the val parameter.

NvVFX_SetF64#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance for which you want to set the specified 64-bit floating-point parameter.

paramName

Type: NvVFX_ParameterSelector

The selector string for the 64-bit floating-point parameter that you want to set.

val

Type: double

The double-precision floating-point number to which the parameter is to be set.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function sets the specified double-precision (64-bit) floating-point parameter for the specified video effect filter to the val parameter.

NvVFX_SetImage#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance for which you want to set the specified image buffer.

paramName

Type: NvVFX_ParameterSelector

One of the following selector strings for the image buffer that you want to set:

  • NVVFX_INPUT_IMAGE_0

  • NVVFX_INPUT_IMAGE

  • NVVFX_OUTPUT_IMAGE_0

  • NVVFX_OUTPUT_IMAGE

Any other selector string returns an error.

im

Type: NvCVImage *

Pointer to the NvCVImage object to which the parameter will be set.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function sets the specified input or output image buffer for the specified video effect filter to the im parameter.

NvVFX_SetObject#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance for which you want to set the specified object.

paramName

Type: NvVFX_ParameterSelector

The selector string for the object parameter that you want to set.

ptr

Type: void *

Pointer to the object to which the object parameter is to be set.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function sets the specified object for the specified video effect filter to the ptr parameter.

NvVFX_SetStateObjectHandleArray#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance.

paramName

Type: NvVFX_ParameterSelector

The selector string for the object parameter that you want to set: NVVFX_STATE.

handle

Type: NvVFX_StateObjectHandle

Pointer to the array of state objects.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function sets the specified object for the specified video effect filter to the handle parameter.

NvVFX_SetS32#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance for which you want to set the specified 32-bit signed integer parameter.

paramName

Type: NvVFX_ParameterSelector

The selector string for the 32-bit signed integer parameter that you want to set.

val

Type: int

The 32-bit signed integer to which the parameter will be set.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function sets the value of the specified 32-bit signed integer parameter for the specified video effects to the val parameter.

NvVFX_SetString#

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

);

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance for which you want to set the specified character string parameter.

paramName

Type: NvVFX_ParameterSelector

The NVVFX_MODEL_DIRECTORY selector string. Any other selector string returns an error.

str

Type: const char *

Pointer to the character string to which you want to set the parameter.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function sets the value of the specified character string parameter for the specified video effect filter to the parameter str.

NvVFX_SetU32#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance for which you want to set the specified 32-bit unsigned integer parameter.

paramName

Type: NvVFX_ParameterSelector

The NVVFX_MODE, NVVFX_STRENGTH, NVVFX_TEMPORAL, NVVFX_GPU, NVVFX_BATCH_SIZE, or NVVFX_MODEL_BATCH selector strings. Any irrelevant selector strings return an error.

val

Type: unsigned int

The 32-bit unsigned integer to which you want to set the parameter.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function sets the value of the specified 32-bit unsigned integer parameter for the specified video effect filter to the val parameter.

NvVFX_SetU64#

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

Parameters#

obj

Type: NvVFX_Handle

The handle to the video effect filter instance for which you want to set the specified 64-bit unsigned integer parameter.

paramName

Type: NvVFX_ParameterSelector

The selector string for the 64-bit unsigned integer parameter that you want to set.

val

Type: unsigned long long

The 64-bit unsigned integer to which you want to set the parameter.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_SELECTOR when the obj parameter specifies a video effect filter instance that cannot parse the selector string that was specified by the paramName parameter or the data type of the parameter that was specified by the selector string.

  • NVCV_ERR_PARAMETER when an unexpected NULL pointer was supplied.

Remarks#

This function sets the value of the specified 64-bit unsigned integer parameter for the specified video effect filter to the val parameter.

NvVFX_ConfigureLogger#

NvCV_Status NvVFX_ConfigureLogger(int verbosity, const char *file,
            void (*cb)(void*, const char*), void *cb_data);

Several specific error codes help to identify the nature of an error. Sometimes more information is needed about specific actions to take to overcome the error during integration into his application. That is the purpose of the logging functions.

But not all applications have an error console, so is it necessary to configure the logger to work in the environment of the application.

All logger instantiations are implemented as callbacks. We have supplied source code examples of five logger instantiations in nvCVLoggerExamples.c:

  • MemLogger: Collects logs into a string in memory.

  • StderrLogger: Log to stderr.

  • FileLogger: Log to a file.

  • FileThreadLogger: Log to a file, with file writes performed in a separate thread to reduce the latency of the FileLogger.

  • Multifile Logger: Log to multiple files, each no larger than a specified size.

These are just examples of logger instantiations. You can of course develop your own logger to better suit the nature of your application.

StderrLogger and FileLogger are compiled into the SDK and can be easily configured:

NvVFX_ConfigureLogger(LOG_ERROR, "stderr", NULL, NULL);

NvVFX_ConfigureLogger(LOG_ERROR, "/logs/vfx.log", NULL, NULL);

Logging can be turned off by supplying NULL:

NvVFX_ConfigureLogger(LOG_ERROR, NULL, NULL, NULL);

Parameters#

verbosity

Type: int

The maximum level of verbosity to be recorded into the log.

NVCV_LOG_FATAL (0)

Message to be printed right before terminating due to an unrecoverable error.

NVCV_LOG_ERROR (1)

An operation has failed, but it is not fatal.

NVCV_LOG_WARNING (2)

Something was not quite right, but we fixed it up, perhaps at a loss in performance.

NVCV_LOG_INFO (3)

Nothing is wrong, but this information might be of interest.

The higher level verbosity also includes the logs from the lower levels of verbosity.

file

Type: const char*

This field is used only when logging to stderr or to a file. Otherwise it should be set to NULL. Examples:

  • “stderr”: Log to stderr.

  • “/path/to/log.txt”: Log to the file named /path/to/log.txt.

cb

Type: void (*)(void *data, const char *msg)

Pointer to the callback function. The function has two arguments:

  • data: Pointer to data used by the callback function.

  • msg: The message to be entered into the log.

cb_data

Type: void*

Pointer provided to the callback function as its first argument.

Return Value#

  • NVCV_SUCCESS on success.

  • NVCV_ERR_FILE on failure to open the specified log file.

Configuring the Logger Examples#

Source code for five example loggers is provided in the SDK, and this section shows how to configure them. Though the built-in loggers StderrLogger and FileLogger require one less line of code to configure them, there are cases where the other examples are more appropriate.

  • Servers typically run for weeks or months without being restarted. Using a standard file logger, the file would grow without bound. That is where the multi-file logger is useful: to limit the size of the log.

  • Coalescing logs from several SDKs cannot be done with the built-in file logger, because each SDK has its own logger. It is necessary, therefore, to instantiate a single logger in the application and then use that instance to configure the logger in each SDK.

  • To minimize the performance impact of copious logging (as when specifying NVCV_LOG_INFO), the FileThreadLogger is preferred to minimize impact on performance. If the standard FileLogger is used instead, the program will stall while writing to the file.

MemLogger#

MemLogger memLog;
NvVFX_ConfigureLogger(LOG_ERROR, NULL, &MemLogger::Callback, &memLog);

StderrLogger#

StderrLogger stdLog;
NvVFX_ConfigureLogger(LOG_ERROR, NULL, &StderrLogger::Callback, &stdLog);

But because the StderrLogger is compiled into the SDK, you can do the following:

NvVFX_ConfigureLogger(LOG_ERROR, "stderr", NULL, NULL);

FileLogger#

FileLogger flog("/path/to/vfx.log", "w");
NvVFX_ConfigureLogger(LOG_ERROR, NULL, &FileLogger::Callback, &flog);

This configures the logger to write to vfx.log, starting fresh. If "a" were supplied instead of "w", it would append to the existing file instead.

But since the FileLogger is compiled into the SDK, you can do the following:

NvVFX_ConfigureLogger(LOG_ERROR, "/path/to/vfx.log", NULL, NULL);

This does not offer the option to append, however; the specified file is overwritten.

FileThreadLogger#

FileThreadLogger flog("/path/to/vfx.log", "w");
NvVFX_ConfigureLogger(LOG_ERROR, NULL, &FileThreadLogger::Callback, &flog);

Similar to the FileLogger, "a" is available as the second argument to append to the specified file instead of overwriting it.

MultifileLogger#

MultifileLogger mflog("/path/to/log%02d.log", 65536, 12, 0);
NvVFX_ConfigureLogger(LOG_ERROR, &MultifileLogger::Callback, &mflog);

This configures the logger to write to a set of 12 files, starting with log00.log, with no file larger than 65536 bytes. When that maximum size is likely to be exceeded, the log00.log file is closed and logging continues in log01.log. When log11.log is full, logging continues with overwriting log00.log, using the same 12 files in a circular manner.

The last argument is used to specify which file is to be written first. This is useful when the service was stopped, then restarted, and it is desired to continue writing in the same sequence as before, without resetting to file 0.

Advanced: Changing the Logging Level#

Sometimes you might want to change the level of logging within the application code. For example, when debugging a particular section of code, you might want a higher level of verbosity while in that code. You can do so by using the special filename same.

MultifileLogger mflog("/path/to/log%d.log", 65536, 4, 0);
NvVFX_ConfigureLogger(LOG_ERROR, &MultifileLogger::Callback, &mflog);
… <code logged at the ERROR level>
NvVFX_ConfigureLogger(LOG_INFO, "same", NULL, NULL);
… <code logged at the INFO level>
NvVFX_ConfigureLogger(LOG_ERROR, "same", NULL, NULL);
… <code logged at the ERROR level>

What if you don’t know the current level of verbosity but want to restore it to that level? Use the cb_data parameter to retrieve that data:

int saved_verbosity;
NvVFX_ConfigureLogger(LOG_INFO, "same", NULL, &saved_verbosity);
… <code logged at the INFO level>
NvVFX_ConfigureLogger(saved_verbosity, "same", NULL, NULL);
… <code logged at the previous verbosity>
On this page