Merge pull request #2243 from ilya-lavrenov:ocl2trash

modules/nonfree/CMakeLists.txt

@@ -4,4 +4,4 @@ endif()
 
 set(the_description "Functionality with possible limitations on the use")
 ocv_warnings_disable(CMAKE_CXX_FLAGS -Wundef)
-ocv_define_module(nonfree opencv_imgproc opencv_features2d opencv_calib3d OPTIONAL opencv_cudaarithm opencv_ocl)
+ocv_define_module(nonfree opencv_imgproc opencv_features2d opencv_calib3d OPTIONAL opencv_cudaarithm)

modules/ocl/CMakeLists.txt

-if(NOT HAVE_OPENCL)
-  ocv_module_disable(ocl)
-  return()
-endif()
-
-set(the_description "OpenCL-accelerated Computer Vision")
-ocv_define_module(ocl opencv_core opencv_imgproc opencv_features2d opencv_objdetect opencv_video opencv_calib3d opencv_ml "${OPENCL_LIBRARIES}")
-if(TARGET opencv_test_ocl)
-  target_link_libraries(opencv_test_ocl "${OPENCL_LIBRARIES}")
-endif()
-ocv_warnings_disable(CMAKE_CXX_FLAGS -Wshadow)

modules/ocl/doc/data_structures.rst

-Data Structures
-=============================
-
-.. ocv:class:: ocl::oclMat
-
-OpenCV C++ 1-D or 2-D dense array class ::
-
-    class CV_EXPORTS oclMat
-    {
-    public:
-        //! default constructor
-        oclMat();
-        //! constructs oclMatrix of the specified size and type (_type is CV_8UC1, CV_64FC3, CV_32SC(12) etc.)
-        oclMat(int rows, int cols, int type);
-        oclMat(Size size, int type);
-        //! constucts oclMatrix and fills it with the specified value _s.
-        oclMat(int rows, int cols, int type, const Scalar &s);
-        oclMat(Size size, int type, const Scalar &s);
-        //! copy constructor
-        oclMat(const oclMat &m);
-
-        //! constructor for oclMatrix headers pointing to user-allocated data
-        oclMat(int rows, int cols, int type, void *data, size_t step = Mat::AUTO_STEP);
-        oclMat(Size size, int type, void *data, size_t step = Mat::AUTO_STEP);
-
-        //! creates a matrix header for a part of the bigger matrix
-        oclMat(const oclMat &m, const Range &rowRange, const Range &colRange);
-        oclMat(const oclMat &m, const Rect &roi);
-
-        //! builds oclMat from Mat. Perfom blocking upload to device.
-        explicit oclMat (const Mat &m);
-
-        //! destructor - calls release()
-        ~oclMat();
-
-        //! assignment operators
-        oclMat &operator = (const oclMat &m);
-        //! assignment operator. Perfom blocking upload to device.
-        oclMat &operator = (const Mat &m);
-        oclMat &operator = (const oclMatExpr& expr);
-
-        //! pefroms blocking upload data to oclMat.
-        void upload(const cv::Mat &m);
-
-
-        //! downloads data from device to host memory. Blocking calls.
-        operator Mat() const;
-        void download(cv::Mat &m) const;
-
-        //! convert to _InputArray
-        operator _InputArray();
-
-        //! convert to _OutputArray
-        operator _OutputArray();
-
-        //! returns a new oclMatrix header for the specified row
-        oclMat row(int y) const;
-        //! returns a new oclMatrix header for the specified column
-        oclMat col(int x) const;
-        //! ... for the specified row span
-        oclMat rowRange(int startrow, int endrow) const;
-        oclMat rowRange(const Range &r) const;
-        //! ... for the specified column span
-        oclMat colRange(int startcol, int endcol) const;
-        oclMat colRange(const Range &r) const;
-
-        //! returns deep copy of the oclMatrix, i.e. the data is copied
-        oclMat clone() const;
-
-        //! copies those oclMatrix elements to "m" that are marked with non-zero mask elements.
-        // It calls m.create(this->size(), this->type()).
-        // It supports any data type
-        void copyTo( oclMat &m, const oclMat &mask = oclMat()) const;
-
-        //! converts oclMatrix to another datatype with optional scalng. See cvConvertScale.
-        void convertTo( oclMat &m, int rtype, double alpha = 1, double beta = 0 ) const;
-
-        void assignTo( oclMat &m, int type = -1 ) const;
-
-        //! sets every oclMatrix element to s
-        oclMat& operator = (const Scalar &s);
-        //! sets some of the oclMatrix elements to s, according to the mask
-        oclMat& setTo(const Scalar &s, const oclMat &mask = oclMat());
-        //! creates alternative oclMatrix header for the same data, with different
-        // number of channels and/or different number of rows. see cvReshape.
-        oclMat reshape(int cn, int rows = 0) const;
-
-        //! allocates new oclMatrix data unless the oclMatrix already has specified size and type.
-        // previous data is unreferenced if needed.
-        void create(int rows, int cols, int type);
-        void create(Size size, int type);
-
-        //! allocates new oclMatrix with specified device memory type.
-        void createEx(int rows, int cols, int type, DevMemRW rw_type, DevMemType mem_type);
-        void createEx(Size size, int type, DevMemRW rw_type, DevMemType mem_type);
-
-        //! decreases reference counter;
-        // deallocate the data when reference counter reaches 0.
-        void release();
-
-        //! swaps with other smart pointer
-        void swap(oclMat &mat);
-
-        //! locates oclMatrix header within a parent oclMatrix. See below
-        void locateROI( Size &wholeSize, Point &ofs ) const;
-        //! moves/resizes the current oclMatrix ROI inside the parent oclMatrix.
-        oclMat& adjustROI( int dtop, int dbottom, int dleft, int dright );
-        //! extracts a rectangular sub-oclMatrix
-        // (this is a generalized form of row, rowRange etc.)
-        oclMat operator()( Range rowRange, Range colRange ) const;
-        oclMat operator()( const Rect &roi ) const;
-
-        oclMat& operator+=( const oclMat& m );
-        oclMat& operator-=( const oclMat& m );
-        oclMat& operator*=( const oclMat& m );
-        oclMat& operator/=( const oclMat& m );
-
-        //! returns true if the oclMatrix data is continuous
-        // (i.e. when there are no gaps between successive rows).
-        // similar to CV_IS_oclMat_CONT(cvoclMat->type)
-        bool isContinuous() const;
-        //! returns element size in bytes,
-        // similar to CV_ELEM_SIZE(cvMat->type)
-        size_t elemSize() const;
-        //! returns the size of element channel in bytes.
-        size_t elemSize1() const;
-        //! returns element type, similar to CV_MAT_TYPE(cvMat->type)
-        int type() const;
-        //! returns element type, i.e. 8UC3 returns 8UC4 because in ocl
-        //! 3 channels element actually use 4 channel space
-        int ocltype() const;
-        //! returns element type, similar to CV_MAT_DEPTH(cvMat->type)
-        int depth() const;
-        //! returns element type, similar to CV_MAT_CN(cvMat->type)
-        int channels() const;
-        //! returns element type, return 4 for 3 channels element,
-        //!becuase 3 channels element actually use 4 channel space
-        int oclchannels() const;
-        //! returns step/elemSize1()
-        size_t step1() const;
-        //! returns oclMatrix size:
-        // width == number of columns, height == number of rows
-        Size size() const;
-        //! returns true if oclMatrix data is NULL
-        bool empty() const;
-
-        //! matrix transposition
-        oclMat t() const;
-
-        /*! includes several bit-fields:
-          - the magic signature
-          - continuity flag
-          - depth
-          - number of channels
-          */
-        int flags;
-        //! the number of rows and columns
-        int rows, cols;
-        //! a distance between successive rows in bytes; includes the gap if any
-        size_t step;
-        //! pointer to the data(OCL memory object)
-        uchar *data;
-
-        //! pointer to the reference counter;
-        // when oclMatrix points to user-allocated data, the pointer is NULL
-        int *refcount;
-
-        //! helper fields used in locateROI and adjustROI
-        //datastart and dataend are not used in current version
-        uchar *datastart;
-        uchar *dataend;
-
-        //! OpenCL context associated with the oclMat object.
-        Context *clCxt;
-        //add offset for handle ROI, calculated in byte
-        int offset;
-        //add wholerows and wholecols for the whole matrix, datastart and dataend are no longer used
-        int wholerows;
-        int wholecols;
-    };
-
-Basically speaking, the ``oclMat`` is the mirror of ``Mat`` with the extension of OCL feature, the members have the same meaning and useage of ``Mat`` except following:
-
-* ``datastart`` and ``dataend`` are replaced with ``wholerows`` and ``wholecols``
-
-* Only basic flags are supported in ``oclMat`` (i.e. depth number of channels)
-
-* All the 3-channel matrix (i.e. RGB image) are represented by 4-channel matrix in ``oclMat``. It means 3-channel image have 4-channel space with the last channel unused. We provide a transparent interface to handle the difference between OpenCV ``Mat`` and ``oclMat``.
-    For example: If a ``oclMat`` has 3 channels, ``channels()`` returns 3 and ``oclchannels()`` returns 4

modules/ocl/doc/introduction.rst

-OpenCL Module Introduction
-==========================
-
-.. highlight:: cpp
-
-General Information
--------------------
-
-The OpenCV OCL module contains a set of classes and functions that implement and accelerate OpenCV functionality on OpenCL compatible devices. OpenCL is a Khronos standard, implemented by a variety of devices (CPUs, GPUs, FPGAs, ARM), abstracting the exact hardware details, while enabling vendors to provide native implementation for maximal acceleration on their hardware. The standard enjoys wide industry support, and the end user of the module will enjoy the data parallelism benefits that the specific platform/hardware may be capable of, in a platform/hardware independent manner.
-
-While in the future we hope to validate (and enable) the OCL module in all OpenCL capable devices, we currently develop and test on GPU devices only. This includes both discrete GPUs (NVidia, AMD), as well as integrated chips (AMD APU and Intel HD devices). Performance of any particular algorithm will depend on the particular platform characteristics and capabilities. However, currently, accuracy and  mathematical correctness has been verified to be identical to that of the pure CPU implementation on all tested GPU devices and platforms (both Windows and Linux).
-
-
-The OpenCV OCL module includes utility functions, low-level vision primitives, and high-level algorithms. The utility functions and low-level primitives provide a powerful infrastructure for developing fast vision algorithms taking advantage of OCL, whereas the high-level functionality (samples) includes some state-of-the-art algorithms (including LK Optical flow, and Face detection) ready to be used by the application developers. The module is also accompanied by an extensive performance and accuracy test suite.
-
-The OpenCV OCL module is designed for ease of use and does not require any knowledge of OpenCL. At a minimum level, it can be viewed as a set of accelerators, that can take advantage of the high compute throughput that GPU/APU devices can provide. However, it can also be viewed as a starting point to really integrate the built-in functionality with your own custom OpenCL kernels, with or without modifying the source of OpenCV-OCL. Of course, knowledge of OpenCL will certainly help, however we hope that OpenCV-OCL module, and the kernels it contains in source code, can be very useful as a means of actually learning openCL. Such a knowledge would be necessary to further fine-tune any of the existing OpenCL kernels, or for extending the framework with new kernels. As of OpenCV 2.4.4, we introduce interoperability with OpenCL, enabling easy use of custom OpenCL kernels within the OpenCV framework.
-
-To correctly run the OCL module, you need to have the OpenCL runtime provided by the device vendor, typically the device driver.
-
-To enable OCL support, configure OpenCV using CMake with ``WITH_OPENCL=ON``. When the flag is set and if OpenCL SDK is installed, the full-featured OpenCV OCL module is built. Otherwise, the module may be not built. If you have AMD'S FFT and BLAS library, you can select it with ``WITH_OPENCLAMDFFT=ON``, ``WITH_OPENCLAMDBLAS=ON``.
-
-The ocl module can be found under the "modules" directory. In "modules/ocl/src" you can find the source code for the cpp class that wrap around the direct kernel invocation. The kernels themselves can be found in "modules/ocl/src/opencl".  Samples can be found under "samples/ocl". Accuracy tests can be found in "modules/ocl/test", and performance tests under "module/ocl/perf".
-
-
-
-Right now, the user can select OpenCL device by specifying the environment variable ``OPENCV_OPENCL_DEVICE``. Variable format:
-
-.. code-block:: cpp
-
-    <Platform>:<CPU|GPU|ACCELERATOR|nothing=GPU/CPU>:<DeviceName or ID>
-
-**Note:** Device ID range is: 0..9 (only one digit, 10 - it is a part of name)
-
-Samples:
-
-.. code-block:: cpp
-
-    '' = ':' = '::' = ':GPU|CPU:'
-    'AMD:GPU|CPU:'
-    'AMD::Tahiti'
-    ':GPU:1'
-    ':CPU:2'
-
-Also the user can use ``cv::ocl::setDevice`` function (with ``cv::ocl::getOpenCLPlatforms`` and ``cv::ocl::getOpenCLDevices``). This function initializes OpenCL runtime and setup the passed device as computing device.
-
-In the current version, all the thread share the same context and device so the multi-devices are not supported. We will add this feature soon. If a function support 4-channel operator, it should support 3-channel operator as well, because All the 3-channel matrix(i.e. RGB image) are represented by 4-channel matrix in ``oclMat``. It means 3-channel image have 4-channel space with the last channel unused. We provide a transparent interface to handle the difference between OpenCV Mat and ``oclMat``.
-
-Developer Notes
--------------------
-
-In a heterogeneous device environment, there may be cost associated with data transfer. This would be the case, for example, when data needs to be moved from host memory (accessible to the CPU), to device memory (accessible to a discrete GPU). in the case of integrated graphics chips, there may be performance issues, relating to memory coherency between access from the GPU "part" of the integrated device, or the CPU "part." For best performance, in either case, it is recommended that you do not introduce data transfers between CPU and the discrete GPU, except in the beginning and the end of the algorithmic pipeline.
-
-Some tidbits:
-
-1. OpenCL version should be larger than 1.1 with FULL PROFILE.
-
-2. Currently there's only one OpenCL context and command queue. We hope to implement multi device and multi queue support in the future.
-
-3. Many kernels use 256 as its workgroup size if possible, so the max work group size of the device must larger than 256. All GPU devices we are aware of indeed support 256 workitems in a workgroup, however non GPU devices may not. This will be improved in the future.
-
-4. If the device does not support double arithmetic, then functions' implementation generates an error.
-
-5. The ``oclMat`` uses buffer object, not image object.
-
-6. All the 3-channel matrices (i.e. RGB image) are represented by 4-channel matrices in ``oclMat``, with the last channel unused. We provide a transparent interface to handle the difference between OpenCV Mat and ``oclMat``.
-
-7. All the matrix in ``oclMat`` is aligned in column (now the alignment factor for ``step`` is 32+ byte). It means, m.cols * m.elemSize() <= m.step.
-
-8. Data transfer between Mat and ``oclMat``: If the CPU matrix is aligned in column, we will use faster API to transfer between Mat and ``oclMat``, otherwise, we will use clEnqueueRead/WriteBufferRect to transfer data to guarantee the alignment. 3-channel matrix is an exception, it's directly transferred to a temp buffer and then padded to 4-channel matrix(also aligned) when uploading and do the reverse operation when downloading.
-
-9. Data transfer between Mat and ``oclMat``: ROI is a feature of OpenCV, which allow users process a sub rectangle of a matrix. When a CPU matrix which has ROI will be transfered to GPU, the whole matrix will be transfered and set ROI as CPU's. In a word, we always transfer the whole matrix despite whether it has ROI or not.
-
-10. All the kernel file should locate in "modules/ocl/src/opencl/" with the extension ".cl". All the kernel files are transformed to pure characters at compilation time in opencl_kernels.cpp, and the file name without extension is the name of the program sources.

modules/ocl/doc/matrix_reductions.rst

-Matrix Reductions
-=============================
-
-.. highlight:: cpp
-
-ocl::absSum
----------------
-Returns the sum of absolute values for matrix elements.
-
-.. ocv:function:: Scalar ocl::absSum(const oclMat &m)
-
-    :param m: The Source image of all depth.
-
-Counts the abs sum of matrix elements for each channel. Supports all data types.
-
-ocl::countNonZero
----------------------
-Returns the number of non-zero elements in src
-
-.. ocv:function:: int ocl::countNonZero(const oclMat &src)
-
-    :param src: Single-channel array
-
-Counts non-zero array elements. Supports all data types.
-
-ocl::min
-------------------
-
-.. ocv:function:: void ocl::min(const oclMat &src1, const oclMat &src2, oclMat &dst)
-
-    :param src1: the first input array.
-
-    :param src2: the second input array, must be the same size and same type as ``src1``.
-
-    :param dst: the destination array, it will have the same size and same type as ``src1``.
-
-Computes element-wise minima of two arrays. Supports all data types.
-
-ocl::max
-------------------
-
-.. ocv:function:: void ocl::max(const oclMat &src1, const oclMat &src2, oclMat &dst)
-
-    :param src1: the first input array.
-
-    :param src2: the second input array, must be the same size and same type as ``src1``.
-
-    :param dst: the destination array, it will have the same size and same type as ``src1``.
-
-Computes element-wise maxima of two arrays. Supports all data types.
-
-ocl::minMax
-------------------
-Returns void
-
-.. ocv:function:: void ocl::minMax(const oclMat &src, double *minVal, double *maxVal = 0, const oclMat &mask = oclMat())
-
-    :param src: Single-channel array
-
-    :param minVal: Pointer to returned minimum value, should not be NULL
-
-    :param maxVal: Pointer to returned maximum value, should not be NULL
-
-    :param mask: The optional mask used to select a sub-array
-
-Finds global minimum and maximum in a whole array or sub-array. Supports all data types.
-
-ocl::minMaxLoc
-------------------
-Returns void
-
-.. ocv:function:: void ocl::minMaxLoc(const oclMat &src, double *minVal, double *maxVal = 0, Point *minLoc = 0, Point *maxLoc = 0,const oclMat &mask = oclMat())
-
-    :param src: Single-channel array
-
-    :param minVal: Pointer to returned minimum value, should not be NULL
-
-    :param maxVal: Pointer to returned maximum value, should not be NULL
-
-    :param minLoc: Pointer to returned minimum location (in 2D case), should not be NULL
-
-    :param maxLoc: Pointer to returned maximum location (in 2D case) should not be NULL
-
-    :param mask: The optional mask used to select a sub-array
-
-The functions minMaxLoc find minimum and maximum element values and their positions. The extremums are searched across the whole array, or, if mask is not an empty array, in the specified array region. The functions do not work with multi-channel arrays.
-
-ocl::sqrSum
-------------------
-Returns the squared sum of matrix elements for each channel
-
-.. ocv:function:: Scalar ocl::sqrSum(const oclMat &m)
-
-    :param m: The Source image of all depth.
-
-Counts the squared sum of matrix elements for each channel. Supports all data types.
-
-ocl::sum
-------------------
-Returns the sum of matrix elements for each channel
-
-.. ocv:function:: Scalar ocl::sum(const oclMat &m)
-
-    :param m: The Source image of all depth.
-
-Counts the sum of matrix elements for each channel.

modules/ocl/doc/ml_machine_learning.rst

-ml.Machine Learning
-=============================
-
-.. highlight:: cpp
-
-ocl::KNearestNeighbour
---------------------------
-.. ocv:class:: ocl::KNearestNeighbour : public ocl::CvKNearest
-
-The class implements K-Nearest Neighbors model as described in the beginning of this section.
-
-ocl::KNearestNeighbour
---------------------------
-Computes the weighted sum of two arrays. ::
-
-    class CV_EXPORTS KNearestNeighbour: public CvKNearest
-    {
-    public:
-        KNearestNeighbour();
-        ~KNearestNeighbour();
-
-        bool train(const Mat& trainData, Mat& labels, Mat& sampleIdx = Mat().setTo(Scalar::all(0)),
-            bool isRegression = false, int max_k = 32, bool updateBase = false);
-
-        void clear();
-
-        void find_nearest(const oclMat& samples, int k, oclMat& lables);
-
-    private:
-        /* hidden */
-    };
-
-ocl::KNearestNeighbour::train
----------------------------------
-Trains the model.
-
-.. ocv:function:: bool ocl::KNearestNeighbour::train(const Mat& trainData, Mat& labels, Mat& sampleIdx = Mat().setTo(Scalar::all(0)), bool isRegression = false, int max_k = 32, bool updateBase = false)
-
-    :param isRegression: Type of the problem: ``true`` for regression and ``false`` for classification.
-
-    :param maxK: Number of maximum neighbors that may be passed to the method :ocv:func:`CvKNearest::find_nearest`.
-
-    :param updateBase: Specifies whether the model is trained from scratch (``update_base=false``), or it is updated using the new training data (``update_base=true``). In the latter case, the parameter ``maxK`` must not be larger than the original value.
-
-The method trains the K-Nearest model. It follows the conventions of the generic :ocv:func:`CvStatModel::train` approach with the following limitations:
-
-* Only ``CV_ROW_SAMPLE`` data layout is supported.
-* Input variables are all ordered.
-* Output variables can be either categorical ( ``is_regression=false`` ) or ordered ( ``is_regression=true`` ).
-* Variable subsets (``var_idx``) and missing measurements are not supported.
-
-ocl::KNearestNeighbour::find_nearest
-----------------------------------------
-Finds the neighbors and predicts responses for input vectors.
-
-.. ocv:function:: void ocl::KNearestNeighbour::find_nearest(const oclMat& samples, int k, oclMat& lables )
-
-    :param samples: Input samples stored by rows. It is a single-precision floating-point matrix of :math:`number\_of\_samples \times number\_of\_features` size.
-
-    :param k: Number of used nearest neighbors. It must satisfy constraint: :math:`k \le` :ocv:func:`CvKNearest::get_max_k`.
-
-    :param labels: Vector with results of prediction (regression or classification) for each input sample. It is a single-precision floating-point vector with ``number_of_samples`` elements.
-
-ocl::kmeans
----------------
-Finds centers of clusters and groups input samples around the clusters.
-
-.. ocv:function:: double ocl::kmeans(const oclMat &src, int K, oclMat &bestLabels, TermCriteria criteria, int attemps, int flags, oclMat &centers)
-
-    :param src: Floating-point matrix of input samples, one row per sample.
-
-    :param K: Number of clusters to split the set by.
-
-    :param bestLabels: Input/output integer array that stores the cluster indices for every sample.
-
-    :param criteria: The algorithm termination criteria, that is, the maximum number of iterations and/or the desired accuracy. The accuracy is specified as ``criteria.epsilon``. As soon as each of the cluster centers moves by less than ``criteria.epsilon`` on some iteration, the algorithm stops.
-
-    :param attempts: Flag to specify the number of times the algorithm is executed using different initial labellings. The algorithm returns the labels that yield the best compactness (see the last function parameter).
-
-    :param flags: Flag that can take the following values:
-
-            * **KMEANS_RANDOM_CENTERS** Select random initial centers in each attempt.
-
-            * **KMEANS_PP_CENTERS** Use ``kmeans++`` center initialization by Arthur and Vassilvitskii [Arthur2007].
-
-            * **KMEANS_USE_INITIAL_LABELS** During the first (and possibly the only) attempt, use the user-supplied labels instead of computing them from the initial centers. For the second and further attempts, use the random or semi-random centers. Use one of  ``KMEANS_*_CENTERS``  flag to specify the exact method.
-
-    :param centers: Output matrix of the cluster centers, one row per each cluster center.
-
-ocl::distanceToCenters
-----------------------
-For each samples in ``source``, find its closest neighour in ``centers``.
-
-.. ocv:function:: void ocl::distanceToCenters(const oclMat &src, const oclMat &centers, Mat &dists, Mat &labels, int distType = NORM_L2SQR)
-
-    :param src: Floating-point matrix of input samples. One row per sample.
-
-    :param centers: Floating-point matrix of center candidates. One row per center.
-
-    :param distType: Distance metric to calculate distances. Supports ``NORM_L1`` and ``NORM_L2SQR``.
-
-    :param dists: The output distances calculated from each sample to the best matched center.
-
-    :param labels: The output index of best matched center for each row of sample.
-
-The method is a utility function which maybe used for multiple clustering algorithms such as K-means.

modules/ocl/doc/object_detection.rst

-Object Detection
-=============================
-
-.. highlight:: cpp
-
-ocl::OclCascadeClassifier
------------------------------
-.. ocv:class:: ocl::OclCascadeClassifier : public CascadeClassifier
-
-Cascade classifier class used for object detection. Supports HAAR cascade classifier  in the form of cross link ::
-
-    class CV_EXPORTS OclCascadeClassifier : public CascadeClassifier
-    {
-    public:
-            void detectMultiScale(oclMat &image, CV_OUT std::vector<cv::Rect>& faces,
-                                              double scaleFactor = 1.1, int minNeighbors = 3, int flags = 0,
-                                              Size minSize = Size(), Size maxSize = Size());
-    };
-
-.. note::
-
-   (Ocl) A face detection example using cascade classifiers can be found at opencv_source_code/samples/ocl/facedetect.cpp
-
-ocl::OclCascadeClassifier::detectMultiScale
-------------------------------------------------------
-Detects objects of different sizes in the input image.
-
-.. ocv:function:: void ocl::OclCascadeClassifier::detectMultiScale(oclMat &image, std::vector<cv::Rect>& faces, double scaleFactor = 1.1, int minNeighbors = 3, int flags = 0, Size minSize = Size(), Size maxSize = Size())
-
-    :param faces: Vector of rectangles where each rectangle contains the detected object.
-
-    :param image:  Matrix of type CV_8U containing an image where objects should be detected.
-
-    :param scaleFactor: Parameter specifying how much the image size is reduced at each image scale.
-
-    :param minNeighbors: Parameter specifying how many neighbors each candidate rectangle should have to retain it.
-
-    :param flags: Parameter with the same meaning for an old cascade as in the function ``cvHaarDetectObjects``. It is not used for a new cascade.
-
-    :param minSize: Minimum possible object size. Objects smaller than that are ignored.
-
-    :param maxSize: Maximum possible object size. Objects larger than that are ignored.
-
-The function provides a very similar interface with that in CascadeClassifier class, except using oclMat as input image.
-
-ocl::MatchTemplateBuf
--------------------------
-.. ocv:struct:: ocl::MatchTemplateBuf
-
-Class providing memory buffers for :ocv:func:`ocl::matchTemplate` function, plus it allows to adjust some specific parameters. ::
-
-    struct CV_EXPORTS MatchTemplateBuf
-    {
-        Size user_block_size;
-        oclMat imagef, templf;
-        std::vector<oclMat> images;
-        std::vector<oclMat> image_sums;
-        std::vector<oclMat> image_sqsums;
-    };
-
-You can use field `user_block_size` to set specific block size for :ocv:func:`ocl::matchTemplate` function. If you leave its default value `Size(0,0)` then automatic estimation of block size will be used (which is optimized for speed). By varying `user_block_size` you can reduce memory requirements at the cost of speed.
-
-ocl::matchTemplate
-----------------------
-Computes a proximity map for a raster template and an image where the template is searched for.
-
-.. ocv:function:: void ocl::matchTemplate(const oclMat& image, const oclMat& templ, oclMat& result, int method)
-
-.. ocv:function:: void ocl::matchTemplate(const oclMat& image, const oclMat& templ, oclMat& result, int method, MatchTemplateBuf &buf)
-
-    :param image: Source image.  ``CV_32F`` and  ``CV_8U`` depth images (1..4 channels) are supported for now.
-
-    :param templ: Template image with the size and type the same as  ``image`` .
-
-    :param result: Map containing comparison results ( ``CV_32FC1`` ). If  ``image`` is  *W x H*  and ``templ`` is  *w x h*, then  ``result`` must be *W-w+1 x H-h+1*.
-
-    :param method: Specifies the way to compare the template with the image.
-
-    :param buf: Optional buffer to avoid extra memory allocations and to adjust some specific parameters. See :ocv:struct:`ocl::MatchTemplateBuf`.
-
-    The following methods are supported for the ``CV_8U`` depth images for now:
-
-    * ``CV_TM_SQDIFF``
-    * ``CV_TM_SQDIFF_NORMED``
-    * ``CV_TM_CCORR``
-    * ``CV_TM_CCORR_NORMED``
-    * ``CV_TM_CCOEFF``
-    * ``CV_TM_CCOEFF_NORMED``
-
-    The following methods are supported for the ``CV_32F`` images for now:
-
-    * ``CV_TM_SQDIFF``
-    * ``CV_TM_CCORR``
-
-.. seealso:: :ocv:func:`matchTemplate`

modules/ocl/doc/ocl.rst

-***************************************
-ocl. OpenCL-accelerated Computer Vision
-***************************************
-
-.. toctree::
-    :maxdepth: 1
-
-    introduction
-    structures_and_utility_functions
-    data_structures
-    operations_on_matrices
-    matrix_reductions
-    image_filtering
-    image_processing
-    ml_machine_learning
-    object_detection
-    feature_detection_and_description
-    video_analysis
-    camera_calibration_and_3D_reconstruction
-..    camera_calibration_and_3d_reconstruction
-..    video

modules/ocl/doc/structures_and_utility_functions.rst

-Data Structures and Utility Functions
-========================================
-
-.. highlight:: cpp
-
-ocl::getOpenCLPlatforms
------------------------
-Returns the list of OpenCL platforms
-
-.. ocv:function:: int ocl::getOpenCLPlatforms( PlatformsInfo& platforms )
-
-    :param platforms: Output variable
-
-ocl::getOpenCLDevices
----------------------
-Returns the list of devices
-
-.. ocv:function:: int ocl::getOpenCLDevices( DevicesInfo& devices, int deviceType = CVCL_DEVICE_TYPE_GPU, const PlatformInfo* platform = NULL )
-
-    :param devices: Output variable
-
-    :param deviceType: Bitmask of ``CVCL_DEVICE_TYPE_GPU``, ``CVCL_DEVICE_TYPE_CPU`` or ``CVCL_DEVICE_TYPE_DEFAULT``.
-
-    :param platform: Specifies preferrable platform
-
-ocl::setDevice
---------------
-Initialize OpenCL computation context
-
-.. ocv:function:: void ocl::setDevice( const DeviceInfo* info )
-
-    :param info: device info
-
-ocl::initializeContext
---------------------------------
-Alternative way to initialize OpenCL computation context.
-
-.. ocv:function:: void ocl::initializeContext(void* pClPlatform, void* pClContext, void* pClDevice)
-
-    :param pClPlatform: selected ``platform_id`` (via pointer, parameter type is ``cl_platform_id*``)
-
-    :param pClContext: selected ``cl_context`` (via pointer, parameter type is ``cl_context*``)
-
-    :param pClDevice: selected ``cl_device_id`` (via pointer, parameter type is ``cl_device_id*``)
-
-This function can be used for context initialization with D3D/OpenGL interoperability.
-
-ocl::setBinaryPath
-------------------
-Returns void
-
-.. ocv:function:: void ocl::setBinaryPath(const char *path)
-
-    :param path: the path of OpenCL kernel binaries
-
-If you call this function and set a valid path, the OCL module will save the compiled kernel to the address in the first time and reload the binary since that. It can save compilation time at the runtime.

modules/ocl/include/opencv2/ocl/ocl.hpp

-/*M///////////////////////////////////////////////////////////////////////////////////////
-//
-//  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
-//
-//  By downloading, copying, installing or using the software you agree to this license.
-//  If you do not agree to this license, do not download, install,
-//  copy or use the software.
-//
-//
-//                           License Agreement
-//                For Open Source Computer Vision Library
-//
-// Copyright (C) 2000-2008, Intel Corporation, all rights reserved.
-// Copyright (C) 2009, Willow Garage Inc., all rights reserved.
-// Copyright (C) 2013, OpenCV Foundation, all rights reserved.
-// Third party copyrights are property of their respective owners.
-//
-// Redistribution and use in source and binary forms, with or without modification,
-// are permitted provided that the following conditions are met:
-//
-//   * Redistribution's of source code must retain the above copyright notice,
-//     this list of conditions and the following disclaimer.
-//
-//   * Redistribution's in binary form must reproduce the above copyright notice,
-//     this list of conditions and the following disclaimer in the documentation
-//     and/or other materials provided with the distribution.
-//
-//   * The name of the copyright holders may not be used to endorse or promote products
-//     derived from this software without specific prior written permission.
-//
-// This software is provided by the copyright holders and contributors "as is" and
-// any express or implied warranties, including, but not limited to, the implied
-// warranties of merchantability and fitness for a particular purpose are disclaimed.
-// In no event shall the Intel Corporation or contributors be liable for any direct,
-// indirect, incidental, special, exemplary, or consequential damages
-// (including, but not limited to, procurement of substitute goods or services;
-// loss of use, data, or profits; or business interruption) however caused
-// and on any theory of liability, whether in contract, strict liability,
-// or tort (including negligence or otherwise) arising in any way out of
-// the use of this software, even if advised of the possibility of such damage.
-//
-//M*/
-
-#ifdef __OPENCV_BUILD
-#error this is a compatibility header which should not be used inside the OpenCV library
-#endif
-
-#include "opencv2/ocl.hpp"

modules/ocl/include/opencv2/ocl/private/opencl_dumpinfo.hpp

-/*M///////////////////////////////////////////////////////////////////////////////////////
-//
-//  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
-//
-//  By downloading, copying, installing or using the software you agree to this license.
-//  If you do not agree to this license, do not download, install,
-//  copy or use the software.
-//
-//
-//                           License Agreement
-//                For Open Source Computer Vision Library
-//
-// Copyright (C) 2010-2013, Advanced Micro Devices, Inc., all rights reserved.
-// Third party copyrights are property of their respective owners.
-//
-// Redistribution and use in source and binary forms, with or without modification,
-// are permitted provided that the following conditions are met:
-//
-//   * Redistribution's of source code must retain the above copyright notice,
-//     this list of conditions and the following disclaimer.
-//
-//   * Redistribution's in binary form must reproduce the above copyright notice,
-//     this list of conditions and the following disclaimer in the documentation
-//     and/or other materials provided with the distribution.
-//
-//   * The name of the copyright holders may not be used to endorse or promote products
-//     derived from this software without specific prior written permission.
-//
-// This software is provided by the copyright holders and contributors "as is" and
-// any express or implied warranties, including, but not limited to, the implied
-// warranties of merchantability and fitness for a particular purpose are disclaimed.
-// In no event shall contributors be liable for any direct,
-// indirect, incidental, special, exemplary, or consequential damages
-// (including, but not limited to, procurement of substitute goods or services;
-// loss of use, data, or profits; or business interruption) however caused
-// and on any theory of liability, whether in contract, strict liability,
-// or tort (including negligence or otherwise) arising in any way out of
-// the use of this software, even if advised of the possibility of such damage.
-//
-//M*/
-
-#if !defined(DUMP_MESSAGE_STDOUT) && !defined(DUMP_PROPERTY_XML)
-#error Invalid usage
-#endif
-
-#if !defined(DUMP_PROPERTY_XML)
-#define DUMP_PROPERTY_XML(...)
-#endif
-
-#if !defined(DUMP_MESSAGE_STDOUT)
-#define DUMP_MESSAGE_STDOUT(...)
-#endif
-
-#include <sstream>
-
-static std::string bytesToStringRepr(size_t value)
-{
-    size_t b = value % 1024;
-    value /= 1024;
-
-    size_t kb = value % 1024;
-    value /= 1024;
-
-    size_t mb = value % 1024;
-    value /= 1024;
-
-    size_t gb = value;
-
-    std::ostringstream stream;
-
-    if (gb > 0)
-        stream << gb << " GB ";
-    if (mb > 0)
-        stream << mb << " MB ";
-    if (kb > 0)
-        stream << kb << " kB ";
-    if (b > 0)
-        stream << b << " B";
-
-    return stream.str();
-}
-
-static void dumpOpenCLDevice()
-{
-    using namespace cv::ocl;
-    try
-    {
-        cv::ocl::PlatformsInfo platforms;
-        cv::ocl::getOpenCLPlatforms(platforms);
-        DUMP_MESSAGE_STDOUT("OpenCL Platforms: ");
-        const char* deviceTypeStr;
-        for(unsigned int i=0; i < platforms.size(); i++)
-        {
-            DUMP_MESSAGE_STDOUT("    " << platforms.at(i)->platformName);
-            const cv::ocl::DevicesInfo& devices = platforms.at(i)->devices;
-            for(unsigned int j=0; j < devices.size(); j++)
-            {
-                const cv::ocl::DeviceInfo& current_device = *devices.at(j);
-                deviceTypeStr = current_device.deviceType == CVCL_DEVICE_TYPE_CPU
-                            ? ("CPU") : (current_device.deviceType == CVCL_DEVICE_TYPE_GPU ? "GPU" : "unknown");
-                DUMP_MESSAGE_STDOUT( "        " << deviceTypeStr << " : " << current_device.deviceName << " : " << current_device.deviceVersion );
-                DUMP_PROPERTY_XML("cv_ocl_platform_"<< i<<"_device_"<<j, "(Platform=" << current_device.platform->platformName << ")(Type="
-                    << deviceTypeStr <<")(Name="<< current_device.deviceName << ")(Version="<< current_device.deviceVersion<<")");
-            }
-        }
-        DUMP_MESSAGE_STDOUT("Current OpenCL device: ");
-
-        const cv::ocl::DeviceInfo& deviceInfo = cv::ocl::Context::getContext()->getDeviceInfo();
-
-        DUMP_MESSAGE_STDOUT("    Platform = "<< deviceInfo.platform->platformName);
-        DUMP_PROPERTY_XML("cv_ocl_current_platformName", deviceInfo.platform->platformName);
-
-        deviceTypeStr = deviceInfo.deviceType == CVCL_DEVICE_TYPE_CPU
-                        ? "CPU" : (deviceInfo.deviceType == CVCL_DEVICE_TYPE_GPU ? "GPU" : "unknown");
-        DUMP_MESSAGE_STDOUT("    Type = "<< deviceTypeStr);
-        DUMP_PROPERTY_XML("cv_ocl_current_deviceType", deviceTypeStr);
-
-        DUMP_MESSAGE_STDOUT("    Name = "<< deviceInfo.deviceName);
-        DUMP_PROPERTY_XML("cv_ocl_current_deviceName", deviceInfo.deviceName);
-
-        DUMP_MESSAGE_STDOUT("    Version = " << deviceInfo.deviceVersion);
-        DUMP_PROPERTY_XML("cv_ocl_current_deviceVersion", deviceInfo.deviceVersion);
-
-        DUMP_MESSAGE_STDOUT("    Compute units = "<< deviceInfo.maxComputeUnits);
-        DUMP_PROPERTY_XML("cv_ocl_current_maxComputeUnits", deviceInfo.maxComputeUnits);
-
-        DUMP_MESSAGE_STDOUT("    Max work group size = "<< deviceInfo.maxWorkGroupSize);
-        DUMP_PROPERTY_XML("cv_ocl_current_maxWorkGroupSize", deviceInfo.maxWorkGroupSize);
-
-        std::string localMemorySizeStr = bytesToStringRepr(deviceInfo.localMemorySize);
-        DUMP_MESSAGE_STDOUT("    Local memory size = "<< localMemorySizeStr.c_str());
-        DUMP_PROPERTY_XML("cv_ocl_current_localMemorySize", deviceInfo.localMemorySize);
-
-        std::string maxMemAllocSizeStr = bytesToStringRepr(deviceInfo.maxMemAllocSize);
-        DUMP_MESSAGE_STDOUT("    Max memory allocation size = "<< maxMemAllocSizeStr.c_str());
-        DUMP_PROPERTY_XML("cv_ocl_current_maxMemAllocSize", deviceInfo.maxMemAllocSize);
-
-        const char* doubleSupportStr = deviceInfo.haveDoubleSupport ? "Yes" : "No";
-        DUMP_MESSAGE_STDOUT("    Double support = "<< doubleSupportStr);
-        DUMP_PROPERTY_XML("cv_ocl_current_haveDoubleSupport", deviceInfo.haveDoubleSupport);
-
-        const char* isUnifiedMemoryStr = deviceInfo.isUnifiedMemory ? "Yes" : "No";
-        DUMP_MESSAGE_STDOUT("    Unified memory = "<< isUnifiedMemoryStr);
-        DUMP_PROPERTY_XML("cv_ocl_current_isUnifiedMemory", deviceInfo.isUnifiedMemory);
-    }
-    catch (...)
-    {
-        DUMP_MESSAGE_STDOUT("OpenCL device not available");
-        DUMP_PROPERTY_XML("cv_ocl", "not available");
-    }
-}
-
-#undef DUMP_MESSAGE_STDOUT
-#undef DUMP_PROPERTY_XML

modules/ocl/include/opencv2/ocl/private/opencl_utils.hpp

-/*M///////////////////////////////////////////////////////////////////////////////////////
-//
-//  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
-//
-//  By downloading, copying, installing or using the software you agree to this license.
-//  If you do not agree to this license, do not download, install,
-//  copy or use the software.
-//
-//
-//                           License Agreement
-//                For Open Source Computer Vision Library
-//
-// Copyright (C) 2010-2013, Advanced Micro Devices, Inc., all rights reserved.
-// Third party copyrights are property of their respective owners.
-//
-// Redistribution and use in source and binary forms, with or without modification,
-// are permitted provided that the following conditions are met:
-//
-//   * Redistribution's of source code must retain the above copyright notice,
-//     this list of conditions and the following disclaimer.
-//
-//   * Redistribution's in binary form must reproduce the above copyright notice,
-//     this list of conditions and the following disclaimer in the documentation
-//     and/or other materials provided with the distribution.
-//
-//   * The name of the copyright holders may not be used to endorse or promote products
-//     derived from this software without specific prior written permission.
-//
-// This software is provided by the copyright holders and contributors as is and
-// any express or implied warranties, including, but not limited to, the implied
-// warranties of merchantability and fitness for a particular purpose are disclaimed.
-// In no event shall contributors be liable for any direct,
-// indirect, incidental, special, exemplary, or consequential damages
-// (including, but not limited to, procurement of substitute goods or services;
-// loss of use, data, or profits; or business interruption) however caused
-// and on any theory of liability, whether in contract, strict liability,
-// or tort (including negligence or otherwise) arising in any way out of
-// the use of this software, even if advised of the possibility of such damage.
-//
-//M*/
-
-#ifndef __OPENCV_OCL_PRIVATE_OPENCL_UTILS_HPP__
-#define __OPENCV_OCL_PRIVATE_OPENCL_UTILS_HPP__
-
-#include "opencv2/core/opencl/runtime/opencl_core.hpp"
-#include <vector>
-#include <string>
-
-namespace cl_utils {
-
-inline cl_int getPlatforms(std::vector<cl_platform_id>& platforms)
-{
-    cl_uint n = 0;
-
-    cl_int err = ::clGetPlatformIDs(0, NULL, &n);
-    if (err != CL_SUCCESS)
-        return err;
-
-    platforms.clear(); platforms.resize(n);
-    err = ::clGetPlatformIDs(n, &platforms[0], NULL);
-    if (err != CL_SUCCESS)
-        return err;
-
-    return CL_SUCCESS;
-}
-
-inline cl_int getDevices(cl_platform_id platform, cl_device_type type, std::vector<cl_device_id>& devices)
-{
-    cl_uint n = 0;
-
-    cl_int err = ::clGetDeviceIDs(platform, type, 0, NULL, &n);
-    if (err != CL_SUCCESS)
-        return err;
-
-    devices.clear(); devices.resize(n);
-    err = ::clGetDeviceIDs(platform, type, n, &devices[0], NULL);
-    if (err != CL_SUCCESS)
-        return err;
-
-    return CL_SUCCESS;
-}
-
-
-
-
-template <typename Functor, typename ObjectType, typename T>
-inline cl_int getScalarInfo(Functor f, ObjectType obj, cl_uint name, T& param)
-{
-    return f(obj, name, sizeof(T), &param, NULL);
-}
-
-template <typename Functor, typename ObjectType>
-inline cl_int getStringInfo(Functor f, ObjectType obj, cl_uint name, std::string& param)
-{
-    ::size_t required;
-    cl_int err = f(obj, name, 0, NULL, &required);
-    if (err != CL_SUCCESS)
-        return err;
-
-    param.clear();
-    if (required > 0)
-    {
-        std::vector<char> buf(required + 1, char(0));
-        err = f(obj, name, required, &buf[0], NULL);
-        if (err != CL_SUCCESS)
-            return err;
-        param = &buf[0];
-    }
-
-    return CL_SUCCESS;
-}
-
-} // namespace cl_utils
-
-#endif // __OPENCV_OCL_PRIVATE_OPENCL_UTILS_HPP__

modules/ocl/perf/main.cpp

-/*M///////////////////////////////////////////////////////////////////////////////////////
-//
-//  IMPORTANT: READ BEFORE DOWNLOADING, COPYING, INSTALLING OR USING.
-//
-//  By downloading, copying, installing or using the software you agree to this license.
-//  If you do not agree to this license, do not download, install,
-//  copy or use the software.
-//
-//
-//                           License Agreement
-//                For Open Source Computer Vision Library
-//
-// Copyright (C) 2010-2012, Multicoreware, Inc., all rights reserved.
-// Copyright (C) 2010-2012, Advanced Micro Devices, Inc., all rights reserved.
-// Third party copyrights are property of their respective owners.
-//
-// Redistribution and use in source and binary forms, with or without modification,
-// are permitted provided that the following conditions are met:
-//
-//   * Redistribution's of source code must retain the above copyright notice,
-//     this list of conditions and the following disclaimer.
-//
-//   * Redistribution's in binary form must reproduce the above copyright notice,
-//     this list of conditions and the following disclaimer in the documentation
-//     and/or other materials provided with the distribution.
-//
-//   * The name of the copyright holders may not be used to endorse or promote products
-//     derived from this software without specific prior written permission.
-//
-// This software is provided by the copyright holders and contributors as is and
-// any express or implied warranties, including, but not limited to, the implied
-// warranties of merchantability and fitness for a particular purpose are disclaimed.
-// In no event shall the Intel Corporation or contributors be liable for any direct,
-// indirect, incidental, special, exemplary, or consequential damages
-// (including, but not limited to, procurement of substitute goods or services;
-// loss of use, data, or profits; or business interruption) however caused
-// and on any theory of liability, whether in contract, strict liability,
-// or tort (including negligence or otherwise) arising in any way out of
-// the use of this software, even if advised of the possibility of such damage.
-//
-//M*/
-
-#include "perf_precomp.hpp"
-
-#define DUMP_PROPERTY_XML(propertyName, propertyValue) \
-    do { \
-        std::stringstream ssName, ssValue;\
-        ssName << propertyName;\
-        ssValue << propertyValue; \
-        ::testing::Test::RecordProperty(ssName.str(), ssValue.str()); \
-    } while (false)
-
-#define DUMP_MESSAGE_STDOUT(msg) \
-    do { \
-        std::cout << msg << std::endl; \
-    } while (false)
-
-
-#include "opencv2/ocl/private/opencl_dumpinfo.hpp"
-
-static const char * impls[] =
-{
-    IMPL_OCL,
-    IMPL_PLAIN,
-#ifdef HAVE_OPENCV_GPU
-    IMPL_GPU
-#endif
-};
-
-
-int main(int argc, char ** argv)
-{
-    ::perf::TestBase::setModulePerformanceStrategy(::perf::PERF_STRATEGY_SIMPLE);
-
-    CV_PERF_TEST_MAIN_INTERNALS(ocl, impls, ::dumpOpenCLDevice())
-}