Intel® Integrated Performance Primitives (Intel® IPP) Developer Guide and Reference
Using Intel IPP Batch Resize Functions
The batch resize functions resize a group of images with a single function call. The parameters of the transform are common to the whole batch, the sizes of the images are not: every image of the batch has its own source and destination sizes, given by its descriptors, while the data type, the number of the channels, the interpolation method, the parameters of the filters, and the border of the transform are common to the whole batch. Because the sizes differ, the scale ratio differs from image to image.
A single call amortizes the call overhead over the whole group, which makes the batch functions preferable when many images of different sizes have to be resized with the same parameters, for example when preparing the fixed size input tensor of an inference pipeline.
The batch resize 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. They are built on top of the _L flavor of the single-image resize, so the sizes of the batch interface are passed through to it unchanged.
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:
typedef struct {
void* pMem;
IppSizeL step;
IppiSizeL size;
} IppiBatchItem;
pMem |
Pointer to the memory of the image. |
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. |
Uniform Directions
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 batchType bitmask states which of the two directions is uniform: the ippBatchUniformSrc flag for the sources, the ippBatchUniformDst flag for the destinations, both flags when both directions are tensors, and ippBatchNonUniform, the empty mask, when neither is.
A single descriptor is enough for a uniform direction, and only one is read: its array holds exactly one element, whose pMem points at the whole tensor and whose size and step are the ones of every image of it. The image of the index i of a uniform direction begins at the byte i * size.height * step of that descriptor. A non-uniform direction is described image by image: its array holds nBatchSize descriptors, and neither the sizes nor the memory of its images are related. The two directions are independent, so a batch of separately allocated sources of different sizes that is resized into one destination tensor, the usual input of an inference pipeline, passes nBatchSize source descriptors, a single destination descriptor, and ippBatchUniformDst.
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 resize produce a wrong destination instead of an error.
Batch Specification Structure
The parameters that are shared by the whole batch are stored in the specification structure of the batch:
typedef struct ResizeBatchSpec IppiResizeBatchSpec;
IppiResizeBatchSpec is opaque, exactly as the single image IppiResizeSpec is: its layout is internal to the library and its fields are not accessible to the application. The structure 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 for every image, in one memory block. Its size is returned by the ResizeBatchGetSize_L function and it is filled by the ResizeBatchInit_L function, which takes no buffers. The ResizeBatchGetBufferSize_L function and the ResizeBatch_L function return the ippStsContextMatchErr status for a structure that was not initialized by it.
The shared parameters are the arguments of the Init function, except for the parameters of the cubic filter, which the BatchSetCubicArgs function replaces in an initialized structure:
dataType |
Data type of the source and destination images of the batch. Supported values: ipp8u and ipp32f. The resize 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. The resize function of the batch must be the channel flavor of that number, otherwise it returns the ippStsNumChannelsErr status. |
interpolation |
Interpolation method combined with the antialiasing flag by the bitwise OR. See the Antialiasing section below. |
valueB |
The B parameter of the cubic filter, used when the interpolation method is IPPI_INTER_CUBIC. The default value, set by the ResizeBatchInit_L function, is 0.0. Replace it with the BatchSetCubicArgs function. The IPPI_INTER_CUBIC2P_ methods name a predefined kernel, so the Init function stores the B value of that kernel instead and there is nothing to replace. |
valueC |
The C parameter of the cubic filter, used when the interpolation method is IPPI_INTER_CUBIC. The default value, set by the ResizeBatchInit_L function, is 0.75. Together with valueB = 0.0 it is the kernel of the OpenCV INTER_CUBIC interpolation. Replace it with the BatchSetCubicArgs function. The IPPI_INTER_CUBIC2P_ methods name a predefined kernel, so the Init function stores the C value of that kernel instead and there is nothing to replace. |
algHint |
Accuracy hint of the transform, applied to every image of the batch. See the Accuracy Hint section below. |
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. It is not used by the supported border types; pass NULL. 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. |
batchType |
Bitmask of the directions in which the batch is uniform, that is of the directions that are one contiguous tensor described by a single descriptor: the ippBatchUniformSrc flag for the sources, the ippBatchUniformDst flag for the destinations, ippBatchNonUniform when neither direction is. It is a combination of the flags of the IppBatchType enumeration, so the parameter is an int and not a value of that enumeration. See the Uniform Directions section above. When both flags are set, all the images of the batch have the same sizes, so the single image specification structure is built once for the whole batch instead of once per image. |
The single image part of the structure is not filled by the Init functions: it describes the scale ratio of one image of the batch, so it is built by the batch functions themselves out of the sizes of the current descriptor.
Because every parameter of the batch is stored here, the ResizeBatchGetBufferSize_L function and the ResizeBatch_L function take no argument of the batch besides the descriptors and this structure. The dataType, the numChannels, the interpolation, and the batchType parameters are arguments of the ResizeBatchGetSize_L function too, because it is called before this structure exists: the size it returns depends on the first three of them and the number of the descriptors it reads on the last one. Pass the same values to the Init function. The number of lobes of the Lanczos filter is carried by the interpolation method: IPPI_INTER_LANCZOS is the Lanczos filter of two lobes (4x4 kernel) and IPPI_INTER_LANCZOS3 the Lanczos filter of three lobes (6x6 kernel).
Processing Sequence
To resize a batch of images, follow these steps:
Choose the batchType of the batch, allocate the descriptor array of each of the two directions, of nBatchSize elements for a non-uniform direction and of one element for a uniform one, and fill the pMem, step, and size fields of every element.
Call the ResizeBatchGetSize_L function with the data type, the number of the channels, the interpolation method, and the batch type of the batch to get the sizes of the specification structure and of the temporary initialization buffer, and allocate them.
Call the ResizeBatchInit_L function to store the parameters that are shared by the whole batch, the data type, the number of the channels, the interpolation method, the accuracy hint, and the border of the transform among them, in the specification structure. It sets the default parameters of the cubic filter, and it replaces them by the predefined kernel of the method when the interpolation is one of the IPPI_INTER_CUBIC2P_ ones. If the batch is a IPPI_INTER_CUBIC one and the default kernel is not the wanted one, call the BatchSetCubicArgs function afterwards to replace those two parameters.
Call the ResizeBatchGetBufferSize_L function to get the size of the work buffer, and allocate it. This function needs the structure initialized in step 3, whose single image part it uses as a scratch space, and the temporary initialization buffer of step 2, which can be released as soon as this call has returned.
Call the ResizeBatch_L function to resize 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 is the maximum of the two and one allocation covers both of them.
Unlike the single image resize, where one initialized specification structure describes one scale ratio, the batch rebuilds the single image part of the shared specification structure from the sizes of the current descriptor before every image. 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 any of the sizes of the batch, the data type, the number of the channels, or the interpolation method, repeat all the steps from step 2 on, because the sizes of the shared memory depend on them. If you only change the parameters of the cubic filter, the accuracy hint, the border, or the batch type of the sizes, repeat the steps from step 3 on. If you only change the image pointers or the steps, only step 5 has to be repeated.
The size of the batch is not restricted from below: a batch of one image is processed as that single image, and an empty batch, that is nBatchSize equal to zero, is no error either. Every function of the batch takes an empty one, processes no image, and returns the ippStsNoOperation warning; the size returned in step 2 is the one of the shared parameters alone, so the sequence above needs no special case for a batch that turns out to be empty. Only a negative nBatchSize is rejected, with the ippStsSizeErr status.
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 resize function applies them to every image of the batch. The supported border types are ippBorderRepl and ippBorderInMem for the transform without antialiasing, and ippBorderRepl, ippBorderMirror, ippBorderMirrorR, and ippBorderInMem for the transform with antialiasing. The IPPI_INTER_NN and the IPPI_INTER_SUPER methods do not use a border; the border parameters are ignored for them.
The border is not verified by the Init function, because the set of the supported types depends on the interpolation method and on the IPPI_ANTIALIASING flag, and the check is the one of the underlying single image resize. A border that the method in use does not support therefore makes the ResizeBatch_L function return the ippStsBorderErr status.
The batch resizes whole images and not tiles of them, so the border of the destination is the border of the source image itself. The destination is a whole image of the destination size of its descriptor, so no destination offset can be specified: an offset would change the scale ratio that the specification structure describes.
Channel Flavors
The number of the channels of the batch is a parameter of the batch: it is an argument of the ResizeBatchGetSize_L 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 ResizeBatch_L function 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 resize, and the transform of a multichannel batch is the multichannel transform of that resize, 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.
Antialiasing
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, IPPI_INTER_CUBIC2P_B05C03, IPPI_INTER_LANCZOS, IPPI_INTER_LANCZOS3, and IPPI_INTER_SUPER methods, optionally combined with the IPPI_ANTIALIASING flag by the bitwise OR, for example IPPI_INTER_LINEAR | IPPI_ANTIALIASING, to use the antialiasing flavor of the underlying single-image resize. The interpolation is shared by the whole batch: pass the same value to the ResizeBatchGetSize_L function and to the Init function, which stores it in the specification structure, and the remaining functions of the batch take it from there.
When the IPPI_ANTIALIASING flag is set, the IPPI_INTER_LINEAR, the four cubic, IPPI_INTER_LANCZOS, and IPPI_INTER_LANCZOS3 methods use their antialiasing flavor. For the IPPI_INTER_NN and the IPPI_INTER_SUPER methods, which have no antialiasing flavor, the functions return the ippStsNoAntialiasing warning and proceed without it.
Accuracy Hint
The algHint parameter of the Init function selects the flavor of the filters that the transform of every image of the batch uses, exactly as the ResizeSetMode function selects it for a single image. The ippAlgHintNone and the ippAlgHintAccurate values select the accurate flavor, which every interpolation method has, and ippAlgHintFast selects the fast one, which trades accuracy for speed.
The fast flavor exists for the ipp8u data type and the IPPI_INTER_LINEAR, the four cubic, IPPI_INTER_LANCZOS, and IPPI_INTER_LANCZOS3 methods without the IPPI_ANTIALIASING flag only. The hint is a parameter of the batch and not of a single image, so an unsupported combination is rejected by the Init function with the ippStsNotSupportedModeErr status and not by the resize function. The size of the specification structure does not depend on the hint, so repeating the Init call is enough to change it.
Threading Layer Functions
Every function of the batch resize group has a Threading Layer flavor, declared in ippi_tl.h. The suffix of that flavor is _LT for the functions of the _L API and _T for the BatchSetCubicArgs function, whose name carries no _L suffix. The Threading Layer distributes the images of the batch over the threads, so each thread resizes 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 resize 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, the data type, the number of the channels, the interpolation method, the accuracy hint, and the border of the transform among them, and stores them in the shared part of the specification structure, which the threads only read. Because IppiResizeBatchSpec is opaque and the layout behind it is private to a flavor, the whole structure must be sized by ResizeBatchGetSize_LT and initialized by ResizeBatchInit_LT; a specification structure of one flavor cannot be passed to the functions of the other one. The batchType parameter is interpreted exactly as in the single threaded flavor, a uniform direction being one tensor of a single descriptor, but it saves no work here: every thread builds its own single image specification structure in its private slice of the memory, so a fully uniform batch does not build it once for the whole batch.
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 resize 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
ResizeBatchGetSize_L Computes the sizes of the specification structure and of the temporary initialization buffer for the batch resize.
ResizeBatchGetBufferSize_L Computes the size of the work buffer for the batch resize.
ResizeBatchInit_L Initializes the specification structure of a resize batch with the default filter parameters.
BatchSetCubicArgs Sets the parameters of the cubic filter in an initialized specification structure of a resize batch.
ResizeBatch_L Resizes a batch of images of different sizes with a single call.