Convolution

Convolves an image with a 2D kernel. More...

Functions
VPIStatus	vpiSubmitConvolution (VPIStream stream, uint64_t backend, VPIImage input, VPIImage output, const float *kernelData, int32_t kernelWidth, int32_t kernelHeight, VPIBorderExtension border)
	Runs a generic 2D convolution over an image. More...
VPIStatus	vpiSubmitSeparableConvolution (VPIStream stream, uint64_t backend, VPIImage input, VPIImage output, const float *kernelXData, int32_t kernelXSize, const float *kernelYData, int32_t kernelYSize, VPIBorderExtension border)
	Runs a generic 2D convolution operation over an image, optimized for separable kernels. More...

Detailed Description

Convolves an image with a 2D kernel.

Refer to Convolution for more details and usage examples regarding Convolution. Refer to Separable Convolution for more details and usage examples regarding Separable Convolution.

vpiSubmitConvolution is used for generic 2D kernels, separable or not. For separable kernels, it's usually more efficient to use vpiSubmitSeparableConvolution.

Function Documentation

vpiSubmitConvolution()

VPIStatus vpiSubmitConvolution	(	VPIStream	stream,
		uint64_t	backend,
		VPIImage	input,
		VPIImage	output,
		const float *	kernelData,
		int32_t	kernelWidth,
		int32_t	kernelHeight,
		VPIBorderExtension	border
	)

#include </opt/nvidia/vpi3/include/vpi/algo/Convolution.h>

Runs a generic 2D convolution over an image.

Parameters

[in]	stream	The stream handle where the operation will be queued in. Must not be NULL. Stream must have enabled the backends that will execute the algorithm.
[in]	backend	Backend that will execute the algorithm. Valid values: VPI_BACKEND_CPU VPI_BACKEND_CUDA VPI_BACKEND_PVA
[in]	input	Input image to be convolved with the kernel. Must not be NULL. On PVA backend, image dimensions must be between 65x33 and 3264x2448. Image must have enabled the backends that will execute the algorithm. The accepted image formats are: Formats CPU CUDA PVA VPI_IMAGE_FORMAT_U8 * * * VPI_IMAGE_FORMAT_S8 * * * VPI_IMAGE_FORMAT_U16 * * * VPI_IMAGE_FORMAT_S16 * * * VPI_IMAGE_FORMAT_Y8 * * * VPI_IMAGE_FORMAT_Y8_ER * * * VPI_IMAGE_FORMAT_Y16 * * * VPI_IMAGE_FORMAT_Y16_ER * * * VPI_IMAGE_FORMAT_F32 * *
[out]	output	Output image where the result is written to. Must not be NULL. Must have same dimensions as input image. Image must have enabled the backends that will execute the algorithm. With PVA, it must have same format as input image. With other backends, format may be: Equal to input format. VPI_IMAGE_FORMAT_F32 (no matter what input format).
[in]	kernelWidth,kernelHeight	Kernel dimensions. Must be between 1x1 and 11x11 and can be non-square.
[in]	kernelData	Convolution kernel coefficients, in row-major layout. The kernel elements are copied to an internal buffer. The buffers passed can be deallocated after the call. It cannot be NULL. It must point to a buffer with kernelWidth * kernelHeight elements, if not it'll lead to undefined behavior On PVA backend, kernel weights are restricted to |weight|<=1.
[in]	border	How to handle pixels outside image boundaries. The accepted border extensions are: VPI_BORDER_ZERO VPI_BORDER_CLAMP

Return values

VPI_ERROR_INVALID_ARGUMENT	stream is NULL.
VPI_ERROR_INVALID_ARGUMENT	input or output are NULL.
VPI_ERROR_INVALID_ARGUMENT	kernelWidth or kernelHeight are outside valid range.
VPI_ERROR_INVALID_ARGUMENT	kernelData is NULL.
VPI_ERROR_INVALID_ARGUMENT	Some weight in kernelData is outside valid range.
VPI_ERROR_INVALID_ARGUMENT	input or output dimensions outside valid range.
VPI_ERROR_INVALID_ARGUMENT	input and output image must have same dimensions.
VPI_ERROR_INVALID_ARGUMENT	border not supported.
VPI_ERROR_INVALID_ARGUMENT	backend is invalid or unknown.
VPI_ERROR_INVALID_IMAGE_FORMAT	input or output format not supported.
VPI_ERROR_INVALID_IMAGE_FORMAT	input and output formats are not compatible.
VPI_ERROR_NOT_IMPLEMENTED	Convolution algorithm is not supported by given backend.
VPI_ERROR_INVALID_OPERATION	Backend hardware not available.
VPI_ERROR_INVALID_OPERATION	The needed backends aren't enabled in stream, input or output.
VPI_SUCCESS	Operation executed successfully.

vpiSubmitSeparableConvolution()

VPIStatus vpiSubmitSeparableConvolution	(	VPIStream	stream,
		uint64_t	backend,
		VPIImage	input,
		VPIImage	output,
		const float *	kernelXData,
		int32_t	kernelXSize,
		const float *	kernelYData,
		int32_t	kernelYSize,
		VPIBorderExtension	border
	)

#include </opt/nvidia/vpi3/include/vpi/algo/Convolution.h>

Runs a generic 2D convolution operation over an image, optimized for separable kernels.

Parameters

[in]	stream	The stream handle where the operation will be queued in. Must not be NULL. Stream must have enabled the backends that will execute the algorithm.
[in]	backend	Backend that will execute the algorithm. Valid values: VPI_BACKEND_CPU VPI_BACKEND_CUDA VPI_BACKEND_PVA
[in]	input	Input image to be convolved with the kernel. Must not be NULL. Image must have enabled the backends that will execute the algorithm. On PVA, image dimensions must be between 32x32 and 3264x2448. The accepted image formats are: Formats CPU CUDA PVA VPI_IMAGE_FORMAT_U8 * * VPI_IMAGE_FORMAT_S8 * * VPI_IMAGE_FORMAT_U16 * * VPI_IMAGE_FORMAT_S16 * * * VPI_IMAGE_FORMAT_Y8 * 1 VPI_IMAGE_FORMAT_Y8_ER * 1 VPI_IMAGE_FORMAT_Y16 * 1 VPI_IMAGE_FORMAT_Y16_ER * 1 VPI_IMAGE_FORMAT_F32 * * VPI_IMAGE_FORMAT_RGB8p 2 VPI_IMAGE_FORMAT_RGBA8p 2 VPI_IMAGE_FORMAT_BGR8p 2 VPI_IMAGE_FORMAT_BGRA8p 2 (1) only for kernel dimensions <= 3x3 (2) only for kernel dimensions >= 3x3
[out]	output	Output image where the result is written to. Must not be NULL. Must have same dimensions and format as input image. Image must have enabled the backends that will execute the algorithm.
[in]	kernelXSize,kernelYSize	Kernel dimensions in X and Y directions. Must be between 1x1 and 11x11.
[in]	kernelXData,kernelYData	Convolution kernel coefficients, in both X and Y directions respectively. The kernel elements are copied to an internal buffer. The buffers passed can be deallocated after the call. kernelXData and kernelYData must point to a buffer with kernelXSize and kernelYSize elements respectively. They can't be NULL. On PVA backend, kernel weights are restricted to |weight|<1.
[in]	border	How to handle pixels outside image boundaries. The accepted border extensions are: VPI_BORDER_ZERO VPI_BORDER_CLAMP

Return values

VPI_ERROR_INVALID_ARGUMENT	stream is NULL.
VPI_ERROR_INVALID_ARGUMENT	input or output are NULL.
VPI_ERROR_INVALID_ARGUMENT	kernelXData or kernelYData are NULL.
VPI_ERROR_INVALID_ARGUMENT	kernelXSize or kernelYSize outside valid range.
VPI_ERROR_INVALID_ARGUMENT	Some weight in kernelData is outside valid range.
VPI_ERROR_INVALID_ARGUMENT	input or output image dimensions outside valid range..
VPI_ERROR_INVALID_ARGUMENT	border not supported.
VPI_ERROR_INVALID_ARGUMENT	input and output image dimensions and format do not match.
VPI_ERROR_INVALID_ARGUMENT	backend is invalid or unknown.
VPI_ERROR_INVALID_IMAGE_FORMAT	input and output formats aren't supported
VPI_ERROR_NOT_IMPLEMENTED	Separable Convolution algorithm is not supported by given backend.
VPI_ERROR_INVALID_OPERATION	Backend hardware not available.
VPI_ERROR_INVALID_OPERATION	The needed backends aren't enabled in stream, input or output.
VPI_SUCCESS	Operation executed successfully.