Intel® Integrated Performance Primitives (Intel® IPP) Developer Guide and Reference
ResizeBatchInit_L
Initializes the specification structure of a resize batch with the default filter parameters.
Syntax
IppStatus ippiResizeBatchInit_L(const IppiBatchItem* pSrcBatch, const IppiBatchItem* pDstBatch, IppSizeL nBatchSize, IppDataType dataType, int numChannels, int interpolation, IppHintAlgorithm algHint, IppiBorderType border, const Ipp<datatype>* pBorderValue, int batchType, IppiResizeBatchSpec* pSpec);
Threading Layer (TL) flavor:
IppStatus ippiResizeBatchInit_LT(const IppiBatchItem* pSrcBatch, const IppiBatchItem* pDstBatch, IppSizeL nBatchSize, IppDataType dataType, int numChannels, int interpolation, IppHintAlgorithm algHint, IppiBorderType border, const Ipp<datatype>* pBorderValue, int batchType, IppiResizeBatchSpec* pSpec);
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. |
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. |
nBatchSize |
Number of the images of the batch. Must not be negative. A batch of one image is legal, that image is simply the only one that is processed. An empty batch, that is nBatchSize equal to zero, is legal as well: no image is processed and the function returns the ippStsNoOperation warning. |
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 ResizeBatchGetSize_L function was called with, and the resize function of the batch must be the flavor of that data type. |
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, shared by the whole batch. The method is one of 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. 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. Add IPPI_ANTIALIASING to switch the antialiasing on, for example IPPI_INTER_LINEAR | IPPI_ANTIALIASING. Must be the value that the ResizeBatchGetSize_L function was called with. |
algHint |
Accuracy hint of the transform of every image of the batch, shared by the whole batch. Supported values: ippAlgHintNone and ippAlgHintAccurate, which select the accurate flavor of the filters, and ippAlgHintFast, which selects the fast one. 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 antialiasing only. |
border |
Type of the border of the transform, shared by the whole batch. Supported values: 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 have no border; the parameter is ignored for them. |
pBorderValue |
Pointer to the constant border value, shared by the whole batch. It is not used by the supported border types; pass NULL. 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 the directions of the batch that are uniform, a combination of the flags of the IppBatchType enumeration, so the parameter is an int and not a value of that enumeration: the ippBatchUniformSrc flag for the sources, the ippBatchUniformDst flag for the destinations, ippBatchUniformSrc | ippBatchUniformDst when both directions are uniform, and ippBatchNonUniform when neither is. A uniform direction is a tensor: 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, so a single descriptor of that direction is enough, its array holds exactly one element whose pMem points at the whole batch, and the image of the index i of it 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. Must be the value that the ResizeBatchGetSize_L function was called with. |
pSpec |
Pointer to the IppiResizeBatchSpec specification structure of the batch, sized by the ResizeBatchGetSize_L function. |
Description
This function stores the parameters that are shared by the whole batch, that is the data type, the interpolation method with the antialiasing flag, the parameters of the filters, the accuracy hint, the border of the transform, and the batch type of the sizes, in the opaque IppiResizeBatchSpec structure and marks that structure as initialized. Every function of the batch that follows takes them from there, so the descriptors are its only other argument. 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 replace them. 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 number of lobes of the Lanczos filter is not a parameter of this function either: it is carried by the interpolation method, where IPPI_INTER_LANCZOS is the filter of two lobes and IPPI_INTER_LANCZOS3 the filter of three lobes.
The border is a parameter of the batch and not of a single image, so it is stored here and the ResizeBatch_L function applies it to every image of the batch. It is not verified here: the set of the supported border types depends on the interpolation method and on the IPPI_ANTIALIASING flag, so an illegal border makes that function return the ippStsBorderErr status.
The single image specification structure itself is not initialized here: the scale ratio differs from image to image, so the ResizeBatch_L function builds it out of the sizes of the current descriptor and of the shared parameters of pSpec. That is why this function needs no buffer.
The batchType parameter is a property of the batch that the function does not derive from the descriptors, so it is supplied by the caller and it is taken on trust: no scan of the batch is performed, and a uniform direction whose images are neither of the size of its single descriptor nor stored contiguously is read, respectively written, at the offsets of that descriptor nevertheless, which produces wrong destination images instead of an error. When both of its flags are set, all the images of the batch have the same sizes, so the ResizeBatchGetBufferSize_L and the ResizeBatch_L functions build the single image specification structure once for the whole batch instead of once per image.
The accuracy hint is applied to the single image specification structure of every image of the batch, exactly as the ResizeSetMode function applies it to the specification structure of a single image. It is a parameter of the batch and not of a single image, so its combination with the data type and the interpolation method is verified here and not by the resize function.
Call this function after the ResizeBatchGetSize_L function, whose memory it needs, and before the ResizeBatchGetBufferSize_L function and the ResizeBatch_L function, both of which need the initialized structure and return the ippStsContextMatchErr status without it. Repeat the call to change the filter parameters, the accuracy hint, the border, or the batch type of the sizes; the size of the specification structure does not depend on them. A change of the data type or of the interpolation method needs the whole sequence from the ResizeBatchGetSize_L function on, because the size of the structure depends on both of them.
Whenever any of the sizes of the batch is changed, repeat the ResizeBatchGetSize_L and ResizeBatchGetBufferSize_L calls, because the sizes of the shared memory depend on the sizes of the images of the batch. 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 IppiResizeBatchSpec is opaque and the layout behind it is private to a flavor, a structure that is used with the _LT flavor of the resize function must be sized by ippiResizeBatchGetSize_LT and initialized by the _LT flavor of this function; the two flavors cannot exchange specification structures. 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 in the _LT flavors: every thread builds its own single image specification structure in its private slice, so a fully uniform batch does not build it once for the whole batch.
Return Values
ippStsNoErr |
Indicates no error. |
ippStsNullPtrErr |
Indicates an error when pSrcBatch, pDstBatch, or pSpec is NULL. |
ippStsSizeErr |
Indicates an error when nBatchSize is negative or when one of the sizes of a descriptor is negative. |
ippStsDataTypeErr |
Indicates an error when dataType has an illegal value. |
ippStsNumChannelsErr |
Indicates an error when numChannels is neither 1 nor 3. |
ippStsInterpolationErr |
Indicates an error when the interpolation method has an illegal value. |
ippStsBadArgErr |
Indicates an error when batchType has a bit outside the flags of the IppBatchType enumeration. |
ippStsNotSupportedModeErr |
Indicates an error when algHint has an illegal value or when it is ippAlgHintFast and the fast flavor of the filters does not exist for the given data type and interpolation method. |
ippStsNoAntialiasing |
Indicates a warning when the IPPI_ANTIALIASING flag is set and the method is IPPI_INTER_NN or IPPI_INTER_SUPER. The specification structure is initialized, the antialiasing is ignored by the transform. |
ippStsNoOperation |
Indicates a warning when nBatchSize is zero. The specification structure is initialized, there is simply nothing to resize with it. |
See Also
Using Intel IPP Batch Resize Functions
BatchSetCubicArgs Sets the parameters of the cubic filter in an initialized specification structure of a resize batch.
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.
ResizeBatch_L Resizes a batch of images of different sizes with a single call.