Windows Opencl clSetKernelArg()函数

Windows Opencl clSetKernelArg()函数详细解析

Setting Kernel Arguments
函数原型

cl_int clSetKernelArg(cl_kernel      kernel,
      				  cl_uint        arg_index,
            		  size_t         arg_size, 
     				  const void     *arg_value) 

clSetKernelArg()用于为内核的特定参数设置参数值。

kernel 是一个有效的内核对象。

arg_index 是参数索引。内核的参数由索引引用，最左边的参数从0到n-1，其中n是内核声明的参数总数。

例如，设置以下内核：

 __kernel void image_filter(int n, int m,  
      __constant float *filter_weights, 
      __read_only image2d_t src_image,  
      __write_only image2d_t dst_image) 
      { 
  		... 
	  } 

image_filter的参数索引值设置n为0，m为1，filter_weights为2，src_image为3，dst_image为4。

arg_value 是指向数据的指针，该数据应用作arg_index指定的参数的参数值。arg_value 指向的参数数据将被复制，因此在clSetKernelArg返回后，应用程序可以重用arg_value指针。指定的参数值是将kernel（clEnqueueNDRangeKernel和clEnqueueTask）排入队列的所有API调用所使用的值，直到对clSetKernelArg的调用更改了kernel 的参数值。

如果一个缓冲区或对象是一个适当的缓冲区或对象，则该对象将是一个指针。内存对象必须使用与内核对象关联的上下文创建。如果参数是缓冲区对象，也可以指定空值，在这种情况下，空值将用作声明为内核中__global 或__constant内存指针的参数的值。如果参数是用__local 限定符声明的，则arg_value 条目必须为NULL。如果参数的类型为sampler_t，则arg_value 条目必须是指向sampler对象的指针。对于所有其他内核参数，arg_value 条目必须是指向要用作参数值的实际数据的指针。

如果参数被声明为具有__global 或 __constant 限定符的内置或用户定义类型的指针，则指定为参数值的内存对象必须是缓冲区对象（或NULL）。如果参数是用__constant 限定符声明的，则内存对象的大小（以字节为单位）不能超过CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE，用 __constant 限定符声明的参数数不能超过CL_DEVICE_MAX_CONSTANT_ARGS。

如果参数被声明为image2d_t类型，则指定为参数值的内存对象必须是2D图像对象。如果参数被声明为image3d_t类型，则指定为参数值的内存对象必须是3D图像对象。

arg_size 指定参数值的大小。如果参数是内存对象，则大小是缓冲区或图像对象类型的大小。对于用__local 限定符声明的参数，指定的大小将是必须为__local 参数分配的缓冲区大小（以字节为单位）。如果参数的类型为sampler_t，则arg_size 值必须等于sizeof（cl_sampler）。对于所有其他参数，大小将为参数类型的大小。

注意：内核对象不会更新clSetKernelArg指定为参数值的对象（如内存、采样器对象）的引用计数，用户可能不会依赖内核对象来保留指定为内核参数值的对象。

实现不应允许cl_kernel对象持有cl_kernel参数的引用计数，因为没有提供任何机制让用户告诉内核释放该所有权。如果内核拥有内核参数的所有权，那么用户就无法确定何时可以安全地释放与OpenCL对象相关联的用户分配的资源，例如与CL_MEM_USE_HOST_PTR一起使用的 cl_mem备份存储。

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

1. CL_INVALID_KERNEL 如果内核不是有效的内核对象。
2. CL_INVALID_ARG_INDEX 如果arg_index不是有效的参数索引。
3. CL_INVALID_ARG_VALUE 如果指定的参数arg_valude为空，而该参数没有使用__local 限定符声明，则反之亦然。
4. CL_INVALID_MEM_OBJECT 当指定的arg_value不是有效内存对象时，声明为内存对象的参数。
5. CL_INVALID_SAMPLER 当指定的arg_value不是有效的sampler对象时，声明为sampler_t类型的参数。
6. CL_INVALID_ARG_SIZE 如果arg_size与不是内存对象的参数的数据类型大小不匹配，或者参数是内存对象和arg_size!=sizeof（cl_mem）或如果arg_size为零并且参数声明为__local 或如果参数是取样器和arg_size！=sizeof（cl_sampler）。