<<TableOfContents(2)>>

''See also:'' [[CUDADevelopersGuide]]

== Detection of OpenCL ==

If an application is built and linked against OpenCL then it is expected that it will run on a machine which has an OpenCL implementation installed.  A typical application should create a GPU context on hosts containing an OpenCL-capable GPU and/or a CPU context on hosts with CPU-only support.  The ATI Stream SDK can be used to provide a CPU-only implementation on Linux-hosts containing just an AMD or Intel CPU.  The implementation will parallelize on a CPU context across the available processors.  If an ATI OpenCL-compatible GPU is present, then the application can also request a GPU context and run on the GPU(s) (or GPU+CPU combination).  On a machine containing an Nvidia GPU, the Nvidia OpenCL driver should be installed.  Finally, on Mac OS X Snow Leopard, the OS itself provides an implementation which provides minimally a CPU context and also a GPU context for OpenCL-capable ATI or Nvidia GPUs.  

The opencl_algorithms library contains an implementation of Dijkstra's Single Source Shortest Path algorithm (used by mris_pmake) and demonstrates how to write an algorithm which will run on CPU-only, GPU-only, CPU+GPU, or multi-GPU.

== Changes to enable OpenCL during configuration ( configure.in ) ==

This section gives an overview of how `configure.in` is changed and what stuff it exports. More often than not, one need not tamper with configure.in -- it is already changed to accommodate OpenCL. 

* OpenCL support is enabled by using a `--with-opencl=<path of cuda>`.  This should be the path to either the ATI Stream SDK or Nvidia OpenCL root.  On Mac OS X, configure.in will automatically look in the appropriate Mac OS X Snow Leopard System directories for the headers and framework.  The ./configure exports certain things which are helpful in compiling OpenCL programs ( and which are to be used in Makefile.am )

=== Flags which configure.in exports ===

These flags are typically used in the Makefile.am of any binary which has a CUDA replacement. 

 * '''OPENCL_CFLAGS''' : This variable contains the include path of OpenCL header files. (eg. OPENCL_CFLAGS="-I<opencl_include_dir>" )

 * '''OPENCL_LIBS''' : This variable contains the OpenCL libraries to link against (eg. OPENCL_LIBS="-L<opencl_lib_dir> -lOpenCL" )

 * '''BUILDOPENCL''' : This important variable is exported as AM_CONDITIONAL. If configure finds OpenCL, it sets this flag and any Makefile.am can test this flag and if it exists, compile OpenCL specific stuff. This is illustrated in the next section. 

 * '''FS_CUDA''' : This is defined and will be placed on config.h if OpenCL is found.  Example usage would be:

{{{
#ifdef FS_OPENCL
    // We have implemented various flavors of the Dijkstra algorithm that runs 
    // with OpenCL using either CPU-only, GPU+CPU, Multi GPU, or Multi GPU + CPU.
    // Based on what set of devices is available, this function will choose which  
    // implementation to use.  This version of Dijkstra selects which devices to use 
    // automatically.  

    // If compiled with OpenCL support, run the OpenCL version of the
    // algorithm
    runDijkstraOpenCL(&graph, &sourceVertices, results, 1);
#else
    // If not compiled with OpenCL, run the reference version of the
    // algorithm
    runDijkstraRef(&graph, &sourceVertices, results, 1);
#endif
}}}

== Tweaking Makefile.am of the binary ==

'''Listing of Makefile.am of `mris_pmake` to illustrate how Makefile.am changes:'''
{{{
bin_PROGRAMS = mris_pmake
mris_pmake_SOURCES = \
        abs2rel.c \
        asynch.cpp \
        c_label.cpp \
        C_mpmProg.cpp \
        c_SMessage.cpp \
        c_SSocket.cpp \
        c_surface.cpp \
        c_vertex.cpp \
        dijkstra.cpp \
        env.cpp \
        general.cpp \
        help.cpp \
        mris_pmake.cpp \
        rel2abs.c \
        scanopt.cpp \
        surface.cpp

AM_CFLAGS=-I$(top_srcdir)/include
AM_CXXFLAGS=-I$(top_srcdir)/include -I../opencl_algorithms/
mris_pmake_LDFLAGS = $(OS_LDFLAGS)
        
if BUILDOPENCL # Include OpenCL version of algorithms    
    mris_pmake_LDADD = $(addprefix $(top_builddir)/, $(LIBS_MGH)) ../opencl_algorithms/libopencl_algorithms.a $(OPENCL_LIBS)
else # No OpenCL present 
    mris_pmake_LDADD = $(addprefix $(top_builddir)/, $(LIBS_MGH)) ../opencl_algorithms/libopencl_algorithms.a    
endif


EXTRA_DIST=asynch.h c_label.h C_mpmProg.h c_SMessage.h c_SSocket.h \
        c_surface.h c_vertex.h dijkstra.h env.h general.h help.h pathconvert.h \
        pstream.h scanopt.h surface.h

# Our release target. Include files to be excluded here. They will be                                                               
# found and removed after 'make install' is run during the 'make 
# release' target.

EXCLUDE_FILES=
include $(top_srcdir)/Makefile.extra
}}}

As one can notice, the Makefile.am of a OpenCL enabled code differs from normal Makefile.am only in the `if BUILDOPENCL.. endif` block. 

'''Notes :''' 
 * OpenCL support is to be enclosed in `if BUILDCUDA.. endif` block ( which is exported by configure.in if it finds OpenCL) 
 * The only difference is the need to link against $(OPENCL_LIBS)

== Attribution ==
A lot of the code in oclCommon.cpp was derived from the NVIDIA GPU Computing SDK.