WTFwd

Performs one-level wavelet decomposition of an image.

Syntax

IppStatus ippiWTFwd_32f_C1R (const Ipp32f* pSrc, int srcStep, Ipp32f* pApproxDst, int approxStep, Ipp32f* pDetailXDst, int detailXStep, Ipp32f* pDetailYDst, int detailYStep, Ipp32f* pDetailXYDst, int detailXYStep, IppiSize dstRoiSize, const IppiWTFwdSpec_32f_C1R* pSpec, Ipp8u* pBuffer);

IppStatus ippiWTFwd_32f_C3R (const Ipp32f* pSrc, int srcStep, Ipp32f* pApproxDst, int approxStep, Ipp32f* pDetailXDst, int detailXStep, Ipp32f* pDetailYDst, int detailYStep, Ipp32f* pDetailXYDst, int detailXYStep, IppiSize dstRoiSize, const IppiWTFwdSpec_32f_C3R* pSpec, Ipp8u* pBuffer);

Parameters

pSrc: Pointer to the source image ROI.
srcStep: Distance in bytes between starts of consecutive lines in the source image buffer.
pApproxDst: Pointer to ROI of the destination approximation image.
approxStep: Distance in bytes between starts of consecutive lines in the approximation image buffer.
pDetailXDst: Pointer to ROI of the destination horizontal detail image.
detailXStep: Distance in bytes between starts of consecutive lines in the horizontal detail image buffer.
pDetailYDst: Pointer to ROI of the destination vertical detail image.
detailYStep: Distance in bytes between starts of consecutive lines in the vertical detail image buffer.
pDetailXYDst: Pointer to ROI of the destination diagonal detail image.
detailXYStep: Distance in bytes between starts of consecutive lines in the diagonal detail image buffer.
dstRoiSize: Size of the ROI in pixels for all destination images.
pSpec: Pointer to the allocated and initialized forward DWT context structure.
pBuffer: Pointer to the allocated buffer for intermediate operations

Description

The function ippiWTFwd is declared in the ippi.h file. It operates with ROI (see Regions of Interest in Intel IPP). This function performs one-level wavelet decomposition of a source image pointed to by pSrc into four destination subimages pointed to by pApproxDst, pDetailXDst, pDetailYDst, and pDetailXYDst. See Figure “Equivalent Scheme of Wavelet Decomposition Algorithm” for the equivalent algorithm of ippiWTFwd function operation.

Wavelet parameters are contained in the forward transform context structure pSpec. It must be allocated and initialized by the function ippiWTFwdInitAlloc beforehand.

The decomposition function needs a buffer pBuffer for temporary calculations. Its size can be computed by calling the function ippiWTFwdGetBufSize. The buffer size does not depend on the size of processed images, and the same buffer can be used for decomposing images of different size. However, it is not recommended to use the same buffer in different threads in a multithreaded mode. For better performance, use an aligned memory location for this buffer, which can be allocated by the function ippiMalloc.

Optimization Notice
The Intel® Integrated Performance Primitives (Intel® IPP) library contains functions that are more highly optimized for Intel microprocessors than for other microprocessors. While the functions in the Intel® IPP library offer optimizations for both Intel and Intel-compatible microprocessors, depending on your code and other factors, you will likely get extra performance on Intel microprocessors. While the paragraph above describes the basic optimization approach for the Intel® IPP library as a whole, the library may or may not be optimized to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include Intel® Streaming SIMD Extensions 2 (Intel® SSE2), Intel® Streaming SIMD Extensions 3 (Intel® SSE3), and Supplemental Streaming SIMD Extensions 3 (Intel® SSSE3) instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors. Intel recommends that you evaluate other library products to determine which best meets your requirements.

Optimization Notice

The Intel® Integrated Performance Primitives (Intel® IPP) library contains functions that are more highly optimized for Intel microprocessors than for other microprocessors. While the functions in the Intel® IPP library offer optimizations for both Intel and Intel-compatible microprocessors, depending on your code and other factors, you will likely get extra performance on Intel microprocessors.

While the paragraph above describes the basic optimization approach for the Intel® IPP library as a whole, the library may or may not be optimized to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include Intel® Streaming SIMD Extensions 2 (Intel® SSE2), Intel® Streaming SIMD Extensions 3 (Intel® SSE3), and Supplemental Streaming SIMD Extensions 3 (Intel® SSSE3) instruction sets and other optimizations. Intel does not guarantee the availability, functionality, or effectiveness of any optimization on microprocessors not manufactured by Intel. Microprocessor-dependent optimizations in this product are intended for use with Intel microprocessors.

Intel recommends that you evaluate other library products to determine which best meets your requirements.

The pointer pSrc points to memory location of the source image rectangular ROI of size srcWidth by srcHeight which is uniquely determined by the size of destination ROI as:

srcWidth = 2 * dstRoiSize.width srcHeight = 2 * dstRoiSize.height

Note the source image ROI does not include border pixels necessary to compute some destination pixels. It means that prior to using ippiWTFwd function the application program must apply some border extension model (symmetrical, wraparound or another) to the source image ROI through filling of neighboring memory locations. As a result, the size of memory block allocated for the source image must be extended to accommodate for added border pixels outside ROI formal boundaries.

Figure “Extended Source Image for Wavelet Decomposition” schematically shows the source image ROI and extended image area.

Extended Source Image for Wavelet Decomposition

Use the following C-language expressions to calculate extended image border sizes:

int leftBorderLow   = lenLow   - 1 - anchorLow;
int leftBorderHigh  = lenHigh  - 1 - anchorHigh;
int rightBorderLow  = lenLow   - 2 - leftBorderLow;
int rightBorderHigh = lenHigh  - 2 - leftBorderHigh;
int leftTopBorder     = IPP_MAX(leftBorderLow, leftBorderHigh);
int rightBottomBorder = IPP_MAX(rightBorderLow, rightBorderHigh);

See the description of the function ippiWTFwdInitAlloc for the explanation of the parameters.

Note that the left and top borders have equal size. The same holds for the right and bottom borders which have equal size too.

The size of the source image area extended by border pixels can be defined as

srcWidthWithBorders = srcWidth  + leftTopBorder + rightBottomBorder;    
srcHeightWithBorders = srcHeight + leftTopBorder + rightBottomBorder;

All destination images have equal size specified by the parameter dstRoiSize.

Conversely, to perform a wavelet reconstruction of the full size source image from the component images obtained by decomposition, use extended component images for the reconstruction pass. See the description of the function ippiWTInv for more details.

The ROI concept used in wavelet transform functions can be applied to processing large images by blocks, or ‘tiles'. To accomplish this, the source image should be subdivided into overlapping blocks in the following way:

Main part (ROI) of each block is adjacent to neighboring blocks and has no intersection with neighbor's ROIs;
Extended borders of each block overlap with ROIs of neighboring blocks.

This subdivision scheme is illustrated in Figure “Image Division into Blocks with Overlapping Borders” .

Image Division into Blocks with Overlapping Borders

Example “Using Intel IPP Functions for Wavelet Transforms” shows how to use the function ippiWTFwd_32f_C1R.

Return Values

ippStsNoErr	Indicates no error. Any other value indicates an error or a warning.
ippStsNullPtrErr	Indicates an error condition if any of the specified pointers is `NULL`.
ippStsSizeErr	Indicates an error condition if dstRoiSize has a field with zero or negative value.
ippStsStepErr	Indicates an error condition if step through any buffer is less than or equal to zero.
ippStsContextMatchErr	Indicates an error condition if a pointer to an invalid context structure is passed.