# Intel® Integrated Performance Primitives Examples

# Disclaimer

## Legal Information

INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT. EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT.
A "Mission Critical Application" is any application in which failure of the Intel Product could result, directly or indirectly, in personal injury or death. SHOULD YOU PURCHASE OR USE INTEL'S PRODUCTS FOR ANY SUCH MISSION CRITICAL APPLICATION, YOU SHALL INDEMNIFY AND HOLD INTEL AND ITS SUBSIDIARIES, SUBCONTRACTORS AND AFFILIATES, AND THE DIRECTORS, OFFICERS, AND EMPLOYEES OF EACH, HARMLESS AGAINST ALL CLAIMS COSTS, DAMAGES, AND EXPENSES AND REASONABLE ATTORNEYS' FEES ARISING OUT OF, DIRECTLY OR INDIRECTLY, ANY CLAIM OF PRODUCT LIABILITY, PERSONAL INJURY, OR DEATH ARISING IN ANY WAY OUT OF SUCH MISSION CRITICAL APPLICATION, WHETHER OR NOT INTEL OR ITS SUBCONTRACTOR WAS NEGLIGENT IN THE DESIGN, MANUFACTURE, OR WARNING OF THE INTEL PRODUCT OR ANY OF ITS PARTS.

Intel may make changes to specifications and product descriptions at any time, without notice. Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined." Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them. The information here is subject to change without notice. Do not finalize a design with this information.
The products described in this document may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request.
Contact your local Intel sales office or your distributor to obtain the latest specifications and before placing your product order.
Copies of documents which have an order number and are referenced in this document, or other Intel literature, may be obtained by calling 1-800-548-4725, or go to: http://www.intel.com/design/literature.htm

Intel processor numbers are not a measure of performance. Processor numbers differentiate features within each processor family, not across different processor families. Go to: http://www.intel.com/products/processor_number/

BlueMoon, BunnyPeople, Celeron, Celeron Inside, Centrino, Centrino Inside, Core Inside, i960, Intel, the Intel logo, Intel Atom, Intel Atom Inside, Intel Core, Intel Inside, Intel Inside logo, Intel NetBurst, Intel NetMerge, Intel NetStructure, Intel SingleDriver, Intel SpeedStep, Intel Sponsors of Tomorrow., the Intel Sponsors of Tomorrow. logo, Intel StrataFlash, Intel Viiv, Intel vPro, Intel XScale, InTru, the InTru logo, InTru soundmark, Itanium, Itanium Inside, MCS, MMX, Moblin, Pentium, Pentium Inside, skoool, the skoool logo, Sound Mark, The Journey Inside, vPro Inside, VTune, Xeon, and Xeon Inside are trademarks of Intel Corporation in the U.S. and other countries.
* Other names and brands may be claimed as the property of others.

Microsoft, Windows, Visual Studio, Visual C++, and the Windows logo are trademarks, or registered trademarks of Microsoft Corporation in the United States and/or other countries.

Java is a registered trademark of Oracle and/or its affiliates.

©Intel Corporation. All rights reserved.

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

# License Definitions

By downloading and installing this product, 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:

- A system based on 4th Generation Intel® Core™ i3, i5, i7 or newer processor

Hardware requirements:

- A system based on Intel® Quark™ System-on-Chip processors;

- A system based on Intel® Pentium® processor, Intel® Xeon® processor, or subsequent IA-32 architecture based system;

- A system based on a processor with Intel® 64 architecture.

Software requirements:

- Microsoft Foundation Class Library (MFC) is required when using Microsoft Visual Studio.

- For the basic system requirements on operating system, Intel® IPP library, IDE and compiler, refer to the corresponding Release Notes document.

For more information please see Intel® IPP System Requirements.

# Introduction

GraphicsMagick (http://www.graphicsmagick.org/) is a popular library for image processing, encoding, and decoding. The patches provided with Intel IPP inject functions from the Intel® IPP library to C Magick API of GraphicsMagick to boost performance with minimal user efforts.

Following features are provided:

- 2-4 times performance boost (depends on particular functionality and parameters)

- Build-time Intel® IPP switches for VisualMagick and autoconf builders (other builders are not supported)

- Run-time switch with API functions or environment variable

- Fall-back to the original code in case of Intel® IPP failure

## Supported Functionality

Note | Results between GraphicsMagick and Intel® IPP may vary due to differences in approaches to internal calculations. Maximum pixel value variation should not exceed 1 for any function except Resize functions. Resize functions in GraphicsMagick and Intel® IPP have different implementations which can result in pixel variations bigger than 1. Most variations are localized around image border due to different border handling techniques.

Here is the list of GraphicsMagick functions which have Intel® IPP integrations:

Magick API | Supported Qs | comments
--- | --- | ---
ResizeImage | 8, 16 | Some pixel values may differ from the reference implementation. Implemented for: PointFilter, TriangleFilter, HermiteFilter, CubicFilter, CatromFilter, MitchellFilter, LanczosFilter
ScaleImage | 8, 16 | Some pixel values may differ from the reference implementation. Implemented only for down-sampling
GaussianBlurImage | 8, 16 |
FlipImage | 8, 16, 32 |
FlopImage | 8, 16, 32 |

## Performance

Measuring performance of image processing is tricky because actual processing could be negligible compared to decoding and encoding steps.

For example, say we improved performance of Resize 10 times compared to the original code. If overall operation takes 1000ms and resize takes only 400ms of this time, then we will improve overall operation time from 1000ms to 640ms, which is ~1.5 times only.

To take the most from such accelerations it is wise to bulk them in a single pipeline avoiding intermediate coding and thus increasing weight of processing itself.

For example, decode→resize→blur→…→rotate→encode

Below you can find simple performance measurements taken with the gm utility on an abstract image:

CPU: i7-4771, 4 cores, Intel® Advanced Vector Extensions 2 (Intel® AVX2)

ResizeImage:

    > gm benchmark -iterations 100 convert -depth 8 -size 1920x1280 rgb:test.raw -resize 600x600 temp.raw

| Q8, 1 thread | Q8, 4 threads | Q16, 1 thread | Q16, 4 threads
--- | --- | --- | --- | ---
GraphicsMagick | 14.0 iter/s | 38.6 iter/s | 12.2 iter/s | 31.3 iter/s
Intel® IPP | 39.6 iter/s | 59.8 iter/s | 33.1 iter/s | 50.0 iter/s
Speedup | 2.8 | 1.5 | 2.7 | 1.6

GaussianBlurImage:

    > gm benchmark -iterations 100 convert -depth 8 -size 1920x1280 rgb:test.raw -gaussian 2 temp.raw

| Q8, 1 thread | Q8, 4 threads | Q16, 1 thread | Q16, 4 threads
--- | --- | --- | --- | ---
GraphicsMagick | 7.2 iter/s | 20.8 iter/s | 6.5 iter/s | 17.7 iter/s
Intel® IPP | 33.8 iter/s | 38.2 iter/s | 20.9 iter/s | 23.6 iter/s
Speedup | 4.7 | 1.8 | 3.2 | 1.3

## History

Intel® IPP 2018 Update 2

- Patch for GraphicsMagick v1.3.26 was introduced

Intel® IPP 2018

- Patch for GraphicsMagick v1.3.25 was introduced

# How to Build GraphicsMagick with Intel® IPP Library

This section provides instructions on how to prepare the GraphicsMagick source code and build the library.

## Prerequisites

We provide patches for specific versions if GraphicsMagick listed under OS instructions below. Other versions may be or may not be compatible with these patches, we do not support them in this version of Intel® IPP.

To use the patch you need to get the GraphicsMagick sources. Please refer to http://www.graphicsmagick.org/ to find source package for the corresponding patch version if links below become deprecated.

Make sure that the IPPROOT environment variable is set up correctly to the root folder of the Intel® IPP package with include and lib folders. E.g.:

    $ export IPPROOT=<composer_loc>/ipp

For Windows* build you need:

- 7-zip (http://www.7-zip.org/) or other compatible archive tool to extract GraphicsMagick sources

- GNU patch tool (http://gnuwin32.sourceforge.net/packages/patch.htm also available in Cygwin or MinGW)

Note | The patch file for Windows* is different from the patch file for Linux* OS and macOS*. Intel® IPP distributions for each OS contain only patch file for GraphicsMagick source package for the corresponding OS.

For information and requirements on how to build GraphicsMagick please refer to the original instructions.

http://www.graphicsmagick.org/README.html

## Downloading, Patching and Building on Linux* and macOS*

1. Download sources of GraphicsMagick <version>

   Version | Link
   --- | ---
   1.3.25 | https://sourceforge.net/projects/graphicsmagick/files/graphicsmagick/1.3.25/GraphicsMagick-1.3.25.tar.gz/download
   1.3.26 | https://sourceforge.net/projects/graphicsmagick/files/graphicsmagick/1.3.26/GraphicsMagick-1.3.26.tar.gz/download

2. Unpack the archive with the following command on Linux*/macOS* systems:

       $ tar xvf <archive file name>

   This command will unpack GraphicsMagick into your working directory.

3. Change directory to the unpacked sources folder (with README.txt file).

4. Apply the source code patch file gm-<version>.patch from the Intel® IPP product distribution with the following command:

       $ patch -p1 -i <path to the patch file>

   If the patching process completed successfully, you will see multiple messages like this:

       patching file <file name>

   Otherwise, make sure that you are using the original untainted sources package.

5. Now you can follow the standard GraphicsMagick build procedure.

   Intel® IPP is enabled by default if the IPPROOT path is correct. To disable Intel® IPP, use the following command:

       $ ./configure --without-ipp

Note | If you are building static GraphicsMagick libraries, you will need to include the following Intel® IPP libraries to any application with which you want to use the enabled libraries: $(IPPROOT)/lib/<arch>/libippcv.a $(IPPROOT)/lib/<arch>/libippi.a $(IPPROOT)/lib/<arch>/libipps.a $(IPPROOT)/lib/<arch>/libippvm.a $(IPPROOT)/lib/<arch>/libippcore.a

## Downloading, Patching, and Building on Windows*

1. Download sources of GraphicsMagick <version>

   Version | Link
   --- | ---
   1.3.25 | https://sourceforge.net/projects/graphicsmagick/files/graphicsmagick/1.3.25/GraphicsMagick-1.3.25-windows-source.7z/download
   1.3.26 | https://sourceforge.net/projects/graphicsmagick/files/graphicsmagick/1.3.26/GraphicsMagick-1.3.26-windows-source.7z/download

2. Unpack the archive with 7-zip compatible archive tool.

3. Change directory to the unpacked sources folder (with README.txt file).

4. Apply the source code patch file gm-<version>.patch from the Intel® IPP product distribution with the following command:

       > patch -p1 -i <patch file location>

   If the patching process completed successfully, you will see multiple messages like this:

       patching file <file name>

   Otherwise, make sure that you are using original untainted sources package.

5. Before building GraphicsMagick you need to rebuild the VisualMagick configuration tool:

   - Go to the <patched_folder>\VisualMagick\configure folder

   - Open Visual Studio solution and build the project

6. Now you can follow the standard GraphicsMagick build procedure and run configure.exe.

   Use new checkbox in configurator to enable or disable Intel® IPP

Note | If you are building static GraphicsMagick libraries, you need to include the following Intel® IPP libraries to any application with which you want to use the enabled libraries: $(IPPROOT)/lib/<arch>/ippcvmt.lib $(IPPROOT)/lib/<arch>/ippimt.lib $(IPPROOT)/lib/<arch>/ippsmt.lib $(IPPROOT)/lib/<arch>/ippvmmt.lib $(IPPROOT)/lib/<arch>/ippcoremt.lib

## Checking GraphicsMagick build

To verify that GraphicsMagick was built with Intel® IPP, you can run the standard gm utility:

    > ./gm version
    GraphicsMagick 1.3.26 2017-07-04 Q8 http://www.GraphicsMagick.org/
    Built with Intel(R) IPP v2018.0.2
    Copyright (C) 2002-2017 GraphicsMagick Group.
    Additional copyrights and licenses apply to this software.
    See http://www.GraphicsMagick.org/www/Copyright.html for details.

    Feature Support:
    ...
      Intel(R) IPP             yes (ippIP AVX2 (l9) 2018.0.2 (r57645))
    ...

Verify that resize function works with the -resize command:

    > set MAGICK_IPP=

    > gm benchmark -iterations 100 convert ..\..\images\gm-282x180t.png -resize !800x800 gm_ipp.jpg
    Results: 4 threads 100 iter 5.27s user 1.52s total 65.963 iter/s 18.991 iter/cpu

    > set MAGICK_IPP=disabled

    > gm benchmark -iterations 100 convert ..\..\images\gm-282x180t.png -resize !800x800 gm_orig.jpg
    Results: 4 threads 100 iter 8.39s user 2.30s total 43.535 iter/s 11.918 iter/cpu

# New functionality introduced by Intel® IPP patch

## MAGICK_IPP environment variable

This variable controls Intel® IPP initialization process. If variable was not set or empty or has invalid value then Intel® IPP will use all available optimizations. To check initialization status use ./gm version command. Actual optimization will be reflected in Intel® IPP entry under Feature Support.

Supported values (case insensitive, other values will be ignored):

Value | Description
--- | ---
disabled | Disable Intel® IPP optimizations
SSE2 | Limit Intel® IPP optimizations to Intel® Streaming SIMD Extensions 2 (Intel® SSE2)
SSE3 | Limit Intel® IPP optimizations to Intel® Streaming SIMD Extensions 3 (Intel® SSE3)
SSSE3 | Limit Intel® IPP optimizations to Supplemental Streaming SIMD Extensions 3 (SSSE3)
SSE41 | Limit Intel® IPP optimizations to Intel® Streaming SIMD Extensions 4.1 (Intel® SSE4.1)
SSE42 | Limit Intel® IPP optimizations to Intel® Streaming SIMD Extensions 4.2 (Intel® SSE4.2)
AVX | Limit Intel® IPP optimizations to Intel® Advanced Vector Extensions (Intel® AVX)
AVX2 | Limit Intel® IPP optimizations to Intel® Advanced Vector Extensions 2 (Intel® AVX2)
AVX512 | Limit Intel® IPP optimizations to Intel® Advanced Vector Extensions 512 (Intel® AVX-512)

## ippEnabled Function

Syntax:

    MagickExport int  ippEnabled();

Description:

This function returns the Intel® IPP enabled flag.

Return Values:

Value | Description
--- | ---
0 | Intel® IPP is disabled
1 | Intel® IPP is enabled

## ippSetEnabled Function

Syntax:

    MagickExport void ippSetEnabled(int flag);

Description:

This function enables or disables Intel® IPP.

Parameters:

Value | Description
--- | ---
0 | Disables Intel® IPP
1 | Enables Intel® IPP

# 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/.