Windows Opencl clBuildProgram()函数

Windows Opencl clBuildProgram()函数详细解析

cl_int clBuildProgram(cl_program program,
					  cl_uint num_devices, 
					  const cl_device_id *device_list,
					  const char *options, 
					  void (*pfn_notify)(cl_program
					  					, void *user_data),    
					  void *user_data) 

为所有设备或与程序相关联的OpenCL上下文中的特定设备，从程序源或二进制文件构建（编译并链接）program 可执行文件。OpenCL允许使用源代码或二进制文件来构建程序可执行文件。必须调用clBuildProgram对于使用clCreateProgramWithSource或 clCreateProgramWithBinary为与program关联的一个或多个设备生成program 可执行文件。

program 是program对象。

device_list 是指向与program 关联的设备列表的指针。如果device_list 为空值，则为与已加载源或二进制文件的程序关联的所有设备生成程序可执行文件。如果device_list 是非空值，则为该列表中指定的已加载源或二进制文件的设备生成程序可执行文件。

num_devices 是设备列表中列出的设备数。

options 是一个指向字符串的指针，该字符串描述用于生成程序可执行文件的生成选项。第5.4.3节描述了支持的选项列表。

pfn_notify 是指向通知例程的函数指针。通知例程是一个回调函数，应用程序可以注册它，当程序可执行文件被构建（成功或失败）时，它将被调用。如果pfn_notify 不为NULL，则clBuildProgram不需要等待生成完成，可以立即返回。如果pfn_notify 为空，则clBuildProgram在生成完成之前不会返回。这个回调函数可以由OpenCL实现异步调用。应用程序负责确保回调函数是线程安全的。

当调用pfn_notify 时，user_data 将作为参数传递。user_data 可以为空。

如果函数成功执行，clBuildProgram将返回CL_SUCCESS。否则，将返回以下错误之一：

1. CL_INVALID_PROGRAM 如果program 不是有效的program对象。
2. CL_INVALID_VALUE 如果device_list 为空且num_devices 大于零，或者device_list 不为NULL且num_devices 为零。
3. CL_INVALID_VALUE 如果pfn_notify 为NULL，但user_data 不为NULL。
4. CL_INVALID_DEVICE 如果device_list 中列出的OpenCL设备不在与program 关联的设备列表中。
5. CL_INVALID_BINARY 如果程序是用clCreateWithProgramBinary创建的，并且device_list 中列出的设备没有加载有效的程序二进制文件。
6. CL_INVALID_BUILD_OPTIONS 如果options 指定的生成选项无效。
7. CL_INVALID_OPERATION 如果先前调用clBuildProgram 对于program 为device_list 中列出的任何设备生成可执行程序的过程尚未完成。
8. CL_COMPILER_NOT_AVAILABLE 如果program 是用clCreateProgramWithSource创建的，并且编译器不可用，即表4.3中指定的可用CL_DEVICE_COMPILER_设置为CL_FALSE。
9. CL_BUILD_PROGRAM_FAILURE 如果生成程序可执行文件失败。如果clBuildProgram在生成完成之前不返回，将返回此错误。
10. CL_INVALID_OPERATION 如果program 附加了内核对象。
11. CL_OUT_OF_HOST_MEMORY 如果在主机上分配OpenCL实现所需的资源失败。