Merge pull request #117 from vpisarev/doc_updates

doc/conf.py

@@ -293,7 +293,7 @@ extlinks = {
             'svms':('http://opencv.itseez.com/modules/ml/doc/support_vector_machines.html#%s', None),
             'drawingfunc':('http://opencv.itseez.com/modules/core/doc/drawing_functions.html#%s', None),
             'xmlymlpers':('http://opencv.itseez.com/modules/core/doc/xml_yaml_persistence.html#%s', None),
-            'huivideo' : ('http://opencv.itseez.com/modules/highgui/doc/reading_and_writing_images_and_video.html#%s', None),
+            'hgvideo' : ('http://opencv.itseez.com/modules/highgui/doc/reading_and_writing_images_and_video.html#%s', None),
             'gpuinit' : ('http://opencv.itseez.com/modules/gpu/doc/initalization_and_information.html#%s', None),
             'gpudatastructure' : ('http://opencv.itseez.com/modules/gpu/doc/data_structures.html#%s', None),
             'gpuopmatrices' : ('http://opencv.itseez.com/modules/gpu/doc/operations_on_matrices.html#%s', None),

doc/tutorials/highgui/video-input-psnr-ssim/video-input-psnr-ssim.rst

@@ -27,9 +27,9 @@ As a test case where to show off these using OpenCV I've created a small program
 How to read a video stream (online-camera or offline-file)?
 ===========================================================
 
-Essentially, all the functionalities required for video manipulation is integrated in the :huivideo:`VideoCapture <videocapture>` C++ class. This on itself builds on the FFmpeg open source library. This is a basic dependency of OpenCV so you shouldn't need to worry about this. A video is composed of a succession of images, we refer to these in the literature as frames. In case of a video file there is a *frame rate* specifying just how long is between two frames. While for the video cameras usually there is a limit of just how many frames they can digitalize per second, this property is less important as at any time the camera sees the current snapshot of the world. 
+Essentially, all the functionalities required for video manipulation is integrated in the :hgvideo:`VideoCapture <videocapture>` C++ class. This on itself builds on the FFmpeg open source library. This is a basic dependency of OpenCV so you shouldn't need to worry about this. A video is composed of a succession of images, we refer to these in the literature as frames. In case of a video file there is a *frame rate* specifying just how long is between two frames. While for the video cameras usually there is a limit of just how many frames they can digitalize per second, this property is less important as at any time the camera sees the current snapshot of the world.
 
-The first task you need to do is to assign to a :huivideo:`VideoCapture <videocapture>` class its source. You can do this either via the :huivideo:`constructor <videocapture-videocapture>` or its :huivideo:`open <videocapture-open>` function. If this argument is an integer then you will bind the class to a camera, a device. The number passed here is the ID of the device, assigned by the operating system. If you have a single camera attached to your system its ID will probably be zero and further ones increasing from there. If the parameter passed to these is a string it will refer to a video file, and the string points to the location and name of the file. For example, to the upper source code a valid command line is: 
+The first task you need to do is to assign to a :hgvideo:`VideoCapture <videocapture>` class its source. You can do this either via the :hgvideo:`constructor <videocapture-videocapture>` or its :hgvideo:`open <videocapture-open>` function. If this argument is an integer then you will bind the class to a camera, a device. The number passed here is the ID of the device, assigned by the operating system. If you have a single camera attached to your system its ID will probably be zero and further ones increasing from there. If the parameter passed to these is a string it will refer to a video file, and the string points to the location and name of the file. For example, to the upper source code a valid command line is:
 
 .. code-block:: bash
 
@@ -46,7 +46,7 @@ We do a similarity check. This requires a reference and a test case video file.
    VideoCapture captUndTst;
    captUndTst.open(sourceCompareWith);
 
-To check if the binding of the class to a video source was successful or not use the :huivideo:`isOpened <video-isopened>` function:
+To check if the binding of the class to a video source was successful or not use the :hgvideo:`isOpened <video-isopened>` function:
 
 .. code-block:: cpp
 
@@ -56,7 +56,7 @@ To check if the binding of the class to a video source was successful or not use
      return -1;
      }
 
-Closing the video is automatic when the objects destructor is called. However, if you want to close it before this you need to call its :huivideo:`release <videocapture-release>` function. The frames of the video are just simple images. Therefore, we just need to extract them from the :huivideo:`VideoCapture <videocapture>` object and put them inside a *Mat* one. The video streams are sequential. You may get the frames one after another by the :huivideo:`read <videocapture-read>` or the overloaded >> operator: 
+Closing the video is automatic when the objects destructor is called. However, if you want to close it before this you need to call its :hgvideo:`release <videocapture-release>` function. The frames of the video are just simple images. Therefore, we just need to extract them from the :hgvideo:`VideoCapture <videocapture>` object and put them inside a *Mat* one. The video streams are sequential. You may get the frames one after another by the :hgvideo:`read <videocapture-read>` or the overloaded >> operator:
 
 .. code-block:: cpp
 
@@ -73,9 +73,9 @@ The upper read operations will leave empty the *Mat* objects if no frame could b
     // exit the program
    }
 
-A read method is made of a frame grab and a decoding applied on that. You may call explicitly these two by using the :huivideo:`grab <videocapture-grab>` and then the :huivideo:`retrieve <videocapture-retrieve>` functions. 
+A read method is made of a frame grab and a decoding applied on that. You may call explicitly these two by using the :hgvideo:`grab <videocapture-grab>` and then the :hgvideo:`retrieve <videocapture-retrieve>` functions.
 
-Videos have many-many information attached to them besides the content of the frames. These are usually numbers, however in some case it may be short character sequences (4 bytes or less). Due to this to acquire these information there is a general function named :huivideo:`get <videocapture-get>` that returns double values containing these properties. Use bitwise operations to decode the characters from a double type and conversions where valid values are only integers. Its single argument is the ID of the queried property. For example, here we get the size of the frames in the reference and test case video file; plus the number of frames inside the reference. 
+Videos have many-many information attached to them besides the content of the frames. These are usually numbers, however in some case it may be short character sequences (4 bytes or less). Due to this to acquire these information there is a general function named :hgvideo:`get <videocapture-get>` that returns double values containing these properties. Use bitwise operations to decode the characters from a double type and conversions where valid values are only integers. Its single argument is the ID of the queried property. For example, here we get the size of the frames in the reference and test case video file; plus the number of frames inside the reference.
 
 .. code-block:: cpp
 
@@ -85,7 +85,7 @@ Videos have many-many information attached to them besides the content of the fr
    cout << "Reference frame resolution: Width=" << refS.width << "  Height=" << refS.height
         << " of nr#: " << captRefrnc.get(CV_CAP_PROP_FRAME_COUNT) << endl;
 
-When you are working with videos you may often want to control these values yourself. To do this there is a :huivideo:`set <videocapture-set>` function. Its first argument remains the name of the property you want to change and there is a second of double type containing the value to be set. It will return true if it succeeds and false otherwise. Good examples for this is seeking in a video file to a given time or frame: 
+When you are working with videos you may often want to control these values yourself. To do this there is a :hgvideo:`set <videocapture-set>` function. Its first argument remains the name of the property you want to change and there is a second of double type containing the value to be set. It will return true if it succeeds and false otherwise. Good examples for this is seeking in a video file to a given time or frame:
 
 .. code-block:: cpp
 
@@ -93,7 +93,7 @@ When you are working with videos you may often want to control these values your
    captRefrnc.set(CV_CAP_PROP_POS_FRAMES, 10); // go to the 10th frame of the video
    // now a read operation would read the frame at the set position
 
-For properties you can read and change look into the documentation of the :huivideo:`get <videocapture-get>` and :huivideo:`set <videocapture-set>` functions. 
+For properties you can read and change look into the documentation of the :hgvideo:`get <videocapture-get>` and :hgvideo:`set <videocapture-set>` functions.
 
 
 Image similarity - PSNR and SSIM

modules/contrib/doc/contrib.rst

@@ -10,3 +10,4 @@ The module contains some recently added functionality that has not been stabiliz
     stereo
     FaceRecognizer Documentation <facerec/index>
     Retina Documentation <retina/index>
+    openfabmap

modules/contrib/doc/openfabmap.rst

-openFABMAP
+OpenFABMAP
 ========================================
 
 .. highlight:: cpp

modules/gpu/doc/feature_detection_and_description.rst

@@ -485,7 +485,7 @@ The class ``BruteForceMatcher_GPU_base`` has an interface similar to the class :
 
 
 gpu::BruteForceMatcher_GPU_base::match
--------------------------------------
+--------------------------------------
 Finds the best match for each descriptor from a query set with train descriptors.
 
 .. ocv:function:: void gpu::BruteForceMatcher_GPU_base::match(const GpuMat& query, const GpuMat& train, std::vector<DMatch>& matches, const GpuMat& mask = GpuMat())
@@ -501,7 +501,7 @@ Finds the best match for each descriptor from a query set with train descriptors
 
 
 gpu::BruteForceMatcher_GPU_base::makeGpuCollection
--------------------------------------------------
+--------------------------------------------------
 Performs a GPU collection of train descriptors and masks in a suitable format for the :ocv:func:`gpu::BruteForceMatcher_GPU_base::matchCollection` function.
 
 .. ocv:function:: void gpu::BruteForceMatcher_GPU_base::makeGpuCollection(GpuMat& trainCollection, GpuMat& maskCollection, const vector<GpuMat>& masks = std::vector<GpuMat>())
@@ -509,7 +509,7 @@ Performs a GPU collection of train descriptors and masks in a suitable format fo
 
 
 gpu::BruteForceMatcher_GPU_base::matchDownload
----------------------------------------------
+----------------------------------------------
 Downloads matrices obtained via :ocv:func:`gpu::BruteForceMatcher_GPU_base::matchSingle` or :ocv:func:`gpu::BruteForceMatcher_GPU_base::matchCollection` to vector with :ocv:class:`DMatch`.
 
 .. ocv:function:: static void gpu::BruteForceMatcher_GPU_base::matchDownload(const GpuMat& trainIdx, const GpuMat& distance, std::vector<DMatch>&matches)
@@ -529,7 +529,7 @@ Converts matrices obtained via :ocv:func:`gpu::BruteForceMatcher_GPU_base::match
 
 
 gpu::BruteForceMatcher_GPU_base::knnMatch
-----------------------------------------
+-----------------------------------------
 Finds the ``k`` best matches for each descriptor from a query set with train descriptors.
 
 .. ocv:function:: void gpu::BruteForceMatcher_GPU_base::knnMatch(const GpuMat& query, const GpuMat& train, std::vector< std::vector<DMatch> >&matches, int k, const GpuMat& mask = GpuMat(), bool compactResult = false)
@@ -561,7 +561,7 @@ The third variant of the method stores the results in GPU memory.
 
 
 gpu::BruteForceMatcher_GPU_base::knnMatchDownload
-------------------------------------------------
+-------------------------------------------------
 Downloads matrices obtained via :ocv:func:`gpu::BruteForceMatcher_GPU_base::knnMatchSingle` or :ocv:func:`gpu::BruteForceMatcher_GPU_base::knnMatch2Collection` to vector with :ocv:class:`DMatch`.
 
 .. ocv:function:: void gpu::BruteForceMatcher_GPU_base::knnMatchDownload(const GpuMat& trainIdx, const GpuMat& distance, std::vector< std::vector<DMatch> >&matches, bool compactResult = false)
@@ -585,7 +585,7 @@ If ``compactResult`` is ``true`` , the ``matches`` vector does not contain match
 
 
 gpu::BruteForceMatcher_GPU_base::radiusMatch
--------------------------------------------
+--------------------------------------------
 For each query descriptor, finds the best matches with a distance less than a given threshold.
 
 .. ocv:function:: void gpu::BruteForceMatcher_GPU_base::radiusMatch(const GpuMat& query, const GpuMat& train, std::vector< std::vector<DMatch> >&matches, float maxDistance, const GpuMat& mask = GpuMat(), bool compactResult = false)
@@ -619,7 +619,7 @@ The third variant of the method stores the results in GPU memory and does not st
 
 
 gpu::BruteForceMatcher_GPU_base::radiusMatchDownload
----------------------------------------------------
+----------------------------------------------------
 Downloads matrices obtained via :ocv:func:`gpu::BruteForceMatcher_GPU_base::radiusMatchSingle` or :ocv:func:`gpu::BruteForceMatcher_GPU_base::radiusMatchCollection` to vector with :ocv:class:`DMatch`.
 
 .. ocv:function:: void gpu::BruteForceMatcher_GPU_base::radiusMatchDownload(const GpuMat& trainIdx, const GpuMat& distance, const GpuMat& nMatches, std::vector< std::vector<DMatch> >&matches, bool compactResult = false)

modules/gpu/doc/image_processing.rst

@@ -886,7 +886,7 @@ gpu::FastNonLocalMeansDenoising
 The class implements fast approximate Non Local Means Denoising algorithm.
 
 gpu::FastNonLocalMeansDenoising::simpleMethod()
--------------------------------------
+-----------------------------------------------
 Perform image denoising using Non-local Means Denoising algorithm http://www.ipol.im/pub/algo/bcm_non_local_means_denoising with several computational optimizations. Noise expected to be a gaussian white noise
 
 .. ocv:function:: void gpu::FastNonLocalMeansDenoising::simpleMethod(const GpuMat& src, GpuMat& dst, float h, int search_window = 21, int block_size = 7, Stream& s = Stream::Null())
@@ -910,7 +910,7 @@ This function expected to be applied to grayscale images. For colored images loo
     :ocv:func:`fastNlMeansDenoising`
 
 gpu::FastNonLocalMeansDenoising::labMethod()
--------------------------------------
+--------------------------------------------
 Modification of ``FastNonLocalMeansDenoising::simpleMethod`` for color images
 
 .. ocv:function:: void gpu::FastNonLocalMeansDenoising::labMethod(const GpuMat& src, GpuMat& dst, float h_luminance, float h_color, int search_window = 21, int block_size = 7, Stream& s = Stream::Null())

modules/highgui/doc/reading_and_writing_images_and_video.rst

@@ -75,11 +75,11 @@ Loads an image from a file.
 
     :param flags: Flags specifying the color type of a loaded image:
     
-        * 1 - 
-        * CV_LOAD_IMAGE_ANYDEPTH - 
-        CV_LOAD_IMAGE_COLOR
-        CV_LOAD_IMAGE_GRAYSCALE
+        * CV_LOAD_IMAGE_ANYDEPTH - If set, return 16-bit/32-bit image when the input has the corresponding depth, otherwise convert it to 8-bit.
         
+        * CV_LOAD_IMAGE_COLOR - If set, always convert image to the color one
+
+        * CV_LOAD_IMAGE_GRAYSCALE - If set, always convert image to the grayscale one
 
         * **>0**  Return a 3-channel color image.
             .. note:: In the current implementation the alpha channel, if any, is stripped from the output image. Use negative value if you need the alpha channel.

modules/ml/doc/statistical_models.rst

@@ -156,7 +156,7 @@ CvStatModel::predict
 --------------------
 Predicts the response for a sample.
 
-.. ocv:function:: float CvStatModel::predict( const Mat& sample[, <prediction_params>] ) const
+.. ocv:function:: float CvStatModel::predict( const Mat& sample, <prediction_params> ) const
 
 The method is used to predict the response for a new sample. In case of a classification, the method returns the class label. In case of a regression, the method returns the output function value. The input sample must have as many components as the ``train_data`` passed to ``train`` contains. If the ``var_idx`` parameter is passed to ``train``, it is remembered and then is used to extract only the necessary components from the input sample in the method ``predict``.
 

modules/ocl/doc/data_structures.rst

+Data Structures
+=============================
+
+.. ocv:class:: 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);
+
+
+            //! 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;
+
+
+            //! 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 the oclMatrix content to "m".
+            // It calls m.create(this->size(), this->type()).
+            // It supports any data type
+            void copyTo( oclMat &m ) const;
+            //! copies those oclMatrix elements to "m" that are marked with non-zero mask elements.
+            //It supports 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4
+            void copyTo( oclMat &m, const oclMat &mask ) const;
+            //! converts oclMatrix to another datatype with optional scalng. See cvConvertScale.
+            //It supports 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4
+            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
+            //It supports 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4
+            oclMat &operator = (const Scalar &s);
+            //! sets some of the oclMatrix elements to s, according to the mask
+            //It supports 8UC1 8UC4 32SC1 32SC4 32FC1 32FC4
+            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);
+            //! 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;
+
+            //! 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;
+
+            //! returns pointer to y-th row
+            uchar *ptr(int y = 0);
+            const uchar *ptr(int y = 0) const;
+
+            //! template version of the above method
+            template<typename _Tp> _Tp *ptr(int y = 0);
+            template<typename _Tp> const _Tp *ptr(int y = 0) 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
+
+add clCxt for oclMat
+
+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
\ No newline at end of file

modules/ocl/doc/introduction.rst

@@ -6,14 +6,39 @@ OpenCL Module Introduction
 General Information
 -------------------
 
-The OpenCV OCL module is a set of classes and functions to utilize OpenCL compatible device. It should support any device compatible with OpenCL 1.1. The module includes utility functions, low-level vision primitives, and a few high-level algorithms ready to be used in the end-user applications.
+The OpenCV OCL module is a set of classes and functions to utilize OpenCL compatible device. In theroy, it supports any OpenCL 1.1 compatible device, but we only test it on AMD's, Intel's and NVIDIA's GPU at this stage. The compatibility, correctness and performance on CPU is not guaranteed. 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 advangtage of OCL whereas the high-level functionality includes some state-of-the-art algorithms(such as surf detector, face detector) ready to be used by the application developers.
 
-The OpenCV OCL module is designed as a host-level API plus device-level kernels. The device-level kernels are converted to text string and are compiled at runtime, so it need OpenCL runtime support. To correctly run the OpenCV OCL module, make sure you have OpenCL runtime provided by your device vendor, which is device driver normally.
+The OpenCV OCL module is designed as a host-level API plus device-level kernels. The device-level kernels are collected as strings at OpenCV compile time and are compiled at runtime, so it need OpenCL runtime support. To correctly build the OpenCV OCL module, make sure you have OpenCL SDK provided your device vendor. To correctly run the OpenCV OCL module, make sure you have OpenCL runtime provided by your device vendor, which is device driver normally.
 
-The OpenCV OCL module is designed for ease of use and does not require any knowledge of OpenCL. Though, such a knowledge will certainly be useful to handle non-trivial cases or achieve the highest performance. It is helpful to understand the cost of various operations, what the module does, what the preferred data formats are, and so on. Since there is data transfer between OpenCL host and OpenCL device, for better performance it's recommended to copy data once to the OpenCL host memory (i.e. copy ``cv::Mat`` to ``cv::ocl::OclMat``), then call several ``cv::ocl`` functions and then copy the result back to CPU memory, rather than do forward and backward transfer for each OCL function.
+The OpenCV OCL module is designed for ease of use and does not require any knowledge of OpenCL. Though, such a knowledge will certainly be useful to handle non-trivial cases or achieve the highest performance. It is helpful to understand the cost of various operations, what the OCL does, what the preferred data formats are, and so on. Since there is data transfer between OpenCL host and OpenCL device, for better performance it's recommended to copy data once to the OpenCL host memory (i.e. copy ``cv::Mat`` to ``cv::ocl::OclMat``), then call several ``cv::ocl`` functions and then copy the result back to CPU memory, rather than do forward and backward transfer for each OCL function.
 
-To enable OCL support, configure OpenCV using CMake with the option ``WITH\_OPENCL=ON``. If the option is passed and if OpenCL SDK is installed (e.g. on MacOSX it's always the case), the full-featured OpenCV OCL module will be built. Otherwise, the module will not be built.
+To enable OCL support, configure OpenCV using CMake with WIHT\_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, WIHT\_OPENCLAMDBLAS=ON.
 
-Right now, the user should define the ``cv::ocl::Info`` class in the application and call ``cv::ocl::getDevice`` before any ``cv::ocl::<func>``. This operation initialize OpenCL runtime and set the first found device as computing device. If there is more than one device and you want to use non-default device, you should call ``cv::ocl::setDevice``.
+Right now, the user should define the cv::ocl::Info class in the application and call cv::ocl::getDevice before any cv::ocl::func. This operation initialize OpenCL runtime and set the first found device as computing device. If there are more than one device and you want to use undefault device, you can call cv::ocl::setDevice then.
 
-In the current version, all the threads share the same context and device so the multi-devices are not supported. This is to be fixed in future releases.
+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
+-------------------
+
+This section descripe the design details of ocl module for who are interested in the detail of this module or want to contribute this module. User who isn't interested the details, can safely ignore it.
+
+1. OpenCL version should be larger than 1.1 with FULL PROFILE.
+
+2. There's only one OpenCL context and commandqueue and generated as a singleton. So now it only support one device with single commandqueue.
+
+3. All the functions use 256 as its workgroup size if possible, so the max work group size of the device must larger than 256.
+
+4. If the device support double, we will use double in kernel if OpenCV cpu version use double, otherwise, we use float instead.
+
+5. The oclMat use buffer object, not image object.
+
+6. 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.
+
+7. All the matrix in oclMat is aligned in column(now the alignment factor is 32 byte). It means, if a matrix is n columns m rows with the element size x byte, we will assign ALIGNMENT(x*n) bytes for each column with the last ALIGNMENT(x*n) - x*n bytes unused, so there's small holes after each column if its size is not the multiply of ALIGN.
+
+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 ocl/src/kernels/ with the extension ".cl". ALL the kernel files are transformed to pure characters at compilation time in kernels.cpp, and the file name without extension is the name of the characters.

modules/ocl/doc/matrix_reductions.rst

+Matrix Reductions
+=============================
+
+.. highlight:: cpp
+
+ocl::countNonZero
+------------------
+Returns the number of non-zero elements in src
+
+.. ocv:function:: int countNonZero(const oclMat &src)
+
+    :param src: Single-channel array
+
+Counts non-zero array elements.
+
+ocl::minMax
+------------------
+Returns void
+
+.. ocv:function:: void 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 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::Sum
+------------------
+Returns the sum of matrix elements for each channel
+
+.. ocv:function:: Scalar sum(const oclMat &m)
+
+    :param m: The Source image of all depth
+
+Counts the sum of matrix elements for each channel.
+
+ocl::sqrSum
+------------------
+Returns the squared sum of matrix elements for each channel
+
+.. ocv:function:: Scalar sqrSum(const oclMat &m)
+
+    :param m: The Source image of all depth
+
+Counts the squared sum of matrix elements for each channel.
\ No newline at end of file

modules/ocl/doc/object_detection.rst

+Object Detection
+=============================
+
+.. highlight:: cpp
+
+ocl::oclCascadeClassifier
+-------------------------
+
+Cascade classifier class used for object detection. Supports HAAR cascade classifier  in the form of cross link ::
+
+    class CV_EXPORTS OclCascadeClassifier : public  cv::CascadeClassifier
+    {
+    public:
+          OclCascadeClassifier() {};
+          ~OclCascadeClassifier() {};
+           CvSeq *oclHaarDetectObjects(oclMat &gimg, CvMemStorage *storage,
+                                      double scaleFactor,int minNeighbors,
+                                      int flags, CvSize minSize = cvSize(0, 0),
+                                      CvSize maxSize = cvSize(0, 0));
+    };
+
+ocl::oclCascadeClassifier::oclHaarDetectObjects
+------------------------------------------------------
+Returns the detected objects by a list of rectangles
+
+.. ocv:function:: CvSeq *OclCascadeClassifier::oclHaarDetectObjects(oclMat &gimg, CvMemStorage *storage, double scaleFactor,int minNeighbors, int flags, CvSize minSize = cvSize(0, 0), CvSize maxSize = cvSize(0, 0))
+
+    :param image:  Matrix of type CV_8U containing an image where objects should be detected.
+
+    :param imageobjectsBuff: Buffer to store detected objects (rectangles). If it is empty, it is allocated with the defaultsize. If not empty, the function searches not more than N  objects, where N = sizeof(objectsBufers data)/sizeof(cv::Rect).
+
+    :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 minSize: Minimum possible object size. Objects smaller than that are ignored.
+
+Detects objects of different sizes in the input image,only tested for face detection now. The function returns the number of detected objects.
+
+ocl::MatchTemplateBuf
+---------------------
+.. ocv:class:: 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:class:`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`
+
+
+ocl::SURF_OCL
+-------------
+.. ocv:class:: ocl::SURF_OCL
+
+Class used for extracting Speeded Up Robust Features (SURF) from an image. ::
+
+    class SURF_OCL
+    {
+    public:
+        enum KeypointLayout
+        {
+            X_ROW = 0,
+            Y_ROW,
+            LAPLACIAN_ROW,
+            OCTAVE_ROW,
+            SIZE_ROW,
+            ANGLE_ROW,
+            HESSIAN_ROW,
+            ROWS_COUNT
+        };
+
+        //! the default constructor
+        SURF_OCL();
+        //! the full constructor taking all the necessary parameters
+        explicit SURF_OCL(double _hessianThreshold, int _nOctaves=4,
+             int _nOctaveLayers=2, bool _extended=false, float _keypointsRatio=0.01f, bool _upright = false);
+
+        //! returns the descriptor size in float's (64 or 128)
+        int descriptorSize() const;
+
+        //! upload host keypoints to device memory
+        void uploadKeypoints(const vector<KeyPoint>& keypoints,
+            oclMat& keypointsocl);
+        //! download keypoints from device to host memory
+        void downloadKeypoints(const oclMat& keypointsocl,
+            vector<KeyPoint>& keypoints);
+
+        //! download descriptors from device to host memory
+        void downloadDescriptors(const oclMat& descriptorsocl,
+            vector<float>& descriptors);
+
+        void operator()(const oclMat& img, const oclMat& mask,
+            oclMat& keypoints);
+
+        void operator()(const oclMat& img, const oclMat& mask,
+            oclMat& keypoints, oclMat& descriptors,
+            bool useProvidedKeypoints = false);
+
+        void operator()(const oclMat& img, const oclMat& mask,
+            std::vector<KeyPoint>& keypoints);
+
+        void operator()(const oclMat& img, const oclMat& mask,
+            std::vector<KeyPoint>& keypoints, oclMat& descriptors,
+            bool useProvidedKeypoints = false);
+
+        void operator()(const oclMat& img, const oclMat& mask,
+            std::vector<KeyPoint>& keypoints,
+            std::vector<float>& descriptors,
+            bool useProvidedKeypoints = false);
+
+        void releaseMemory();
+
+        // SURF parameters
+        double hessianThreshold;
+        int nOctaves;
+        int nOctaveLayers;
+        bool extended;
+        bool upright;
+
+        //! max keypoints = min(keypointsRatio * img.size().area(), 65535)
+        float keypointsRatio;
+
+        oclMat sum, mask1, maskSum, intBuffer;
+
+        oclMat det, trace;
+
+        oclMat maxPosBuffer;
+    };
+
+
+The class ``SURF_OCL`` implements Speeded Up Robust Features descriptor. There is a fast multi-scale Hessian keypoint detector that can be used to find the keypoints (which is the default option). But the descriptors can also be computed for the user-specified keypoints. Only 8-bit grayscale images are supported.
+
+The class ``SURF_OCL`` can store results in the GPU and CPU memory. It provides functions to convert results between CPU and GPU version ( ``uploadKeypoints``, ``downloadKeypoints``, ``downloadDescriptors`` ). The format of CPU results is the same as ``SURF`` results. GPU results are stored in ``oclMat``. The ``keypoints`` matrix is :math:`\texttt{nFeatures} \times 7` matrix with the ``CV_32FC1`` type.
+
+* ``keypoints.ptr<float>(X_ROW)[i]`` contains x coordinate of the i-th feature.
+* ``keypoints.ptr<float>(Y_ROW)[i]`` contains y coordinate of the i-th feature.
+* ``keypoints.ptr<float>(LAPLACIAN_ROW)[i]``  contains the laplacian sign of the i-th feature.
+* ``keypoints.ptr<float>(OCTAVE_ROW)[i]`` contains the octave of the i-th feature.
+* ``keypoints.ptr<float>(SIZE_ROW)[i]`` contains the size of the i-th feature.
+* ``keypoints.ptr<float>(ANGLE_ROW)[i]`` contain orientation of the i-th feature.
+* ``keypoints.ptr<float>(HESSIAN_ROW)[i]`` contains the response of the i-th feature.
+
+The ``descriptors`` matrix is :math:`\texttt{nFeatures} \times \texttt{descriptorSize}` matrix with the ``CV_32FC1`` type.
+
+The class ``SURF_OCL`` uses some buffers and provides access to it. All buffers can be safely released between function calls.
+
+.. seealso:: :ocv:class:`SURF`
\ No newline at end of file

modules/ocl/doc/ocl.rst

@@ -6,15 +6,13 @@ ocl. OpenCL-accelerated Computer Vision
     :maxdepth: 1
 
     introduction
-    structures_and_functions
-..    initalization_and_information
-..    data_structures
-..    operations_on_matrices
-..    per_element_operations
-..    image_processing
-..    matrix_reductions
-..    object_detection
-..    feature_detection_and_description
-..    image_filtering
+    structures_and_utility_functions
+    data_structures
+    operations_on_matrices
+    matrix_reductions
+    image_filtering
+    image_processing
+    object_detection
+    feature_detection_and_description
 ..    camera_calibration_and_3d_reconstruction
 ..    video

modules/ocl/doc/structures_and_functions.rst → modules/ocl/doc/structures_and_utility_functions.rst

-Data Structures and Functions
-=============================
+Data Structures and Utility Functions
+========================================
 
 .. highlight:: cpp
 
@@ -21,3 +21,38 @@ Returns the list of devices
 
 the function must be called before any other ``cv::ocl`` functions; it initializes ocl runtime.
 
+ocl::setDevice
+------------------
+Returns void
+
+.. ocv:function:: void ocl::setDevice( Info &oclinfo, int devnum = 0 )
+
+    :param oclinfo: Output vector of ``ocl::Info`` structures
+
+    :param devnum: the selected OpenCL device under this platform.
+
+ocl::setBinpath
+------------------
+Returns void
+
+.. ocv:function:: void setBinpath(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.
+
+ocl::getoclContext
+------------------
+Returns the pointer to the opencl context
+
+.. ocv:function:: void *getoclContext()
+
+Thefunction are used to get opencl context so that opencv can interactive with other opencl program.
+
+ocl::getoclCommandQueue
+--------------------------
+Returns the pointer to the opencl command queue
+
+.. ocv:function:: void *getoclCommandQueue()
+
+Thefunction are used to get opencl command queue so that opencv can interactive with other opencl program.
\ No newline at end of file