OpenCL编程指南-10.1C++包装器API

C++包装器API概述

C++API划分为多个类，分别映射到一个OpenCL C类型，例如，cl::Memory类就映射到OpenCL C中的cl_mem。不过，C++ API会尽可能使用继承提供额外的一层类型抽象；例如，类cl::Buffer派生自基类cl::Memory，表示所有可能的OpenCL内存对象的1维内存子类。类层次体系结构见图12-1。

一般地，C++类类型到底层OpenCL C类型有直接的映射，在这种情况下，底层C类型可以通过操作符()访问。例如，以下代码可以得到第一个OpenCL平台，查询底层OpenCL C类型cl_platform，并把它赋给变量platform：

extern void someFunction(cl_program);

cl_platform platform;
{
    std::vector<cl::Platform> platformList;
    cl::Platform::get(&platformList);
    platform = platformList[0]();
    someFunction(platform); //safe call
}
someFunction(platform); //not safe

这个例子中的最后一行是不安全的，因为矢量platform-List在退出基本代码块时已经撤销，因此，会对platformList中的各个平台做一个隐式的clReleasePlatform调用，从而允许底层OpenCL实现释放所有相关联的内存。

C++包装器API异常

最后，在深入介绍一个详细的例子之前，我们介绍OpenCL C++异常。为了跟踪应用程序中由于OpenCL操作错误而产生的错误，C API使用了cl_int类型错误值。这些错误值会作为一个API函数的结果返回，或者，如果这个API函数返回一个OpenCL对象，错误码会作为函数的最后一个参数返回。C++API支持以这种形式跟踪错误，不过也可以使用C++异常。默认情况下并没有启用异常，会根据底层CAPI设置并返回OpenCL错误码。

要使用异常，必须显式地启用异常，在包含cl.hpp之前定义以下预处理器宏：

__CL_ENABLE_EXCEPTIONS

一旦启用，由OpenCLC调用报告的非CL_SUCCESS错误值将抛出异常类cl::Error。默认情况下，方法cl::Error::what()会返回指向一个串的const指针，指示报告错误的特定C API调用，例如clGetDeviceInfo。可以覆盖cl::Error::what()的默认行为，为此在包含cl.hpp之前要定义以下预处理器宏：

__CL_USER_OVERRIDE_ERROR_STRINGS

//表12-1 预处理器错误宏及其默认值
预处理器宏名                                       默认值
__GET_DEVICE_INFO_ERR                             clCetDeviceInfo
__GET_PLATPORM_INEO_ERR                           clGetPlatformInfo
__GET_DEVICE_IDS_ERR                              clGetDeviceIds
__GET_CONTEXT_INFO_ERR                            clGetContextInfo
__GET_EVENT_INFO_ERR                              clGetEventInfo
__GET_EVENT_PROFILE_INFO_ERR                      clGetEventProfileInfo
__GET_MEM_OBJECT_INPO_ERR                         clGetMemmObjectInfo
__GET_IMAGE_INFO_ERR                              clCetImageInfo
__GET_SAMPLER_INFO_ERR                            clGetSampleInfo
__GET_KERNEL_INFO_ERR                             clGetKernelInfo
__GET_KERNEL_WORK_GROUP_INPO_ERR                  clGetKernelWorkGroupInfo
__GET_PROGRAM_INPO_ERR                            clGetProgramInfo
__GET_PROGRAM_BUILD_INFO_ERR                      clGetProgramBuildInfo
__GET_CONAND_QUEUE_INFO_ERR                       clGetCommandQueueInfo
__CREATE_CONTEXT_FROM_TYPE_ERR                    clCreateContextFromType
__GET_SUPPORTED_IMAGE_FORMATS_ERR                 clGetSupportedImageFormats
__CREATE_BUFEER_ERR                               clCreateBuffer
__CREATE_SUBBUFFER_ERR                            clCreateSubBuffer
__CREATE_GL_BUFFER_ERR                            clCreateGLBuffer
__CREATE_IMAGE2D_ERR                              clCreateImage2D
__CREATE_IMAGE3D_ERR                              clCreateImage3D
__SET_MEM_OBJECT_DESTRUCTOR_CALLBACK_ERR          clSetMemmObjectDestructorCallback
__CREATE_USER_EVENT_ERR                           clCreateUserEvent
__SET_USER_EVENT_STATUS_ERR                       clSetUserEventStatus
__SET_EVENT_CALLBACK_ERR                          clSetEventCallback
__WAIT_FOR_EVENTS_ERR                             clWaitForEvents
__CREATE_KERNEL_ERR                               clCreateKernel
__SET_KERNEL_ARGS_ERR                             clSetKernelArgs
__CREATE_PROGRAM_WITH_SOURCE_ERR                  clCreateProgramWithSource
__CREATE_PROGRAM_WITH_BINARY_ERR                  clCreateProgramWithBinary
__BUILD_PROGRAM_ERR                               clBuildProgram
__CREATE_KERNELS_IN_PROGRAM_ERR                   clCreateKernelsInProgram
__CREATE_COMMAND_OUEUE_ERR                        clCreateCommandQueue
__SET_CONMAND_QUEUE_PROPERTY_ERR                  clSetCommandQueueProperty
__ENQUEUE_READ_BUFEER_ERR                         clEnqueueReadBuffer
__ENQUEUE_READ_BUFEER_RECT_ERR                    clEnqueueReadBufferRect
__ENQUEUE_WRITE_BUFFER_ERR                        clEnqueueWriteBuffer
__ENQUEUE_WRITE_BUEFER_RECT_ERR                   clEnqueueWriteBufferRect
__ENQEUE_COPY_BUFEER_ERR                          clEnqueueCopyBuffer
__ENQEUE_COPY_BUFFER_RECT_ERR                     clEnqueueCopyBufferRect
__ENQUEUE_READ_IMAGE_ERR                          clEnqueueReadImage
__ENQUEUE_WRITE_IMAGE_ERR                         clEnqueueWriteImage
__ENQUEUE_COPY_IMAG_ERR                           clEnqueueCopyImage
__ENQUEUE_COPY_IMAGE_TO_BJFEER_ERR                clEnqueueCopyImageToBuffer
__ENQUEUE_COPY_BUFEER_TO_IMAGE_ERR                clEnqueueCopyBufferToImage
__ENQUEUE_MAP_BUFFER_ERR                          clEnqueueMapBuffer
__ENQUEUE_MAP_IMAGE_ERR                           clEnqueueMapImage
__ENQUEUE_UNNAP_MEM_OBJECT_ERR                    clEnqueueUnmapMemObject
__ENQUEUE_NDRANGE_KERNEL_ERR                      clEnqueueNDRangeKernel
__ENQUEUE_TASK_ERR                                clEnqueueTask
__ENQUEUE_NATIVE_KERNEL                           clEnqueueNativeKernel
__ENQUEUE_MARKER_ERR                              clEnqueueMarker
__ENQUEUE_WAIT_FOR_EVENTS_ERR                     clEnqueueWaitForEvents
__ENRQUEUE_BARRIER_ERR                            clEnqueueBarriers
__UNLOAD_COMPILER_ERR                             clUnloadCompiler
__FLUSH_ERR                                       clFlush
__FINISH_ERR                                      clFinish