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

Data Structures
struct	VPIImagePlanePitchLinear
	Represents one image plane in pitch-linear layout. More...

struct	VPIImageBufferPitchLinear
	Stores the image plane contents. More...

union	VPIImageBuffer
	Represents the available methods to access image contents. More...

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

struct	VPIImageWrapperParams
	Parameters for customizing image wrapping. 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.

Enumerations
enum	VPIImageBufferType
	Represents how the image data is stored. More...

Functions
VPIStatus	vpiImageCreate (int32_t width, int32_t height, VPIImageFormat fmt, uint64_t flags, VPIImage *img)
	Create an empty image instance with the specified flags. More...

VPIStatus	vpiInitImageWrapperParams (VPIImageWrapperParams *params)
	Initialize VPIImageWrapperParams with default values. More...

VPIStatus	vpiImageCreateView (VPIImage imgParent, const VPIRectangleI clipBounds, uint64_t flags, VPIImage imgView)
	Create an image that wraps an axis-aligned rectangular sub-region of an existing image. More...

VPIStatus	vpiImageSetView (VPIImage view, VPIImage parent, const VPIRectangleI *clipBounds)
	Redefines the image view position inside a parent image. More...

VPIStatus	vpiImageCreateWrapper (const VPIImageData data, const VPIImageWrapperParams params, uint64_t flags, VPIImage *img)
	Create an image object by wrapping an existing memory block. More...

VPIStatus	vpiImageSetWrapper (VPIImage img, const VPIImageData *data)
	Redefines the wrapped memory in an existing VPIImage wrapper. More...

void	vpiImageDestroy (VPIImage img)
	Destroy an image instance. More...

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

VPIStatus	vpiImageGetFormat (VPIImage img, VPIImageFormat *format)
	Get the image format. More...

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

VPIStatus	vpiImageLock (VPIImage img, VPILockMode mode)
	Acquires the lock on an image object. More...

VPIStatus	vpiImageLockData (VPIImage img, VPILockMode mode, VPIImageBufferType bufType, VPIImageData *data)
	Acquires the lock on an image object and returns the image contents. More...

VPIStatus	vpiImageUnlock (VPIImage img)
	Releases the lock on an image object. 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 memory buffers, the user can also create an image object that wraps a user-allocated (and managed) image data using vpiImageCreateWrapper. Similarly to vpiImageCreate, image parameters passed to it are fixed.

The wrapped memory can be redefined by calling vpiImageSetWrapper 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 vpiImageLockData / 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.

Data Structure Documentation

◆ VPIImagePlanePitchLinear

struct VPIImagePlanePitchLinear

Represents one image plane in pitch-linear layout.

Definition at line 111 of file Image.h.

Collaboration diagram for VPIImagePlanePitchLinear:

Data Fields
VPIPixelType	pixelType	Type of each pixel within this plane. If it is VPI_PIXEL_TYPE_INVALID, it will be inferred from VPIImageBufferPitchLinear::format.
int32_t	width	Width of this plane in pixels. It must be >= 1.
int32_t	height	Height of this plane in pixels. It must be >= 1.
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 + pitchBytesheight)+width; VPIImagePlanePitchLinear::data void * data Pointer to the first row of this plane. Definition: Image.h:141 VPIImagePlanePitchLinear::height int32_t height Height of this plane in pixels. Definition: Image.h:123 VPIImagePlanePitchLinear::width int32_t width Width of this plane in pixels. Definition: Image.h:119 VPIImagePlanePitchLinear::pitchBytes int32_t pitchBytes Difference in bytes of beginning of one row and the beginning of the previous. Definition: Image.h:134 where T is the C type related to pixelType. It must be at least `(width * \ref vpiPixelTypeGetBitsPerPixel(pixelType) + 7)/8`.
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.

◆ VPIImageBufferPitchLinear

struct VPIImageBufferPitchLinear

Stores the image plane contents.

Definition at line 149 of file Image.h.

Collaboration diagram for VPIImageBufferPitchLinear:

Data Fields
VPIImageFormat	format	Image format.
int32_t	numPlanes	Number of planes. Must be >= 1.
VPIImagePlanePitchLinear	planes[VPI_MAX_PLANE_COUNT]	Data of all image planes in pitch-linear layout. Only the first numPlanes elements must have valid data.

◆ VPIImageBuffer

union VPIImageBuffer

Represents the available methods to access image contents.

The correct method depends on VPIImageData::bufferType.

Definition at line 203 of file Image.h.

Collaboration diagram for VPIImageBuffer:

Data Fields
VPIImageBufferPitchLinear	pitch	Image stored in pitch-linear layout. To be used when VPIImageData::bufferType is: VPI_IMAGE_BUFFER_HOST_PITCH_LINEAR VPI_IMAGE_BUFFER_CUDA_PITCH_LINEAR
cudaArray_t	cudaarray	Image stored in a `cudaArray_t`. To be used when VPIImageData::bufferType is: VPI_IMAGE_BUFFER_CUDA_ARRAY
EGLImageKHR	egl	Image stored as an EGLImageKHR. To be used when VPIImageData::bufferType is: VPI_IMAGE_BUFFER_EGLIMAGE
int	fd	Image stored as an NvBuffer file descriptor. To be used when VPIImageData::bufferType is: VPI_IMAGE_BUFFER_NVBUFFER

◆ VPIImageData

struct VPIImageData

Stores information about image characteristics and content.

Definition at line 233 of file Image.h.

Collaboration diagram for VPIImageData:

Data Fields
VPIImageBufferType	bufferType	Type of image buffer. It defines which member of the VPIImageBuffer tagged union that must be used to access the image contents.
VPIImageBuffer	buffer	Stores the image contents.

◆ VPIImageWrapperParams

struct VPIImageWrapperParams

Parameters for customizing image wrapping.

These parameters are used to customize how image wrapping will be made. Make sure to call vpiInitImageWrapperParams to initialize this structure before updating its attributes. This guarantees that new attributes added in future versions will have a suitable default value assigned.

Definition at line 293 of file Image.h.

Collaboration diagram for VPIImageWrapperParams:

Data Fields
VPIColorSpec	colorSpec	Color spec to override the one defined by the VPIImageData wrapper. If set to VPI_COLOR_SPEC_DEFAULT, infer the color spec from VPIImageData, i.e., no overriding will be done.

Enumeration Type Documentation

◆ VPIImageBufferType

enum VPIImageBufferType

#include </opt/nvidia/vpi3/include/vpi/Image.h>

Represents how the image data is stored.

Enumerator
VPI_IMAGE_BUFFER_INVALID	Invalid buffer type. This is commonly used to inform that no buffer type was selected.
VPI_IMAGE_BUFFER_HOST_PITCH_LINEAR	Host-accessible with planes in pitch-linear memory layout.
VPI_IMAGE_BUFFER_CUDA_PITCH_LINEAR	CUDA-accessible with planes in pitch-linear memory layout.
VPI_IMAGE_BUFFER_CUDA_ARRAY	Buffer stored in a cudaArray_t. Please consult cudaArray_t for more information.
VPI_IMAGE_BUFFER_EGLIMAGE	EGLImage. Please consult EGLImageKHR for more information.
VPI_IMAGE_BUFFER_NVBUFFER	NvBuffer. Please consult NvBuffer for more information. Note Interop with NvBuffer objects created with older nvbuf_utils isn't supported anymore.

Definition at line 165 of file Image.h.

Function Documentation

◆ vpiImageCreate()

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

#include </opt/nvidia/vpi3/include/vpi/Image.h>

Create an empty image instance with the specified flags.

Image data is zeroed.

The following flags affect the behavior of the allocated image

Parameters

[in]	width,height	Dimensions of the created image. Width and height must be > 0.
[in]	fmt	Format of the created image. Must be a valid format.
[in]	flags	Bit field specifying the desired characteristics of the image. The field must be a combination of zero or more of the following flags: VPIBackend flags. This image can be used in algorithms running in these backends. If no backend flags are given and VPI_REQUIRE_BACKENDS is not set, it'll consider all backends supported by the active VPIContext, but disable the backends that are incompatible with the given image parameters. VPI_RESTRICT_MEM_USAGE For block-linear formats, this flag will avoid an internal pitch-linear buffer alocation. The downside is that vpiImageLockData will fail for these formats. Pass this flag if system is under memory restrictions, and no image locking is required. Common object flags. If flag VPI_REQUIRE_BACKENDS is given, user must pass at least one valid backend that is enabled in current context AND is compatible with the given image parameters.
[out]	img	Pointer to memory that will receive the created image handle.

Return values

VPI_ERROR_INVALID_ARGUMENT	Output `img` handle is NULL.
VPI_ERROR_INVALID_ARGUMENT	`width` or `height` outside valid range.
VPI_ERROR_INVALID_ARGUMENT	`fmt` is invalid or not supported.
VPI_ERROR_INVALID_ARGUMENT	`flags` is invalid.
VPI_ERROR_INVALID_ARGUMENT	No backend were given and VPI_REQUIRE_BACKENDS is set.
VPI_ERROR_OUT_OF_MEMORY	Not enough resources to allocate image.
VPI_ERROR_INVALID_CONTEXT	Current context was destroyed.
VPI_ERROR_INVALID_OPERATION	Some requested backend isn't enabled in current context.
VPI_ERROR_INVALID_OPERATION	Some requested backend can't be created with given image parameters.
VPI_SUCCESS	Operation executed successfully.

◆ vpiInitImageWrapperParams()

VPIStatus vpiInitImageWrapperParams ( VPIImageWrapperParams * params )

#include </opt/nvidia/vpi3/include/vpi/Image.h>

Initialize VPIImageWrapperParams with default values.

Default values are:

colorSpec: VPI_COLOR_SPEC_DEFAULT, color spec won't be overriden.

Parameters

[in]

params

Structure to be initialized with default values.

Mandatory, can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	`params` is NULL.
VPI_SUCCESS	Operation executed successfully.

◆ vpiImageCreateView()

VPIStatus vpiImageCreateView	(	VPIImage	imgParent,
		const VPIRectangleI *	clipBounds,
		uint64_t	flags,
		VPIImage *	imgView
	)

#include </opt/nvidia/vpi3/include/vpi/Image.h>

Create an image that wraps an axis-aligned rectangular sub-region of an existing image.

Create an image instance that is a view of the input image with specific position (x, y), dimensions (width, height) and flags. The resulting image shares the underlying data with the input image, i.e. there is no copy involved in the creation of a view. Similarly to creating image instances that wrap around external buffers, the resulting image view instances do not own the data. It is legal to create a view from another image view instance.

Parameters

[in]	imgParent	Handle to the input parent image. Mandatory, it can't be NULL. On Tegra devices: parent image must be either wrapping CPU or CUDA buffer, or have only CPU or CUDA backends enabled. It must not be destroyed while there are image views associated with it.
[in]	clipBounds	Rectangle defining the clip bounds of the created image view. The rectangle must be inside input parent image.
[in]	flags	Flags with the characteristics of the created image view. They must be combination of zero or more of the following flags: VPIBackend flags. This image view will work with streams with these backends enabled. The enable backends must have some common backend with the input image flags. If no backend flags are passed, it'll consider all backends supported by the active VPIContext.
[out]	imgView	Pointer to memory that will receive the created image view handle. Mandatory, it can't be NULL.

Return values

VPI_ERROR_INVALID_OPERATION	`imgView` cannot be created with the given `imgParent`.
VPI_ERROR_INVALID_OPERATION	The backends in `imgParent` and `flags` are not compatible.
VPI_ERROR_INVALID_ARGUMENT	Input parent image `imgParent` is NULL.
VPI_ERROR_INVALID_ARGUMENT	`imgParent` has no backends.
VPI_ERROR_INVALID_ARGUMENT	`output` handle is NULL.
VPI_ERROR_INVALID_ARGUMENT	`clipBounds` is NULL or outside the valid range.
VPI_ERROR_INVALID_ARGUMENT	`flags` are invalid.
VPI_ERROR_NOT_IMPLEMENTED	Image view is not implemented for the given input parent image.
VPI_ERROR_INVALID_CONTEXT	`imgParent` and `imgView` contexts are different.
VPI_ERROR_INVALID_CONTEXT	Current context was destroyed.
VPI_SUCCESS	Operation executed successfully.

◆ vpiImageSetView()

VPIStatus vpiImageSetView	(	VPIImage	view,
		VPIImage	parent,
		const VPIRectangleI *	clipBounds
	)

#include </opt/nvidia/vpi3/include/vpi/Image.h>

Redefines the image view position inside a parent image.

This operation is efficient and does not allocate memory. The view memory will be accessible to the same backends specified during view creation. The parent image may be the original parent of the view or a new parent.

Parameters

[in]	view	Handle to image view. It must have been created by vpiImageCreateView.
[in]	parent	Handle to a potentially new input parent image. The parent image format must match the view's. Mandatory, it can't be NULL. On Tegra devices: parent image must be either wrapping CPU or CUDA buffer, or have only CPU or CUDA backends enabled. It must not be destroyed while there are image views associated with it.
[in]	clipBounds	Rectangle defining the clip bounds of the redefined image view. The rectangle must be inside chosen parent image. The width and height of the rectangle must be the same as the image view.

Return values

VPI_ERROR_INVALID_ARGUMENT	Input `view` is NULL.
VPI_ERROR_INVALID_ARGUMENT	Input `parent` is NULL.
VPI_ERROR_INVALID_ARGUMENT	`clipBounds` is NULL.
VPI_ERROR_INVALID_ARGUMENT	`clipBounds` is outside valid range.
VPI_ERROR_INVALID_ARGUMENT	`clipBounds` has different size than image view.
VPI_ERROR_INVALID_ARGUMENT	`parent` image format does not match `view` image format.
VPI_ERROR_INVALID_ARGUMENT	`parent` has no backends.
VPI_ERROR_INVALID_OPERATION	`view` is not created using vpiImageCreateView.
VPI_ERROR_INVALID_OPERATION	`view` cannot be redefined with the given `parent`.
VPI_SUCCESS	Operation executed successfully.

◆ vpiImageCreateWrapper()

VPIStatus vpiImageCreateWrapper	(	const VPIImageData *	data,
		const VPIImageWrapperParams *	params,
		uint64_t	flags,
		VPIImage *	img
	)

#include </opt/nvidia/vpi3/include/vpi/Image.h>

Create an image object by wrapping an existing memory block.

The underlying image object does not own/claim the memory block.

Parameters

[in]

data

Pointer to structure with memory to be wrapped.

Mandatory, it can't be NULL.
The following buffer types are supported:
- VPI_IMAGE_BUFFER_HOST_PITCH_LINEAR
- VPI_IMAGE_BUFFER_CUDA_PITCH_LINEAR
- VPI_IMAGE_BUFFER_EGLIMAGE (on Tegra platforms only)
- VPI_IMAGE_BUFFER_NVBUFFER (on Tegra platforms only)

[in] params If not NULL, use the parameters to modify how data is wrapped. Otherwise, it'll use defaults given by vpiInitImageWrapperParams.

[in]

flags

Bit field specifying the desired characteristics of the image. Depending on some buffer types, the following flags will be added automatically:

Buffer type	Added flag
VPI_IMAGE_BUFFER_HOST_PITCH_LINEAR	VPI_BACKEND_CPU
VPI_IMAGE_BUFFER_CUDA_PITCH_LINEAR	VPI_BACKEND_CUDA

The field must be a combination of zero or more of the following flags:
- VPIBackend flags. This image can be used in algorithms running in these backends. If no backend flags are given and VPI_REQUIRE_BACKENDS is not set, it'll consider all backends supported by the active VPIContext, but disable the backends that are incompatible with the given image parameters.
- VPI_RESTRICT_MEM_USAGE For block-linear formats, this flag will avoid an internal pitch-linear buffer alocation. The downside is that vpiImageLockData will fail for these formats. Pass this flag if system is under memory restrictions, and no image locking is required.
- Common object flags.
If backends are given and VPI_REQUIRE_BACKENDS is set, they all must enabled in current context.
If backends are automatically added, they must be enabled in current context.

Parameters

[out] img Pointer to memory that will receive the created image handle.

Return values

VPI_ERROR_INVALID_ARGUMENT	`img` is NULL.
VPI_ERROR_INVALID_ARGUMENT	`data` is NULL or contains invalid/unsupported values.
VPI_ERROR_INVALID_ARGUMENT	Buffer type in `data` isn't supported.
VPI_ERROR_INVALID_ARGUMENT	EGLImage handle is NULL or invalid (e.g. EGL_NO_IMAGE).
VPI_ERROR_INVALID_ARGUMENT	NvBuffer file descriptor is invalid.
VPI_ERROR_INVALID_ARGUMENT	No backend were given and VPI_REQUIRE_BACKENDS is set.
VPI_ERROR_OUT_OF_MEMORY	Not enough resources to create image.
VPI_ERROR_INTERNAL	Can't retrieve default EGLDisplay when wrapping EGLImage, or some unspecified internal error.
VPI_ERROR_INVALID_CONTEXT	Current context is destroyed.
VPI_ERROR_INVALID_OPERATION	Requested backend isn't enabled in current context.
VPI_ERROR_INVALID_OPERATION	A requested backend can't be created with given image parameters.
VPI_SUCCESS	Operation executed successfully.

Here is the caller graph for this function:

◆ vpiImageSetWrapper()

VPIStatus vpiImageSetWrapper	(	VPIImage	img,
		const VPIImageData *	data
	)

#include </opt/nvidia/vpi3/include/vpi/Image.h>

Redefines the wrapped memory in an existing VPIImage wrapper.

This operation is efficient and does not allocate memory. The wrapped memory will be accessible to the same backends specified during wrapper creation.

The wrapped memory must not be deallocated while it's still being wrapped.

Parameters

[in]	img	Handle to image. It must have been created by vpiImageCreateWrapper Image must not be locked.
[in]	data	Pointer to structure with memory buffer to be wrapped. Mandatory, it can't be NULL. The existing wrapped image and the new one must have same dimensions and format. The old and new buffer types must match. The wrapped memory must point to a buffer that corresponds to the given buffer type.

Return values

VPI_ERROR_INVALID_ARGUMENT	`data` is NULL.
VPI_ERROR_INVALID_ARGUMENT	New and old buffer types don't match.
VPI_ERROR_INVALID_ARGUMENT	`data` dimensions and/or format don't match `img`.
VPI_ERROR_INVALID_ARGUMENT	Wrapped EGLImage is invalid (e.g. EGL_NO_IMAGE).
VPI_ERROR_INTERNAL	Cannot retrieve EGLDisplay.
VPI_ERROR_INVALID_OPERATION	`img` is not created using vpiImageCreateWrapper.
VPI_ERROR_INVALID_OPERATION	`img` is locked.
VPI_ERROR_INVALID_OPERATION	EGL/NvBuffer wrapping not supported on this platform.
VPI_SUCCESS	Operation executed successfully.

Here is the caller graph for this function:

◆ vpiImageDestroy()

void vpiImageDestroy ( VPIImage img )

#include </opt/nvidia/vpi3/include/vpi/Image.h>

Destroy an image instance.

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

Parameters

[in]

img

img to be destroyed. Passing NULL is allowed, to which the function simply does nothing.

Image must not be in use by any stream, or else undefined behavior might ensue.

◆ vpiImageGetSize()

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

#include </opt/nvidia/vpi3/include/vpi/Image.h>

Get the image dimensions in pixels.

Parameters

[in]	img	Image to be queried. Mandatory, it can't be NULL.
[out]	width,height	Pointers to buffers where the image width and height (respectively) will be written to.

Return values

VPI_ERROR_INVALID_ARGUMENT	`img` is NULL or doesn't represent a VPIImage instance.
VPI_ERROR_INVALID_ARGUMENT	Output `width` or `height` pointers are NULL.
VPI_SUCCESS	Operation executed successfully.

◆ vpiImageGetFormat()

VPIStatus vpiImageGetFormat	(	VPIImage	img,
		VPIImageFormat *	format
	)

#include </opt/nvidia/vpi3/include/vpi/Image.h>

Get the image format.

Parameters

[in]	img	Image to be queried. Mandatory, it can't be NULL.
[out]	format	A pointer to where the mage format will be written to. Mandatory, it can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	`img` is NULL or doesn't represent a VPIImage instance.
VPI_ERROR_INVALID_ARGUMENT	`format` pointer is NULL.
VPI_SUCCESS	Operation executed successfully

Here is the caller graph for this function:

◆ vpiImageGetFlags()

VPIStatus vpiImageGetFlags	(	VPIImage	img,
		uint64_t *	flags
	)

#include </opt/nvidia/vpi3/include/vpi/Image.h>

Get the image flags.

Parameters

[in]	img	Image to be queried. Mandatory, it can't be NULL.
[out]	flags	A pointer to where the flags will be written to. Mandatory, it can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	`flags` pointer is NULL.
VPI_ERROR_INVALID_ARGUMENT	`img` is NULL or doesn't represent a VPIImage instance.
VPI_SUCCESS	Operation executed successfully.

◆ vpiImageLock()

VPIStatus vpiImageLock	(	VPIImage	img,
		VPILockMode	mode
	)

#include </opt/nvidia/vpi3/include/vpi/Image.h>

Acquires the lock on an image object.

Image locking is required when the image object wraps externally-accessible buffers, and these buffers will be accessed outside VPI. As long as the lock is held, any attempt of VPI to access the image in a mode not compatible with the lock mode will result in asynchronous stream errors, VPI_ERROR_BUFFER_LOCKED.

The image can be locked multiple times. Each lock operation increments a counter and must be matched by a corresponding vpiImageUnlock call.

Parameters

[in]	img	Image to be locked. Mandatory, it can't be NULL. Image must not be locked in a mode that is incompatible with given `mode`.
[in]	mode	Lock mode, depending on whether the memory will be written to and/or read from. Valid values: VPI_LOCK_READ VPI_LOCK_WRITE VPI_LOCK_READ_WRITE

Return values

VPI_ERROR_INVALID_ARGUMENT	`img` is NULL or doesn't represent a VPIImage instance.
VPI_ERROR_BUFFER_LOCKED	Image is already locked by either a stream or the user.
VPI_SUCCESS	Operation executed successfully.

◆ vpiImageLockData()

VPIStatus vpiImageLockData	(	VPIImage	img,
		VPILockMode	mode,
		VPIImageBufferType	bufType,
		VPIImageData *	data
	)

#include </opt/nvidia/vpi3/include/vpi/Image.h>

Acquires the lock on an image object and returns the image contents.

Depending on the internal image representation, as well as the actual location in memory, this function might have a significant performance overhead due to format conversion, layout conversion, device-to-host memory copy, etc.

The image can be locked multiple times. Each lock operation increments a counter and must be matched by a corresponding vpiImageUnlock call.

Parameters

[in]

img

Image to be locked.

Mandatory, it can't be NULL.
Image must not be locked in a mode that is incompatible with given mode.
For some buffer types, the image must have the following backend enabled:

Buffer type Required backend flags

VPI_IMAGE_BUFFER_HOST_PITCH_LINEAR VPI_BACKEND_CPU

VPI_IMAGE_BUFFER_CUDA_PITCH_LINEAR VPI_BACKEND_CUDA

[in]

mode

Lock mode, depending on whether the memory will be written to and/or read from.

Valid values:

[in]

bufType

The type of buffer returned in data. It defines how the image contents can be accessed by the caller. Valid types are:

[out]

data

A pointer to a structure that will be filled with image memory contents information.

Must not be NULL.
The buffers it points to are valid until the image is unlocked.

Return values

VPI_ERROR_INVALID_ARGUMENT	`img` is NULL or doesn't represent a VPIImage instance.
VPI_ERROR_INVALID_ARGUMENT	`data` must not be NULL.
VPI_ERROR_INVALID_ARGUMENT	`bufType` isn't supported.
VPI_ERROR_INVALID_OPERATION	`img` doesn't have required backends enabled.
VPI_ERROR_BUFFER_LOCKED	Image is already locked by either a stream or the user.
VPI_SUCCESS	Operation executed successfully.

◆ vpiImageUnlock()

VPIStatus vpiImageUnlock ( VPIImage img )

#include </opt/nvidia/vpi3/include/vpi/Image.h>

Releases the lock on an image object.

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

Parameters

[in]

img

Image to be unlocked.

Mandatory, it can't be NULL.
Image must have CPU backend enabled.

Return values

VPI_ERROR_INVALID_ARGUMENT	`img` is NULL or doesn't represent a VPIImage instance.
VPI_ERROR_INVALID_OPERATION	`img` isn't locked.
VPI_SUCCESS	Operation executed successfully.

VPI - Vision Programming Interface

3.0 Release

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ VPIImagePlanePitchLinear

◆ VPIImageBufferPitchLinear

◆ VPIImageBuffer

◆ VPIImageData

◆ VPIImageWrapperParams

Enumeration Type Documentation

◆ VPIImageBufferType

Function Documentation

◆ vpiImageCreate()

◆ vpiInitImageWrapperParams()

◆ vpiImageCreateView()

◆ vpiImageSetView()

◆ vpiImageCreateWrapper()

◆ vpiImageSetWrapper()

◆ vpiImageDestroy()

◆ vpiImageGetSize()

◆ vpiImageGetFormat()

◆ vpiImageGetFlags()

◆ vpiImageLock()

◆ vpiImageLockData()

◆ vpiImageUnlock()