An abstract representation of a 2D image. More...

Data Structures
struct	VPIImagePlane
	Stores information about an image plane. More...

struct	VPIImageData
	Stores information about image characteristics and content. More...

Macros
#define	VPI_MAX_PLANE_COUNT (6)
	Maximum number of data planes an image can have.

Typedefs
typedef struct VPIImageImpl *	VPIImage
	A handle to an image.

Functions
VPIStatus	vpiImageCreate (uint32_t width, uint32_t height, VPIImageType type, uint32_t flags, VPIImage *img)
	Create an empty image instance with the specified flags. More...

void	vpiImageDestroy (VPIImage img)
	Destroy an image instance as well as all resources it owns. More...

VPIStatus	vpiImageInvalidate (VPIImage img)
	This method is useful for unmanaged images only (created with `vpiImageWrap*`). More...

VPIStatus	vpiImageGetSize (VPIImage img, uint32_t width, uint32_t height)
	Get the image size in pixels. More...

VPIStatus	vpiImageGetType (VPIImage img, VPIImageType *type)
	Get the image type. More...

VPIStatus	vpiImageGetFlags (VPIImage img, uint32_t *flags)
	Get the image flags. More...

VPIStatus	vpiImageLock (VPIImage img, VPILockMode mode, VPIImageData *hostData)
	Acquires the lock on an image object and returns a pointer to the image planes Depending on the internal image representation, as well as the actual location in memory, this function might have a significant performance overhead (format conversion, layout conversion, device-to-host memory copy). More...

VPIStatus	vpiImageUnlock (VPIImage img)
	Releases the lock on an image object. More...

Image creation flags
#define	VPI_IMAGE_DISABLE_PVA VPI_BACKEND_DISABLE_PVA
	Image won't be used in a PVA stream.

#define	VPI_IMAGE_DISABLE_CPU VPI_BACKEND_DISABLE_CPU
	Image won't be used in a CPU stream.

#define	VPI_IMAGE_DISABLE_CUDA VPI_BACKEND_DISABLE_CUDA
	Image won't be used in a CUDA stream.

#define	VPI_IMAGE_ONLY_PVA VPI_BACKEND_ONLY_PVA
	Image will only be used in a PVA stream.

#define	VPI_IMAGE_ONLY_CPU VPI_BACKEND_ONLY_CPU
	Image will only be used in a CPU stream.

#define	VPI_IMAGE_ONLY_CUDA VPI_BACKEND_ONLY_CUDA
	Image will only be used in a CUDA stream.

Deprecated image creation flags
#define	VPI_IMAGE_NO_PVA VPI_IMAGE_DISABLE_PVA
	Deprecated.

#define	VPI_IMAGE_NO_CPU VPI_IMAGE_DISABLE_CPU
	Deprecated.

#define	VPI_IMAGE_NO_CUDA VPI_IMAGE_DISABLE_CUDA
	Deprecated.

Detailed Description

An abstract representation of a 2D image.

There are two ways of creating 2D image containers with the API. The most basic one is to use vpiImageCreate to allocate and initialize an empty (zeroed) VPIImage object. The memory for the image data is allocated and managed by the backend implementation. Parameters such as width, height and pixel type are immutable and specified at the construction time. The internal memory layout is also backend-specific. More importantly, efficient exchange of image data between different hardware blocks might force the implementation to allocate the memory in multiple memory pools (e.g. dGPU and system DRAM). In some scenarios (to optimize performance and memory use), it might be beneficial to constrain the internal allocation policy to support only a particular set of backends. This is implemented with VPI_IMAGE_DISABLE_PVA / VPI_IMAGE_DISABLE_CPU / VPI_IMAGE_DISABLE_CUDA set of flags which are passed during image construction. For example, an image allocated with VPI_IMAGE_DISABLE_CUDA flag set, will not be readable or writable by any CUDA VPIStream instance.

To enable interop with existing host-side code, the user can also create an image object that will wrap user-allocated (and managed) image data. Similarly to vpiImageCreate, image parameters passed to vpiImageWrap*() are fixed and expected memory layout is pitch-linear. To prevent excessive copying, users can point to image data that resides directly in the CUDA device memory with vpiImageWrapCudaDeviceMem.

The set of vpiImageLock / vpiImageUnlock allows the user to read from/write to the image data from the host. These functions are non-blocking and oblivious to the device command queue, so it's up to the user to make sure that all pending operations using this image as input or output are finished. Also, depending on the VPIStream type, lock/unlock operation might be time-consuming and, for example, involve copying data over PCIe bus for dGPUs.

VPI allows image interoperability with the following memory types:

CUDA memory: vpiImageWrapCudaDeviceMem
Host/CPU memory: vpiImageWrapHostMem
EGLImage: vpiImageWrapEglImage
NvBuffer: vpiImageWrapNvBuffer

Data Structure Documentation

◆ VPIImagePlane

struct VPIImagePlane

Stores information about an image plane.

Image planes represent 2D data where consecutive rows are laid out in memory one after the other. This structure has all information needed to address any pixel in the plane.

Definition at line 133 of file Image.h.

Collaboration diagram for VPIImagePlane:

Data Fields
void *	data	Pointer to the first row of this plane. This points to the actual data represented by this plane. Depending on how the plane is used, the pointer might be addressing a GPU memory or host memory. Care is needed to know when it is allowed to dereference this memory.
uint32_t	height	Height of this plane in pixels.
VPIPixelType	pixelType	Type of each pixel within this plane.
uint32_t	rowStride	Difference in bytes of beginning of one row and the beginning of the previous. This is used to address every row (and ultimately every pixel) in the plane. T pix_addr = (T )((uint8_t )data + rowStrideheight)+width; where T is the C type related to pixelType.
uint32_t	width	Width of this plane in pixels.

◆ VPIImageData

struct VPIImageData

Stores information about image characteristics and content.

Definition at line 154 of file Image.h.

Collaboration diagram for VPIImageData:

Data Fields
int32_t	numPlanes	Number of planes.
VPIImagePlane	planes[VPI_MAX_PLANE_COUNT]	Data of all image planes. Only the first numPlanes elements have valid data.
VPIImageType	type	Image type.

Function Documentation

◆ vpiImageCreate()

VPIStatus vpiImageCreate	(	uint32_t	width,
		uint32_t	height,
		VPIImageType	type,
		uint32_t	flags,
		VPIImage *	img
	)

#include <vpi/Image.h>

Create an empty image instance with the specified flags.

Image data is zeroed.

Parameters

width	[in] width
height	[in] height
type	[in] image pixel type
flags	[in] flags
img	[out] pointer to image handle

Returns: an error code on failure else VPI_SUCCESS

◆ vpiImageDestroy()

void vpiImageDestroy ( VPIImage img )

#include <vpi/Image.h>

Destroy an image instance as well as all resources it owns.

Parameters

img	[in] image handle

◆ vpiImageGetFlags()

VPIStatus vpiImageGetFlags	(	VPIImage	img,
		uint32_t *	flags
	)

#include <vpi/Image.h>

Get the image flags.

Parameters

img	[in] an image handle
flags	[out] a pointer to where the flags will be written to

Returns: an error code on failure else VPI_SUCCESS

◆ vpiImageGetSize()

VPIStatus vpiImageGetSize	(	VPIImage	img,
		uint32_t *	width,
		uint32_t *	height
	)

#include <vpi/Image.h>

Get the image size in pixels.

Parameters

img	[in] an image handle
width	[out] a pointer to a variable which will be set to the width of the image
height	[out] a pointer to a variable which will be set to the height of the image

Returns: an error code on failure else VPI_SUCCESS

◆ vpiImageGetType()

VPIStatus vpiImageGetType	(	VPIImage	img,
		VPIImageType *	type
	)

#include <vpi/Image.h>

Get the image type.

Parameters

img	[in] an image handle
type	[out] a pointer to where the type will be written to

Returns: an error code on failure else VPI_SUCCESS

◆ vpiImageInvalidate()

VPIStatus vpiImageInvalidate ( VPIImage img )

#include <vpi/Image.h>

This method is useful for unmanaged images only (created with vpiImageWrap*).

If the underlying image data has been modified outside the API, use this method to mark the image as invalid. This will force the API to update its internal representation (e.g., re-upload to CUDA memory) when necessary.

Parameters

img	[in] an image handle

Returns: an error code on failure else VPI_SUCCESS

◆ vpiImageLock()

VPIStatus vpiImageLock	(	VPIImage	img,
		VPILockMode	mode,
		VPIImageData *	hostData
	)

#include <vpi/Image.h>

Acquires the lock on an image object and returns a pointer to the image planes Depending on the internal image representation, as well as the actual location in memory, this function might have a significant performance overhead (format conversion, layout conversion, device-to-host memory copy).

Parameters

img	[in] an image handle
mode	[in] lock mode
hostData	[out] a pointer to a variable which will be set to the pointer to the image data

Returns: an error code on failure else VPI_SUCCESS

◆ vpiImageUnlock()

VPIStatus vpiImageUnlock ( VPIImage img )

#include <vpi/Image.h>

Releases the lock on an image object.

This function might have a significant performance overhead (format conversion, layout conversion, host-to-device memory copy).

Parameters

img	[in] an image handle

Returns: an error code on failure else VPI_SUCCESS

VPI - Vision Programming Interface

0.3.7 Release

Data Structures

Macros

Typedefs

Functions

Image creation flags

Deprecated image creation flags

Detailed Description

Data Structure Documentation

◆ VPIImagePlane

◆ VPIImageData

Function Documentation

◆ vpiImageCreate()

◆ vpiImageDestroy()

◆ vpiImageGetFlags()

◆ vpiImageGetSize()

◆ vpiImageGetType()

◆ vpiImageInvalidate()

◆ vpiImageLock()

◆ vpiImageUnlock()