To provide easy-to-use APIs and reduce the effort required to add Intel® Integrated Performance Primitives (Intel® IPP) functions to your application, Intel® IPP library introduces new Integration Wrappers APIs. These APIs aggregate multiple Intel® IPP functions and provide easy interfaces to support external threading of Intel® IPP functions.
Integration Wrappers consist of C and C++ interfaces:
- C interface aggregates Intel IPP functions of similar functionality with various data types and channels into one function. Initialization steps required by several Intel IPP functions are implemented in one initialization function for each functionality. To reduce the size of your code and save time required for integration, the wrappers handle all memory management and Intel IPP function selection routines.
- C++ interface wraps around the C interface to provide default parameters, easily initialized objects as parameters, exception handling, and objects for complex Intel IPP functions with automatic memory management for specification structures.
Integration Wrappers are available as a separate download in the form of source and pre-built binaries.
1. Intel® IPP Integration Wrappers Overview
1.1 Key Features
Integration Wrappers simplify usage of Intel IPP functions and address some of the advanced use cases of Intel IPP. They consist of the C and C++ APIs which provide the following key features:
C interface provides compatibility with C libraries and applications and enables you to use the following features of Integration Wrappers:
- Automatic selection of the proper Intel IPP function based on input parameters
- Automatic handling of temporary memory allocations for Intel IPP functions
- Improved tiling handling and automatic borders processing for tiles
- Memory optimizations for threading
C++ interface additionally provides:
- Easier to use classes like IwSize (image size structure in Integration Wrappers) instead of IppiSize (image size structure in Intel IPP functions), IwRect instead of IppiRect, and IwValue as a unified scalar parameter for borders and other per-channel input values
- Complex Intel IPP functions designed as classes to use automatic construction and destruction features
The following two code examples implement the image resizing operation with two APIs 1) Resizing image with the Intel® IPP functions 2) Resizing image using the Intel® IPP Integration Wrappers APIs. The second implementation is much simpler requires less effort to use the Intel IPP functions.
1.Image Resizing with Intel® IPP functions
2. Image Resize with Intel® IPP Integration Wrappers (C++ interface)
1.2 Threading
The API of Integration Wrappers (IW) is designed to simplify tile-based processing of images. Tiling is based on the concept of region of interest (ROI).
Most IW image processing functions operate not only on whole images but also on image areas - ROIs. Image ROI is a rectangular area that is either some part of the image or the whole image.
The sections below explain the following IW tiling techniques:
- Manual tiling
- IwiRoi-based tiling, including:
IW functions are designed to be tiled using the IwiRoi interface. But if for some reasons automatic tiling with IwiRoi is not suitable, there are special APIs to perform tiling manually.
When using manual tiling you need to:
- Shift images to a correct position for a tile using iwiImage_GetRoiImage
- If necessary, pass correct border InMem flags to a function using iwiRoi_GetTileBorder
- If necessary, check the filter border around the image border using iwiRoi_CorrectBorderOverlap
Here is an example of IW threading with OpenMP* using manual tiling:
You can use basic tiling to tile or thread one standalone function or a group of functions without borders. To apply basic tiling, initialize the IwiRoi structure with the current tile rectangle and pass it to the processing function.
For functions operating with different sizes for source and destination images, use the destination size as a base for tile parameters.
Here is an example of IW threading with OpenMP* using basic tiling with IwiRoi:
With the IwiRoi interface you can easily tile pipelines by applying a current tile to an entire pipeline at once instead of tiling each function one by one. This operation requires borders handling and tracking pipeline dependencies, which increases complexity of the API. But when used properly, pipeline tiling can increase scalability of threading or performance of non-threaded functions by performing all operations inside the CPU cache.
Here are some important details that you should take into account when performing pipeline tiling:
- Pipeline tiling is performed in reverse order: from destination to source, therefore:
- Use the tile size based on the destination image size
- Initialize the IwiRoi structure with the IwiRoiPipeline_Init for the last operation
- Initialize the IwiRoi structure for other operations from the last to the first with IwiRoiPipeline_InitChild
- Obtain the border size for each operation from its mask size, kernel size, or using the specific function returning the border size, if any.
- If you have a geometric transform inside the pipeline, fill in the IwiRoiScale structure for IwiRoi for this transform operation.
- In case of threading, copy initialized IwiRoi structures to a local thread or initialize them on a per-thread basis. Access to structures is not thread-safe.
- Do not exceed the maximum tile size specified during initialization. Otherwise, this can lead to buffers overflow.
The IW package contains several advanced tiling examples, which can help you understand the details of the process. For more information on how to find and use these examples, please download package and view contained developer reference for Integration Wrappers for Intel IPP.
The following example demonstrates IW threading with OpenMP* using IwiRoi pipeline tiling:
2. Getting Started
To learn more about Integration Wrappers, please refer to the developer guide here.
3. Support
If you have any problems with Intel® IPP Integration Wrappers, post your questions at Intel® IPP forum. If you already register your Intel® software product at the Intel® Software Development Products Registration Center, you can also submit your question by Intel® Premier Support.