Top > Programming > OpenCL > JpnReference > clSetKernelArg
Last-modified: Fri, 13 Sep 2013 10:07:14 JST
Counter:2258 Today:1 Yesterday:1 Online:4
このエントリーをはてなブックマークに追加

clSetKernelArg

About

OpenCL カーネルオブジェクトの引数を設定します。

C/C++

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

C#

int clSetKernelArg (IntPtr kernel,
                    uint arg_index,
                    uint arg_size,
                    ref IntPtr arg_value);

Args

  • kernel
    • 有効なOpenCLカーネルオブジェクトを指定します。
  • arg_index
    • カーネルに定義される引数のインデックスを指定します。
  • arg_size
    • 引数に与える値の大きさを指定します。
  • arg_value
    • arg_index で指定した引数に与える値を指定します。

arg_value 詳細

原文の翻訳を試みたものです。

arg_index で指定された引数の値として使用するべきデータへのポインタを指定します。arg_value によって示される引数のデータはコピーされます。そのため、arg_value に指定したポインタは、clSetKernelArg から処理が戻った後に再利用することができます。引数として指定された値は、カーネルへの実行 (enqueue) に関する全てのAPIの呼び出し (clEnqueueNDRangeKernel および clEnqueueTask) で利用され、カーネルに対して clSetKernelArg を実行して値を変更するまで利用されます。

要約 : ポインタが示す値は複製される。再び SetKernelArg が対象の引数に実行されるまで与えた値は変わらず利用される。

引数がメモリオブジェクト (バッファ、画像または画像の配列) であるとき、arg_value は適切なバッファ、画像または画像の配列オブジェクトへの適切なポインタとして登録されます。メモリオブジェクトはそのカーネルオブジェクトと関連付けられたコンテキストによって作られる必要があります。引数がメモリオブジェクトであり、カーネル中の、__global または __constant として定義される引数に NULL を与えるためのポインタとして利用するとき、arg_value に指定するポインタは NULL または NULL へのポインタであっても良いです。引数が __local 修飾子で定義されるとき、arg_value は NULL である必要があります。引数が sampler_t 型であるとき、arg_value は サンプラーオブジェクトに対するポインタである必要があります。

要約 : バッファオブジェクトの時、引数はポインタで、引き数に NULL を与えるときは NULL を指定して良い。__local 修飾子が付けられた引数に対する実行のとき、arg_value は NULL である必要がある。

引数が OpenCL に実装される (ビルトインな) スカラー(scalar) や ベクター(vector) 型であるとき、または、ユーザがグローバルまたは定数アドレスの領域に定義した構造体であるとき、引数の値として指定されるメモリオブジェクトはバッファオブジェクト (または NULL) である必要があります。引数が __constant 修飾子を付けて定義されるとき、メモリオブジェクトの byte 単位の大きさは、CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE を超えることができません。さらに、__constant メモリへのポインタとして定義される引数の数は、CL_DEVICE_MAX_CONSTANT_ARGS の値を超えることができません。

要約 : scalar、vector、構造体 に対する引数であるとき、バッファオブジェクトである必要がある。__constant が付けられた引数に渡せるデータの大きさと、その数は CL_DEVICE_MAX_CONSTANT_BUFFER_SIZE ないし CL_DEVICE_MAX_CONSTANT_ARGS の値を超えないようにする必要がある。

引数が image2d_t 型で定義されるとき、引数の値として指定するメモリオブジェクトは、2次元の画像オブジェクトである必要があります。引数が image3d_t 型で定義されるとき、引数の値として指定するメモリオブジェクトは、3次元の画像オブジェクトである必要があります。引数が image1d_t 型で定義されるとき、引数の値として指定するメモリオブジェクトは、1次元の画像オブジェクトである必要があります。引数が image1d_buffer_t 型で定義されるとき、引数の値として指定するメモリオブジェクトは、1次元の画像オブジェクトバッファである必要があります。引数が image1d_array_t 型で定義されるとき、引数の値として指定するメモリオブジェクトは、1次元の画像配列オブジェクトである必要があります。引数が image2d_array_t 型で定義されるとき、引数の値として指定するメモリオブジェクトは、2次元の画像配列オブジェクトである必要があります。

要約 : 画像に関する型を引数とするとき、適切なメモリオブジェクトを指定する必要がある。

他の全てのカーネル引数については、 arg_value は引数の値として利用される実データへのポインタでなければなりません。

Return

実行に成功したとき、CL_SUCCESS を返します。それ以外のとき、次のうち1つのエラーを返します。

  • CL_INVALID_KERNEL
    • kernel に無効な値が指定されたとき。
  • CL_INVALID_MEM_OBJECT
    • arg_value に無効なメモリオブジェクトが指定されたとき。
  • CL_INVALID_SAMPLER
    • arg_value に無効なサンプラーオブジェクトが指定されたとき。
  • CL_INVALID_ARG_INDEX
    • arg_index に無効な値が指定されたとき。
  • CL_INVALID_ARG_VALUE
    • arg_value に無効な値が指定されたとき。'__local' 修飾子が宣言されていない引数に NULL を設定しているとき。'__local' 修飾子が宣言されている引数に NULL を設定していないとき。
  • CL_INVALID_ARG_SIZE
    • arg_size に指定したデータの大きさと、メモリオブジェクトでない引数のデータ型の大きさが一致しないとき。arg_size が 0 で、対象の引数が '__local' 修飾子付きで定義されるとき。引数がメモリオブジェクトで、'arg_size != sizeof(cl_mem)'が成立するとき。引数が sampler で、'arg_size != sizeof(cl_sampler)'が成立するとき。
  • CL_OUT_OF_RESOURCES
    • デバイス上でリソースの確保、割り当てに失敗したとき。
  • CL_OUT_OF_HOST_MEMORY
    • ホスト上でリソースの確保、割り当てに失敗したとき。