QtOpenCL : Building QtOpenCL

Obtaining the source code

The QtOpenCL source code can be obtained from the external Qt git server: http://qt.gitorious.org/qt-labs/opencl

See the Contributing to QtOpenCL page for more information on contributing to this project.

Required Qt version

It is recommended that you use Qt 4.7, but the library will build with Qt 4.6. The main missing feature is support for QGLBuffer in the QCLContextGL class. QGLBuffer implements VBO support for QtOpenGL and is in Qt 4.7, but not 4.6.

It is recommended that QtOpenCL be built against a developer build of Qt rather than an installed Qt SDK because the QtOpenCL library #include's private headers from the Qt sources. The library can be compiled against a Qt installation that does not have private headers, but the QCLImage2D::drawImage() function will have reduced performance when painting into a raster-based QPixmap.

Building for Linux

The top-level directory of the source tree contains a configure script that detects the system's OpenCL library and configures the build system of QtOpenCL to use it. The simplest way to configure and build is as follows:

    ./configure -qmake path
    make

The path should be the complete path to the qmake binary if it is not on the PATH. For example:

    ./configure -qmake /usr/local/Trolltech/Qt-4.7.0/bin/qmake

It is very important that the -qmake command-line option be supplied if you are cross-compiling for a device because the host system's qmake will not work.

By default, the build system assumes that the OpenCL headers are found in the normal system location for header files (usually /usr/include), and that the library to link against is called libOpenCL.so. These defaults can be overridden with command-line options to configure:

-Idir - Specify the directory that contains the includes <CL/cl.h>, <CL/cl_gl.h>, etc.
-Ldir - Specify the directory that contains the libOpenCL.so library.
-lname - Override the -lOpenCL default library name. This can also be used to add additional libraries; e.g. "-lOpenCL -lGLESv2".
-no-openclgl - The OpenCL library does not have any of the functions that are needed to perform OpenGL interoperation. This will cause the sharing functionality of QCLContextGL to be disabled. Applications can still use QCLContextGL, but they will have reduced functionality. Normally this option will be detected automatically by configure.

For example, if your OpenCL library is called libOCL.so installed under /opt/ocl/include and /opt/ocl/lib, and it does not support GL interoperation, you would configure as follows:

    ./configure -qmake path -I/opt/ocl/include \
          -L/opt/ocl/lib -lOCL -no-openclgl

Building for MacOSX

The instructions are similar to Linux:

    ./configure -qmake path
    make

It is assumed that the "OpenCL" framework has been installed to provide the OpenCL headers and libraries. If the OpenCL headers and libraries are provided by a different framework, it can be specified as follows:

    ./configure -qmake path -fw OCL

Building for Windows

Currently there isn't an equivalent of configure for Windows. The alternative build instructions are as follows:

    qmake opencl.pro
    nmake

Shadow building

The configure script supports building the QtOpenCL library in a different directory than the source code. The following example builds the sources from $HOME/sources/opencl into $HOME/build/opencl:

    mkdir $HOME/build/opencl
    cd $HOME/build/opencl
    $HOME/sources/opencl/configure -qmake path
    make

Checking that QtOpenCL is working

Once the library has been built, you can check if QtOpenCL is basically working by running the clinfo program, which should print out the capabilities of your OpenCL implementation:

    $ export LD_LIBRARY_PATH=`pwd`/lib:$LD_LIBRARY_PATH
    $ util/clinfo/clinfo
    Platform ID       : 12289
    Profile           : FULL_PROFILE
    Version           : OpenCL 1.0
    ...

The LD_LIBRARY_PATH, or its equivalent under other operating systems, needs to be set to point at the lib directory.

Another way to check that QtOpenCL is working is to run the Vector Addition Example:

    $ examples/opencl/vectoradd/vectoradd
    Answer is correct: 2048

If you get a CL_INVALID_PLATFORM, CL_INVALID_VALUE, CL_DEVICE_NOT_AVAILABLE, or similar error, then you may need to modify QCLContext::create() to locate the correct platform or device on your system.

You can also run the tests/auto/qcl/tst_qcl program to execute the QtOpenCL unit tests, which will check that the OpenCL implementation is operating in accordance with QtOpenCL's expectations.

When reporting bugs, it is recommended that you include the output of the clinfo program in the bug report.

Generating the Documentation

From the top-level, type make docs to generate the documentation into the doc/html directory in the build tree. This will use the qdoc3 binary from the Qt you used to build QtOpenCL. If that qdoc3 binary does not exist, it will use the qdoc3 binary on the PATH instead.

Return to Home

Contents

Building QtOpenCL