Added IPP Async converters, doc and sample

CMakeLists.txt

@@ -157,7 +157,7 @@ OCV_OPTION(WITH_OPENCLAMDFFT   "Include AMD OpenCL FFT library support"      ON
 OCV_OPTION(WITH_OPENCLAMDBLAS  "Include AMD OpenCL BLAS library support"     ON   IF (NOT ANDROID AND NOT IOS) )
 OCV_OPTION(WITH_DIRECTX        "Include DirectX support"                     ON   IF WIN32 )
 OCV_OPTION(WITH_INTELPERC      "Include Intel Perceptual Computing support"  OFF  IF WIN32 )
-
+OCV_OPTION(WITH_IPP_A          "Include Intel IPP_A support"                 OFF  IF (MSVC OR X86 OR X86_64) )
 
 # OpenCV build components
 # ===================================================
@@ -923,6 +923,10 @@ else()
   status("    Use IPP:"   WITH_IPP AND NOT IPP_FOUND THEN "IPP not found" ELSE NO)
 endif()
 
+if(DEFINED WITH_IPP_A)
+status("    Use IPP Async:"  HAVE_IPP_A       THEN "YES" ELSE NO)
+endif(DEFINED WITH_IPP_A)
+
 status("    Use Eigen:"      HAVE_EIGEN       THEN "YES (ver ${EIGEN_WORLD_VERSION}.${EIGEN_MAJOR_VERSION}.${EIGEN_MINOR_VERSION})" ELSE NO)
 status("    Use TBB:"        HAVE_TBB         THEN "YES (ver ${TBB_VERSION_MAJOR}.${TBB_VERSION_MINOR} interface ${TBB_INTERFACE_VERSION})" ELSE NO)
 status("    Use OpenMP:"     HAVE_OPENMP      THEN YES ELSE NO)

cmake/OpenCVFindIPPAsync.cmake

@@ -0,0 +1,45 @@
+# Main variables:
+# IPP_A_LIBRARIES and IPP_A_INCLUDE to use IPP Async
+# HAVE_IPP_A for conditional compilation OpenCV with/without IPP Async
+
+# IPP_ASYNC_ROOT - root of IPP Async installation
+
+if(X86_64)
+    find_path(
+    IPP_A_INCLUDE_DIR
+    NAMES ipp_async_defs.h
+    PATHS $ENV{IPP_ASYNC_ROOT}
+    PATH_SUFFIXES include
+    DOC "Path to Intel IPP Async interface headers")
+
+    find_file(
+    IPP_A_LIBRARIES
+    NAMES ipp_async_preview.lib
+    PATHS $ENV{IPP_ASYNC_ROOT}
+    PATH_SUFFIXES lib/intel64
+    DOC "Path to Intel IPP Async interface libraries")
+
+else()
+    find_path(
+    IPP_A_INCLUDE_DIR
+    NAMES ipp_async_defs.h
+    PATHS $ENV{IPP_ASYNC_ROOT}
+    PATH_SUFFIXES include
+    DOC "Path to Intel IPP Async interface headers")
+
+    find_file(
+    IPP_A_LIBRARIES
+    NAMES ipp_async_preview.lib
+    PATHS $ENV{IPP_ASYNC_ROOT}
+    PATH_SUFFIXES lib/ia32
+    DOC "Path to Intel IPP Async interface libraries")
+endif()
+
+if(IPP_A_INCLUDE_DIR AND IPP_A_LIBRARIES)
+    set(HAVE_IPP_A TRUE)
+else()
+    set(HAVE_IPP_A FALSE)
+    message(WARNING "Intel IPP Async library directory (set by IPP_A_LIBRARIES_DIR variable) is not found or does not have Intel IPP Async libraries.")
+endif()
+
+mark_as_advanced(FORCE IPP_A_LIBRARIES IPP_A_INCLUDE_DIR)

cmake/OpenCVFindLibsPerf.cmake

@@ -19,6 +19,17 @@ if(WITH_IPP)
   endif()
 endif(WITH_IPP)
 
+# --- IPP Async ---
+
+if(WITH_IPP_A)
+  include("${OpenCV_SOURCE_DIR}/cmake/OpenCVFindIPPAsync.cmake")
+  if(IPP_A_INCLUDE_DIR AND IPP_A_LIBRARIES)
+    ocv_include_directories(${IPP_A_INCLUDE_DIR})
+    link_directories(${IPP_A_LIBRARIES})
+    set(OPENCV_LINKER_LIBS ${OPENCV_LINKER_LIBS} ${IPP_A_LIBRARIES})
+   endif()
+endif(WITH_IPP_A)
+
 # --- CUDA ---
 if(WITH_CUDA)
   include("${OpenCV_SOURCE_DIR}/cmake/OpenCVDetectCUDA.cmake")

cmake/templates/cvconfig.h.in

@@ -94,6 +94,9 @@
 /* Intel Integrated Performance Primitives */
 #cmakedefine HAVE_IPP
 
+/* Intel IPP Async */
+#cmakedefine HAVE_IPP_A
+
 /* JPEG-2000 codec */
 #cmakedefine HAVE_JASPER
 

doc/conf.py

@@ -416,5 +416,7 @@
             'background_subtractor' : ('http://docs.opencv.org/modules/video/doc/motion_analysis_and_object_tracking.html?highlight=backgroundsubtractor#backgroundsubtractor%s', None),
             'background_subtractor_mog' : ('http://docs.opencv.org/modules/video/doc/motion_analysis_and_object_tracking.html?highlight=backgroundsubtractorMOG#backgroundsubtractormog%s', None),
             'background_subtractor_mog_two' : ('http://docs.opencv.org/modules/video/doc/motion_analysis_and_object_tracking.html?highlight=backgroundsubtractorMOG2#backgroundsubtractormog2%s', None),
-            'video_capture' : ('http://docs.opencv.org/modules/highgui/doc/reading_and_writing_images_and_video.html?highlight=videocapture#videocapture%s', None)
+            'video_capture' : ('http://docs.opencv.org/modules/highgui/doc/reading_and_writing_images_and_video.html?highlight=videocapture#videocapture%s', None),
+            'ippa_convert': ('http://docs.opencv.org/modules/core/doc/ipp_async_converters.html#%s', None),
+            'ptr':('http://docs.opencv.org/modules/core/doc/basic_structures.html?highlight=Ptr#Ptr%s', None)
            }

doc/tutorials/core/how_to_use_ippa_conversion/how_to_use_ippa_conversion.rst

@@ -0,0 +1,164 @@
+.. _howToUseIPPAconversion:
+
+Intel® IPP Asynchronous C/C++ library in OpenCV
+***********************************************
+
+Goal
+====
+
+.. _hppiSobel: http://software.intel.com/en-us/node/474701
+.. _hppiMatrix: http://software.intel.com/en-us/node/501660
+
+The tutorial demonstrates the `Intel® IPP Asynchronous C/C++ <http://software.intel.com/en-us/intel-ipp-preview>`_ library usage with OpenCV.
+The code example below illustrates implementation of the Sobel operation, accelerated with Intel® IPP Asynchronous C/C++ functions.
+In this code example, :ippa_convert:`hpp::getMat <>` and :ippa_convert:`hpp::getHpp <>` functions are used for data conversion between hppiMatrix_ and ``Mat`` matrices.
+
+Code
+====
+
+You may also find the source code in the :file:`samples/cpp/tutorial_code/core/ippasync/ippasync_sample.cpp`
+file of the OpenCV source library or :download:`download it from here
+<../../../../samples/cpp/tutorial_code/core/ippasync/ippasync_sample.cpp>`.
+
+.. literalinclude:: ../../../../samples/cpp/tutorial_code/core/ippasync/ippasync_sample.cpp
+   :language: cpp
+   :linenos:
+   :tab-width: 4
+
+Explanation
+===========
+
+#. Create parameters for OpenCV:
+
+   .. code-block:: cpp
+
+      VideoCapture cap;
+      Mat image, gray, result;
+
+   and IPP Async:
+
+   .. code-block:: cpp
+
+      hppiMatrix* src,* dst;
+      hppAccel accel = 0;
+      hppAccelType accelType;
+      hppStatus sts;
+      hppiVirtualMatrix * virtMatrix;
+
+#. Load input image or video. How to open and read video stream you can see in the :ref:`videoInputPSNRMSSIM` tutorial.
+
+   .. code-block:: cpp
+
+      if( useCamera )
+      {
+         printf("used camera\n");
+         cap.open(0);
+      }
+      else
+      {
+         printf("used image %s\n", file.c_str());
+         cap.open(file.c_str());
+      }
+
+      if( !cap.isOpened() )
+      {
+         printf("can not open camera or video file\n");
+         return -1;
+      }
+
+#. Create accelerator instance using `hppCreateInstance <http://software.intel.com/en-us/node/501686>`_:
+
+   .. code-block:: cpp
+
+      accelType = sAccel == "cpu" ? HPP_ACCEL_TYPE_CPU:
+                  sAccel == "gpu" ? HPP_ACCEL_TYPE_GPU:
+                                    HPP_ACCEL_TYPE_ANY;
+
+      //Create accelerator instance
+      sts = hppCreateInstance(accelType, 0, &accel);
+      CHECK_STATUS(sts, "hppCreateInstance");
+
+#. Create an array of virtual matrices using `hppiCreateVirtualMatrices <http://software.intel.com/en-us/node/501700>`_ function.
+
+   .. code-block:: cpp
+
+      virtMatrix = hppiCreateVirtualMatrices(accel, 1);
+
+#. Prepare a matrix for input and output data:
+
+   .. code-block:: cpp
+
+      cap >> image;
+      if(image.empty())
+         break;
+
+      cvtColor( image, gray, COLOR_BGR2GRAY );
+
+      result.create( image.rows, image.cols, CV_8U);
+
+#. Convert ``Mat`` to hppiMatrix_ using :ippa_convert:`getHpp <>` and call hppiSobel_ function.
+
+   .. code-block:: cpp
+
+      //convert Mat to hppiMatrix
+      src = getHpp(gray, accel);
+      dst = getHpp(result, accel);
+
+      sts = hppiSobel(accel,src, HPP_MASK_SIZE_3X3,HPP_NORM_L1,virtMatrix[0]);
+      CHECK_STATUS(sts,"hppiSobel");
+
+      sts = hppiConvert(accel, virtMatrix[0], 0, HPP_RND_MODE_NEAR, dst, HPP_DATA_TYPE_8U);
+      CHECK_STATUS(sts,"hppiConvert");
+
+      // Wait for tasks to complete
+      sts = hppWait(accel, HPP_TIME_OUT_INFINITE);
+      CHECK_STATUS(sts, "hppWait");
+
+   We use `hppiConvert <http://software.intel.com/en-us/node/501746>`_ because hppiSobel_ returns destination
+   matrix with ``HPP_DATA_TYPE_16S`` data type for source matrix with ``HPP_DATA_TYPE_8U`` type.
+   You should check ``hppStatus`` after each call IPP Async function.
+
+#. Create windows and show the images, the usual way.
+
+   .. code-block:: cpp
+
+      imshow("image", image);
+      imshow("rez", result);
+
+      waitKey(15);
+
+#. Delete hpp matrices.
+
+   .. code-block:: cpp
+
+      sts =  hppiFreeMatrix(src);
+      CHECK_DEL_STATUS(sts,"hppiFreeMatrix");
+
+      sts =  hppiFreeMatrix(dst);
+      CHECK_DEL_STATUS(sts,"hppiFreeMatrix");
+
+#. Delete virtual matrices and accelerator instance.
+
+   .. code-block:: cpp
+
+      if (virtMatrix)
+      {
+         sts = hppiDeleteVirtualMatrices(accel, virtMatrix);
+         CHECK_DEL_STATUS(sts,"hppiDeleteVirtualMatrices");
+      }
+
+      if (accel)
+      {
+         sts = hppDeleteInstance(accel);
+         CHECK_DEL_STATUS(sts, "hppDeleteInstance");
+      }
+
+Result
+=======
+
+After compiling the code above we can execute it giving an image or video path and accelerator type as an argument.
+For this tutorial we use baboon.png image as input. The result is below.
+
+  .. image:: images/How_To_Use_IPPA_Result.jpg
+    :alt: Final Result
+    :align: center

doc/tutorials/core/table_of_content_core/table_of_content_core.rst

@@ -200,7 +200,28 @@ Here you will learn the about the basic building blocks of the library. A must r
                    :height: 90pt
                    :width:  90pt
 
+  =============== ======================================================
++
+  .. tabularcolumns:: m{100pt} m{300pt}
+  .. cssclass:: toctableopencv
+
+  =============== ======================================================
+   |IPPIma|       **Title:** :ref:`howToUseIPPAconversion`
+
+                  *Compatibility:* > OpenCV 2.0
 
+                  *Author:* |Author_ElenaG|
+
+                  You will see how to use the IPP Async with OpenCV.
+
+  =============== ======================================================
+
+  .. |IPPIma| image:: images/How_To_Use_IPPA.jpg
+                   :height: 90pt
+                   :width:  90pt
+  .. |Author_ElenaG| unicode:: Elena U+0020 Gvozdeva
+
+  =============== ======================================================
 
 .. raw:: latex
 
@@ -219,3 +240,4 @@ Here you will learn the about the basic building blocks of the library. A must r
    ../discrete_fourier_transform/discrete_fourier_transform
    ../file_input_output_with_xml_yml/file_input_output_with_xml_yml
    ../interoperability_with_OpenCV_1/interoperability_with_OpenCV_1
+   ../how_to_use_ippa_conversion/how_to_use_ippa_conversion

doc/tutorials/introduction/windows_install/windows_install.rst

@@ -62,6 +62,8 @@ Building the OpenCV library from scratch requires a couple of tools installed be
 .. _IntelTBB: http://threadingbuildingblocks.org/file.php?fid=77
 .. |IntelIIP| replace:: Intel |copy| Integrated Performance Primitives (*IPP*)
 .. _IntelIIP: http://software.intel.com/en-us/articles/intel-ipp/
+.. |IntelIIPA| replace:: Intel |copy| IPP Asynchronous C/C++
+.. _IntelIIPA: http://software.intel.com/en-us/intel-ipp-preview
 .. |qtframework| replace:: Qt framework
 .. _qtframework: http://qt.nokia.com/downloads
 .. |Eigen| replace:: Eigen
@@ -97,6 +99,8 @@ OpenCV may come in multiple flavors. There is a "core" section that will work on
 
    + |IntelIIP|_ may be used to improve the performance of color conversion, Haar training and DFT functions of the OpenCV library. Watch out, since this isn't a free service.
 
+   + |IntelIIPA|_ is currently focused delivering Intel |copy| Graphics support for advanced image processing and computer vision functions.
+
    + OpenCV offers a somewhat fancier and more useful graphical user interface, than the default one by using the |qtframework|_. For a quick overview of what this has to offer look into the documentations *highgui* module, under the *Qt New Functions* section. Version 4.6 or later of the framework is required.
 
    + |Eigen|_ is a C++ template library for linear algebra.
@@ -168,6 +172,8 @@ Building the library
          :alt: The Miktex Install Screen
          :align: center
 
+   #) For the |IntelIIPA|_ download the source files and set environment variable **IPP_ASYNC_ROOT**. It should point to :file:`<your Program Files(x86) directory>/Intel/IPP Preview */ipp directory`. Here ``*`` denotes the particular preview name.
+
    #) In case of the |Eigen|_ library it is again a case of download and extract to the :file:`D:/OpenCV/dep` directory.
 
    #) Same as above with |OpenEXR|_.

modules/core/doc/core.rst

@@ -16,3 +16,4 @@ core. The Core Functionality
     clustering
     utility_and_system_functions_and_macros
     opengl_interop
+    ipp_async_converters