「OpenCLをクラスでラップしてみた」で作成したOpenCLのラッパークラスのドキュメントをDoxygenを使って作成した。Doxygenについては「doxygenを使ってドキュメントを作成してみる」や「doxygenで複数言語のドキュメントを生成してみる」あたりでも話題にしている。
今回は複数言語の切り替えは特に行っておらず、基本的に英語で記載している。
Doxygenコメント入りのヘッダファイルが次のようになる。
/******************************************************************************
* 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)。
このブログの開発用PCはこちら
」と「
」を見ながら書いたが、「
