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, uint32_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, uint32_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, VPIPyramidData *out) |
Acquires the lock on a pyramid object and returns pointers to each level of the pyramid. More... | |
VPIStatus | vpiPyramidUnlock (VPIPyramid pyr) |
Releases the lock on a image pyramid object. More... | |
VPIStatus | vpiImageCreatePyramidLevelWrapper (VPIPyramid pyr, int32_t level, VPIImage *img) |
Creates an image that wraps one pyramid level. More... | |
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 vpiPyramidLock / 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.
struct VPIPyramidData |
Stores the pyramid contents.
Every level is represented by an entire VPIImageData. There are numLevels
levels, and they can be accessed from levels[0]
to levels[numLevels-1]
.
Data Fields | ||
---|---|---|
VPIImageData | levels[VPI_MAX_PYRAMID_LEVEL_COUNT] |
Scale factor of resolution between two adjecent levels. Contents of every pyramid level. Only the first numLevels levels has valid data. |
int32_t | numLevels |
Number of levels (i.e. height) of the pyramid. |
float | scale |
VPIStatus vpiImageCreatePyramidLevelWrapper | ( | VPIPyramid | pyr, |
int32_t | level, | ||
VPIImage * | img | ||
) |
#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.
[in] | pyr | The pyramid whose level will be wrapped. |
[in] | level | Pyramid level to wrap. |
[out] | img | Pointer to an image handle that will hold the created image. |
VPIStatus vpiPyramidCreate | ( | int32_t | width, |
int32_t | height, | ||
VPIImageFormat | fmt, | ||
int32_t | numLevels, | ||
float | scale, | ||
uint32_t | flags, | ||
VPIPyramid * | pyr | ||
) |
#include <vpi/Pyramid.h>
Create an empty image pyramid instance with the specified flags.
Pyramid data is zeroed.
[in] | width,height | Dimensions of the finest pyramid level. |
[in] | numLevels | Number of levels. |
[in] | scale | Downscale factor from one level and the next. |
[in] | fmt | Image format of each level. |
[in] | flags | Pyramid flags. Here it can be specified in what backends the pyramid 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] | pyr | Pointer to memory that will receive the created pyramid handle. |
void vpiPyramidDestroy | ( | VPIPyramid | pyr | ) |
#include <vpi/Pyramid.h>
Destroy an image pyramid instance as well as all resources it owns.
[in] | pyr | pyramid handle |
VPIStatus vpiPyramidGetFlags | ( | VPIPyramid | pyr, |
uint32_t * | flags | ||
) |
#include <vpi/Pyramid.h>
Returns the flags associated with the pyramid.
[in] | pyr | pyramid handle |
[out] | flags | pointer to where the flags will be written. |
VPIStatus vpiPyramidGetFormat | ( | VPIPyramid | pyr, |
VPIImageFormat * | fmt | ||
) |
#include <vpi/Pyramid.h>
Returns the image format of the pyramid levels.
[in] | pyr | pyramid handle |
[out] | fmt | pointer to where the image format will be written. |
VPIStatus vpiPyramidGetNumLevels | ( | VPIPyramid | pyr, |
int32_t * | numLevels | ||
) |
#include <vpi/Pyramid.h>
Get the image pyramid level count.
[in] | pyr | an image pyramid handle |
[out] | numLevels | a pointer to a variable which will be set to the number of levels of the image pyramid |
VPIStatus vpiPyramidGetScale | ( | VPIPyramid | pyr, |
float * | scale | ||
) |
#include <vpi/Pyramid.h>
Returns the scale factor of the pyramid levels.
[in] | pyr | pyramid handle |
[out] | scale | pointer to where the scale will be written. |
VPIStatus vpiPyramidGetSize | ( | VPIPyramid | pyr, |
int32_t | outSize, | ||
int32_t * | outWidth, | ||
int32_t * | outHeight | ||
) |
#include <vpi/Pyramid.h>
Get the image width and height in pixels (for all levels at once).
[in] | pyr | an image pyramid handle |
[in] | outSize | size of the output arrays, in elements. |
[out] | outWidth,outHeight | Pointers to a C array which will be filled widths and heights (respectively) of all image pyramid levels. If any of them is NULL, the corresponding data isn't returned. |
VPIStatus vpiPyramidLock | ( | VPIPyramid | pyr, |
VPILockMode | lock, | ||
VPIPyramidData * | out | ||
) |
#include <vpi/Pyramid.h>
Acquires the lock on a pyramid object and returns 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).
[in] | pyr | an image pyramid handle |
[in] | lock | lock mode |
[out] | out | a pointer to a structure that will receive the pyramid data to be accessed by host. If it's NULL, the pyramid will still be locked. This is useful to make sure wrapped image is updated. |
VPIStatus vpiPyramidUnlock | ( | VPIPyramid | pyr | ) |
#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).
[in] | pyr | an image pyramid handle |