Data Structures | |
| struct | VPIImagePlaneRec |
| Stores information about an image plane. More... | |
| struct | VPIImageDataRec |
| 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 VPIImagePlaneRec | VPIImagePlane |
| Stores information about an image plane. More... | |
| typedef struct VPIImageDataRec | VPIImageData |
| Stores information about image characteristics and content. | |
| typedef struct VPIImageImpl * | VPIImage |
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 | vpiImageWrapHostMem (const VPIImageData *hostData, uint32_t flags, VPIImage *img) |
| Create an image object by wrapping around an existing host-memory block. More... | |
| VPIStatus | vpiImageWrapCudaDeviceMem (const VPIImageData *cudaData, uint32_t flags, VPIImage *img) |
| Create an image object by wrapping around an existing device-memory (CUDA) block. 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 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 image object. More... | |
image creation flags | |
| #define | VPI_IMAGE_NO_PVA 0x01 /*< image can't be used by PVA device instance */ |
| shared helper flags | |
| #define | VPI_IMAGE_NO_CPU 0x02 /*< image can't be used by CPU device instance */ |
| shared helper flags | |
| #define | VPI_IMAGE_NO_CUDA 0x04 /*< image can't be used by CUDA device instance */ |
| shared helper flags | |
| #define | VPI_IMAGE_ONLY_CUDA (VPI_IMAGE_NO_PVA | VPI_IMAGE_NO_CPU) |
| shared helper flags | |
| #define | VPI_IMAGE_ONLY_CPU (VPI_IMAGE_NO_PVA | VPI_IMAGE_NO_CUDA) |
| shared helper flags | |
| #define | VPI_IMAGE_ONLY_PVA (VPI_IMAGE_NO_CUDA | VPI_IMAGE_NO_CPU) |
| shared helper flags | |
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_NO_PVA/VPI_IMAGE_NO_CPU/ VPI_IMAGE_NO_CUDA set of flags which are passed during image construction. For example, an image allocated with VPI_IMAGE_NO_CUDA flag set, will not be readable or writeable 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 VPIImageWrapDeviceMem().
The set of VPIImageLock()/VPIImageUnlock() allows 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.
| typedef struct VPIImageImpl* VPIImage |
| typedef struct VPIImagePlaneRec VPIImagePlane |
#include <vpi/Image.h>
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.
| 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.
| width | [in] width |
| height | [in] height |
| type | [in] image pixel type |
| flags | [in] flags |
| img | [out] pointer to image handle |
| void vpiImageDestroy | ( | VPIImage | img | ) |
#include <vpi/Image.h>
Destroy an image instance as well as all resources it owns.
| img | [in] image handle |
#include <vpi/Image.h>
Get the image flags.
| img | [in] an image handle |
| flags | [out] a pointer to where the flags will be written to |
#include <vpi/Image.h>
Get the image size in pixels.
| 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 |
| VPIStatus vpiImageGetType | ( | VPIImage | img, |
| VPIImageType * | type | ||
| ) |
#include <vpi/Image.h>
Get the image type.
| img | [in] an image handle |
| type | [out] a pointer to where the type will be written to |
#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.
| img | [in] an image handle |
| VPIStatus vpiImageLock | ( | VPIImage | img, |
| VPILockMode | mode, | ||
| VPIImageData * | hostData | ||
| ) |
#include <vpi/Image.h>
Acquires the lock on 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).
| 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 |
#include <vpi/Image.h>
Releases the lock on image object.
This function might have a significant performance overhead (format conversion, layout conversion, host-to-device memory copy).
| img | [in] an image handle |
| VPIStatus vpiImageWrapCudaDeviceMem | ( | const VPIImageData * | cudaData, |
| uint32_t | flags, | ||
| VPIImage * | img | ||
| ) |
#include <vpi/Image.h>
Create an image object by wrapping around an existing device-memory (CUDA) block.
Only pitch-linear format is supported. The underlying image object does not own/claim the memory block.
| cudaData | [in] Pointer to structure with cuda memory to be wrapped. |
| flags | [in] flags |
| img | [out] pointer to an image handle |
| VPIStatus vpiImageWrapHostMem | ( | const VPIImageData * | hostData, |
| uint32_t | flags, | ||
| VPIImage * | img | ||
| ) |
#include <vpi/Image.h>
Create an image object by wrapping around an existing host-memory block.
Only pitch-linear format is supported. The underlying image object does not own/claim the memory block.
| hostData | [in] Pointer to structure with host memory to be wrapped. |
| flags | [in] flags |
| img | [out] pointer to an image handle |