clSetKernelArg
提供: Tommy6
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（clEnqueueNDRangeKernel() および clEnqueueTask()）の呼び出しで利用されます。
- 引数がメモリオブジェクト（バッファオブジェクトやイメージオブジェクト）であるとき、arg_value にはバッファ/イメージオブジェクトへのポインタを指定します。指定するメモリオブジェクトは、kernel と関連付けられたOpenCLコンテキスト上で作成したものでなければなりません。引数がバッファオブジェクトであれば、NULL 値を指定することもでき、この場合、カーネル内で __global もしくは __constant メモリへのポインタとして宣言された引数への値として NULL 値が設定されます。引数が __local 修飾子付で宣言されたものであるとき、arg_value には NULL を指定しなければなりません。引数型が sampler_t であるとき、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_value には引数値として実際に利用されるデータへのポインタを指定しなければなりません。
- arg_size
- 引数値のサイズを指定します。引数がメモリオブジェクトであるとき、サイズはバッファ/イメージオブジェクト型のサイズでなければなりません。__local 修飾子付で宣言された引数については、指定したサイズは、__local 引数のために確保しなければならないバッファのバイトサイズになります。引数型が sampler_t であるとき、arg_size に指定する値は sizeof(cl_sampler) と等しくなければなりません。他の全ての引数については、引数型のサイズを指定します。
注: カーネルオブジェクトは、clSetKernelArg() で引数値として指定したメモリオブジェクトやサンプラーオブジェクトなどのオブジェクトの参照カウントを更新しません。カーネルに引数値として指定したオブジェクトのリテインをカーネルオブジェクトに頼らないでください[1]。
エラー
実行が成功した場合、clSetKernelArg は CL_SUCCESS を返します。そうでない場合は以下のエラーのうちひとつを返します。
- CL_INVALID_KERNEL - kernel が有効なカーネルオブジェクトでないとき。
- CL_INVALID_ARG_INDEX - arg_index で指定した引数のインデックスが適切でないとき。
- CL_INVALID_ARG_VALUE - __local 修飾子付で宣言されていない引数に対して arg_value で NULL を設定しているとき、あるいは__local 修飾子付で宣言されている引数に対して arg_value で NULL を設定していないとき。
- 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_OUT_OF_RESOURCES - デバイス上でのリソース確保に失敗したとき。
- CL_OUT_OF_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。
変更記録
脚注
- ↑ Implementations shall not allow cl_kernel objects to hold reference counts to cl_kernel arguments, because no mechanism is provided for the user to tell the kernel to release that ownership right. If the kernel holds ownership rights on kernel args, that would make it impossible for the user to tell with certainty when he may safely release user allocated resources associated with OpenCL objects such as the cl_mem backing store used with CL_MEM_USE_HOST_PTR.
―――― Version 1.1, The OpenCL Specification
より翻訳
