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® oneAPI Base Toolkit to <install_dir> of your computer. By default, <install_dir> is C:\Program Files (x86)\Intel\oneAPI directory.

First - the simplest - method is to start command-line window, using menu Start Menu\Programs\Intel oneAPI 2022\Intel oneAPI command prompt for Intel 64 for Visual Studio 2022

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

The second method is to use specialized script to setup environment for Intel® oneAPI from existing command-line window. The script is <install_dir>\setvars.bat and has two optional arguments: requred CPU architecture ("ia32" or "intel64") and required Microsoft* Visual Studio* environment ("vs2019" or "vs2022"). In case of no arguments passed, by default the script will configure the environment for intel64 CPU architecture and the latest Microsoft* Visual Studio* version installed.

For example,

>"C:\Program Files (x86)\Intel\oneAPI\setvars.bat" intel64 vs2022
:: initializing oneAPI environment...
   Initializing Visual Studio command-line environment...
   Visual Studio version 17.3.3 environment configured.
   "C:\Program Files\Microsoft Visual Studio\2022\Professional\"
   Visual Studio command-line environment initialized for: 'x64'
:  compiler -- latest
:  debugger -- latest
:  dev-utilities -- latest
:  dpl -- latest
:  ipp -- latest
:  tbb -- latest
:  vtune -- latest
:: oneAPI environment initialized ::

The third method is to set separately environment variable for Intel® IPP and, if you want, for oneTBB. For that, two scripts are placed in Intel® oneAPI directory tree: <install_dir>\ipp\latest\env\vars.bat and <install_dir>\tbb\latest\env\vars.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* 2019 environment and Intel® IPP example environment, you need to do

>"%VS2019INSTALLDIR%\VC\Auxiliary\Build\vcvarsall.bat" x64
>set "IPPROOT=C:\Program Files (x86)\Intel\oneAPI\ipp\latest"
>set "TBBROOT=C:\Program Files (x86)\Intel\oneAPI\tbb\latest"

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/oneapi directory.

So, you can do any of the following steps.

$ source /opt/intel/oneapi/setvars.sh
$ export PATH=$CMPLR_ROOT/linux/bin-llvm:$PATH
$ echo $IPPROOT; echo $TBBROOT
/opt/intel/oneapi/ipp/latest
/opt/intel/oneapi/tbb/latest

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

Or, you can set Intel® IPP and oneTBB separately

$ source /opt/intel/oneapi/ipp/latest/env/vars.sh
$ source /opt/intel/oneapi/tbb/latest/env/vars.sh
$ echo $IPPROOT; echo $TBBROOT
/opt/intel/oneapi/ipp/latest
/opt/intel/oneapi/tbb/latest

Or, you can export the required environment variables manually

$ export IPPROOT=/opt/intel/oneapi/ipp/latest
$ export TBBROOT=/opt/intel/oneapi/tbb/latest

Note

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

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

  • For all examples: Debug|Win32, Release|Win32, Debug|x64, or Release|x64;

  • For ipp_resize_mt and ipp_thread examples: Debug_tbb|Win32, Release_tbb|Win32, Debug_tbb|x64, or Release_tbb|x64.

Build Examples On Linux* Using Makefiles

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

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

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 from Intel® oneAPI installation directory as

$ source setvars.sh ia32

or from Intel® IPP env directory

$ source vars.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 oneTBB support. The possible configurations are

Configuration Description

release

Default configuration for release build without oneTBB. The compiler option is "-O2"

debug

Debug build with compiler options "-O0 -g" without oneTBB

release_tbb

Release build with oneTBB support. The compiler options are "-O2 -DUSE_TBB"

debug_tbb

Debug build with oneTBB support. The compiler options are "-O0 -g -DUSE_TBB". The debug libraries of oneTBB 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]

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, oneTBB tool is used, specificially, the parallel_for loop functionality. The multi-threading mode works if the project is built with oneTBB 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 oneTBB 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

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.

  • oneTBB 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 oneTBB

The HarmonizeTBBParallel function is quite simple. The oneTBB 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 oneTBB 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 oneTBB, "-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 oneTBB 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: (https://community.intel.com/t5/Intel-Integrated-Performance/bd-p/integrated-performance-primitives) and browse the Intel® IPP support page: https://www.intel.com/content/www/us/en/developer/get-help/tools.html.

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