関数

cl_int

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

kernelの特定の引数に対して引数値を設定。

引数

kernel

有効なカーネル
オブジェクトを指定。

arg_index

引数の添字（インデックス）
を指定。

カーネルが宣言している
引数の数をnとした場合、
左端の引数を0で始めて
n - 1 までの添字で
カーネルの引数の番号
を指定。

一例として、以下の５つ
の引数をもつカーネル
を考察する。

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

引数のインデックスは、
引数nが0、引数mが1、
引数filter_weightsが2、
引数src_imageが3、
引数dst_imageが4となる。

arg_value

arg_indexで指定した
引数に、カーネルの引数
値として渡したいデータ
へのポインタを指定。

arg_valueが指す引数
データは複製され、
clSetKernelArg()が戻
った後にアプリケーション
はarg_valueポインタを
再利用可能。

指定した引数値は、
clSetKernelArg() を
呼び出して kernel の
引数値を変更するまで、全
てのカーネルを挿入する
API（clEnqueueND
RangeKernel() および
clEnqueueTask()）の呼
び出しで使用。

引数がメモリオブジェクト
（バッファオブジェクトや
イメージオブジェクト）
である場合、arg_value
にはバッファ・イメージ・
イメージ配列オブジェクト
へのポインタを指定。指定
するメモリオブジェクトは、
kernelと関連付けられた
OpenCLコンテキスト上で
生成される必要がある。

引数がバッファオブジェク
トの場合、NULL値を指定
できる。またはNULL値に
ポインタを指すことができ、
その際、カーネル内で
__globalもしくは
__constant メモリへの
ポインタとして宣言された
引数への値としてNULL値
が設定される。

引数が__local修飾子付
で宣言された場合、
arg_valueにはNULL値を
指定する必要がある。引数
型がsampler_tである場合
は、arg_valueエントリは
サンプラーオブジェクトへ
のポインタを指定する
必要がある。

引数が組み込み、または
グローバル・コンスタント
アドレス空間内のユーザ定
義型へのポインタであると
き、引数値として指定する
メモリオブジェクトはバッ
ファオブジェクト（または
NULL）である必要がある。
引数が`__constant`修飾
子付で宣言された場合、
メモリオブジェクトのバイ
トサイズは CL_DEVICE_
MAX_CONSTANT_BUFFER_
SIZEの値を超えることはで
きない。また、
__constant修飾子付で
宣言できる引数の数は
CL_DEVICE_MAX_
CONSTANT_ARGSの値を
超えることはできない。

引数型がimage2d_tの
場合、引数として指定す
るメモリオブジェクトは
2Dイメージオブジェクト
となる必要がある。

引数型がimage3d_tの
場合、引数として指定する
メモリオブジェクトは3D
イメージオブジェクトと
なる必要がある。

引数型がimage1d_
buffer_tの場合、引数
として指定するメモリオ
ブジェクトは1Dイメージ
オブジェクトとなる必要
がある。

引数型がimage1d_
array_tの場合、引数と
して指定するメモリオブ
ジェクトは1Dイメージ
配列オブジェクトと
なる必要がある。

引数型がimage2d_
array_tの場合、引数と
して指定するメモリオ
ブジェクトは2Dイメージ
配列オブジェクトとな
る必要がある。

他の全てのカーネル引
数については、
arg_valueに引数値と
して実際に使用される
データへのポインタを指
定する必要がある。

arg_size

引数値のサイズを指定。

引数がメモリオブ
ジェクトの場合、サイズ
はバッファ・イメージ
オブジェクト型のサイズ
となる必要がある。

`__local`修飾子付で
宣言された引数につい
ては、指定したサイズは
、__local 引数のため
に割り当てるバッファの
バイトサイズとなる。

引数型がsampler_tで
ある場合、arg_sizeに
指定する値は
sizeof(cl_sampler)
と等しくなる。他の全て
の引数については、引数
型のサイズを指定。

成功した場合の戻り値

CL_SUCCESS

失敗した場合の戻り値

CL_INVALID_ KERNEL

kernelが有効なカーネル
オブジェクトでない場合。

CL_INVALID_ ARG_INDEX

arg_indexで指定した引
数のインデックスが適切
でない場合。

CL_INVALID_ ARG_VALUE

arg_valueで指定した
引数が有効な値でない
場合。


CL_INVALID_ MEM_OBJECT

メモリオブジェクトと
宣言された引数に対して
arg_valueで設定した
引数値が有効なメモリオブ
ジェクトでない場合。

CL_INVALID_ SAMPLER

 sampler_t型を指定
するように宣言された
引数に対してarg_value
で設定した引数値が有効
なサンプラーオブジェク
トでないとき。

CL_INVALID_ ARG_SIZE

メモリオブジェクトで
はない引数に対して
arg_sizeが引数型と
一致しない場合。

引数がメモリオブジェクト
で、arg_sizeがsizeof
(cl_mem)と一致しない
場合。

引数が`__local`修飾
子付で宣言され、
arg_zeroが0の場合。

引数がサンプラーオブ
ジェクトで、arg_size
がsizeof(cl_sampler)
と一致しない場合。

CL_INVALID_ ARG_VALUE

引数がread_only修飾子
で宣言されたイメージで、
arg_valueがcl_mem_
flagsでCL_MEM_WRITE
を指定したイメージオブ
ジェクトを参照する場合。

イメージ引数がwrite_
only修飾子で宣言され、
arg_valueがcl_mem_
flagsで CL_MEM_READ
を指定したイメージオブ
ジェクトを参照する場合。

CL_OUT_OF_ RESOURCES

デバイス上のOpenCL
実装が必要とする
リソース確保に失敗
した場合。

CL_OUT_OF_ HOST_MEMORY

ホスト上のOpenCL
実装が必要とする
リソース確保に失敗
した場合。