IPPWrappers

IPP wrapper functions

Most of the IPP functions follow a simple internal logic which can be derived from their corresponding function header. This is exploited by script config.php for automatically creating wrapper functions in the QVision. Other IPP functions will not follow precisely this logic, and their corresponding wrapper function must be hand-crafted.

Automatically generated wrapper functions are contained in the qvippfunctions.h and qvippfunctions.cpp source files, in the directory ‘trunk/src/qvipp’. Hand-crafted wrapper functions are contained inside the qvipp.h and qvipp.cpp source files, in the same path.

The scripts require to know the path to the QVision and IPP header. Both paths should be specified in the script file ‘config.php’. The files ‘ippfunctions.txt’ and ‘ippblocks.txt’ text files list the IPP functions that should be parsed to create the wrapper function and the QVision processing block respectively. To finally generate the files ‘qvippfunctions.*’ simply use the command ‘make’ in the scripts directory.

The scripts generate IPP wrapper functions from their corresponding IPP header function as follows. IPP wrapper functions have the same parameters and in the same order than the corresponding IPP function. An example for this can be seen in the following IPP function:

:::c++
IppStatus ippiAdd_8u_C1RSfs(
    const Ipp8u* pSrc1, int src1Step,
    const Ipp8u* pSrc2, int src2Step,
    Ipp8u* pDst, int dstStep,
    IppiSize roiSize,
    int scaleFactor);

And its corresponding wrapper function in the qvipp package:

:::c++
void Add(
    const QVImage<uChar, 1> & qvimage_pSrc1,
    const QVImage<uChar, 1> & qvimage_pSrc2,
    QVImage<uChar, 1> & qvimage_pDst,
    const int scaleFactor = 1,
    const QPoint &destROIOffset = QPoint(0,0)
);

The prefix 'ippi' and the sufix '_8u_C1RSfs' in the original IPP function name are suppressed for the IPP wrapper function name, so the call for the IPP wrapper function is quite simple.

Sets of parameters in the IPP function corresponding to an input image (specified by a data pointer, step size and image width and height) or an array are translated to a single input parameter of type QVImage and QVMatrix respectively.
For example, the following conversion of sets of parameters is used:

:::c++
const Ipp8u * src, int step ->    const QVImage<uChar> /* Input image */
Ipp16s *dest, int step      ->    QVImage<sShort> /* Output image */

The image bit-depth and number of channels can be inferred from the suffix of the IPP function name. For example:

:::c++
ippiAddC_8u_C1C3R   -> 1 channel for input images and 3 channels for output images.
ippiAddC_8u_C4C1R   -> 4 channels for input images and 1 channel for output images.
ippiAddC_8u_C3R         -> 3 channels for either input and output images.

In certain cases, a single ‘Ippi8u*’ parameter with name ‘pBuffer’ in the IPP function is conveniently mapped to a buffer data image of type ‘QVImage<uchar, 1="">’. For example, the IPP function for FastMarching with header:</uchar,>

:::c++
IppStatus ippiFastMarching_8u32f_C1R(
    const Ipp8u* pSrc, int srcStep,
    Ipp32f* pDst, int dstStep,
    IppiSize roiSize,
    Ipp32f radius,
    Ipp8u* pBuffer);

Is mapped to the following wrapper function definition:

:::c++
void FastMarching(
    const QVImage<uChar, 1> & qvimage_pSrc,
    QVImage<sFloat, 1> & qvimage_pDst,
    const sFloat radius,
    QVImage<uChar, 1> & qvimage_pBuffer,
    const QPoint &destROIOffset);

Parameters of type ‘IppiSize’ with name ‘roiSize’ or ‘dstRoiSize’ in the IPP function header are interpreted as image ROI’s. These parameters are suppressed in the header of the wrapper function, because the code of the wrapper function obtain the image ROI from the QVImage object.

Furthermore, certain IPP wrapper function will augment the header of the IPP function with extra
parameters. For example, the wrapper functions corresponding to IPP functions with several input images and one output image will include an extra parameter denominated ‘destROIOffset’, of type ‘QPoint’. The programmer can indicate in this parameter where to locate the ROI in the destination image. The size of the destination ROI is inferred from the ROI of the input images.

Parameters of type ‘IppiSize’ wiith name ‘maskSize’ in IPP functions are converted to constant ‘QSize’ type parameters in the wrapper function. Parameters of type ‘IppiPoint’ are converted to ‘QPoint’ parameters as well. An example for both conversions can be seen in the function FilterMedian. The following header for the IPP function:

:::c++
IppStatus ippiFilterMedian_8u_C1R(
    const Ipp8u* pSrc, int srcStep,
    Ipp8u* pDst, int dstStep,
    IppiSize dstRoiSize,
    IppiSize maskSize,
    IppiPoint anchor);

converts to the following header for the wrapper function:

:::c++
void FilterMedian(
    const QVImage<uChar, 1> & qvimage_pSrc,
    QVImage<uChar, 1> & qvimage_pDst,
    const QSize &maskSize,
    const QPoint &anchor,
    const QPoint &destROIOffset);

In the code of wrapper functions which use fixed size or variable size masks, the destination ROI size must be reduced according to the mask size. This applies for example in IPP functions ippiFilterMax_8u_C1R, ippiFilterGauss_8u_C1R, or ippiFilterMedian_8u_C1R.

The remaining pointer type parameters in IPP functions are converted to reference parameters for the wrapper functions, to make the code more elegant. The rest of the parameters are converted to constant parameters.