/*! \page TUTO_INTEGRATION_PRJ Using GpuCV into your project
* \section TUTO_INTEGRATION_PRJ__SCT_INTRO Intro
* \par "PRE-REQUIS"
<ul>
<li>none</li>
</ul>
\sa
\author Yannick Allusse
\version GpuCV v1.0.0 rev 600
\note Turorial tag: <b>TUTO_INTEGRATION_PRJ_TAG</b>
*
<br>In this tutorial, we will describe how to use GpuCV accelerated operators into your existing OpenCV application. We will cover two integration modes:
<ol>
<li>"easy-way" based on GpuCV Switch: minor code changes will allow your application to take benefit of GPU acceleration based on the plugins available on your system.</li>
<li>"manual-way" based on manul GpuCV plugins usage: you will manually update you code where it will benefit the most of the GPU acceleration, you need to choose the right implementation to call based on available one.</li>
</ol>
<br>
<br>We will write a simple OpenCV application step-by-step and see differences between "OpenCV-native"/"GpuCV-Switch"/"GpuCV-Manual" implementation.
*\section TUTO_INTEGRATION_PRJ__STP1__MAIN_FILE The Main.cpp file
\note All modified lines will be noticed by a !!GCV!! flag.
The following table shows the two possible implementation of GpuCV into a simple OpenCV example (addition).
<br>
<table border="1" width="100%">
<tr bgcolor="#EEEEEE"><td colspan="4" align="center"><b>Main.cpp file</b></tr>
<tr bgcolor="#EEEEEE">
<td></td>
<td width="30%" bgcolor="#FFFFEE">OpenCV-Native</td>
<td bgcolor="#DDEEFF">GpuCV-Switch</td>
<td width="30%" bgcolor="#EEFFFF">GpuCV-Manual</td>
</tr>
<tr>
<td><b>Headers part</b>
<td bgcolor="#FFFFEE">
\code
//include standard headers
#include <stdio.h>
//include OpenCV headers
#include <cv.h>
#include <cxcore.h>
#include <highgui.h>
\endcode
</td>
<td bgcolor="#DDEEFF">
\code
//include standard headers
#include <stdio.h>
//include GpuCV-switch headers
#include <cv_switch.h>//GCV
#include <cxcore_switch.h>//GCV
#include <highgui_switch.h>//GCV
\endcode
</td>
<td bgcolor="#EEFFFF">
\code
//include standard headers
#include <stdio.h>
//include GpuCV-GLSL headers
#include <cvg.h>//GCV
#include <cxcoreg.h>//GCV
#include <highguig.h>//GCV
//...additionnal plugins can be included
\endcode
</td>
</tr>
<tr>
<td><b>main() - libraries init part</b>
<td bgcolor="#FFFFEE">
\code
int main(int argc, char** argv)
{
//nothing to init...
\endcode
</td>
<td bgcolor="#DDEEFF">
\code
int main(int argc, char** argv)
{
//init GpuCV-switch
//first parameter says to init OpenGL context
//second parameter says ...
//we are in single thread application
cvgswInit(true, false); //GCV
\endcode
</td>
<td bgcolor="#EEFFFF">
\code
int main(int argc, char** argv)
{
//init GpuCV-GLSL
//first parameter says to init OpenGL context
//second parameter says we are in single thread application
cvgInit(true, false);//GCV
\endcode
</td>
</tr>
<tr>
<td><b>main() - data init part</b>
<td bgcolor="#FFFFEE">
\code
IplImage *Img1 = cvCreateImage(cvSize(256,256), IPL_DEPTH_8U, 3);
IplImage *Img2 = cvCreateImage(cvSize(256,256), IPL_DEPTH_8U, 3);
IplImage *Dst = cvCreateImage(cvGetSize(Img1), Img1->depth,
Img1->nChannels);
cvSet(Img1, cvScalar(100,0,0,0),NULL);
cvSet(Img2, cvScalar(0,100,0,0),NULL);
cvSet(Dst, cvScalar(0,0,0,0),NULL);
\endcode
</td>
<td bgcolor="#DDEEFF">
NO CHANGE
</td>
<td bgcolor="#EEFFFF">
\code
//add the 'g' prefix to call GpuCV GLSL function
IplImage *Img1 = cvgCreateImage(cvSize(256,256), IPL_DEPTH_8U, 3);//GCV
IplImage *Img2 = cvgCreateImage(cvSize(256,256), IPL_DEPTH_8U, 3);//GCV
IplImage *Dst = cvgCreateImage(cvGetSize(Img1), Img1->depth,
Img1->nChannels);//GCV
//add the 'g' prefix to call GpuCV GLSL function
cvgSet(Img1, cvScalar(100,0,0,0),NULL);//GCV
cvgSet(Img2, cvScalar(0,100,0,0),NULL);//GCV
cvgSet(Dst, cvScalar(0,0,0,0),NULL);//GCV
\endcode
</td>
</tr>
<tr>
<td><b>main() - process data and show result</b>
<td bgcolor="#FFFFEE">
\code
cvAdd(Img1, Img2, Dst, NULL);
cvNamedWindow("Result", 1);
cvShowImage("Result", Dst);
\endcode
</td>
<td bgcolor="#DDEEFF">
NO CHANGE
</td>
<td bgcolor="#EEFFFF">
\code
//add the 'g' prefix to call GpuCV GLSL function
cvgAdd(Img1, Img2, Dst, NULL);//GCV
cvNamedWindow("Result", 1);
cvgShowImage("Result", Dst);//GCV
cvWaitKey(0);
\endcode
</td>
</tr>
<tr>
<td><b>main() - process data and show result</b>
<td bgcolor="#FFFFEE">
\code
//release data
cvReleaseImage(&Img1);
cvReleaseImage(&Img2);
cvReleaseImage(&Dst);
//release windows
cvDestroyWindow("Result");
return 0;
}
\endcode
</td>
<td bgcolor="#DDEEFF">
NO CHANGE
</td>
<td bgcolor="#EEFFFF">
\code
//add the 'g' prefix to call GpuCV GLSL function
//release data
cvgReleaseImage(&Img1);//GCV
cvgReleaseImage(&Img2);//GCV
cvgReleaseImage(&Dst);//GCV
//release windows
cvDestroyWindow("Result");
return 0;
}
\endcode
</td>
</tr>
</table>
*\section TUTO_INTEGRATION_PRJ__STP2__PROJECT_FILE The project file
We now have a main.cpp file ready to compile, the next step is to create/update the project/makefiles.
<br>
<table border="1" width="100%">
<tr bgcolor="#EEEEEE"><td colspan="4" align="center"><b>project file</b></tr>
<tr bgcolor="#EEEEEE">
<td ></td>
<td width="30%" bgcolor="#FFFFEE">OpenCV-Native</td>
<td width="30%" bgcolor="#DDEEFF">GpuCV-Switch</td>
<td width="30%" bgcolor="#EEFFFF">GpuCV-Manual</td>
</tr>
<tr bgcolor="#EEEEEE">
<td align="center"><b>Include path</b></tr>
<td bgcolor="#FFFFEE">
\code
OPENCV_PATH\include
\endcode
Under Linux:
\code
INCLUDES += -IOPENCV_PATH/include
\endcode
</td>
<td bgcolor="#DDEEFF">
\code
OPENCV_PATH\include
GPUCV_PATH\include
GPUCV_PATH\src\plugin\
\endcode
Under Linux:
\code
INCLUDES += -IOPENCV_PATH/include
INCLUDES += -IGPUCV_PATH/include
INCLUDES += -IGPUCV_PATH/src/plugin/
\endcode
</td>
<td bgcolor="#EEFFFF">
Under Windows:
\code
OPENCV_PATH\include
GPUCV_PATH\include
GPUCV_PATH\src\plugin\
\endcode
Under Linux:
\code
INCLUDES += -IOPENCV_PATH/include
INCLUDES += -IGPUCV_PATH/include
INCLUDES += -IGPUCV_PATH/src/plugin/
\endcode
</td>
</tr>
<tr bgcolor="#EEEEEE">
<td align="center"><b>Libraries path</b></tr>
<td bgcolor="#FFFFEE">
Under Windows:
\code
OPENCV_PATH\lib
\endcode
Under Linux:
\code
LIBS += -LOPENCV_PATH/lib
\endcode
</td>
<td bgcolor="#DDEEFF">
Under Windows:
\code
OPENCV_PATH\lib
GPUCV_PATH\lib\windows-vs2008\[x32/x64]\[Debug|Release]\
\endcode
Under Linux:
\code
LIBS += -LOPENCV_PATH/lib
LIBS += -LGPUCV_PATH/lib/linux-gmake/[x32/x64]/[Debug|Release]/
\endcode
</td>
<td bgcolor="#EEFFFF">
Under Windows:
\code
OPENCV_PATH\lib
GPUCV_PATH\lib\windows-vs2008\[x32/x64]\[Debug|Release]\
\endcode
Under Linux:
\code
LIBS += -LOPENCV_PATH/lib
LIBS += -LGPUCV_PATH/lib/linux-gmake/[x32/x64]/[Debug|Release]/
\endcode
</td>
</tr>
<tr bgcolor="#EEEEEE">
<td align="center"><b>Libraries</b></tr>
<td bgcolor="#FFFFEE">
Under Windows:
\code
cv$(OPENCV_VERSION).lib
cxcore$(OPENCV_VERSION).lib
cvaux$(OPENCV_VERSION).lib
highgui$(OPENCV_VERSION).lib
\endcode
Under Linux:
\code
LIBS += -lcv -lcxcore -lcvaux -lhighgui
\endcode
</td>
<td bgcolor="#DDEEFF">
Under windows:
\code
cv$(OPENCV_VERSION).lib
cxcore$(OPENCV_VERSION).lib
cvaux$(OPENCV_VERSION).lib
highgui$(OPENCV_VERSION).lib
GPUCVSwitch32.lib
cxcore_switch32.lib
cv_switch32.lib
highgui_switch32.lib
\endcode
Under Linux:
\code
LIBS += -lcv -lcxcore -lcvaux -lhighgui
LIBS += -lGPUCVSwitch32 -lcxcore_switch32
LIBS += -lcv_switch32 -lhighgui_switch32
\endcode
</td>
<td bgcolor="#EEFFFF">
Under Windows:
\code
cv$(OPENCV_VERSION).lib
cxcore$(OPENCV_VERSION).lib
cvaux$(OPENCV_VERSION).lib
highgui$(OPENCV_VERSION).lib
cxcoreg32.lib
cvg32.lib
highguig32.lib
\endcode
Under Linux:
\code
LIBS += -lcv -lcxcore -lcvaux -lhighgui
LIBS += -lcxcoreg32 -lcvg32 -lcvauxg32 -lhighguig32
\endcode
</td>
</tr>
</table>
\note The possible suffixes for GpuCV libraries are [32|32D|64|64D] depending on the architecture and Debug/Release mode.
\note Replace GPUCV_PATH/OPENCV_PATH/OPENCV_VERSION by the corresponding values.
<br><br><br><br><br><br>
<br><br><br><br><br><br>
<br><br><br><br><br><br>
We will see all required porting stepsuse the <b>morphology</b> sample supplied with OpenCV.
The major differences are in the way you call 'OpenCV like' accelerated operators, see \ref TUTO_INTEGRATION_PRJ__STP3__CODE_CHANGE.
<ol>
<li>\ref TUTO_INTEGRATION_PRJ__STP1__INCLUDE</li>
<li>\ref TUTO_INTEGRATION_PRJ__STP2__LIBS</li>
<li>\ref TUTO_INTEGRATION_PRJ__STP3__CODE_CHANGE</li>
<li>\ref TUTO_INTEGRATION_PRJ__STP4__EXTRA_FILES</li>
</ol>
\section TUTO_INTEGRATION_PRJ__STP3__NAMING Global naming convention
\par Include files
GpuCV use some naming rules to identify the header files roles, based on OpenCV header files name ($NAME$.h)
<ul>
<li>$NAME$.h: Original OpenCV library header.</li>
<li>$NAME$<b>g</b>.h: GpuCV-GLSL accelerated library header. Contains some cv<b>g</b>*() functions corresponding to OpenCV cv*() functions.</li>
<li>$NAME$<b>gcu</b>.h: GpuCV-CUDA accelerated library header. Contains some cv<b>gCuda</b>*() functions corresponding to OpenCV cv*() functions.</li>
<li>$NAME$<b>_switch</b>.h: GpuCV switch function library header. Contains all cv<b>gsw</b>*() functions corresponding to OpenCV cv*() functions.</li>
<li>$NAME$<b>_switch_wrapper</b>.h: GpuCV switch function wrapper library header. Contains all cvgsw*() wrapping definitions to map with all OpenCV cv*() functions.</li>
</ul>
<br>Here is an example of all the function declarations related to the OpenCV function cvAdd():
\code
//cxcore.h
void cvAdd(const CvArr* src1, const CvArr* src2, CvArr* dst, const CvArr* mask CV_DEFAULT(NULL) );
//cxcoreg.h
void cvgAdd(CvArr* src1, CvArr* src2, CvArr* dst, CvArr* mask CV_DEFAULT(NULL) );
//cxcoregcu.h
void cvgCudaAdd(CvArr* src1, CvArr* src2, CvArr* dst, CvArr* mask CV_DEFAULT(NULL) );
//cxcore_switch.h
void cvgswAdd(CvArr* src1, CvArr* src2, CvArr* dst, CvArr* mask CV_DEFAULT(NULL) );
//cxcore_switch_wrapper.h
#define cvAdd cvgswAdd
\endcode
\par Using GpuCV auto-switch mechanism
Include all $NAME$<b>_switch_wrapper</b>.h files corresponding to your current OpenCV files.
<br>NOTE: By using the switch mechanism you do not need to include GpuCV-GLSL or GpuCV-Cuda headers.
\par Using GpuCV manualy
You have the choice to use the GLSL, CUDA or both versions into your applications. Use the corresponding suffix <b>g</b> or <b>gcu</b> to include the corresponding libraries.
\section TUTO_INTEGRATION_PRJ__STP2__LIBS Library files
GpuCV uses the naming convention described in previous section for its libraries files using the <b>g</b>/<b>gcu</b>/<b>_switch</b> suffixes.
Here are some list of files that you might have to link with:
<ul>
<li>Required libs:
<ul>
<li>cv, cxcore, cvaux, highgui for main OpenCV libraries.</li>
<li>opengl32, glu32, glut32, glew for all OpenGL libraries.</li>
<li>SugoiTools, SugoiTracer</li>
<li>GPUCVHardware, GPUCVTexture, GPUCVCore, GPUCVGpuCV for GpuCV framework</li>
</ul>
</li>
<li>Optional libs:
<ul>
<li>cxcoreg, cvg, highguig for GpuCV-GLSL libraries.</li>
<li>cxcoregcu, cvgcu for GpuCV-CUDA libraries.</li>
<li>cxcore_switch, cv_switch, highgui_switch for GpuCV-Switch libraries.</li>
</ul>
</li>
</ul>
\note By using the switch mechanism you do not need to link with GpuCV-GLSL or GpuCV-Cuda plugins.
\note Even if you do not link with all the libraries, they must remain reachable in your $PATH.
\section TUTO_INTEGRATION_PRJ__STP3__CODE_CHANGE Code modifications
\subsection TUTO_INTEGRATION_PRJ__STP3__CODE_CHANGE__INIT Initialization
In order to use GpuCV function, you must initialize the libraries by calling cvgInit() at the beginning of your application. Two parameters can be used to specify options (see cvgInit() for details):
* InitGLContext: If set to true, GpuCV will initialize an OpenGL context and GLUT, default is TRUE.
* isMultiThread: If set to true, GpuCV will run in a compatibility mode for multi-threaded application, default is FALSE.
\subsection TUTO_INTEGRATION_PRJ__STP3__CODE_CHANGE__CALL OpenCV function calls
Now you are ready to make calls to cvg operators, the calling convention of GpuCV operators is cvgOperator. Consult the list of available operators to find OpenCV operators already ported to GPU or go to How to call GpuCVOperators for more details.
\section TUTO_INTEGRATION_PRJ__STP4__EXTRA_FILES Extra files
GLSL filter files
GpuCV operators are mainly base on GLSL shader programs that are executed on GPU. Theses programs are automatically compiled at runtime by GpuCV and must be reachable by your application to work correctly:
<ul>
<li>Have a local copy of folders FShaders and VShaders from ./GPUCV/bin/ into your current directory at runtime.</li>
OR
<li>Set the shader program path before initializing GpuCV libraries(cvgInit()) by calling the function cvgSetShaderPath() from misc.h. The given path must be the root directory containing FShaders and VShaders folders, ex: "c:\program_files\gpucv\bin\".</li>
</ul>
*/
|
