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

Data Structures
struct	VPIPyramidData
	Stores the pyramid contents. More...

Macros
#define	VPI_MAX_PYRAMID_LEVEL_COUNT (10)
	Maximum number of pyramid levels.

Typedefs
typedef struct VPIPyramidImpl *	VPIPyramid
	A handle to an image pyramid.

Functions
VPIStatus	vpiPyramidCreate (int32_t width, int32_t height, VPIImageFormat fmt, int32_t numLevels, float scale, uint64_t flags, VPIPyramid *pyr)
	Create an empty image pyramid instance with the specified flags. More...

void	vpiPyramidDestroy (VPIPyramid pyr)
	Destroy an image pyramid instance as well as all resources it owns. More...

VPIStatus	vpiPyramidGetFlags (VPIPyramid pyr, uint64_t *flags)
	Returns the flags associated with the pyramid. More...

VPIStatus	vpiPyramidGetFormat (VPIPyramid pyr, VPIImageFormat *fmt)
	Returns the image format of the pyramid levels. More...

VPIStatus	vpiPyramidGetNumLevels (VPIPyramid pyr, int32_t *numLevels)
	Get the image pyramid level count. More...

VPIStatus	vpiPyramidGetSize (VPIPyramid pyr, int32_t outSize, int32_t outWidth, int32_t outHeight)
	Get the image width and height in pixels (for all levels at once). More...

VPIStatus	vpiPyramidGetScale (VPIPyramid pyr, float *scale)
	Returns the scale factor of the pyramid levels. More...

VPIStatus	vpiPyramidLock (VPIPyramid pyr, VPILockMode lock)
	Acquires the lock on an pyramid object. More...

VPIStatus	vpiPyramidLockData (VPIPyramid pyr, VPILockMode lock, VPIImageBufferType bufType, VPIPyramidData *out)
	Acquires the lock on a pyramid object and returns host-accessible pointers to each level of the pyramid. More...

VPIStatus	vpiPyramidUnlock (VPIPyramid pyr)
	Releases the lock on a image pyramid object. More...

VPIStatus	vpiImageCreateWrapperPyramidLevel (VPIPyramid pyr, int32_t level, VPIImage *img)
	Creates an image that wraps one pyramid level. More...

Detailed Description

An abstract representation of a 2D image pyramid.

2D image pyramid containers are created by calling vpiPyramidCreate to allocate and initialize an empty (zeroed) VPIPyramid object. The memory for the image pyramid data is allocated and managed by VPI.

Image formats match the ones supported by image container. The pyramid is not necessarily dyadic. The scale between levels is defined in the constructor.

Parameters such as levels, scale, width, height and image format are immutable and specified at the construction time. The internal memory layout is also backend-specific. More importantly, efficient exchange of image pyramid 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.

The set of vpiPyramidLockData / vpiPyramidUnlock calls allows the user 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 pyramid as input or output are finished. Also, depending on the enabled backends lock/unlock operation might be time-consuming and, for example, involve copying data over PCIe bus for dGPUs.

Data Structure Documentation

◆ VPIPyramidData

struct VPIPyramidData

Stores the pyramid contents.

Each level is represented by an entire VPIImageData. There are numLevels levels, and they can be accessed from levels[0] to levels[numLevels-1].

Definition at line 111 of file Pyramid.h.

Collaboration diagram for VPIPyramidData:

Data Fields
int32_t	numLevels	Number of levels (i.e. height) of the pyramid.
float	scale	Scale factor of resolution between two adjecent levels.
VPIImageData	levels[VPI_MAX_PYRAMID_LEVEL_COUNT]	Contents of every pyramid level. Only the first numLevels levels has valid data.

Function Documentation

◆ vpiPyramidCreate()

VPIStatus vpiPyramidCreate	(	int32_t	width,
		int32_t	height,
		VPIImageFormat	fmt,
		int32_t	numLevels,
		float	scale,
		uint64_t	flags,
		VPIPyramid *	pyr
	)

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

Create an empty image pyramid instance with the specified flags.

Pyramid data is zeroed.

Parameters

[in]	width,height	Dimensions of the finest pyramid level. Width and height must be > 0.
[in]	numLevels	Number of levels. Must be >= 1 and <= VPI_MAX_PYRAMID_LEVEL_COUNT.
[in]	scale	Scale factor from one level and the next. Must be > 0 and <= 1.
[in]	fmt	Image format of each level. Accepts non-YUV or YUV 4:4:4 formats (no chroma subsampling allowed) CPU and CUDA backends only support pitch-linear formats. Can't be VPI_IMAGE_FORMAT_INVALID.
[in]	flags	Bit field specifying the desired characteristics of the pyramid. The field must be a combination of zero or more of the following flags: VPIBackend flags. This pyramid 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. 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]	pyr	Pointer to memory that will receive the created pyramid handle.

Return values

VPI_ERROR_INVALID_ARGUMENT	Output `pyr` is NULL.
VPI_ERROR_INVALID_ARGUMENT	`numLevels` outside valid range.
VPI_ERROR_INVALID_ARGUMENT	`width` or `height` outside valid range.
VPI_ERROR_INVALID_ARGUMENT	`scale` outside valid range.
VPI_ERROR_INVALID_ARGUMENT	No backend were given and VPI_REQUIRE_BACKENDS is set.
VPI_ERROR_INVALID_IMAGE_FORMAT	`fmt` is not accepted.
VPI_ERROR_INVALID_ARGUMENT	Invalid `flags`.
VPI_ERROR_OUT_OF_MEMORY	Not enough resources to create image.
VPI_ERROR_INVALID_CONTEXT	Current context it destroyed.
VPI_ERROR_INVALID_OPERATION	Requested backend isn't enabled in current context.
VPI_SUCCESS	Operation executed successfully.

◆ vpiPyramidDestroy()

void vpiPyramidDestroy ( VPIPyramid pyr )

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

Destroy an image pyramid instance as well as all resources it owns.

Parameters

[in]

pyr

Pyramid handle. Passing NULL is allowed, to which the function simply does nothing.

Pyramid must not be in use by any stream, or else undefined behavior will ensue.

◆ vpiPyramidGetFlags()

VPIStatus vpiPyramidGetFlags	(	VPIPyramid	pyr,
		uint64_t *	flags
	)

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

Returns the flags associated with the pyramid.

Parameters

[in]	pyr	Pyramid handle. Mandatory, it can't be NULL.
[out]	flags	Pointer to where the flags will be written. Mandatory, it can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	Output `flags` pointer is NULL.
VPI_ERROR_INVALID_ARGUMENT	`pyr` is NULL or doesn't represent a VPIPyramid instance.
VPI_SUCCESS	Operation executed successfully.

◆ vpiPyramidGetFormat()

VPIStatus vpiPyramidGetFormat	(	VPIPyramid	pyr,
		VPIImageFormat *	fmt
	)

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

Returns the image format of the pyramid levels.

Parameters

[in]	pyr	Pyramid handle. Mandatory, it can't be NULL.
[out]	fmt	Pointer to where the image format will be written. Mandatory, it can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	Output `fmt` is NULL.
VPI_ERROR_INVALID_ARGUMENT	`pyr` is NULL or doesn't represent a VPIPyramid instance.
VPI_SUCCESS	Operation executed successfully.

◆ vpiPyramidGetNumLevels()

VPIStatus vpiPyramidGetNumLevels	(	VPIPyramid	pyr,
		int32_t *	numLevels
	)

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

Get the image pyramid level count.

Parameters

[in]	pyr	Pyramid handle. Mandatory, it can't be NULL.
[out]	numLevels	A pointer to a variable which will be set to the number of levels of the image pyramid. Mandatory, it can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	Output `numLevels` pointer is NULL.
VPI_ERROR_INVALID_ARGUMENT	`pyr` is NULL or doesn't represent a VPIPyramid instance.
VPI_SUCCESS	Operation executed successfully.

◆ vpiPyramidGetSize()

VPIStatus vpiPyramidGetSize	(	VPIPyramid	pyr,
		int32_t	outSize,
		int32_t *	outWidth,
		int32_t *	outHeight
	)

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

Get the image width and height in pixels (for all levels at once).

Parameters

[in]	pyr	Pyramid handle. Mandatory, it can't be NULL.
[in]	outSize	Size of the output arrays, in elements. Must be >= 1.
[out]	outWidth,outHeight	Pointers to an array which will be filled with widths and heights (respectively) of all image pyramid levels. If any of them is NULL, the corresponding data isn't returned.

Return values

VPI_ERROR_INVALID_ARGUMENT	`outSize` outside valid range.
VPI_ERROR_INVALID_ARGUMENT	`pyr` is NULL or doesn't represent a VPIPyramid instance.
VPI_ERROR_INVALID_ARGUMENT	`outWidth` and `outHeight` can't be NULL.
VPI_SUCCESS	Operation executed successfully.

◆ vpiPyramidGetScale()

VPIStatus vpiPyramidGetScale	(	VPIPyramid	pyr,
		float *	scale
	)

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

Returns the scale factor of the pyramid levels.

Parameters

[in]	pyr	Pyramid handle. Mandatory, it can't be NULL.
[out]	scale	Pointer to where the scale will be written. Mandatory, it can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	Output `scale` pointer is NULL.
VPI_ERROR_INVALID_ARGUMENT	`pyr` is NULL or doesn't represent a VPIPyramid instance.
VPI_SUCCESS	Operation executed successfully.

◆ vpiPyramidLock()

VPIStatus vpiPyramidLock	(	VPIPyramid	pyr,
		VPILockMode	lock
	)

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

Acquires the lock on an pyramid object.

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.

Parameters

[in]	pyr	Pyramid handle. Mandatory, it can't be NULL. Pyramid must not be locked in a mode that is incompatible with given `mode`.
[in]	lock	Lock mode. Valid values are: VPI_LOCK_READ VPI_LOCK_WRITE VPI_LOCK_READ_WRITE

Return values

VPI_ERROR_INVALID_ARGUMENT	`pyr` is NULL or doesn't represent a VPIPyramid instance.
VPI_ERROR_BUFFER_LOCKED	Pyramid is already locked by either a stream or the user.
VPI_ERROR_INVALID_ARGUMENT	`out` is NULL.
VPI_SUCCESS	Operation executed successfully

◆ vpiPyramidLockData()

VPIStatus vpiPyramidLockData	(	VPIPyramid	pyr,
		VPILockMode	lock,
		VPIImageBufferType	bufType,
		VPIPyramidData *	out
	)

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

Acquires the lock on a pyramid object and returns host-accessible pointers to each level of the pyramid.

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).

Parameters

[in]

pyr

Pyramid handle.

Mandatory, it can't be NULL.
Pyramid must not be locked in a mode that is incompatible with given mode.
For some buffer types, the pyramid 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]

lock

Lock mode.

Valid values are:

[in]

bufType

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

VPI_IMAGE_BUFFER_HOST_PITCH_LINEAR

[out]

out

A pointer to a structure that will receive the pyramid data to be accessed from host. Pass NULL if you're only interested in making sure that the wrapped image is updated with the most recent contents from VPI. The image will still be locked.

The buffers it points to are valid until the pyramid is unlocked.

Return values

VPI_ERROR_INVALID_ARGUMENT	`pyr` is NULL or doesn't represent a VPIPyramid instance.
VPI_ERROR_INVALID_OPERATION	`img` doesn't have required backends enabled.
VPI_ERROR_INVALID_ARGUMENT	`out` is NULL.
VPI_ERROR_BUFFER_LOCKED	Pyramid is already locked by either a stream or the user.
VPI_SUCCESS	Operation executed successfully

◆ vpiPyramidUnlock()

VPIStatus vpiPyramidUnlock ( VPIPyramid pyr )

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

Releases the lock on a image pyramid object.

This function might have a significant performance overhead (format conversion, layout conversion, host-to-device memory copy).

Parameters

[in]

pyr

Pyramid handle.

Mandatory, it can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	`pyr` is NULL or doesn't represent a VPIPyramid instance.
VPI_ERROR_INVALID_OPERATION	`pyr` doesn't have CPU backend enabled.
VPI_ERROR_INVALID_OPERATION	`pyr` isn't locked.
VPI_SUCCESS	Operation executed successfully.

◆ vpiImageCreateWrapperPyramidLevel()

VPIStatus vpiImageCreateWrapperPyramidLevel	(	VPIPyramid	pyr,
		int32_t	level,
		VPIImage *	img
	)

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

Creates an image that wraps one pyramid level.

The created image doesn't own its contents. Destroying the pyramid while there are images wrapping its levels leads to undefined behavior. If image wraps the base pyramid level, locking the pyramid will also lock the image. Once the image isn't needed anymore, call vpiImageDestroy to free resources.

The created image inherits the flags of the wrapped pyramid, including the enabled backends.

Parameters

[in]	pyr	The pyramid whose level will be wrapped. Mandatory, it can't be NULL.
[in]	level	Pyramid level to wrap. Must be >= 0.
[out]	img	Pointer to an image handle that will hold the created image. Mandatory, it can't be NULL.

Return values

VPI_ERROR_INVALID_ARGUMENT	Output `img` is NULL.
VPI_ERROR_INVALID_ARGUMENT	`pyr` is NULL.
VPI_ERROR_INVALID_ARGUMENT	`level` outside valid range.
VPI_ERROR_INVALID_ARGUMENT	`pyr` is NULL or doesn't represent a VPIPyramid instance.
VPI_ERROR_INVALID_OPERATION	Wrapped image is not created in current context.
VPI_ERROR_INVALID_CONTEXT	Current context was destroyed.
VPI_ERROR_OUT_OF_MEMORY	Not enough resources to create image.
VPI_SUCCESS	Operation executed successfully.

VPI - Vision Programming Interface

3.0 Release

Data Structures

Macros

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ VPIPyramidData

Function Documentation

◆ vpiPyramidCreate()

◆ vpiPyramidDestroy()

◆ vpiPyramidGetFlags()

◆ vpiPyramidGetFormat()

◆ vpiPyramidGetNumLevels()

◆ vpiPyramidGetSize()

◆ vpiPyramidGetScale()

◆ vpiPyramidLock()

◆ vpiPyramidLockData()

◆ vpiPyramidUnlock()

◆ vpiImageCreateWrapperPyramidLevel()