「OpenCLをクラスでラップしてみた」で作成したOpenCLのラッパークラスのドキュメントをDoxygenを使って作成した。Doxygenについては「doxygenを使ってドキュメントを作成してみる」や「doxygenで複数言語のドキュメントを生成してみる」あたりでも話題にしている。
今回は複数言語の切り替えは特に行っておらず、基本的に英語で記載している。
Doxygenコメント入りのヘッダファイルが次のようになる。
- OpenCL.hpp
/****************************************************************************** * Copyright (c) 2012 INCHOKI Studio * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions are met: * * 1. Redistributions of source code must retain the above copyright notice, * this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright notice, * this list of conditions and the following disclaimer in the documentation * and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE * ******************************************************************************/ /*! \file * \brief DECS CL for OpenCL C++ Bindings 1.1 * \author INCHOKI Studio * * \version 0.1 * \date April 2012 */ /*! \mainpage * \section intro Introduction * OpenCL enable to give effectivness to various kinds of software. It is good * acpect of OpenCL. However, It has complex prosedure to use it for hobby * programings and to go through its advantages. Many lines of code must be to * written before the caluculations which you want are begun. The C++ classes * including in this file help to use OpenCL easily. * * The interface for wrapping OpenCL is contained with a single header file * DECS/OpenCL/OpenCL.hpp and all definitions are within the namespace * DECS::CL. However, some definitions included DECS/OpenCL/OpenCL.hpp are * implemented in a binary file, for example decsopencl.lib on Windows. The * binary library should be lined when the software is built. * * For detail or other information see: * * WASABI Tokyo (Author's Blog in English) * http://www.wasabi-tokyo.net/ * * INCHOKI Journal (Author's Blog in Japanese) * http://blog.inchoki.com/ * * \section example Example * The following example shows a simple use case for the DECS CL * for OpenCL C++ Bindings. * * \code * * #include "OpenCL.hpp" * #include <iostream> * #include <cstdlib> * * const int nElements = 9000000; * float input1[nElements]; * float input2[nElements]; * float output[nElements]; * * int main(int argc, char* argv[]) * { * for(int i = 0; i < nElements; i++){ * input1[i] = (float)i * 10.0f; * input2[i] = (float)i / 20.0f; * output[i] = 0.0f; * } * * try{ * DECS::OpenCL::OpenCL ocl; * ocl.setSourceFromFile("addVector.cl"); * ocl.buildProgram(); * ocl.setKernel(std::string("addVector")); * ocl.setKernelInputArgument(0, input1, nElements); * ocl.setKernelInputArgument(1, input2, nElements); * ocl.setKernelOutputArgument(2, nElements); * ocl.enqueueNDRange(nElements); * ocl.readBuffer(2, output, nElements); * * for(int i = 0; i < 20; i++){ * std::cout << "input1[" << i << "], input2[" << i << "], output[" << i << "] : "; * std::cout << input1[i] << ", " << input2[i] << ", " << output[i] << std::endl; * } * * }catch(cl::Error err){ * std::cerr << "ERROR: " << err.what() << "(" << err.err() << ")" << std::endl; * * } * * return EXIT_SUCCESS; * } * * \endcode */ #ifndef __OPENCL_HPP__ #define __OPDNCL_HPP__ #if defined(__APPLE__) || defined(__MACOSX) #include <OpenCL/cl.hpp> // For Mac OSX #else #include <CL/cl.hpp> // For Windows/Linux #endif #include <iostream> #if defined(__ENABLE_BOOST__) #include <boost/filesystem/fstream.hpp> #else #include <fstream> #endif /*! \namespace DECS * \brief The top level namespace for Discrete Element Calculation Suite(DECS) * * DECS(\em D escrete \em E lement \em C alculation \em S uite) is the set of * utilities and libraries for Granular and Powder pysical simulation. Their * definitions are contained within this namespace or sub-namespace under this * namespace. */ namespace DECS{ /*! \namespace OpenCL * \brief The DECS CL for OpenCL C++ Bindings is defined within this namespace * * All Classes, structures, constants and macros are defined within this * namespace. This namespace is one of sub-namespace of DECS. */ namespace OpenCL{ #if defined(__ENABLE_BOOST__) typedef boost::filesystem::path PATH; typedef boost::filesystem::ifstream IFSTREAM; #else typedef std::string PATH; typedef std::ifstream IFSTREAM; #endif /*! \var cl_device_type DEFAULT_DEVICE_TYPE * \brief This variable is the constant default device type. * * DEFAULT_DEVICE_TYPE is defined for the default constructor of OpenCL Class. * CL_DEVICE_TYPE_GPU is set in this variable. When the default constructor of * OpenCL Class is used, only GPU devices are selected. */ const cl_device_type DEFAULT_DEVICE_TYPE = CL_DEVICE_TYPE_GPU; /*! \class OpenCL * \brief This class is the main class of DECS CL for OpenCL C++ Bindings. * * The OpenCL class supply to the series of procedures to use OpenCL in the * softwares from initialization to finalization. The initialization process, * for example getting platforms, contexts, devices and creating command * queues is run in constructor. * * \todo Preparing the function to load binary program (Priority: High) * \todo Preparing the function to make kernel with binary program * (Priority: High) */ class OpenCL{ private: cl_int error_; std::vector platforms_; std::vector devices_; cl::Context context_; cl::CommandQueue queue_; cl::Program::Sources source_; cl::Program program_; cl::Kernel kernel_; std::vector argument_; protected: cl_int setPlatform(); cl_int setContext(); cl_int setContext(cl_device_type deviceType); cl_int setDevice(); public: /*! \fn OpenCL() * \brief The default constructor * * This is the default constructor of DECS::OpenCL::OpenCL class. This * constructor is initialize the class as following steps. * -# All platforms set into the private variabe * std::vector platforms_ using the setPlatform * protected function. * -# The Context with DEFAULT_DEVICE_TYPE set into the private * variable cl::Context context_ using the setContext protected * function. * -# All devices related with context_ set into the private varible * std::vector device_ using the setDevice protected * function. * -# The Command Queue related the first device in device_ set into * the private varible cl::CommandQueue queue_. * * \todo Change due to select the device creating the command queue (Priority: High) * \todo Change due to select the platform creating the context (Priority: Low) */ OpenCL(); /*! \fn OpenCL(cl_device_type deviceType) * \brief The constructor with the device type * * This is the constructor of DECS::OpenCL::OpenCL class with the device type. * This constructor is initialize the class as following steps. * -# All platforms set into the private variabe * std::vector platforms_ using the setPlatform * protected function. * -# The Context with the argument deviceType set into the private * variable cl::Context context_ using the setContext protected * function. * -# All devices related with context_ set into the private varible * std::vector device_ using the setDevice protected * function. * -# The Command Queue related the first device in device_ set into * the private varible cl::CommandQueue queue_. * * @param[in] deviceType The device type of context. * * All parameters are defined in OpenCL. * * For detail see: The OpenCL Specification * http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf * * \todo Change due to select the device creating the command queue (Priority: High) * \todo Change due to select the platform creating the context (Priority: Low) */ OpenCL(cl_device_type deviceType); /*! \fn ~OpenCL() * \brief The default destructor * * The default destructor does not have the specific process at this time. */ ~OpenCL(); /*! \fn setSource(std::string& source) * \brief The function to set source strings for the program * * This function set the source strings into the private variable * cl::Program::Sources source_. cl::Program::Sources is * std::vector for source string and its size. When this function * call second time and more, the source strings push back the std::vector. * The size of std::vector is managed in this function, so the user don't need * to conserned with the size. * * @param[in] source The source string refference. */ void setSource(std::string& source); /*! \fn setSourceFromFile(std::string& srcFile) * \brief The function to load and set a source file * * This function load a souce from source file and set its contents into the * private variable source_. This function call the function setSource * in its internal process. If you define the macro "__ENABLE_BOOST__", the * type "PATH" is "boost::filesystem::path". And "std::string" is used in the * default settings. * * @param[in] srcFilePath The path to source file. * \return 0: Success, 1: "srcFilePath cannot be opened */ int setSourceFromFile(PATH srcFilePath); /*! \fn buildProgram() * \brief The function to build the program * * This fucntion initialize the private variable program_ and build the * programs from the sources stored in the private variable source_. If an * error occur in initializing program, this function return the error code of * cl::Program and throw the exception. If an error occur in building program, * this function return the error code of cl::Program::Build and throw the * exception. These exception is defined in OpenCL C++ Bindings. * * For detail of the error code see: * * The OpenCL Specification * http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf * * For Detail of the exception see: * * The OpenCL C++ Wrapper API * http://www.khronos.org/registry/cl/specs/opencl-cplusplus-1.1.pdf * * \return The error code of cl::Program or cl::Program::Build. */ cl_int buildProgram(); /*! \fn setKernel(std::string functionName) * \brief The function to set kernel * * This function set the kernel with the OpenCL function included in the * private variable program_instance into the private variable cl::Kernel * kernel_. If an error occur in making the kernel instance, this function * return the error code of cl::Kernel and throw the OpenCL C++ Bindings * exception. * * For detail of the error code see: * * The OpenCL Specification * http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf * * For Detail of the exception see: * * The OpenCL C++ Wrapper API * http://www.khronos.org/registry/cl/specs/opencl-cplusplus-1.1.pdf * * @param[in] functionName The function name to set into kernel. * \return The error code of cl::Kernel. * * \todo Change due to use binary program (Priority: High) */ cl_int setKernel(std::string functionName); /*! \fn setKernelInputArgument(cl_int index, float* argument, const int n) * \brief The function to set the input argument into the private variable kernel_ * * This Function set the input argument for kernel into the private variable kernel_. * The memory object is create based on the pointer of argument and the number * of element of argument. In actual, this memory object is set into the kernel. * If a error occur in making the memory object, this function return the error * code of cl::Buffer and throw the exception. And if a error occur in setting * the argument into the kernel, this function return the error code of * cl::kernel::setArg and throw the exception. * * \warning At this time this function can deal with only float type. And this * function can only deal with the memory object with only CL_MEM_READ_ONLY. * * For detail of the error code see: * * The OpenCL Specification * http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf * * For Detail of the exception see: * * The OpenCL C++ Wrapper API * http://www.khronos.org/registry/cl/specs/opencl-cplusplus-1.1.pdf * * @param[in] index The index of argument order of the kernel. * @param[in] argument The pointer of a argument for the kernel. * @param[in] n The number of element of the argument. * \return The error code of cl::Buffer or cl::Kernel::setArg. * * \todo Change due to deal with other type argument (Priority: High) * \todo Change due to switch multi kernels (Priority: Mid) */ cl_int setKernelInputArgument(cl_int index, float* argument, const int n); /*! \fn setKernelOutputArgument(cl_int index, const int n) * \brief The function to set the output argument into the private variable kernel_ * * This Function set the output argument for kernel into the private variable kernel_. * The memory object is create based on the pointer of argument and the number * of element of argument. In actual, this memory object is set into the kernel. * If a error occur in making the memory object, this function return the error * code of cl::Buffer and throw the exception. And if a error occur in setting * the argument into the kernel, this function return the error code of * cl::kernel::setArg and throw the exception. * * \warning At this time this function can deal with only float type. And this * function can only deal with the memory object with only CL_MEM_WRITE_ONLY. * * For detail of the error code see: * * The OpenCL Specification * http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf * * For Detail of the exception see: * * The OpenCL C++ Wrapper API * http://www.khronos.org/registry/cl/specs/opencl-cplusplus-1.1.pdf * * @param[in] index The index of argument order of the kernel. * @param[in] n The number of element of the argument. * \return The error code of cl::Buffer or cl::Kernel::setArg. * * \todo Change due to deal with other type argument (Priority: High) * \todo Change due to switch multi kernels (Priority: Mid) */ cl_int setKernelOutputArgument(cl_int index, const int n); /*! \fn enqueueNDRange(const int n) * * \brief The function to enqueue the kernel * * This function enqueue the private variable kernel_ into the command queue * which created as the private variable queue_. If a error occur, this * function return the error code of cl::CommandQueue::enqueueNDRangeKernel, * and throw the exception of its. * * For detail of the error code see: * * The OpenCL Specification * http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf * * For Detail of the exception see: * * The OpenCL C++ Wrapper API * http://www.khronos.org/registry/cl/specs/opencl-cplusplus-1.1.pdf * * @param[in] n The number of index of the arguments. * * \return The error code of cl::CommandQueue::enqueueNDRangeKernel */ cl_int enqueueNDRange(const int n); /*! \fn readBuffer(cl_int index, float* output, const int n) * \brief The fucntion to read the buffer * * This function read the output from the buffer into the argument * "output". If a error occur duaring the reading buffer, this function * return the error code of cl::CommandQueue::enqueueReadBuffer and throw * the exception of cl::CommandQueue::enqueueReadBuffer and throw. * For detail of the error code see: * * The OpenCL Specification * http://www.khronos.org/registry/cl/specs/opencl-1.1.pdf * * For Detail of the exception see: * * The OpenCL C++ Wrapper API * http://www.khronos.org/registry/cl/specs/opencl-cplusplus-1.1.pdf * * \warning At this time this function can deal with only float type. * * @param[in] index The index of argument order of the kernel. * @param[out] output The variable to store the output. * @param[in] The number of element of the argument. * * \return The error code of cl::CommandQueue::enqueueReadBuffer */ cl_int readBuffer(cl_int index, float* output, const int n); }; } } #endif // __OPENCL_HPP__
これからDoxygenを使って生成したドキュメントはこちら(doclpp_201204014.pdf)。
GCC 4.4.2でもerrorでした g++ -std=c++0x ref_test.cppref_test.cpp: In function void f(Type) [with Type = std::reference_wrapper]':ref_test.cpp:23: inseintaattd from hereref_test.cpp:13: error: no match for operator=' in x = 1'/usr/include/c++/4.3/tr1_impl/functional:452: note: candidates are: std::reference_wrapper& std::reference_wrapper::operator=(const std::reference_wrapper&) [with _Tp = int]
投稿情報: Ezatulla | 2012/06/19 05:43