Intel® Integrated Performance Primitives (Intel® IPP) Developer Guide and Reference
Using Intel IPP Batch Warp Functions
The batch warp functions apply an affine or a perspective transform to a group of images with a single function call. The transform of the batch is the warpType parameter, one value of the IppiWarpTransformType enumeration, so one group of functions serves both of them. The batch is uniform in the parameters of the transform and not in the transform itself: every image of the batch has its own source and destination sizes, given by its source and its destination descriptor, and its own transform matrix, given by its descriptor of the matrices of the batch, while the transform of the batch, the data type, the number of the channels, the interpolation method, the parameters of the cubic filter, the uniformity of the batch, and the border of the transform are common to the whole batch.
A single call amortizes the call overhead over the whole group, which makes the batch functions preferable when many images have to be warped with the same parameters, for example when preparing the input tensors of an inference pipeline out of a set of differently oriented images.
The batch warp functions are platform-aware ones: their names carry the _L suffix, they are declared in ippi_l.h, and their sizes and steps are of the IppSizeL and IppiSizeL types. The ippWarpAffine transform of the batch is built on top of the _L flavor of the single-image affine warp, so the sizes of the batch interface are passed through to it unchanged. The single-image perspective warp has no _L flavor, so the ippWarpPerspective transform of the batch is built on top of the standard, 32-bit-length, flavor of it and returns the ippStsExceededSizeErr status whenever one of its sizes does not fit the 32-bit signed integer type.
Transform of the Batch
The transform of the batch is the warpType parameter of the WarpBatchGetSize_L and of the WarpBatchInit_L functions and not an entry point of its own:
typedef enum {
ippWarpAffine,
ippWarpPerspective,
ippWarpBilinear
} IppiWarpTransformType;
The Init function stores it in the specification structure of the batch, so the WarpBatchGetBufferSize_L function and the WarpBatch_L function take it from there and no other function of the batch has a transform argument. The batch supports the affine and the perspective transform of that enumeration; ippWarpBilinear, which has no single image warp of its own in the library, and any other value make the GetSize and the Init functions return the ippStsBadArgErr status.
The transform decides the size of the matrix of an image, 2x3 for the affine transform and 3x3 for the perspective one, so it also decides how many coefficients one descriptor of the matrices of the batch counts, six or nine of them.
Uniform Directions and Uniform Transform
A direction of a batch is uniform when all its images have the same size and they are stored in one block of contiguous memory, one after another and without a gap between them, that is when the direction is one tensor of nBatchSize images. The transform of a batch is uniform in the same sense: the matrices of its images are one contiguous tensor of nBatchSize matrices, one matrix per image exactly as a non-uniform transform has, and not one single matrix that all the images share.
The batchType parameter of the WarpBatchGetSize_L and of the WarpBatchInit_L functions states which of them is a tensor, a bitmask of the flags of the IppBatchType enumeration:
typedef enum {
ippBatchNonUniform = 0,
ippBatchUniformSrc = 1,
ippBatchUniformDst = 2,
ippBatchUniformTransform = 4
} IppBatchType;
ippBatchUniformSrc says that the source images of the batch are one tensor, ippBatchUniformDst the same for the destination images, ippBatchUniformTransform that the transform matrices of the batch are one tensor, and ippBatchNonUniform, the empty mask, that none of the three is. A bit outside those flags makes the GetSize and the Init functions return the ippStsBadArgErr status. The mask is a combination of the flags, so the parameter is an int and not a value of the enumeration, exactly as the interpolation method is: the enumeration names the values of the bits and no legal argument of its own.
A single descriptor is enough for whatever a flag declares to be a tensor, and only one is read: its array holds exactly one element, whose pMem points at the whole tensor. 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, size being the number of the coefficients of one matrix. What is not declared to be a tensor is described item by item: its array holds nBatchSize descriptors, and neither the sizes nor the memory of the items are related. The three are independent, so a batch of separately allocated sources of different sizes that is warped into one destination tensor with the matrices held in one array, the usual input of an inference pipeline, passes nBatchSize source descriptors, a single destination descriptor, a single descriptor of the matrices, and ippBatchUniformDst | ippBatchUniformTransform.
batchType is a statement of the caller and is not verified, no scan of the batch is performed. A uniform direction whose images are neither of the size of its single descriptor nor stored contiguously is read, respectively written, at the offsets above nevertheless, which makes the warp produce wrong destination images instead of an error. No flag promises that the images of the batch share a transform matrix, so the single image specification structure of an image is built per image in every batch.
Batch Size and Empty Images
nBatchSize is the number of the images of the batch, and the number of the descriptors of whatever batchType does not declare to be a tensor. A batch of a single image is a legal batch: it is the shape that a single image of an inference pipeline takes, and it goes through the same sequence as a larger one. An empty batch, that is nBatchSize equal to zero, is legal as well: it has nothing to transform, so the GetSize function returns the size of the shared parameters alone, the GetBufferSize function returns zero, and every function of the group returns the ippStsNoOperation warning. A negative nBatchSize is an error and returns the ippStsSizeErr status.
An image whose source or destination width or height is zero is legal too. It has nothing to transform, so it needs neither a single image specification structure nor a work buffer and it does not contribute to the sizes that the size functions return, the warp function leaves its destination image unchanged and continues with the remaining images of the batch, and the ippStsNoOperation warning reports it. An empty image of a uniform direction is the single descriptor of that direction, so it makes every image of the batch an empty one.
Batch Descriptors
The batch functions take one array of the descriptors per direction, the pSrcBatch array of the source images and the pDstBatch array of the destination ones, and one image of a batch is described by one element of each of them. Both transforms, and the batch resize as well, take the descriptors of the IppiBatchItem type:
typedef struct {
void* pMem;
IppSizeL step;
IppiSizeL size;
} IppiBatchItem;
pMem |
Pointer to the memory of the image. The whole source image is transformed and the whole destination image is filled, so there is no rectangle to place inside either of them. |
step |
Distance, in bytes, between the starting points of consecutive lines of the image. |
size |
Size of the image, in pixels. The sizes of the batch may differ from image to image; there is no size argument in the batch functions, the descriptors of an image are the only place where its sizes are given. |
The transform matrices of the batch are described the same way, by the pTransforms array of the descriptors of the one-dimensional IppBatchItem type:
typedef struct {
void* pMem;
IppSizeL size;
} IppBatchItem;
pMem points at the coefficients of the Ipp64f type and size counts the coefficients of one matrix, that is six of the 2x3 matrix of the ippWarpAffine transform and nine of the 3x3 matrix of the ippWarpPerspective one, both in the row-major order. A batch that does not declare its transform to be a tensor passes nBatchSize such descriptors, one per image, and one that does passes a single descriptor of the whole tensor of the matrices, in which the matrix of the image i begins at the element i * size.
Batch Specification Structure
The parameters that are shared by the whole batch, the transform of it included, are stored in the specification structure of the batch, one type for both transforms:
typedef struct WarpBatchSpec IppiWarpBatchSpec;
The structure is opaque, exactly as the single image IppiWarpSpec is: its layout is internal to the library and its fields are not accessible to the application. It holds the parameters that are shared by all images of the batch and the single image specification structure that the batch builds out of them and out of the sizes and the matrix of an image, in one memory block. Its size is returned by the WarpBatchGetSize_L function, together with the size of the temporary buffer that the Init function needs, and it is filled by the WarpBatchInit_L function. The GetBufferSize function and the warp function of the batch return the ippStsContextMatchErr status for a structure that was not initialized by it. One structure serves both transforms: the transform is a parameter of it, so a structure of one transform is a valid argument of every function of the batch and the transform it performs is the stored one.
The shared parameters are the arguments of the Init function:
warpType |
Transform of the batch: ippWarpAffine or ippWarpPerspective. See the Transform of the Batch section above. |
dataType |
Data type of the source and destination images of the batch. Supported values: ipp8u and ipp32f. The warp function of the batch must be the flavor of that data type, otherwise it returns the ippStsDataTypeErr status. |
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. See the Channel Flavors section below. |
batchType |
Which of the two directions and of the transform matrices of the batch are one contiguous tensor, a bitmask of the flags of the IppBatchType enumeration. See the Uniform Directions and Uniform Transform section above. |
interpolation |
Interpolation method. See the Interpolation Methods section below. |
direction |
Direction of the transform of every image of the batch. Supported values: ippWarpForward and ippWarpBackward. It is passed on to the underlying single image warp as it is. |
valueB |
The B parameter of the cubic filter, used when the interpolation method is IPPI_INTER_CUBIC. The default value, set by the Init function, is 0.0. The IPPI_INTER_CUBIC2P_ methods name a predefined kernel, so the Init function stores the B value of that kernel instead. |
valueC |
The C parameter of the cubic filter, used when the interpolation method is IPPI_INTER_CUBIC. The default value, set by the Init function, is 0.75. Together with valueB = 0.0 it is the kernel of the OpenCV INTER_CUBIC interpolation. The IPPI_INTER_CUBIC2P_ methods name a predefined kernel, so the Init function stores the C value of that kernel instead. |
border |
Type of the border of the transform, applied to every image of the batch. See the Border Processing section below. |
pBorderValue |
Pointer to the constant border value, used when border equals ippBorderConst. It holds one value per channel, so it points to numChannels elements, and all of them must be equal ones. See the Border Processing section below. Only the pointer is stored in the specification structure, not the value behind it, so that memory must stay valid as long as the structure is in use. |
The single image part of the structure is not filled by the Init function: it describes the transform of one image of the batch, so it is built by the batch warp functions themselves out of the sizes of the descriptors of the current image, of its matrix, and of the shared parameters. Every image of the batch has a transform matrix of its own, a uniform transform included, so those functions build it per image, in every batch.
The Init function does build the single image specification structure of the first image of the batch, in the pInitBuf temporary buffer, to verify the shared parameters against the underlying single image warp, and it discards it when the call returns. The buffer is therefore needed during the call alone, its pointer is not stored in the specification structure, and its size is the one that the GetSize function returns in pInitBufSize. A shared parameter that the single image warp rejects makes the Init function return the status of that check and leave pSpec uninitialized.
Because every parameter of the batch is stored here, the GetBufferSize function and the warp function take no argument of the batch besides the descriptors, the matrices, and this structure. The transform of the batch, the data type, the number of the channels, the interpolation method, the direction of the transform, the uniformity of the batch, and the border are arguments of the GetSize function too, because it is called before this structure exists and its size depends on them; pass the same values to the Init function.
Processing Sequence
To warp a batch of images, follow these steps:
Allocate the array of the source descriptors, the array of the destination descriptors, and the array of the descriptors of the transform matrices of the batch, and fill the pMem, step, and size fields of every element of them. Each array holds nBatchSize descriptors, or a single one of the whole tensor when batchType declares that direction, respectively the transform, to be a tensor.
Call the WarpBatchGetSize_L function with the descriptors, the matrices, the transform of the batch, the data type, the number of the channels, the interpolation method, the direction of the transform, the uniformity of the batch, and the border of the batch to get the size of the specification structure and the size of the temporary buffer of the Init function, and allocate both of them. The size of a single image specification structure of the warp depends on the sizes and on the transform matrix of an image, so the function scans the whole batch and returns the maximum over the group; the sizes of every descriptor and the matrices must therefore be set before the call.
Call the WarpBatchInit_L function to store the parameters that are shared by the whole batch in the specification structure. It sets the default parameters of the cubic filter, and the BatchSetCubicArgs function replaces them in the initialized structure. Both of them keep the predefined kernel of the method when the interpolation is one of the IPPI_INTER_CUBIC2P_ ones. The Init function verifies the shared parameters in the temporary buffer of step 2, which may be released as soon as the call returns.
Call the WarpBatchGetBufferSize_L function to get the size of the work buffer, and allocate it. This function needs the structure initialized in step 3, which carries every parameter of the batch, so the descriptors and the matrices are its only other arguments.
Call the WarpBatch_L function to warp the whole batch. It takes the work buffer alone: the single image specification structure of an image is built in that buffer, and the two roles do not overlap in time, so the size returned in step 4 covers both of them and one allocation is enough.
Unlike the single image warp, where one initialized specification structure describes one geometry and one transform matrix, the batch rebuilds the single image part of the shared specification structure from the sizes of the descriptors of an image and from its matrix before every image of the batch, whatever its uniformity is. Steps 2 to 4 must therefore be performed in that order, because the size of the work buffer is a property of an initialized specification structure. If you change the transform of the batch, any of the sizes, the data type, the number of the channels, the interpolation method, the direction of the transform, the uniformity of the batch, or one of the transform matrices of the batch, repeat all the steps from step 2 on, because the size of the shared memory depends on all of them. If you only change the parameters of the cubic filter or the border, repeat the steps from step 3 on. If you only change the image pointers or the steps, only step 5 has to be repeated.
Border Processing
The border type and the border value are shared by the whole batch, so they are parameters of the Init function and are stored in the specification structure; the warp function applies them to every image of the batch. The supported border types are ippBorderRepl, ippBorderConst, ippBorderTransp, and ippBorderInMem, exactly as for the single image warp. Only the pBorderValue pointer is stored, not the value behind it, so that memory must stay valid as long as the specification structure is in use.
The check of the border is the one of the underlying single image warp, and the Init function performs it in the pInitBuf temporary buffer, together with the checks of the direction of the transform and of the number of the channels, so a border that the transform does not support makes the GetSize, the Init, the GetBufferSize, and the warp functions return the ippStsBorderErr status.
The border is a parameter of the batch and not a parameter of a channel of it, so a constant border of a multichannel batch has to be one value: the Init 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 there. The border types that do not use the value ignore its components.
Channel Flavors
The number of the channels of the batch is a parameter of the batch: it is an argument of the GetSize function and of the Init function, which store it in the specification structure. All the images of the batch have the same number of the channels, and the supported values are 1 and 3, so the warp function of the batch exists in the C1R and in the C3R flavor of each data type. The flavor in use must be the channel flavor of the number that the specification structure was initialized with, otherwise the function returns the ippStsNumChannelsErr status.
The channels of an image are interleaved, exactly as in the underlying single image warp, and the transform of a multichannel batch is the multichannel transform of that warp, so the step field of a descriptor counts all the channels of a line, and the channels of a destination pixel are interpolated from the channels of the same source pixels.
Interpolation Methods
The interpolation parameter of the batch is an int: it is one of the IPPI_INTER_NN, IPPI_INTER_LINEAR, IPPI_INTER_CUBIC, IPPI_INTER_CUBIC2P_BSPLINE, IPPI_INTER_CUBIC2P_CATMULLROM, and IPPI_INTER_CUBIC2P_B05C03 methods of ipptypes.h. The interpolation is shared by the whole batch: pass the same value to the GetSize function and to the Init function, which stores it in the specification structure, and the remaining functions of the batch take it from there.
The four cubic methods are the same two-parameter cubic filter and cost the same. 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
IPPI_INTER_CUBIC2P_BSPLINE |
B = 1.0 and C = 0.0 |
IPPI_INTER_CUBIC2P_CATMULLROM |
B = 0.0 and C = 0.5 |
IPPI_INTER_CUBIC2P_B05C03 |
B = 0.5 and C = 0.3 |
so the Init function stores the parameters of that kernel and ignores the given ones. The methods that are not cubic ignore both parameters.
Unlike the batch resize, the batch warp has no antialiasing flavor of its filters and no IPPI_INTER_SUPER or Lanczos method, so IPPI_INTER_SUPER, IPPI_INTER_LANCZOS, and IPPI_INTER_LANCZOS3 are rejected here, and so is any other value of the method, with the ippStsInterpolationErr status: a method that is ignored would leave the batch without an interpolation at all.
The options of the interpolation parameter, that is the flags a method of it is combined with, are ignored instead: the IPPI_ANTIALIASING flag that the batch resize accepts, and the IPPI_SUBPIXEL_EDGE and IPPI_SMOOTH_EDGE flags of the warp of a quadrangle, name no filter of the batch warp, so the WarpBatchGetSize_L and WarpBatchInit_L functions take the method alone, store it in the specification structure, and report the ignored options with a warning: ippStsNoAntialiasing for the antialiasing flag and ippStsOperationNotSupported for the two edge flags. The remaining functions of the batch read the stored method, so they never see an option and never return one of those warnings for it.
Threading Layer Functions
Every function of the batch warp group has a Threading Layer flavor with the _LT suffix, declared in ippi_tl.h. The Threading Layer distributes the images of the batch over the threads, so each thread warps a whole image and no image is split. As a consequence:
The _LT flavors of the size functions return sizes that cover all threads: every thread gets a private single image specification structure and a private slice of the work buffer, so the sizes grow with the number of threads. The layout of the specification structure of the _LT flavor is not the layout of the single threaded one, so memory for the _LT warp functions must always be sized by the _LT flavors of the size functions.
The sizes depend on the number of threads reported by ippGetNumThreads_LT. If you change it with ippSetNumThreads_LT, call the _LT flavors of the size functions again and reallocate the memory.
The _LT flavor of the Init function takes the same parameters and stores them in the shared part of the specification structure, which the threads only read. Because the specification structure is opaque and the layout behind it is private to a flavor, the whole structure must be sized by the _LT flavor of the GetSize function and initialized by the _LT flavor of the Init function; a specification structure of one flavor cannot be passed to the functions of the other one. The temporary buffer of the Init function holds one single image specification structure in either flavor, but its size is a property of the flavor as well, so size it by the GetSize function that belongs to the Init function you call.
The parallel speedup grows with nBatchSize and is limited by the number of threads. A batch that is smaller than the number of threads leaves the remaining threads idle.
Unlike the single threaded functions, which stop at the first image that returns an error, the _LT functions warp every image of the batch even if one of them fails. If several images return a status other than ippStsNoErr, the returned status is the one of an unspecified image among them, because the order in which the threads complete is not defined.
See Also
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.
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.