Intel® Integrated Performance Primitives (Intel® IPP) Developer Guide and Reference
WarpBatch_L
Performs an affine or a perspective transform of a batch of images with a single call.
Syntax
IppStatus ippiWarpBatch_<mod>(const IppiBatchItem* pSrcBatch, const IppiBatchItem* pDstBatch, IppSizeL nBatchSize, const IppBatchItem* pTransforms, IppiWarpBatchSpec* pSpec, Ipp8u* pBuffer);
Supported values for mod:
8u_C1R_L |
8u_C3R_L |
32f_C1R_L |
32f_C3R_L |
Threading Layer (TL) flavor:
IppStatus ippiWarpBatch_<mod>(const IppiBatchItem* pSrcBatch, const IppiBatchItem* pDstBatch, IppSizeL nBatchSize, const IppBatchItem* pTransforms, IppiWarpBatchSpec* pSpec, Ipp8u* pBuffer);
Supported values for mod:
8u_C1R_LT |
8u_C3R_LT |
32f_C1R_LT |
32f_C3R_LT |
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. All of the fields 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. All of the fields 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 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 shared by the batch, initialized by the WarpBatchInit_L function. It carries every parameter of the batch: 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. |
pBuffer |
Pointer to the single work buffer shared by the batch, sized by the WarpBatchGetBufferSize_L function. The function uses it as the temporary buffer of the initialization of the single image specification structure as well, so no separate temporary buffer is passed here. |
Description
This function applies the transform of pSpec to every source image of the batch and writes the result to the destination image of the same index. There is one entry point per data type, and the transform it performs is the warpType value that the WarpBatchInit_L function stored, ippWarpAffine or ippWarpPerspective. The transform matrix of the image k of the batch is the matrix of the descriptor k of pTransforms, or the one at the element k * size of its single descriptor when the uniformity of pSpec carries the ippBatchUniformTransform flag, so the transform differs from image to image whatever the uniformity of the batch is. For the ippWarpAffine transform a matrix, spelled coeffs here, is a 2x3 one:
x' = coeffs[0][0] * x + coeffs[0][1] * y + coeffs[0][2]
y' = coeffs[1][0] * x + coeffs[1][1] * y + coeffs[1][2]
and for the ippWarpPerspective transform a 3x3 one:
x' = (coeffs[0][0] * x + coeffs[0][1] * y + coeffs[0][2]) /
(coeffs[2][0] * x + coeffs[2][1] * y + coeffs[2][2])
y' = (coeffs[1][0] * x + coeffs[1][1] * y + coeffs[1][2]) /
(coeffs[2][0] * x + coeffs[2][1] * y + coeffs[2][2])
A group of images of arbitrary sizes and matrices is warped with a single call, and the batch is uniform in the parameters of the transform and not in the transform itself.
All images of the batch share the specification structure and the work buffer, and every parameter of the transform is taken from pSpec: 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. The size of an image, its pointer, and its step are the ones of its source and of its destination descriptor, and its transform matrix is the one of its own descriptor of pTransforms. Because the sizes and the matrix differ from image to image, the single image specification structure inside pSpec is rebuilt from the size fields of the source and of the destination descriptor of the current image, from its matrix, and from the shared parameters of pSpec before every image of the batch, whatever the uniformity of the batch is, which is why the batch cannot share it with a single image warp call that is in progress. That initialization needs a temporary buffer, and pBuffer is it: the two roles do not overlap in time, so the WarpBatchGetBufferSize_L function sizes one buffer for both of them.
The flags of the uniformity of pSpec say 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 about the memory of the batch and no request to check it, so it is not verified and no scan of that memory is performed: a batch that contradicts the statement is read at those offsets nevertheless, which makes this function 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 an image whose source or destination width or height is zero are no errors. Such an image has nothing to transform, so the function leaves its destination image unchanged, continues with the remaining images of the batch, and reports it with the ippStsNoOperation warning.
The whole source image of an index is transformed into the whole destination image of it, both of them at their origin, so the pMem field of a source descriptor points at the origin of its source image, the pMem field of a destination descriptor at the origin of its destination image, and there is no rectangle to place inside either of them. The pMem field of a descriptor of a uniform direction points at the origin of the tensor, that is at the origin of the image of the index zero.
The number of the channels of the batch is stored in pSpec too, so the flavor of this function must be the channel flavor of that number, otherwise it returns the ippStsNumChannelsErr status. All the images of the batch have the same number of the channels, and the channels of an image are interleaved, exactly as in the underlying single image warp, so the step field of a descriptor counts all the channels of a line, and a constant border of a multichannel batch is one value that the Init function has accepted for all the channels.
Destination pixels that are mapped outside the source image are processed according to the border that pSpec was initialized with, ippBorderRepl, ippBorderConst, ippBorderTransp, or ippBorderInMem. The check of the border is the one of the underlying single image warp, so the Init function already validated it, on the single image specification structure of the first image of the batch, and it is validated here again, on the one of every image. When it equals ippBorderConst, the pBorderValue pointer that pSpec holds must still be valid.
The parameters of the cubic filter are the ones stored in pSpec: its B and C, exactly as the border of the transform is. The WarpBatchInit_L function sets the default ones, that is B = 0.0 and C = 0.75, which is the kernel of the OpenCV INTER_CUBIC interpolation; use the BatchSetCubicArgs function to replace them. Both parameters are used by the IPPI_INTER_CUBIC method only: each of the IPPI_INTER_CUBIC2P_ methods names a predefined kernel, whose B and C values the Init function stores instead.
Before calling this function, do the following:
Fill the pMem, step, and size fields of every descriptor of pSrcBatch and of pDstBatch, the pMem and size fields of every descriptor of pTransforms, and the transform matrices themselves. A uniform direction, respectively a uniform transform, takes a single descriptor of the whole tensor.
Compute the size of pSpec with the WarpBatchGetSize_L function and allocate the memory.
Initialize pSpec with the transform of the batch, the data type, the interpolation method, the direction of the transform, the number of the channels, the uniformity of the batch, the border of the transform, and the filter parameters by the WarpBatchInit_L function, and replace the parameters of the cubic filter with the BatchSetCubicArgs function if the default ones are not the wanted ones.
Compute the size of pBuffer with the WarpBatchGetBufferSize_L function and allocate the memory.
The single threaded flavors stop at the first image that returns an error and return its status, so the destination images of the remaining descriptors are left unchanged. A warning does not stop the processing: the whole batch is warped and the returned status is the warning of the image with the smallest index among the ones that warned.
The flavors with the _LT suffix distribute the images of the batch over the threads, so each thread warps whole images. The memory passed in pSpec and pBuffer must be sized by ippiWarpBatchGetSize_LT and ippiWarpBatchGetBufferSize_LT, which reserve a private slice for every thread. Unlike the single threaded flavors, the _LT flavors 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.
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, or one of the pMem fields of the descriptors that are read, is NULL, or when the border of pSpec equals ippBorderConst and its border value pointer 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. |
ippStsDataTypeErr |
Indicates an error when pSpec was initialized for the other data type. |
ippStsNumChannelsErr |
Indicates an error when pSpec was initialized for another number of the channels. |
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. |
ippStsStepErr |
Indicates an error when one of the step values is not a multiple of the data type size. |
Example
/*******************************************************************************
* Copyright 2026 Intel Corporation.
*
*
* This software and the related documents are Intel copyrighted materials, and your use of them is governed by
* the express license under which they were provided to you ('License'). Unless the License provides otherwise,
* you may not use, modify, copy, publish, distribute, disclose or transmit this software or the related
* documents without Intel's prior written permission.
* This software and the related documents are provided as is, with no express or implied warranties, other than
* those that are expressly stated in the License.
*******************************************************************************/
// A simple example of the batch warp transform using
// Intel(R) Integrated Performance Primitives (Intel(R) IPP) functions:
// ippiGetPerspectiveTransform
// ippiWarpBatchGetSize_L
// ippiWarpBatchInit_L
// ippiWarpBatchGetBufferSize_L
// ippiWarpBatch_8u_C1R_L
//
// The batch is described by three arrays of the descriptors: one of the source images,
// one of the destination images and one of the transform matrices. The sources and the
// destinations of this batch have their own sizes, so each of them is a separate image
// of one descriptor, while the matrices are packed into one contiguous array of
// BATCH_SIZE matrices of nine coefficients each. Such a contiguous block is a tensor,
// one descriptor describes all of it, and batchType therefore carries the
// ippBatchUniformTransform flag: the matrix of the image i is read at the element
// i * size of the single descriptor. The flag says nothing about the matrices being
// equal, every image of the batch keeps a transform of its own.
#include <stdio.h>
#include "ipp.h"
#define BATCH_SIZE 4
#define SRC_WIDTH 640
#define SRC_HEIGHT 480
#define DST_WIDTH 320
#define DST_HEIGHT 240
/* The numbers 1 and 3 of the channels are supported by the batch warp; this example warps single
// channel images */
#define NUM_CHANNELS 1
/* The perspective transform of this example takes a 3x3 matrix per image; the affine one takes a
// 2x3 matrix, so its matrices are packed six coefficients apart */
#define NUM_COEFFS 9
/* Next two defines are created to simplify code reading and understanding */
#define EXIT_MAIN \
exitLine: /* Label for Exit */
#define check_sts(st) \
if ((st) != ippStsNoErr) \
goto exitLine; /* Go to Exit if Intel(R) IPP function returned status different from ippStsNoErr */
/* The region of an image of the batch is the quadrangle its whole source image is mapped to: four
// vertices, in the clockwise order, starting at the image of the upper left corner of that source
// image. Every image of the batch has its own region, so this is the array the batch is described
// by, and the transform matrices are computed out of it. The vertices are given in the units of the
// destination image of that image of the batch, which this example shrinks by 16 pixels per image,
// so they stay inside it. */
static Ipp64f quads[BATCH_SIZE][4][2] = {{{0.0, 0.0}, {270.0, 0.0}, {270.0, 190.0}, {0.0, 190.0}},
{{20.0, 10.0}, {260.0, 30.0}, {250.0, 180.0}, {10.0, 190.0}},
{{40.0, 0.0}, {240.0, 20.0}, {260.0, 170.0}, {0.0, 160.0}},
{{0.0, 30.0}, {250.0, 0.0}, {230.0, 180.0}, {30.0, 170.0}}};
/* The transform matrices of the batch, one contiguous tensor of the matrices of its images, so one
// descriptor of NUM_COEFFS elements describes all of them */
static Ipp64f coeffs[BATCH_SIZE][3][3];
int main(void)
{
IppStatus status = ippStsNoErr;
int i;
/* The transform of the whole batch, one value of the IppiWarpTransformType enumeration. It is an
// argument of the size and of the Init functions, which store it in the specification structure,
// so ippWarpAffine selects the affine transform through the very same entry points. */
IppiWarpTransformType warpType = ippWarpPerspective;
/* The uniformity of the batch, a bitmask of the flags of the IppBatchType enumeration, so it is
// an int and not a value of that enumeration. A flag states that the items of that kind are one
// contiguous tensor, described by a single descriptor: the image i of a uniform direction begins
// at the byte i * size.height * step of its descriptor and the matrix of the image i of a
// uniform transform at the element i * size of its one. The sources and the destinations of this
// batch are separate images of their own sizes, so only the matrices, which are one contiguous
// array here, carry a flag. It is a statement of the caller and it is not verified, so the
// memory of a direction that is declared uniform must really be that tensor. */
int batchType = ippBatchUniformTransform;
Ipp8u *pSrcImages[BATCH_SIZE] = {NULL};
Ipp8u *pDstImages[BATCH_SIZE] = {NULL};
int srcSteps[BATCH_SIZE] = {0};
int dstSteps[BATCH_SIZE] = {0};
/* one descriptor per source and per destination image, and the single descriptor of the tensor
// of the transform matrices */
IppiBatchItem srcBatch[BATCH_SIZE];
IppiBatchItem dstBatch[BATCH_SIZE];
IppBatchItem coeffsBatch[1];
IppiWarpBatchSpec *pSpec = NULL;
Ipp8u *pInitBuf = NULL;
Ipp8u *pBuffer = NULL;
IppSizeL specSize = 0, initBufSize = 0, bufSize = 0;
/* The interpolation of the batch is one method of the IPPI_INTER_ set of ipptypes.h */
int interpolation = IPPI_INTER_LINEAR;
IppiBorderType border = ippBorderConst;
/* The constant border value holds one component per channel of the batch. 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 NUM_CHANNELS components
// and returns ippStsBadArgErr when they are not equal ones. */
Ipp64f borderValue[3] = {0.0, 0.0, 0.0};
/* The direction of the transform and the number of the channels are shared by the batch too, they
// are passed on to the underlying single image warp as they are. The warp function must be the
// channel flavor of that number: ippiWarpBatch_8u_C3R_L for NUM_CHANNELS equal to 3, whose images
// are allocated by ippiMalloc_8u_C3, and so on. */
IppiWarpDirection direction = ippWarpBackward;
/* The single descriptor of the tensor of the matrices: its pMem points at the matrix of the image
// of the index zero and its size counts the coefficients of one matrix, not of the whole tensor */
coeffsBatch[0].pMem = &coeffs[0][0][0];
coeffsBatch[0].size = NUM_COEFFS;
/* Allocate the source and the destination images and fill their descriptors. The sizes of an
// image of the batch are the ones of its descriptor, and the whole source image is transformed
// into the whole destination image, so an image of its own sizes needs no rectangle. */
for (i = 0; i < BATCH_SIZE; i++) {
int srcWidth = SRC_WIDTH - 32 * i;
int srcHeight = SRC_HEIGHT - 32 * i;
int dstWidth = DST_WIDTH - 16 * i;
int dstHeight = DST_HEIGHT - 16 * i;
/* ippiGetPerspectiveTransform belongs to the standard API, so it takes the 32 bit flavor of
// the source rectangle whose image the quadrangle of a region is */
IppiRect srcROI = {0, 0, srcWidth, srcHeight};
pSrcImages[i] = ippiMalloc_8u_C1(srcWidth, srcHeight, &srcSteps[i]);
pDstImages[i] = ippiMalloc_8u_C1(dstWidth, dstHeight, &dstSteps[i]);
/* Step 1: the matrix that maps the source image of this image of the batch to its region.
// The matrices of the batch are one contiguous tensor, so the one of this image is at its
// own position inside it. */
check_sts(status = ippiGetPerspectiveTransform(srcROI, quads[i], coeffs[i]));
srcBatch[i].pMem = pSrcImages[i];
srcBatch[i].step = (IppSizeL)srcSteps[i];
srcBatch[i].size.width = srcWidth;
srcBatch[i].size.height = srcHeight;
dstBatch[i].pMem = pDstImages[i];
dstBatch[i].step = (IppSizeL)dstSteps[i];
dstBatch[i].size.width = dstWidth;
dstBatch[i].size.height = dstHeight;
}
/* Step 2: compute the size of the specification structure of the batch. The size of a single
// image specification structure depends on the sizes and on the transform matrix of that image,
// so the descriptors and the matrices of the whole batch must be filled before this call. */
check_sts(status = ippiWarpBatchGetSize_L(srcBatch, dstBatch, BATCH_SIZE, coeffsBatch, warpType, ipp8u, NUM_CHANNELS, interpolation, direction,
border, batchType, &specSize, &initBufSize));
pSpec = (IppiWarpBatchSpec *)ippsMalloc_8u_L(specSize);
/* Step 3: allocate the temporal buffer of the initialization. It is used by the call below only,
// so it can be released as soon as the specification structure is built. */
if (initBufSize > 0)
pInitBuf = ippsMalloc_8u_L(initBufSize);
/* Step 4: store the parameters that are shared by the whole batch, the transform among them. The
// parameters of the cubic filter are the default ones here, that is B = 0.0 and C = 0.75; call
// ippiBatchSetCubicArgs afterwards to replace them */
check_sts(status = ippiWarpBatchInit_L(srcBatch, dstBatch, BATCH_SIZE, coeffsBatch, warpType, ipp8u, NUM_CHANNELS, interpolation, direction,
border, borderValue, batchType, pSpec, pInitBuf));
/* Step 5: the size of the work buffer is a property of an initialized specification structure,
// which carries every parameter of the batch, the transform among them, so this call takes the
// descriptors and the matrices only */
check_sts(status = ippiWarpBatchGetBufferSize_L(srcBatch, dstBatch, BATCH_SIZE, coeffsBatch, pSpec, &bufSize));
pBuffer = ippsMalloc_8u_L(bufSize);
/* Step 6: transform the whole batch. There is one entry point per data type, and the transform
// it performs is the one stored in the specification structure. */
check_sts(status = ippiWarpBatch_8u_C1R_L(srcBatch, dstBatch, BATCH_SIZE, coeffsBatch, pSpec, pBuffer));
EXIT_MAIN
for (i = 0; i < BATCH_SIZE; i++) {
ippiFree(pSrcImages[i]);
ippiFree(pDstImages[i]);
}
ippsFree(pSpec);
ippsFree(pInitBuf);
ippsFree(pBuffer);
printf("Exit status %d (%s)\n", (int)status, ippGetStatusString(status));
return (int)status;
}
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.
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.
ResizeBatch_L Resizes a batch of images of different sizes with a single call.
WarpAffineLinear Performs an affine warp transform of an image with linear interpolation.