Intel® Integrated Performance Primitives (Intel® IPP) Developer Guide and Reference
WarpBatchGetSize_L
Computes the size of the specification structure that is shared by all images of a batch warp.
Syntax
IppStatus ippiWarpBatchGetSize_L(const IppiBatchItem* pSrcBatch, const IppiBatchItem* pDstBatch, IppSizeL nBatchSize, const IppBatchItem* pTransforms, IppiWarpTransformType warpType, IppDataType dataType, int numChannels, int interpolation, IppiWarpDirection direction, IppiBorderType border, int batchType, IppSizeL* pSpecSize, IppSizeL* pInitBufSize);
Threading Layer (TL) flavor:
IppStatus ippiWarpBatchGetSize_LT(const IppiBatchItem* pSrcBatch, const IppiBatchItem* pDstBatch, IppSizeL nBatchSize, const IppBatchItem* pTransforms, IppiWarpTransformType warpType, IppDataType dataType, int numChannels, int interpolation, IppiWarpDirection direction, IppiBorderType border, int batchType, IppSizeL* pSpecSize, IppSizeL* pInitBufSize);
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 batchType 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 batchType 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, which the ippStsNoOperation warning reports. 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 batchType 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. Pass the same array to the Init function of the batch. |
warpType |
Transform of the batch, one value of the IppiWarpTransformType enumeration: ippWarpAffine or ippWarpPerspective. The batch performs one transform, so it is a parameter of the whole batch and the matrices of pTransforms are the matrices of that transform. The ippWarpBilinear value of that enumeration is not supported. Pass the same value to the Init function of the batch. |
dataType |
Data type of the source and destination images. It is shared by the whole batch. Supported values: ipp8u and ipp32f. Pass the same value to the Init function of the batch. |
numChannels |
Number of the channels of the images of the batch. All the images of the batch have the same number of the channels. Supported values: 1 and 3. Pass the same value to the Init function of the batch. |
interpolation |
Interpolation method, one of IPPI_INTER_NN, IPPI_INTER_LINEAR, IPPI_INTER_CUBIC, IPPI_INTER_CUBIC2P_BSPLINE, IPPI_INTER_CUBIC2P_CATMULLROM, and IPPI_INTER_CUBIC2P_B05C03. The four cubic methods are the same two-parameter cubic filter: IPPI_INTER_CUBIC uses the B and C parameters of the Init function, and each of the IPPI_INTER_CUBIC2P_ methods uses its own predefined kernel, that is B = 1.0 and C = 0.0 for IPPI_INTER_CUBIC2P_BSPLINE, B = 0.0 and C = 0.5 for IPPI_INTER_CUBIC2P_CATMULLROM, and B = 0.5 and C = 0.3 for IPPI_INTER_CUBIC2P_B05C03. The options of the parameter, that is the IPPI_ANTIALIASING flag, which the batch resize accepts, and the IPPI_SUBPIXEL_EDGE and IPPI_SMOOTH_EDGE flags, are ignored and not rejected: the warp of a batch has no antialiasing flavor of its filters and no smoothing of the edges, so the method alone is stored in the specification structure and the ignored options are reported with the ippStsNoAntialiasing warning for the antialiasing and with the ippStsOperationNotSupported warning for the two edge flags. An unsupported method is an error nevertheless, because ignoring a method would leave the batch without an interpolation, so IPPI_INTER_SUPER, IPPI_INTER_LANCZOS, and IPPI_INTER_LANCZOS3 return the ippStsInterpolationErr status. Pass the same value to the Init function of the batch. |
direction |
Direction of the transform of every image of the batch. It is shared by the whole batch. Supported values: ippWarpForward and ippWarpBackward. It is passed on to the underlying single image warp as it is. Pass the same value to the Init function of the batch. |
border |
Type of the border of the transform of every image of the batch. It is shared by the whole batch. Supported values: ippBorderRepl, ippBorderConst, ippBorderTransp, and ippBorderInMem. Pass the same value to the Init function of the batch. |
batchType |
Bitmask of what is one contiguous tensor in the batch, that is one block of contiguous memory that holds the items of that kind, of equal size and one after another without a gap, described by a single descriptor: the ippBatchUniformSrc flag for the source images, the ippBatchUniformDst flag for the destination images, the ippBatchUniformTransform flag for the transform matrices, and ippBatchNonUniform, the empty mask, when none of the three is. It tells this function how many descriptors each of pSrcBatch, pDstBatch, and pTransforms holds. The mask is a combination of the flags, so it is an int and not a value of the enumeration. Pass the same value to the Init function of the batch. |
pSpecSize |
Pointer to the size, in bytes, of the IppiWarpBatchSpec specification structure of the batch. The structure is opaque, and the returned size covers the whole memory block: the parameters that are shared by the batch and the single image specification structure that is a part of it. |
pInitBufSize |
Pointer to the size, in bytes, of the temporary buffer of the Init function of the batch. That buffer is used by an initialization call only, so it can be released as soon as the specification structure is built. |
Description
This function computes the size of the IppiWarpBatchSpec specification structure that all images of the batch share. The structure is opaque, exactly as the single image IppiWarpSpec is, and the single image specification structure is a part of the same memory block, so the returned size does not depend on the parameters of the cubic filter, which the BatchSetCubicArgs function replaces in the initialized structure.
The transform of the batch is the warpType argument and not an entry point of its own: one IppiWarpBatchSpec structure serves both transforms of the IppiWarpTransformType enumeration that the batch supports, the Init function stores the transform in it, and the remaining functions of the batch take it from there. The size depends on the transform, so pass the same warpType to the Init function.
Every image of the batch has its own sizes, given by the size fields of its source and of its destination descriptor, and its own transform matrix, given by its descriptor of the matrices of the batch. The size of a single image specification structure of the warp depends on both of them, so the function scans the whole batch and returns the maximum over all images. Because of that, the sizes of every descriptor and the matrices of pTransforms must be set before the call.
batchType says which of the two directions and of the transform matrices of the batch are one contiguous tensor, described by a single descriptor: 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. So the arrays of a uniform direction, respectively of a uniform transform, hold one element and no other one is read. It is a statement of the caller and no request to check the batch, so it is not verified and no scan of the memory of the batch is performed: a batch that contradicts the statement is read at those offsets nevertheless, which makes the warp produce wrong destination images instead of an error. No flag of it promises that the images of the batch share a transform matrix, because a uniform transform is a tensor of the matrices of the images, one per image exactly as a non-uniform one is, so the single image specification structure of the batch is built per image in every batch.
An empty batch, that is nBatchSize equal to zero, and an image whose source or destination width or height is zero are no errors. Such an image is not transformed, so it needs no single image specification structure and it does not contribute to the returned sizes, and the ippStsNoOperation warning reports it. The size of an empty batch is the one of the shared parameters alone, which the Init function of the batch still initializes.
The parameters of this function are the ones the specification structure does not hold yet, because it is called before that structure exists. The Init function stores them in it, so the remaining functions of the batch take no parameter of the batch besides the descriptors and the matrices.
The function also returns the size of the temporary buffer that the Init function of the batch needs. It validates the parameters of the batch against the underlying single image warp, so it builds the single image specification structure of the first image of the batch in that buffer and discards it. The buffer is used by an initialization call only, its address is not stored in the specification structure, so it can be released as soon as that structure is built.
The ippWarpPerspective transform of the batch is built on top of the standard, 32-bit-length, flavor of the single image perspective warp, because that transform has no _L flavor. For that transform the function therefore 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 first in the batch processing sequence. Then allocate the memory, initialize the specification structure with the WarpBatchInit_L function, and get the size of the work buffer with the WarpBatchGetBufferSize_L function, which needs the initialized structure sized by this one.
For the flavor with the _LT suffix, the returned size covers all the threads that the Threading Layer uses: the specification structure holds a private single image specification structure for every thread, so the size grows with the number of threads. The layout of that structure is not the layout of the single threaded flavor, so the two sizes are not comparable and memory for the ippiWarpBatch_<mod>_LT functions must be sized by this flavor. 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. |
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 warpType is neither ippWarpAffine nor ippWarpPerspective, or when batchType carries a bit that is no flag of the IppBatchType enumeration. |
ippStsDataTypeErr |
Indicates an error when dataType has an illegal value. |
ippStsNumChannelsErr |
Indicates an error when numChannels is neither 1 nor 3. |
ippStsNoAntialiasing |
Indicates a warning when the interpolation parameter carries the IPPI_ANTIALIASING flag, which the warp of a batch ignores. |
ippStsOperationNotSupported |
Indicates a warning when the interpolation parameter carries the IPPI_SUBPIXEL_EDGE or the IPPI_SMOOTH_EDGE flag, which the warp of a batch ignores. |
ippStsInterpolationErr |
Indicates an error when the interpolation method has an illegal value. |
ippStsWarpDirectionErr |
Indicates an error when direction has an illegal value. |
ippStsBorderErr |
Indicates an error when border 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
WarpBatchGetBufferSize_L Computes the size of the work buffer for 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.
WarpAffineGetSize Computes the size of the specification structure and the size of the temporary buffer for the affine warp transform.