Image

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:

• CUDA memory: vpiImageCreateCUDAMemWrapper
• Host/CPU memory: vpiImageCreateHostMemWrapper
• EGLImage: vpiImageCreateEGLImageWrapper
• NvBuffer: vpiImageCreateNvBufferWrapper

---

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; 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,height	Image dimensions.
[in]	fmt	Image format.
[in]	flags	Image 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]	img	Pointer 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]

img

Image 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]	img	Nn image handle
[out]	flags	A 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]	img	An image handle
[out]	format	A 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]	img	an image handle
[out]	width,height	Pointers 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]

img

An 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]	img	An image handle
[in]	mode	Lock mode, depending on whether the memory will be written to and/or read from.
[out]	hostData	A 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]

img

An image handle

Returns

an error code on failure else VPI_SUCCESS