Syntax/Functions used in the OpenCL-Implemantation of OpenCV - opencv

Question

I try to understand the use of OpenCL within OpenCV but I don´t get it:
This is an example Codepart from orb.cpp where a Kernel with the name ORB_HarrisResponses located in orb.cl is created (propably):
ocl::Kernel hr_ker("ORB_HarrisResponses", ocl::features2d::orb_oclsrc,
format("-D ORB_RESPONSES -D blockSize=%d -D scale_sq_sq=%.12ef -
D HARRIS_K=%.12ff", blockSize, scale_sq_sq, harris_k));
return hr_ker.args(ocl::KernelArg::ReadOnlyNoSize(imgbuf),
ocl::KernelArg::PtrReadOnly(layerinfo),
ocl::KernelArg::PtrReadOnly(keypoints),
ocl::KernelArg::PtrWriteOnly(responses),
nkeypoints).run(1, globalSize, 0, true);
But this isn't the regular OpenCL-Syntax (functions like clCreateKernel ...). Does someone know where I can get a basic understanding of the OpenCV`s OpenCL implementations to answer questions like:
Where is the connection between the "normal" OpenCL and the OpenCV OpenCL?
Where the program is built from the kernel source files？
Where is the function, which creates the kernel explained？
etc
I couldn´t find a document or related questions on the web.
Thanks
Edit: Thanks for answering it helped to understand a few things:
ocl::Kernel hr_ker("ORB_HarrisResponses", ocl::features2d::orb_oclsrc,
format("-D ORB_RESPONSES -D blockSize=%d -D scale_sq_sq=%.12ef -D HARRIS_K=%.12ff", blockSize, scale_sq_sq, harris_k));
In this part the kernel code ORB_HarrisResponses located in orb.cl build within the string ocl::features2d::orb_oclsrc is created as hr_ker (right?).
But what does the format(...) thing do?
if hr_ker.empty() return false;
return hr_ker.args(ocl::KernelArg::ReadOnlyNoSize(imgbuf),
ocl::KernelArg::PtrReadOnly(layerinfo),
ocl::KernelArg::PtrReadOnly(keypoints),
ocl::KernelArg::PtrWriteOnly(responses),
nkeypoints).run(1, globalSize, 0, true);
In this part of the Kernel arguments imgbuf, layerinfo, keypoints are set and output of the kernel is stored in responses.
What is going on with nkeypoints?
Why no ocl::KernelArg infront of this parameter?
The kernel in orb.cl has 7 arguments but only 5 are set, why?
What exactly is returned from return hr_ker.args(...)?

Answer 1

This syntax is kind of internal OpenCV "sugar" to not repeat some common code blocks. Unfortunately there is no good documentation so the only way to learn it is looking through source code and examples.
Some tips for you:
Connection between OpenCL API and opencv are in modules\core\src\ocl.cpp (see Kernel, Kernel::Impl, Program, ProgramSource, KernelArg classes).
Source code of kernels stored in *.cl files (for example ORB kernels are in modules\features2d\src\opencl\orb.cl file). On module building code of kernels are copying to auto-generated cpp file (for example opencl_kernels_features2d.cpp) and code can be accessed by ocl::features2d::orb_oclsrc.
To use opencl implementation in opencv you need to pass to function cv::UMat instead of regular cv::Mat (see CV_OCL_RUN_ macro and cv::OutputArray::isUMat() method).
Basically all opencl implementation inside opencv does the following:
Defines kernel parameters, like global size, block size, etc.
Creates cv::ocl::Kernel using string with source code and defined parameters. (If kernel is not created or there is no opencl implementation for specified input parameters processing is passed to regular cpu code).
Pass kernel arguments via cv::ocl::KernelArgs. There is several types of parameters to optimize processing: read-only, write-only, constant, etc.
Run kernel.
So for end user using opencl implementation is transparent. If something goes wrong processing is switched to cpu implementation.
Let's discuss following code snippet:
return hr_ker.args(ocl::KernelArg::ReadOnlyNoSize(imgbuf),
ocl::KernelArg::PtrReadOnly(layerinfo),
ocl::KernelArg::PtrReadOnly(keypoints),
ocl::KernelArg::PtrWriteOnly(responses),
nkeypoints).run(1, globalSize, 0, true);
and ocl function declaration:
ORB_HarrisResponses(__global const uchar* imgbuf, int imgstep, int imgoffset0,
__global const int* layerinfo, __global const int* keypoints,
__global float* responses, int nkeypoints )
nkeypoints is integer, so no need to wrap it to ocl::KernelArg. It will be passed directly to kernel.
ocl::KernelArg::ReadOnlyNoSize actually expands to three parameters: imgbuf, imgstep, imgoffset0.
Other kernel arguments doesn't expand, so it represent single parameter.
hr_ker.args returns reference to cv::ocl::Kernel so you may use following construction: kernel.args(...).run(...).
Some useful links:
cv::format documentation. It works like boost::format.
Hope it will help.