VPI - Vision Programming Interface

1.0 Release

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 (int32_t width, int32_t height, VPIImageFormat fmt, uint32_t flags, VPIImage *img)
 Create an empty image instance with the specified flags. More...
 
void vpiImageDestroy (VPIImage img)
 Destroy an image instance. More...
 
VPIStatus vpiImageInvalidate (VPIImage img)
 Informs that the image's wrapped memory was updated outside VPI. More...
 
VPIStatus vpiImageGetSize (VPIImage img, int32_t *width, int32_t *height)
 Get the image size in pixels. More...
 
VPIStatus vpiImageGetFormat (VPIImage img, VPIImageFormat *format)
 Get the image format. 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. More...
 
VPIStatus vpiImageUnlock (VPIImage img)
 Releases the lock on an image object. More...
 

Image-specific flags.

#define VPI_DISABLE_BL_HOST_LOCK   (1u << 31)
 Flag to allow vpiImageLock of block-linear images to succeed. More...
 

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 VPI. 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 backends 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.

To enable interop with existing host- or gpu-side code, the user can also create an image object that wraps a user-allocated (and managed) image data. Similarly to vpiImageCreate, image parameters passed to vpiImageCreate*Wrapper() are fixed. To prevent excessive copying, users can point to image data that resides directly in the CUDA device memory with vpiImageCreateCUDAMemWrapper.

The wrapped memory can be redefined by calling vpiImageSetWrapped*() corresponding to the image wrapper creation function used, as long as the new wrapped memory has the same capacity and type as the one originally wrapped. It's more efficient to create the VPIImage wrapper once and reuse it later then creating and destroying it all the time.

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 stream 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 which device the memory is allocated, 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:


Data Structure Documentation

◆ VPIImagePlane

struct VPIImagePlane

Stores information about an image plane.

Image planes represent 2D data where consecutive rows are laid out in pitch-linear format. This structure has all information needed to address any pixel in the plane.

Definition at line 134 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.

int32_t height Height of this plane in pixels.
int32_t pitchBytes 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 + pitchBytes*height)+width;
int32_t height
Height of this plane in pixels.
Definition: Image.h:138
int32_t width
Width of this plane in pixels.
Definition: Image.h:137
void * data
Pointer to the first row of this plane.
Definition: Image.h:147
int32_t pitchBytes
Difference in bytes of beginning of one row and the beginning of the previous.
Definition: Image.h:139

where T is the C type related to pixelType.

VPIPixelType pixelType Type of each pixel within this plane.
int32_t width Width of this plane in pixels.

◆ VPIImageData

struct VPIImageData

Stores information about image characteristics and content.

Definition at line 158 of file Image.h.

+ Collaboration diagram for VPIImageData:
Data Fields
VPIImageFormat format Image format.
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.

Macro Definition Documentation

◆ VPI_DISABLE_BL_HOST_LOCK

#define VPI_DISABLE_BL_HOST_LOCK   (1u << 31)

#include <vpi/Image.h>

Flag to allow vpiImageLock of block-linear images to succeed.

It'll allocate an extra buffer to store the corresponding pitch-linear image.

Definition at line 126 of file Image.h.

Function Documentation

◆ vpiImageCreate()

VPIStatus vpiImageCreate ( int32_t  width,
int32_t  height,
VPIImageFormat  fmt,
uint32_t  flags,
VPIImage img 
)

#include <vpi/Image.h>

Create an empty image instance with the specified flags.

Image data is zeroed.

Parameters
[in]width,heightImage dimensions.
[in]fmtImage format.
[in]flagsImage flags. Here it can be specified in what backends the image can be used by or-ing together VPIBackend flags. Set flags to 0 to enable it in all backends supported by the active VPI context.
[out]imgPointer to memory that will receive the created image handle.
Returns
an error code on failure else VPI_SUCCESS

◆ vpiImageDestroy()

void vpiImageDestroy ( VPIImage  img)

#include <vpi/Image.h>

Destroy an image instance.

This function deallocates all resources allocated by the image creation function. When destroying an VPIImager wrapper, the wrapped memory itself isn't deallocated.

Parameters
[in]imgImage handle to be destroyed. Passing NULL is allowed, to which the function simply does nothing.

◆ vpiImageGetFlags()

VPIStatus vpiImageGetFlags ( VPIImage  img,
uint32_t *  flags 
)

#include <vpi/Image.h>

Get the image flags.

Parameters
[in]imgNn image handle
[out]flagsA pointer to where the flags will be written to.
Returns
an error code on failure else VPI_SUCCESS

◆ vpiImageGetFormat()

VPIStatus vpiImageGetFormat ( VPIImage  img,
VPIImageFormat format 
)

#include <vpi/Image.h>

Get the image format.

Parameters
[in]imgAn image handle
[out]formatA pointer to where the mage format will be written to
Returns
an error code on failure else VPI_SUCCESS
+ Here is the caller graph for this function:

◆ vpiImageGetSize()

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

#include <vpi/Image.h>

Get the image size in pixels.

Parameters
[in]imgan image handle
[out]width,heightPointers to memories where the image width and height (respectively) will be written to.
Returns
an error code on failure else VPI_SUCCESS

◆ vpiImageInvalidate()

VPIStatus vpiImageInvalidate ( VPIImage  img)

#include <vpi/Image.h>

Informs that the image's wrapped memory was updated outside VPI.

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
[in]imgAn image handle created by one of the wrapper image creation functions.
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).

The image can be locked multiple times. Each lock operation increments a counter and must be matched by a corresponding vpiImageUnlock call. Lock will fail if the image is being used by an algorithm.

Parameters
[in]imgAn image handle
[in]modeLock mode, depending on whether the memory will be written to and/or read from.
[out]hostDataA pointer to a structure that will be filled with image memory information. If it's NULL, the image will still be locked. This is useful to make sure wrapped image is updated.
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).

The mage is effectively unlocked when the internal lock counter reaches 0.

Parameters
[in]imgAn image handle
Returns
an error code on failure else VPI_SUCCESS