Top > Programming > OpenCL > JpnReference > clEnqueueNDRangeKernel
Last-modified: Fri, 13 Sep 2013 21:32:23 JST
Counter:2432 Today:1 Yesterday:0 Online:6
このエントリーをはてなブックマークに追加

clEnqueueNDRangeKernel

About

OpenCLデバイス上のOpenCLカーネルにコマンドキューを追加します

C/C++

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

C#

int clEnqueueNDRangeKernel ( IntPtr command_queue,
                             IntPtr kernel,
                             uint work_dim,
                             IntPtr[] global_work_offset,
                             IntPtr[] global_work_size,
                             IntPtr[] local_work_size,
                             uint num_events_in_wait_list,
                             IntPtr[] event_wait_list,
                             IntPtr eventobj);

Args

  • command_queue
    • 有効なコマンドキューを指定します。カーネルはコマンドキューに関連付けられたデバイス上で実行するように追加されます。
  • kernel
    • 有効なカーネルオブジェクトを指定します。kernel と command_qaueue に関連付けられたOpenCLコンテキストは、同一のものである必要があります。
  • work_dim
    • ワークグループ内のグローバルワークアイテムおよびワークアイテムの次元数を指定します。work_dim は 0 より大きく、CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS 以下の値である必要があります。
  • global_work_offset
    • ワークアイテムのグローバルIDを計算するときに利用されるオフセットを指定します。NULL を指定するとき、グローバル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
    • カーネルによって指定された、カーネルが実行するワークグループを構成するワークアイテムの数(ワークグループのサイズとも呼ぶ)を指定します。ワークグループ内のワークアイテムの総数は、local_work_size[0] *... * local_work_size[work_dim - 1] で求まります。ワークグループ内のワークアイテムの総数は、clGetDeviceInfo によって取得できる、OpenCL Device Query のテーブルに定義される、CL_DEVICE_MAX_WORK_GROUP_SIZE 以下である必要があります。また、clGetDeviceInfo と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-1] に指定される値は、local_work_size[0],…local_work_size[work_dim-1]に指定された対応する値によって、それぞれ割り切れる必要があります。NULL を指定するとき、OpenCLが、グローバルアイテムを適切なワークグループに分割する方法を決定します。
  • num_events_in_wait_list
    • event_wait_list に指定されるイベントオブジェクトの数を指定します。
  • event_wait_list
    • このコマンドが実行される前に完了する必要があるイベントを指定します。NULL を指定するとき、任意のイベントを待機しません。NULL を指定するとき、num_events_in_wait_list は 0 である必要があります。NULL でないとき、 num_events_in_wait_list は 0 より大きい値である必要があります。event_wait_list と、command_queue に関連付けられたOpenCLコンテキストは同一のものである必要があります。event_wait_list に関連付けられたメモリは、処理が返った後に、解放ないし再利用することができます。
  • event
    • このカーネルの実行を識別するイベントオブジェクトの出力先を指定します。イベントオブジェクトは一意であり、カーネルの実行を識別するために利用することができます。NULL を指定するとき、このカーネルの実行はイベントを生成しません。したがってそのような時には、特定のカーネルの実行(のインスタンス)に対し、実行を待機させるクエリまたはキューを実行できません。

Return

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

  • 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_DIMENTION
    • work_dim に無効な値がしていされたとき。
  • CL_INVALID_GROBAL_WORK_SIZE
    • global_work_size が NULL であるとき。global_work_size[0],…global_work_size[work_dim-1] に指定された何れかの値が 0 または、カーネル実行が追加(enqueue)されるデバイス上で、sizeof(size_t) によって得られる範囲を超えているとき。
  • CL_INVALID_GROBAL_OFFSET
    • global_work_size とそれに対応するあらゆる次元の global_work_offset の値の合計が、カーネル実行が追加されるデバイス上で、sizeof(size_t) より大きいくなるとき。
  • CL_INVALID_WORK_GROUP_SIZE
    • local_work_size が指定されるときに、ワークアイテムの数が global_work_size によって指定され、local_work_size によって与えられるワークグループの数によって割り切れないとき。または、ワークグループのサイズが、kernel が利用するプログラムソース中の、修飾子__attribute__((reqd_work_group_size(X, Y, Z)))とマッチしないとき。
  • CL_INVALID_WORK_GROUP_SIZE
    • local_work_size が指定され、local_work_size[0] *... local_work_size[work_dim-1] から求まるワークグループに含まれるワークアイテムの総数が、clGetDeviceInfo によって得られる OpenCL Device Queries のテーブル中の、CL_DEVICE_MAX_WORK_GROUP_SIZE よりも大きいとき。
  • CL_INVALID_WORK_GROUP_SIZE
    • local_work_size が NULL で、プログラムソース中の修飾子 __attribute__((reqd_work_group_size(X, Y, Z)))が、kernel 用に、ワークグループのサイズを指定するために使用されるとき。
  • 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_INVALID_IMAGE_FORMAT
    • カーネルの引数にイメージオブジェクトが指定され、そのイメージ(の画像チャネルの順序とデータ型)が command_queue と関連付けられたデバイスによってサポートされないとき。
  • 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
    • ホスト上でリソースの確保、割り当てに失敗したとき。