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... | |
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:
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.
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. 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. |
struct 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. |
#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.
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.
[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. |
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.
[in] | img | Image handle to be destroyed. Passing NULL is allowed, to which the function simply does nothing. |
#include <vpi/Image.h>
Get the image flags.
[in] | img | Nn image handle |
[out] | flags | A pointer to where the flags will be written to. |
VPIStatus vpiImageGetFormat | ( | VPIImage | img, |
VPIImageFormat * | format | ||
) |
#include <vpi/Image.h>
Get the image format.
[in] | img | An image handle |
[out] | format | A pointer to where the mage format will be written to |
#include <vpi/Image.h>
Get the image size in pixels.
[in] | img | an image handle |
[out] | width,height | Pointers to memories where the image width and height (respectively) will be written to. |
#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.
[in] | img | An image handle created by one of the wrapper image creation functions. |
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.
[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. |
#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.
[in] | img | An image handle |