[opencl] Add FindOpenCLhpp CMake module; vendor cl2.hpp; fixup includes

CL/cl2.hpp, which the OpenCL support is based upon, is not always
included with OpenCL on some platforms, e.g. Mac, or not readily
available as a package. This work adds a CMake module specifically for
finding cl2.hpp, as installed by OpenCL-CLHPP project.

If not found, but standard OpenCL lib and headers are, the vendored
cl2.hpp in external/opencl-clhpp is used, as it needs no compilation.

- Only the cl2.hpp, license and README are vendored from OpenCL-CLHPP.

- Fix up referenced includes in other CMake targets, to ensure the
includes for OpenCL are specifically added (previously, they were
sometimes found in existing include directories of other dependencies).

- Fixup for standard FindOpenCL module not assinging proper framework
headers directory for Mac.

CMakeLists.txt

@@ -39,6 +39,18 @@ IF (USE_OPENCL)
     FIND_PACKAGE(OpenCL)
     IF(${OpenCL_FOUND})
         SET(HAVE_OPENCL TRUE)
+        # Fixup for standard FindOpenCL module not assinging proper framework headers directory
+        IF (APPLE AND "${OpenCL_INCLUDE_DIR}" MATCHES "OpenCL\\.framework/?$")
+            SET(OpenCL_INCLUDE_DIR "${OpenCL_INCLUDE_DIR}/Headers" CACHE PATH "" FORCE)
+            SET(OpenCL_INCLUDE_DIRS ${OpenCL_INCLUDE_DIR})
+        ENDIF ()
+        FIND_PACKAGE(OpenCLhpp)
+        IF(NOT OPENCL_HPP_FOUND)
+            # Use internal headers copied from OpenCL-CLHPP project
+            SET(OPENCL_HPP_INCLUDE_DIR ${CMAKE_SOURCE_DIR}/external/opencl-clhpp/include CACHE PATH "" FORCE)
+            MESSAGE(STATUS "Couldn't find OpenCL C++ headers, using internal: ${OPENCL_HPP_INCLUDE_DIR}")
+        ENDIF(NOT OPENCL_HPP_FOUND)
+        SET(OpenCL_INCLUDE_DIRS ${OpenCL_INCLUDE_DIRS} ${OPENCL_HPP_INCLUDE_DIR})
     ELSE(${OpenCL_FOUND})
         MESSAGE(STATUS "Couldn't find OpenCL: support DISABLED")
     ENDIF(${OpenCL_FOUND})

cmake/FindOpenCLhpp.cmake

@@ -0,0 +1,48 @@
+# Find OpenCLhpp
+# ~~~~~~~~~~~~~~~
+# CMake module to search for OpenCL headers for C++ bindings from:
+#    https://github.com/KhronosGroup/OpenCL-CLHPP
+#
+# Specifically, it finds the cpl2 header.
+#
+# If it's found it sets OPENCL_HPP_FOUND to TRUE
+# and following variables are set:
+#    OPENCL_HPP_INCLUDE_DIR
+#
+# Copyright (c) 2018, Boundless Spatial
+# Author: Larry Shaffer <lshaffer (at) boundlessgeo (dot) com>
+#
+# Redistribution and use is allowed according to the terms of the BSD license.
+# For details see the accompanying COPYING-CMAKE-SCRIPTS file.
+
+if (OPENCL_HPP_INCLUDE_DIR)
+    SET(OPENCL_HPP_FOUND TRUE)
+else ()
+    find_path(OPENCL_HPP_INCLUDE_DIR
+        NAMES CL/cl2.hpp
+        PATHS
+        ${LIB_DIR}/include
+        "$ENV{LIB_DIR}/include"
+        $ENV{INCLUDE}
+        /usr/local/include
+        /usr/include
+    )
+    if (OPENCL_HPP_INCLUDE_DIR)
+        SET(OPENCL_HPP_FOUND TRUE)
+    else ()
+        SET(OPENCL_HPP_FOUND FALSE)
+    endif ()
+endif ()
+
+
+if (OPENCL_HPP_FOUND)
+    if (NOT OPENCLHPP_FIND_QUIETLY)
+        message(STATUS "Found OpenCL C++ headers: ${OPENCL_HPP_INCLUDE_DIR}")
+    endif ()
+else ()
+    if (OPENCLHPP_FIND_REQUIRED)
+      message(FATAL_ERROR "Could not find OpenCL C++ headers")
+    endif ()
+endif ()
+
+mark_as_advanced(OPENCL_HPP_INCLUDE_DIR)

external/opencl-clhpp/LICENSE.txt

@@ -0,0 +1,25 @@
+Copyright (c) 2008-2015 The Khronos Group Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and/or associated documentation files (the
+"Materials"), to deal in the Materials without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Materials, and to
+permit persons to whom the Materials are furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Materials.
+
+MODIFICATIONS TO THIS FILE MAY MEAN IT NO LONGER ACCURATELY REFLECTS
+KHRONOS STANDARDS. THE UNMODIFIED, NORMATIVE VERSIONS OF KHRONOS
+SPECIFICATIONS AND HEADER INFORMATION ARE LOCATED AT
+    https://www.khronos.org/registry/
+
+THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.

external/opencl-clhpp/README.txt

@@ -0,0 +1,63 @@
+Output cl2.hpp Header from OpenCL-CLHPP Project
+===============================================
+
+Copied here to QGIS project on 2018-09-30 from source tree bbccc50 commit.
+
+https://github.com/KhronosGroup/OpenCL-CLHPP
+
+During CMake build, header is directly copied from source's 'input_cl2.hpp'.
+
+Useful for platforms where v2 C++ bindings are not provided with the default
+OpenCL installation, e.g. Mac.
+
+
+
+OpenCL-CLHPP Project README (below)
+===================================
+
+Sources for the OpenCL Host API C++ bindings (cl.hpp and cl2.hpp).
+
+Doxgen documentation for the cl2.hpp header is available here:
+
+  http://khronosgroup.github.io/OpenCL-CLHPP/
+
+
+Components:
+  input_cl.hpp:
+    Acts as the master source for the 1.x version of the header.
+    The reason for doing it this way is to generate an appropriate set of functors with varying argument counts without assuming variadic template support in the header.
+
+  input_cl2.hpp:
+    Acts as the master source for the 2.x version of the header.
+    Directly copied as cl2.hpp
+
+  gen_cl_hpp.py:
+    A generator script written in python to convert input_cl.hpp into cl.hpp, generating the functor expansions as necessary.
+    cl2.hpp does not require this as it uses variadic templates expanded in the compiler.
+
+  docs:
+    Doxygen file used to generate HTML documentation for cl2.hpp.
+
+  examples:
+    A simple example application using the very basic features of the header and generating cl.hpp dynamically through the build system.
+
+  tests:
+    A (very small, incomplete) set of regression tests. Building the tests requires Python, Ruby, Unity and CMock. For the last two I've used Unity 2.1.0 [1] and CMock top-of-tree from Github [2] (the version 2.0.204 on Sourceforge does not work). At the moment there is no way to skip building the tests.
+
+  CMake scripts:
+    A build system that both generates the example and drives generation of cl.hpp.
+
+You need to tell cmake where to find external dependencies, using the variables OPENCL_DIST_DIR, UNITY_DIR and CMOCK_DIR. These can be set either as environment variables, or on the cmake command line using the syntax -D<VAR>=<VALUE>. For the lazy, I use the following commands to build and test (you'll need to adapt your paths):
+
+mkdir build
+cd build
+cmake -DUNITY_DIR=$HOME/src/unity -DCMOCK_DIR=$HOME/src/cmock -DOPENCL_DIST_DIR=/opt/AMD-APP-SDK-v2.7-RC-lnx64/ ..
+make
+tests/test_clhpp
+tests/test_clhpp_cxx11
+tests/test_clhpp_deprecated_1_1
+
+After building, the headers appear in build/include/CL/. If Doxygen is available, you can generate HTML documentation by typing `make docs`.
+
+[1] https://github.com/ThrowTheSwitch/Unity/releases/tag/v2.1.0
+[2] https://github.com/ThrowTheSwitch/CMock