Intel® Integrated Performance Primitives (Intel® IPP) Developer Guide and Reference
WarpBatchGetBufferSize_L
Computes the size of the work buffer for a batch warp.
Syntax
IppStatus ippiWarpBatchGetBufferSize_L(const IppiBatchItem* pSrcBatch, const IppiBatchItem* pDstBatch, IppSizeL nBatchSize, const IppBatchItem* pTransforms, IppiWarpBatchSpec* pSpec, IppSizeL* pBufSize);
Threading Layer (TL) flavor:
IppStatus ippiWarpBatchGetBufferSize_LT(const IppiBatchItem* pSrcBatch, const IppiBatchItem* pDstBatch, IppSizeL nBatchSize, const IppBatchItem* pTransforms, IppiWarpBatchSpec* pSpec, IppSizeL* pBufSize);
Include Files
ippi_l.h
Flavors with the _LT suffix: ippi_tl.h
Domain Dependencies
Headers: ippcore.h, ippvm.h, ipps.h
Libraries: ippcore.lib, ippvm.lib, ipps.lib
Flavors with the _LT suffix additionally require ippcore_tl.h and ippcore_tl.lib.
Parameters
pSrcBatch |
Pointer to the descriptors of the source images of the batch. For a non-uniform batch it points to the array of nBatchSize elements. For a uniform batch, that is when the batchType that pSpec was initialized with carries ippBatchUniformSrc, it points to a single descriptor whose pMem pointer addresses the memory of the entire batch, without gaps. The size field of every descriptor that is read must be set before the call. |
pDstBatch |
Pointer to the descriptors of the destination images of the batch. For a non-uniform batch it points to the array of nBatchSize elements. For a uniform batch, that is when the batchType that pSpec was initialized with carries ippBatchUniformDst, it points to a single descriptor whose pMem pointer addresses the memory of the entire batch, without gaps. The size field of every descriptor that is read must be set before the call. |
nBatchSize |
Number of the images of the batch. A batch of a single image is a legal batch, and an empty batch, that is nBatchSize equal to zero, is legal as well: it has nothing to transform, so the returned size is zero and the function returns the ippStsNoOperation warning. A negative value is an error. |
pTransforms |
Pointer to the descriptors of the transform matrices of the batch. For a non-uniform batch it points to the array of nBatchSize warp transformation matrices, one per image. For a uniform batch, that is when the batchType that pSpec was initialized with carries ippBatchUniformTransform, it points to a single descriptor whose pMem pointer addresses the memory of the entire batch of nBatchSize matrices, without gaps. The pMem field of a descriptor points at allocated memory of the Ipp64f type and its size field counts the coefficients of a single matrix, that is six of the 2x3 matrix of the ippWarpAffine transform and nine of the 3x3 matrix of the ippWarpPerspective transform, both in the row-major order. Must be the array that the WarpBatchInit_L function was called with. |
pSpec |
Pointer to the IppiWarpBatchSpec specification structure of the batch, sized by the WarpBatchGetSize_L function and initialized by the WarpBatchInit_L function. The single image specification structure inside it is used as a scratch space. |
pBufSize |
Pointer to the size, in bytes, of the single work buffer that the warp function of the batch takes. |
Description
This function computes the size of the work buffer that the WarpBatch_L function needs. All images of the batch share one work buffer.
The size of the work buffer is a property of an initialized single image specification structure, which is why this function is separate from the WarpBatchGetSize_L function and takes the specification structure of the batch as a parameter. The function takes no parameter of the batch besides the descriptors and the matrices: the transform of the batch, the data type, the interpolation method, the direction of the transform, the number of the channels, the parameters of the cubic filter, the uniformity of the batch, and the border are the ones the Init function stored in pSpec, so the order of the calls is WarpBatchGetSize_L, WarpBatchInit_L, this function.
The WarpBatch_L function takes one buffer only: it builds the single image specification structure of an image in the work buffer instead of a temporary buffer of its own, so the returned size is the maximum of the work buffer size of the transform and of the temporary buffer size of the initialization of a single image specification structure over the batch. The two roles do not overlap in time, because the specification structure of an image is built before its warp starts.
The work buffer size of the warp of an image depends on its sizes and on its transform matrix, so the function walks the whole batch and returns the maximum over its images, which is why the sizes of every descriptor that is read and the matrices of pTransforms must be set before the call. The uniformity that pSpec carries changes where the image of an index, and the matrix of it, begin and nothing else: the image of the index i of a uniform direction begins at the byte i * size.height * step of its single descriptor and the matrix of the image i of a uniform transform at the element i * size of its single one. Every image of the batch has a transform matrix of its own, a uniform transform included, so the whole batch is walked whatever its uniformity is. An image whose source or destination width or height is zero is not transformed, so it needs no work buffer and it does not contribute to the returned size, and the ippStsNoOperation warning reports it. The returned size of an empty batch is zero. The single image specification structure inside pSpec is used as a scratch space only: its content after the call is undefined, so the warp function does not depend on it. The parameters that the Init function stores are not modified.
The ippWarpPerspective transform of the batch is built on top of the standard, 32-bit-length, flavor of the single image perspective warp, so for that transform the function returns the ippStsExceededSizeErr status whenever one of the sizes or of the steps of the batch does not fit the 32-bit signed integer type.
Call this function after the specification structure has been sized by the WarpBatchGetSize_L function and initialized by the WarpBatchInit_L function, and before the WarpBatch_L function.
For the flavor with the _LT suffix, the returned size covers all the threads that the Threading Layer uses: every thread gets a private slice of the work buffer, so the size grows with the number of threads. The pSpec parameter of the _LT flavor must be sized by ippiWarpBatchGetSize_LT; only the slice of the first thread is written to. The size depends on the number of threads reported by ippGetNumThreads_LT, so call the function again after changing the number of threads with ippSetNumThreads_LT.
Return Values
ippStsNoErr |
Indicates no error. |
ippStsNoOperation |
Indicates a warning when nBatchSize is zero, or when the width or the height of the source or of the destination size of one of the descriptors is zero. |
ippStsNullPtrErr |
Indicates an error when one of the specified pointers is NULL. |
ippStsContextMatchErr |
Indicates an error when pSpec was not initialized by the WarpBatchInit_L function. |
ippStsSizeErr |
Indicates an error when nBatchSize is negative, or when the width or the height of the source or of the destination size of one of the descriptors is negative. |
ippStsBadArgErr |
Indicates an error when the transform of pSpec is neither ippWarpAffine nor ippWarpPerspective. |
ippStsInterpolationErr |
Indicates an error when the interpolation method of pSpec has an illegal value. |
ippStsBorderErr |
Indicates an error when the border that pSpec was initialized with has an illegal value. |
ippStsCoeffErr |
Indicates an error when one of the transform matrices of the batch is singular. |
ippStsExceededSizeErr |
Indicates an error when one of the sizes of the ippWarpPerspective transform exceeds the maximum positive value of the 32-bit signed integer type, or when the computed size exceeds the maximum positive value of the IppSizeL data type. |
See Also
Using Intel IPP Batch Warp Functions
WarpBatchGetSize_L Computes the size of the specification structure that is shared by all images of a batch warp.
WarpBatchInit_L Initializes the specification structure of a batch warp with the default parameters of the cubic filter.
BatchSetCubicArgs Sets the parameters of the cubic filter in an initialized specification structure of a batch.
WarpBatch_L Performs an affine or a perspective transform of a batch of images with a single call.
WarpGetBufferSize Computes the size of the external buffer for the warp transform.