Intel® Integrated Performance Primitives (Intel® IPP) Developer Guide and Reference
WarpBatchInit_L
Initializes the specification structure of a batch warp with the default parameters of the cubic filter.
Syntax
IppStatus ippiWarpBatchInit_L(const IppiBatchItem* pSrcBatch, const IppiBatchItem* pDstBatch, IppSizeL nBatchSize, const IppBatchItem* pTransforms, IppiWarpTransformType warpType, IppDataType dataType, int numChannels, int interpolation, IppiWarpDirection direction, IppiBorderType border, const Ipp64f* pBorderValue, int batchType, IppiWarpBatchSpec* pSpec, Ipp8u* pInitBuf);
Threading Layer (TL) flavor:
IppStatus ippiWarpBatchInit_LT(const IppiBatchItem* pSrcBatch, const IppiBatchItem* pDstBatch, IppSizeL nBatchSize, const IppBatchItem* pTransforms, IppiWarpTransformType warpType, IppDataType dataType, int numChannels, int interpolation, IppiWarpDirection direction, IppiBorderType border, const Ipp64f* pBorderValue, int batchType, IppiWarpBatchSpec* pSpec, Ipp8u* pInitBuf);
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 the descriptor of the first image of the batch 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 the descriptor of the first image of the batch 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 this function initializes the shared parameters alone and 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 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. Must be the array that the WarpBatchGetSize_L function was called with. Neither the array nor the matrices are copied into pSpec: the warp function of the batch reads the matrix of every image it transforms, so both must stay valid until the transform returns. |
warpType |
Transform of the batch, one value of the IppiWarpTransformType enumeration: ippWarpAffine or ippWarpPerspective. It is stored in pSpec, so the warp function of the batch performs the transform given here and the matrices of pTransforms are the matrices of that transform. Must be the value that the WarpBatchGetSize_L function was called with. |
dataType |
Data type of the source and destination images, shared by the whole batch. Supported values: ipp8u and ipp32f. Must be the value that the WarpBatchGetSize_L function was called with, and the warp function of the batch must be the flavor of that data type. |
numChannels |
Number of the channels of the images of the batch, shared by the whole batch. All the images of the batch have the same number of the channels. Supported values: 1 and 3. The warp function of the batch must be the channel flavor of that number, otherwise it returns the ippStsNumChannelsErr status. |
interpolation |
Interpolation method, shared by the whole batch: 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 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. Must be the value that the WarpBatchGetSize_L function was called with. |
direction |
Direction of the transform of every image of the batch, shared by the whole batch. Supported values: ippWarpForward and ippWarpBackward. It is passed on to the underlying single image warp as it is. Must be the value that the WarpBatchGetSize_L function was called with. |
border |
Type of the border of the transform, shared by the whole batch. Supported values: ippBorderRepl, ippBorderConst, ippBorderTransp, and ippBorderInMem. |
pBorderValue |
Pointer to the constant border value, shared by the whole batch. It is used when border equals ippBorderConst and holds one value per channel, so it points to numChannels elements. The border is a parameter of the batch and not of a channel, so a constant border of a multichannel batch has to be one value: all the numChannels components must be equal ones, otherwise this function returns the ippStsBadArgErr status. Only the pointer is stored in pSpec, not the value behind it, so that memory must stay valid as long as pSpec is in use. |
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 the functions of the batch 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. It is stored in pSpec. Must be the value that the WarpBatchGetSize_L function was called with. |
pSpec |
Pointer to the IppiWarpBatchSpec specification structure of the batch, sized by the WarpBatchGetSize_L function. |
pInitBuf |
Pointer to the temporary buffer of the initialization, of the size that the WarpBatchGetSize_L function returned in pInitBufSize. The buffer is used by this call only, its address is not stored in pSpec, so it can be released as soon as this function returns. |
Description
This function stores the parameters that are shared by the whole batch, that is 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 of the transform, in the opaque IppiWarpBatchSpec structure and marks that structure as initialized. Every function of the batch that follows takes them from there, so the descriptors and the transform matrices are its only other arguments. The parameters of the cubic filter are the default ones, that is B = 0.0 and C = 0.75, which is the kernel of the legacy IPPI_INTER_CUBIC interpolation and of the OpenCV INTER_CUBIC one. Use the BatchSetCubicArgs function to set other ones in the initialized structure. Both parameters are used by the IPPI_INTER_CUBIC method only: each of the IPPI_INTER_CUBIC2P_ methods names a predefined kernel, so this function stores the B and C values of that kernel instead, and the methods that are not cubic ignore both values.
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, this function stores the transform in it, and the WarpBatchGetBufferSize_L function and the WarpBatch_L function take it from there.
The single image specification structure itself is not initialized here: the sizes and the transform matrix differ from image to image, so the WarpBatch_L function builds it out of the size fields of the source and of the destination descriptor of an image, of its transform matrix, and of the shared parameters of pSpec. Every image of the batch has a transform matrix of its own, a uniform transform included, so that function builds it per image, in every batch.
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.
An empty batch, that is nBatchSize equal to zero, and a first image whose source or destination width or height is zero are no errors. There is no single image specification structure to validate against the underlying single image warp in that case, so this function stores the shared parameters, marks the structure as initialized, and returns the ippStsNoOperation warning. The warp function of the batch skips such an image and reports the same warning.
The parameters of the batch are nevertheless validated against the underlying single image warp here: the function builds the single image specification structure of the first image of the batch in pInitBuf and discards it, so a border type, a direction, a number of the channels, or a transform matrix that the single image warp does not support makes this function fail with the ippStsBorderErr, the ippStsWarpDirectionErr, the ippStsNumChannelsErr, or the ippStsCoeffErr status. The sizes of that image are therefore the ones this function checks, and pSpec is left uninitialized. pInitBuf is used by this call only, its address is not stored in pSpec.
The border is a parameter of the batch and not of a single image, so it is stored here and the WarpBatch_L function applies it to every image of the batch. Only the pBorderValue pointer is kept and not the value behind it. The check of the border is the one of the underlying single image warp, and this function performs it, together with the check of the direction of the transform and of the number of the channels, on the first image of the batch, so an illegal border makes this function return the ippStsBorderErr status.
The direction of the transform and the number of the channels are parameters of the batch as well, so they are stored here and the WarpBatch_L function passes them on to the transform of every image. The supported numbers of the channels are 1 and 3, and all the images of the batch have the same one, so the flavor of the warp function must be the channel flavor of the number that is stored here.
A constant border is one value of the batch and not one value per channel of it, so this function compares the numChannels components of pBorderValue when border equals ippBorderConst and returns the ippStsBadArgErr status when they are not equal ones. It is the only function of the batch that sees the border value, so the check is performed here. The border types that do not use the value ignore its components.
Call this function after the WarpBatchGetSize_L function, whose memory it needs, and before the WarpBatchGetBufferSize_L function and the WarpBatch_L function, both of which need the initialized structure and return the ippStsContextMatchErr status without it. Repeat the call to change the parameters of the cubic filter or the border; the size of the specification structure does not depend on them. A change of the transform of the batch, of a size of an image of it, of the data type, of the interpolation method, of the uniformity of the batch, or of one of the transform matrices of the batch needs the whole sequence from the WarpBatchGetSize_L function on, because the size of the shared memory depends on all of them. Changing only the image pointers or the steps does not require new calls.
The flavor with the _LT suffix stores the same parameters in the shared part of the specification structure, which the threads only read. Because IppiWarpBatchSpec is opaque and the layout behind it is private to a flavor, a structure that is used with the _LT flavor of the warp function must be sized by ippiWarpBatchGetSize_LT and initialized by the _LT flavor of this function; the two flavors cannot exchange specification structures.
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 the first image of the batch is zero. |
ippStsNullPtrErr |
Indicates an error when pSrcBatch, pDstBatch, pTransforms, or pSpec 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 the first image of the batch 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. |
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. |
ippStsNumChannelsErr |
Indicates an error when numChannels is neither 1 nor 3. |
ippStsBorderErr |
Indicates an error when border has an illegal value. |
ippStsBadArgErr |
Indicates an error when border equals ippBorderConst and the numChannels components of pBorderValue are not equal ones. |
ippStsCoeffErr |
Indicates an error when the transform matrix of the first image of the batch is singular. |
ippStsExceededSizeErr |
Indicates an error when a size of the transform exceeds the range of the underlying single image warp. |
See Also
Using Intel IPP Batch Warp Functions
BatchSetCubicArgs Sets the parameters of the cubic filter in an initialized specification structure of a batch.
WarpBatchGetSize_L Computes the size of the specification structure that is shared by all images of a batch warp.
WarpBatchGetBufferSize_L Computes the size of the work buffer for a batch warp.
WarpBatch_L Performs an affine or a perspective transform of a batch of images with a single call.