License Definitions

By downloading and installing this sample, you hereby agree that the accompanying materials are being provided to you under the terms and conditions of the End User License Agreement for the Intel® Integrated Performance Primitives (Intel® IPP) product previously accepted by you.

System Requirements

Recommended hardware:

Hardware requirements:

Software requirements:

Product specific requirements:

For more information please see Intel® IPP System Requirements.

Installation and Build

Extract files from the examples package to the desired destination folder. Make sure that the directory structure is preserved.

Setting the Build Environment

There are different methods of preparation of build environment for the Intel® IPP examples. They are described below.

Setting the Build Environment on Windows*

Suppose, that you have installed Intel® Parallel Studio XE or Intel® System Studio to <install_dir> of your computer. By default, <install_dir> is C:\Program Files (x86)\IntelSWTools directory.

First - the simplest - method is to start command-line window, using menu Start\All Programs\Intel Parallel Studio XE <yyyy>\Compiler and Performance Libraries\Command Prompt with Intel Compiler <vv>\Compiler <vv> for <cpu_arch> Visual Studio <vs_ver> environment. If Intel® System Studio is installed on your computer, the command line window shortcut is located in Start\All Programs\Intel System Studio YYYY for Windows target\Compiler and Performance Libraries... folder.

Here

  • <yyyy> is Intel® Parallel Studio XE (or, Intel® System Studio) version with specific update and package numbers;

  • <vv> is Intel® C/C++ compiler version;

  • <cpu_arch> is "IA-32" or "Intel 64".

You will have command-line window with all required evironment prepared.

The second method is to use specialized script to setup environment for Intel® tools from existing command-line window. The script is <install_dir>\parallel_studio_xe\compilers_and_libraries_<yyyy>\windows\bin\compilervars.bat and has two arguments: requred CPU architecture ("ia32" or "intel64") and required Microsoft* Visual Studio* environment ("vs2012", "vs2013", "vs2013shell", or "vs2015"). In case of Intel® System Studio installation the location of script is <install_dir>\system_studio_for_windows_yyyy.r.uuu\compilers_and_libraries_yyyy\windows\bin.

For example,

>"C:\Program Files (x86)\IntelSWTools\parallel_studio_xe\compilers_and_libraries_<yyyy>\windows\bin\compilervars.bat" ia32 vs2012
Copyright (C) 1985-2020 Intel Corporation. All rights reserved.
Intel(R) Compiler xx.yy

>set IPPROOT
IPPROOT=C:\Program Files (x86)\IntelSWTools\parallel_studio_xe\compilers_and_libraries_2017\windows\ipp

>set TBBROOT
TBBROOT=C:\Program Files (x86)\IntelSWTools\parallel_studio_xe\compilers_and_libraries_2017\windows\tbb\bin\..

The third method is to set separately environment variable for Intel® IPP and, if you want, for Intel® TBB. For that, two scripts are placed in Intel® Parallel Studio XE directory tree (or, in appropriate directory of Intel® System Studio installation): <install_dir>\parallel_studio_xe_<yyyy>\compilers_and_libraries_<yyyy>\windows\ipp\bin\ippvars.bat and <install_dir>\parallel_studio_xe_<yyyy>\compilers_and_libraries_<yyyy>\windows\tbb\bin\tbbvars.bat.

The fourth method is to set IPPROOT and TBBROOT manually. The main idea is that

  • IPPROOT/include should point to Intel® IPP include files;

  • IPPROOT/lib should point to Intel® IPP library directories. IPPROOT/lib/ia32 - to 32-bit Intel® IPP libraries, IPPROOT/lib/intel64 to 64-bit Intel® IPP libraries. The command-line window must have appropriate Visual Studio* environment set in this case.

For example, to set Microsoft* Visual Studio* 2015 environment and Intel® IPP example environment, you need to do

>"C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\bin\amd64\vcvars64.bat"
>set IPPROOT=C:\Program Files (x86)\IntelSWTools\parallel_studio_xe\compilers_and_libraries_2017\windows\ipp
>set TBBROOT=C:\Program Files (x86)\IntelSWTools\parallel_studio_xe\compilers_and_libraries_2017\windows\tbb

For details look into corresponding Intel® development package user’s guide.

Setting the Build Environment on Linux*

Start terminal window on Linux*. In this system Intel® software tools are installed by default to /opt/intel directory.

So, you can do any of the following steps.

$ source /opt/intel/compilers_and_libraries/linux/bin/compilervars.sh intel64
$ echo $IPPROOT; echo $TBBROOT
/opt/intel/compilers_and_libraries_<yyyy>/linux/ipp
/opt/intel/compilers_and_libraries_<yyyy>/linux/tbb

This is to set up both Intel® IPP and Intel® TBB environment.

Or, you can set Intel® IPP and Intel® TBB separately

$ source /opt/intel/compilers_and_libraries/linux/ipp/bin/ippvars.sh intel64
$ source /opt/intel/compilers_and_libraries/linux/tbb/bin/tbbvars.sh intel64
$ echo $IPPROOT; echo $TBBROOT
/opt/intel/compilers_and_libraries_<yyyy>/linux/ipp
/opt/intel/compilers_and_libraries_<yyyy>/linux/tbb

Or, you can export the required environment variables manually

$ export IPPROOT=/opt/intel/compilers_and_libraries_<yyyy>/linux/ipp
$ export TBBROOT=/opt/intel/compilers_and_libraries_<yyyy>/linux/tbb

Note

Using of specialized scripts compilervars, ippvars, or tbbvars has one important benefit. They add path to Intel® IPP and Intel® TBB dynamic shared objects to LD_LIBRARY_PATH environment variable, which allows to run application dynamically linked to these libraries.

Setting the Build Environment on macOS*

Setting of environment on macOS* system is much the same as on Linux*. The only difference is that you need to use mac subdirectory instead of linux in the paths to environment scripts.

Build Procedure

Before the build, you need to un-archive the examples from the package (zip on Windows* and tgz on Linux*/macOS* to your working directory.

Build Examples On Windows* Using Microsoft* Visual Studio*

Go to main examples directory examples_core. Load Visual Studio* projects directly to Microsoft* Visual Studio* or build them from command-line:

> devenv <example>.sln /build <configuration>

The <configuration> can be

  • "Debug|Win32", "Release|Win32", "Debug|x64", or "Release|x64" for all examples;

  • And, "Debug_tbb|Win32", "Release_tbb|Win32", "Debug_tbb|x64", or "Release_tbb|x64" for ipp_resize_mt and ipp_thread examples.

Build Examples On Linux* Using Makefiles

Go to main examples directory examples_core. Execute GNU* Make as

$ make [ARCH=ia32|intel64] [CONF=configuration] [clean]

where ARCH and CONF are optional parameters.

ARCH=ia32 is set, if you want to build 32-bit example on a 64-bit operating system. For that, the Intel® IPP environment must be set for 32-bit architecture as

$ compilervars.sh ia32

or

$ ippvars.sh ia32

and 32-bit GCC libraries must be installed on your system.

CONF=configuration is optional parameter to build release or debug version of example application with or without Intel® TBB support. The possible configurations are

Configuration Description

release

Default configuration for release build without Intel® TBB. The compiler option is "-O2"

debug

Debug build with compiler options "-O0 -g" without Intel® TBB

release_tbb

Release build with Intel® TBB support. The compiler options are "-O2 -DUSE_TBB"

debug_tbb

Debug build with Intel® TBB support. The compiler options are "-O0 -g -DUSE_TBB". The debug libraries of Intel® TBB are used

The optional parameter clean cleans up the working directory.

You can run make command either from top directory of Intel® IPP examples components/examples_core or from example specific sub-directory, for example, components/examples_core/ipp_fft. In the first case all examples will be built, in the second - you will build only the specific example.

Note

The libraries in common directory are not meant to be built standalone. They are to be built automatically when building examples. If you need to build them standalone for some reason, use the following command while in common directory:

$ make [all] -f Makefile_base.mk -f Makefile [ARCH=ia32|intel64] [CONF=configuration]

Build Examples On macOS* Using Xcodebuild

On macOS*, load XCode* project directly to XCode* or build it from command-line:

$ xcodebuild -configuration <configuration>

Build Examples On Windows* For Intel® System Studio

Execute <ISS install dir>\bin\compilervars.bat script for target architecture (ia32 or intel64) to obtain PATH variable update for Intel® C/C++ compiler and IPPROOT environment variable. Set the target environment according to required OS target and toolchain.

Basically, you need to set SYSROOT and GNU_PREFIX environment variables and to update PATH variable to be able to execute binary tools from the selected toolchain.

Then, execute build script

 > build_iss_win.bat

For example, to build Intel® IPP examples for Wind River* Linux* target OS you need to set the following environment variables in your command line window

//On Windows* host
//For 32-bit target:
set PATH=C:\<WRL6_path>\x86_64-linux\usr\bin\i586-wrs-linux;%PATH%
set SYSROOT=C:\<WRL6_path>\qemux86
set GNU_PREFIX=i586-wrs-linux-

//For 64-bit target:
set PATH=C:\<WRL6_path>\x86_64-linux\usr\bin\x86_64-wrs-linux;%PATH%
set SYSROOT=C:\<WRL6_path>\qemux86-64
set GNU_PREFIX=x86_64-wrs-linux-

Note

Look into corresponding Intel® System Studio Documentation on how to setup environment for different target OS.

Build Examples On Linux* for Intel® System Studio

Execute <ISS install dir>/bin/compilervars.sh script for target architecture (ia32 or intel64) to obtain PATH variable update for Intel® C/C++ compiler and IPPROOT environment variable. Set the target environment according to required OS target and toolchain.

Basically, you need to set SYSROOT and GNU_PREFIX environment variables and to update PATH variable to be able to execute binary tools from the selected toolchain. For example, for standard installation of Yocto Project v.1.7 on Linux* these environment variables should be

$ export GNU_PREFIX=i586-poky-linux-
$ export SYSROOT=/opt/poky/1.7/sysroots/i586-poky-linux

For Wind River* Linux* OS the required environment variables are

//On Linux* host
//For 32-bit target:
export PATH=<WRL6_path>/x86_64-linux/usr/bin/i586-wrs-linux:$PATH
export SYSROOT=<WRL6_path>/qemux86
export GNU_PREFIX=i586-wrs-linux-

//For 64-bit target:
export PATH=<WRL6_path>/x86_64-linux/usr/bin/x86_64-wrs-linux:$PATH
export SYSROOT=<WRL6_path>/qemux86-64
export GNU_PREFIX=x86_64-wrs-linux-

Then, execute build script

 $ ./build_iss_lin.sh

Note

Look into corresponding Intel® System Studio Documentation on how to setup environment for different target OS.

Buildspace Structure

Build projects or Makefiles generate necessary work files and final executable files in components/build/<configuration> directory.

Examples

The "-T <CPU>" command line option in all examples allows to turn on specific CPU architecture optimization. Together with timing this option helps to see the difference in performance of specific functions for different CPU architectures.

Option Description

-T SSE3

Intel® Streaming SIMD Extensions 3 (Intel® SSE3) optimization (m7 code)

-T SSSE3

Supplemental Streaming SIMD Extensions 3 (SSSE3) optimization (s8/n8 code on Intel® Atom™ processors)

-T SSE41

Intel® Streaming SIMD Extensions 4.1 (Intel® SSE4.1) optimization (s8/n8 code)

-T SSE42

Intel® Streaming SIMD Extensions 4.2 (Intel® SSE4.2) optimization (p8/y8 code)

-T AES

Intel® AES New Instructions (Intel® AES-NI) optimization (p8/y8 code)

-T AVX

Intel® Streaming SIMD Extensions 4.2 (Intel® SSE4.2) optimization (s8/n8 code)

-T AVX2

Intel® Advanced Vector Extensions 2 (Intel® AVX2) optimization (h9/l9 code)

-T <any other string>

In case of invalid string, the default optimization for current CPU used

After example execution, look at the Intel® IPP library names displayed at the top lines of example’s output, it will help to determine which particular optimization was used.

Help on command line can be obtained using "-h" option.

Multi-thread Image Resize Example: ipp_resize_mt

This Intel® IPP example shows how to use the ippiResize functionality in single- and multi-thread mode. For external multi-threading, Intel TBB tool is used, specificially, the parallel_for loop functionality. The multi-threading mode works if the project is built with Intel TBB support. See Setting the Build Environment for the details.

Command Line Options

The command line options for ipp_resize_mt are:

Usage: ipp_resize_mt [-i] InputFile [[-o] OutputFile] [Options]
Options:
  -i <1 arg>  input file name
  -o <1 arg>  output file name
  -r <2 args> destination resolution (width height)
  -k          do not keep aspect ratio
  -p <1 arg>  interpolation:
              0 - Nearest
              1 - Linear (default)
              2 - Cubic
              3 - Lanczos

  -s          suppress window output
  -w <1 arg>  minimum test time in milliseconds
  -l <1 arg>  number of loops (overrides test time)
  -T <1 arg>  target Intel(R) IPP optimization (SSE3, SSSE3, SSE41, SSE42, AES, AVX, AVX2)
  -h          print help and exit

Currently ipp_resize_mt example works only with bitmap (BMP) files.

The options are as follows:

Option Description

-i <arg>

The name of the source image BMP file to process. Here "-i" is optional.

-o <arg>

The name of the output BMP file with corners detected. "-o" is optional.

-r <2 args>

Destination image resolution in format "-r width height". Note: without "-k" option (see below) the example tries to keep aspect ratio of the source image. It means that without "-k" only first "-r" argument, width, is effective. The height of destination image is calculated as destination_height = destination_width * source_aspect_ratio, where source_aspect_ratio is source_height / source_width, i.e. destination image keeps source image proportions.

-k

Do not kee aspect ratio. With this option the example creates destination image with resolution specified in "-r width height" command line option.

-t <1 arg>

The number of execution threads that will be used in resizing. By default, "-t 0" number of threads is equal to the number of CPU cores. (*)

-p <1 arg>

Resizing interpolation method. One-digit number from 0 to 3.

-w <1 arg>

This option specifies the execution time. The execution time affects performance measurement accuracy. This option has similar effect with "-l <arg>" option (see below). Time is specified as a floating point value in milliseconds (e.g. "-w 1000" for one second duration). The argument of this option must be positive value, otherwise, the example application executes only one internal loop. No diagnostics message is displayed in this case.

-l <1 arg>

This option specifies the number of internal execution loops. This option also affects performance measurement accuracy. <arg> is an integer positive value.

-h

This option shows the above help message.

Note

(*) "-t <1 arg>" option will be effective and visible in usage message only if ipp_resize_mt example is built with Intel TBB support. Otherwise, the sequential resize will be used.

Example Output

The output messages during example execution show the number of resizing threads used, source and destination image resolutions, the number of loops executed, and execution time in seconds and CPE (CPU clocks per image element) like in the example below:

Threads: 4
Src size: 1200x900
Dst size: 1024x768

Loops:      1
Time total: 0.003735s
Loop avg:   0.003735s
CPE total:  2.917901
CPE avg:    2.917901

Image Linear Transform Example: ipp_fft

Intel® IPP image linear transform (ipp_fft) example shows how to use the Intel® IPP image linear transforms: Fourier transforms (fast and discrete) and discrete cosine transform (DCT).

Example Structure

The example contains 3 classes - FFT, DFT and DCT - inherited from the base class Transform. Each class implements its own, specific Init, Forward, and Inverse methods with corresponding functionalities.

Additionally, the ipp_fft example has source code for performance measurement and performance statistics output.

Command Line Options

To display help for the ipp_fft command line options, call the example with "-h" option.

Usage: ipp_fft [-i] InputFile [[-o] OutputFile] [Options]
Options:
  -i <1 arg>  input file name
  -o <1 arg>  output file name
  -d <1 arg>  save coefficients matrix
  -x <1 arg>  create coefficients map image
  -m <1 arg>  image transform method: FFT (default), DFT, DCT
  -b <2 args> apply transform by blocks (width height, 0 0 by default)
              block size will be set to first lower power of 2 value

  -n <1 arg>  algorithm mode: 0 - default, 1 - fast, 2 - accurate
  -s          suppress window output
  -w <1 arg>  minimum test time in milliseconds
  -l <1 arg>  number of loops (overrides test time)
  -T <1 arg>  target Intel(R) IPP optimization (SSE3, SSSE3, SSE41, SSE42, AES, AVX, AVX2)
  -h          print help and exit

All command line switches except source image file name are optional.

The options are as follows:

Option Description

-i <1 arg>

The name of the source image BMP file to process. Here "-i" is optional.

-o <1 arg>

The name of the output BMP file with corners detected.

-d <1 arg>

The name of a binary file to save the transformation coefficients. They are saved as 32-bit floating-point values.

-x <1 arg>

The name of the output file for transformation coefficients. The coefficients are saved normalized in bitmap BMP format.

-m <1 arg>

Linear transform method to use. Examples: "-m FFT", "-m DFT", "-m DCT".

-b <2 args>

Use image blocks (tiles) to linear transformation. By default, block is equal to the whole image. Blocks are defined by "-b width height" argument ("-b 128 128" for example). Using of image tiles for transformation can improve overall performance, because with small tiles all required data is stored in CPU cache.

-n <1 arg>

Linear transform algorithm hint (default, fast, or accurate).

-w <1 arg>

This option specifies the execution time. The execution time affects performance measurement accuracy. This option has similar effect with "-l <arg>" option (see below). Time is specified as a floating point value in milliseconds (e.g. "-w 1000" for one second duration).

-l <1 arg>

This option specifies the number of internal execution loops. This option also affects performance measurement accuracy. <arg> is an integer positive value.

-T <1 arg>

Target Intel® IPP optimization.

-h

This option shows the above help message.

External Threading Example: ipp_thread

As internal threading is deprecated in Intel® IPP functions (see Intel® IPP deprecation strategy at http://software.intel.com/sites/products/ipp-deprecated-features-feedback), it is important to know how generic Intel® IPP function can be threaded externally. This is the purpose of the Intel® IPP external threading example (ipp_thread).

This example shows threading of image harmonization filter. The harmonization filter steps are

  • Generate gray image (src);

  • Filterbox 7x7 with anchor 1,1 (tmp = filterbox(src));

  • Multiply by constant 255 (tmp = tmp * 255);

  • Subtract from source (dst = tmp - src);

  • Multiply by constant 205 (dst = dst * 205);

  • Threshold < 6 or > 250 (dst = threshold(6, 250).

The example demonstrates 3 methods of harmonization filtering:

  • Direct (serial) execution of above steps on the whole image.

  • Using native threads. On Windows*, WinAPI threads are used, on Linux* OS and macOS* pthreads are used.

  • Intel TBB usage model.

The threading methods use simple data-parallel approach when source image is split into slices and each slice is processed in a separate thread in parallel mode. It is possible because there is no data dependency between the slices.

Example Structure

In general, the ipp_thread example consists of main function and three processing functions - HarmonizeSerial, HarmonizeNativeParallel, and HarmonizeTBBParallel.

Before the source image gets to filtering, the source data is copied into a bigger image to set up border around source image data (necessary for ippiFilterBox_8u_C1R function).

Threading Using Native Threads

In the HarmonizeNativeParallel function, thread control is organized using VM library functions to hide operating system specifics.

The main thread processing function is named HarmonizeNativeSlice. It does exactly the same job as the HarmonizeSerial function but on a source image slice only.

Synchronization of threads is done using mutex and event objects. When the last thread is finishing, it sets vm_event* ThreadParam::pLastThreadStop flag notifying the thread controlling function that it can continue execution.

Threading Using Intel® TBB

The HarmonizeTBBParallel function is quite simple. The Intel TBB class for parallel_for construction is

Filtering is done in the SliceHarmonize::operator() function the same way as in serial and native methods on slices defined by the tbb::blocked_range<int>& height function argument.

In Intel TBB model, thread synchronization is done automatically.

Command Line Options

Command line options can be obtained by "-h" option as follows:

Usage: ipp_thread [-i] InputFile [[-o] OutputFile] [Options]
Options:
  -i <1 arg> input file name
  -o <1 arg> output file name
  -m <1 arg> threading method: tbb (default), native (*)
  -t <1 arg> number of threads (0 - auto, 0 by default)
  -s         suppress window output
  -w <1 arg> minimum test time in milliseconds
  -l <1 arg> number of loops (overrides test time)
  -T <1 arg> target Intel(R) IPP optimization (SSE3, SSSE3, SSE41, SSE42, AES, AVX, AVX2)
  -h         print help and exit

The options are as follows:

Option Description

-i <1 arg>

The name of the source image BMP file to process. Here "-i" is optional.

-o <1 arg>

Output bitmap BMP file name (optional).

-m <1 arg>

Threading method. "-m tbb" starts parallelization using Intel® TBB, "-m native" starts parallelization using native OS methods. (*)

-t <1 arg>

The number of threads to be used in paralelization.

-w <1 arg>

This option specifies the execution time. The execution time affects performance measurement accuracy. This option has similar effect with "-l <arg>" option (see below). Time is specified as a floating point value in milliseconds (e.g. "-w 1000" for one second duration).

-l <1 arg>

This option specifies the number of internal execution loops. This option also affects performance measurement accuracy. <arg> is an integer positive value.

-T <1 arg>

Target Intel® IPP optimization.

-h

This option shows the above help message.

Note

(*) "-t <1 arg>" option will be effective and visible in usage message only if ipp_resize_mt example is built with Intel TBB support. Otherwise, the sequential resize will be used.

Image Morphology Example: ipp_morphology

Intel® IPP image morphology (ipp_morphology) example shows how to use the Intel® IPP image morphological operations: Erode and Dilate.

Example Structure

The example contains Morphology class with Erode and Dilate methods. Both operations are initialized simultaneously and can be applied in iterations.

In GUI mode amount of Erosion or Dilation can be controlled with arrow keys in real time. Use "Arrow Up" key to increase Dilation and "Arrow Down" key to decrease Dilation and increase Erosion.

Additionally, the ipp_morphology example has source code for performance measurement and performance statistics output.

Command Line Options

To display help for the ipp_morphology command line options, call the example with "-h" option.

Usage: ipp_morphology.exe [-i] InputFile [[-o] OutputFile] [Options]
Options:
  -i <1 arg> input file name
  -o <1 arg> output file name
  -d <1 arg> initial number of dilate iterations (1 by default). Negative values apply erode
  -s         suppress window output
  -w <1 arg> minimum test time in milliseconds
  -l <1 arg> number of loops (overrides test time)
  -T <1 arg> target Intel(R) IPP optimization (SSE3, SSSE3, SSE41, SSE42, AES, AVX, AVX2)
  -h         print help and exit

All command line switches except source image file name are optional.

The options are as follows:

Option Description

-i <1 arg>

The name of the source image BMP file to process. Here "-i" is optional.

-o <1 arg>

The name of the output BMP file with corners detected.

-d <1 arg>

The initial number of iterations of Dilation. If value is negative then Erosion iterations will be applied.

-w <1 arg>

This option specifies the execution time. The execution time affects performance measurement accuracy. This option has similar effect with "-l <arg>" option (see below). Time is specified as a floating point value in milliseconds (e.g. "-w 1000" for one second duration).

-l <1 arg>

This option specifies the number of internal execution loops. This option also affects performance measurement accuracy. <arg> is an integer positive value.

-T <1 arg>

Target Intel® IPP optimization.

-h

This option shows the above help message.

Technical Support

If you did not register your Intel® software product during installation, please do so now at the Intel® Software Development Products Registration Center. Registration entitles you to free technical support, product updates and upgrades for the duration of the support term.

For general information about Intel technical support, product updates, user forums, FAQs, tips and tricks, and other support questions, please visit (http://www.intel.com/software/products/support).

Note

If your distributor provides technical support for this product, please contact them rather than Intel.

For technical information about the Intel® IPP library, including FAQ’s, tips and tricks, and other support information, please visit the Intel® IPP forum: (http://software.intel.com/en-us/forums/intel-integrated-performance-primitives) and browse the Intel® IPP support page: https://software.intel.com/en-us/intel-ipp-support/.

Optimization Notice

Intel's compilers may or may not optimize to the same degree for non-Intel microprocessors for optimizations that are not unique to Intel microprocessors. These optimizations include SSE2, SSE3, and 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. Certain optimizations not specific to Intel microarchitecture are reserved for Intel microprocessors. Please refer to the applicable product User and Reference Guides for more information regarding the specific instruction sets covered by this notice.

Notice revision #20110804