clEnqueueNDRangeKernel

OpenCL > OpenCLマニュアル > OpenCLランタイム > OpenCLランタイムAPI > カーネルの実行 > clEnqueueNDRangeKernel

cl_int clEnqueueNDRangeKernel (cl_command_queue command_queue, cl_kernel kernel, cl_uint work_dim, 　　　　　　　　　　　　　　　　　　　　　　const size_t *global_work_offset, const size_t *gloal_work_size, 　　　　　　　　　　　　　　　　　　　　　　const size_t *local_work_size, 　　　　　　　　　　　　　　　　　　　　　　cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)

OpenCLデバイス上でカーネルを実行するコマンドを挿入します。

1.1 : OpenCL 1.1で削除

1.1 : OpenCL 1.1で追加

パラメータ

command_queue

有効なコマンドキューを指定します。カーネルは、command_queue と関連付けられたOpenCLデバイス上での実行待ちに追加されます。

kernel

有効なカーネルオブジェクトを指定します。kernel と関連付けられたOpenCLコンテキストと command_queue と関連付けられたOpenCLコンテキストは同じでなければなりません。

work_dim

グローバルワークアイテム数とワークグループ内のワークアイテム数を決定する際の次元数を指定します。work_dim は、0 より大きく CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS（OpenCL 1.0 では 3） 以下の値でなければなりません。

global_work_offset

現時点では、global_work_offset は NULL でなければなりません。将来的には、要素数 work_dim の配列で、ワークアイテムのグローバルIDを決定する際のオフセット値を指定できます。global_work_offset が NULL のとき（OpenCL 1.0では常に）、グローバルIDはオフセット値 (0,0,...0) で始まる値になります。

global_work_size

要素数 work_dim の配列で、カーネル関数を実行する work_dim 次元のグローバルワークアイテムの数を指定します。グローバルワークアイテムの総数は、global_work_size[0] * global_work_size[1] * ... * global_work_size[work_dim - 1] です。

local_work_size

要素数 work_dim の配列で、カーネル関数を実行する各ワークグループを構成するワークアイテムの数（ワークグループの「サイズ」とも呼ばれる）を指定します。ワークグループ内のワークアイテムの総数は、local_work_size[0] * local_work_size[1] * ... * local_work_size[work_dim - 1] です。ワークグループ内のワークアイテムの総数は、CL_DEVICE_MAX_WORK_GROUP_SIZE の値以下でなければなりません。また、local_work_size[0], ... local_work_size[work_dim - 1] で指定するワークアイテム数は、対応する CL_DEVICE_MAX_WORK_ITEM_SIZES[0], ... CL_DEVICE_MAX_WORK_ITEM_SIZES[work_dim - 1] の値以下でなければなりません。local_work_size は、global_work_size で指定したグローバルワークアイテムをどのようにしてワークグループに分割するのかを決定するために利用されます。local_work_size を指定したとき、global_work_size[0], ... global_work_size[work_dim - ] で指定した値は対応する local_work_size[0], ... local_work_size[work_dim - 1] の値で整除できなければなりません。

kernel を実行するワークグループのサイズは、__attribute__((reqd_work_group_size(X, Y, Z))) 修飾子を利用してプログラムのソース中で指定することもできます。この場合、local_work_size で指定したワークグループサイズは、reqd_work_group_size 属性修飾子で指定した値と一致していなければなりません。

local_work_size には NULL を指定することもでき、この場合、グローバルワークアイテムをどのようにワークグループに分割するかは OpenCL 実装が決定します。

それぞれのワークアイテムは、グローバル識別子を利用して一意に識別できます。カーネル内で利用できる「グローバルID」は、global_work_size と global_work_offset の値から決定されます。OpenCL 1.0 では、グローバルIDは常に (0,0, ... , 0) から始まります。さらに、ワークグループ内で一意のローカルIDを利用してワークアイテムを識別することもできます。カーネル内で利用できる「ローカルID」は、local_work_size の値から決定されます。ローカルIDは常に (0,0, ... , 0) から始まります。

num_events_in_wait_list

event_wait_list で指定したイベントオブジェクトの数を指定します。

event_wait_list

このコマンドが実行される前に完了していなければならないイベントを指定します。event_wait_list が NULL のとき、num_events_in_wait_list は 0 でなければなりません。event_wait_list に指定したイベントは同期点としてふるまいます。event_wait_list 内のイベントと関連付けられたOpenCLコンテキストとcommand_queue と関連付けられたOpenCLコンテキストは同じでなければなりません。

event

このカーネル実行を識別するイベントオブジェクトが返されます。イベントオブジェクトは一意であり、後で特定のカーネル実行を識別するのに利用できます。event が NULL のとき、このカーネル実行に関するイベントは作成されず、アプリケーションがカーネル実行待ちを行えなくなります。

エラー

カーネル実行の挿入に成功すると、clEnqueueNDRangeKernel は CL_SUCCESS を返します。そうでない場合は以下のエラーのうちひとつを返します。

• CL_INVALID_PROGRAM_EXECUTABLE - command_queue と関連付けられたデバイス上で実行可能な、正常にビルドされたプログラムが一つもないとき。
• CL_INVALID_COMMAND_QUEUE - command_queue が有効なコマンドキューでないとき。
• CL_INVALID_KERNEL - kernel が有効なカーネルオブジェクトでないとき。
• CL_INVALID_CONTEXT - command_queue と関連付けられたコンテキストと kernel と関連付けられたコンテキストが同じでないとき、あるいは command_queue と関連付けられたコンテキストと event_wait_list 内のイベントと関連付けられたコンテキストが同じでないとき。
• CL_INVALID_KERNEL_ARGS - カーネル引数が指定されていないとき。
• CL_INVALID_WORK_DIMENSIONS - work_dim が適切な値（1 から CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS （OpenCL 1.0 では 3））でないとき。
• CL_INVALID_GLOBAL_WORK_SIZE - global_work_size が NULL のとき。あるいは、global_work_size[0], ... global_work_size[work_dim - 1] で指定した値のいずれかが 0 のときもしくはカーネルを実行するデバイス上での sizeof(size_t) で与えられる範囲をこえているとき。
• CL_INVALID_GLOBAL_OFFSET - global_work_offset が NULL でないとき。
• CL_INVALID_GLOBAL_OFFSET - いずれかの次元での (global_work_size で指定した値 + 対応する global_work_offset の値) がカーネルを実行するデバイス上での sizeof(size_t) で与えられる範囲をこえているとき。
• CL_INVALID_WORK_GROUP_SIZE - local_work_size を指定していて、global_work_size で指定したワークアイテム数が local_work_size で指定したワークグループサイズの値で整除できないときもしくは、プログラムソース内で __attribute__((reqd_work_group_size(X, Y, Z))) 修飾子を利用して指定したワークグループサイズと local_work_size で指定した値が一致しないとき。
• CL_INVALID_WORK_GROUP_SIZE - local_work_size を指定していて、local_work_size[0] * ... * local_work_size[work_dim - 1] で求められるワークグループ内のワークアイテムの総数が CL_DEVICE_MAX_WORK_GROUP_SIZE の値をこえているとき。
• CL_INVALID_WORK_GROUP_SIZE - local_work_size が NULL で、プログラムソース内で ((reqd_work_group_size(X, Y, Z))) 修飾子を利用してワークグループサイズを宣言しているとき。
• CL_INVALID_WORK_ITEM_SIZE - local_work_size[0], ... local_work_size[work_dim - 1] で指定したワークアイテム数が対応する CL_DEVICE_MAX_WORK_ITEM_SIZES[0], ... CL_DEVICE_MAX_WORK_ITEM_SIZES[work_dim - 1] の値こえているとき。
• CL_MISALIGNED_SUB_BUFFER_OFFSET - カーネルの引数にサブバッファオブジェクトを指定していて、そのサブバッファオブジェクトを作成する際に指定した offset が、command_queue と関連付けられたデバイスの CL_DEVICE_MEM_BASE_ADDR_ALIGN にアラインされていないとき。
• CL_INVALID_IMAGE_SIZE - カーネルの引数にイメージオブジェクトを指定していて、イメージの次元が command_queue と関連付けられたデバイスでサポートされていないとき。
• CL_OUT_OF_RESOURCES - カーネルを実行するのに必要なリソースが不足しているためにカーネル実行を挿入できないとき。一例として、local_work_size を指定すると、レジスタやローカルメモリなどのようなリソースの不足によりカーネルを実行できないことがあります。他の例として、kernel の引数に指定した読み取り専用イメージオブジェクトの数がデバイスの CL_DEVICE_MAX_READ_IMAGE_ARGS をこえているとき、あるいは kernel の引数に指定した書き込み専用イメージオブジェクトの数がデバイスの CL_DEVICE_MAX_WRITE_IMAGE_ARGS をこえているとき、あるいは kernel の引数に指定したサンプラーの数がデバイスの CL_DEVICE_MAX_SAMPLERS をこえているときが挙げられます。
• CL_MEM_OBJECT_ALLOCATION_FAILURE - kernel の引数に指定されたバッファ/イメージオブジェクトに関連付けられたデータ保存のためのメモリ領域の確保に失敗したとき。
• CL_INVALID_EVENT_WAIT_LIST - event_wait_list が NULL で num_events_in_wait_list が 0 より大きいとき。あるいは event_wait_list が NULL でなく num_events_in_wait_list が 0 のとき。あるいは event_wait_list 内のイベントオブジェクトが有効なものでないとき。
• CL_OUT_OF_RESOURCES - デバイス上でのリソース確保に失敗したとき。
• CL_OUT_OF_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。

変更記録

• OpenCL 1.1
  • global_offset の仕様変更
  • エラー CL_INVALID_GLOBAL_OFFSET の仕様変更
  • エラー CL_MISALIGNED_SUB_BUFFER_OFFSET, CL_INVALID_IMAGE_SIZE の追加

脚注

―――― Version 1.1, The OpenCL Specification より翻訳