clEnqueueReadBuffer
About
バッファオブジェクトからホストメモリへデータを読み込むためのコマンドキューを、OpenCL カーネルに追加します。
- Original Reference
C/C++
cl_int clEnqueueReadBuffer (cl_command_queue command_queue, cl_mem buffer, cl_bool blocking_read, size_t offset, size_t size, void *ptr, cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)
C#
int clEnqueueReadBuffer (IntPtr command_queue, IntPtr buffer, uint blocking_read, uint offset, uint size, IntPtr ptr, uint num_events_in_wait_list, IntPtr[] event_wait_list, IntPtr eventobj);
Args
- command_queue
- 読み込み命令のコマンドキューを指定します。
- buffer
- 有効なバッファオブジェクトを指定します。
- blocking_read
- 読み込み操作が、ブロッキング操作であるか、非ブロッキング操作であるかを指定します。CL_TRUE が指定されるとき、読み込み操作はブロッキング操作となります。バッファのデータを読み込み、ptr に指定されるメモリ領域にコピーされている間は、clEnqueueReadBuffer は処理を返しません。CL_FALSE が指定されるとき、読み込み操作は非ブロッキング操作になり、処理をすぐに返します。そのとき、ptr に指定されるバッファの内容は、読み込み処理が完了するまで利用できません。eventobj は読み込み命令の実行状況を参照するために利用できるイベントオブジェクトが出力されます。
- offset
- バッファオブジェクトから読み込むときのオフセットを byte 単位で指定します。
- size
- 読み込むデータのサイズを byte 単位で指定します。
- ptr
- データの読み込み先となる、ホストメモリ上のバッファのポインタを指定します。
- 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 に指定されたイベントは、同期点 (synchronization points) として動作します。event_wait_list と、command_queue に関連付けられたOpenCLコンテキストは同一のものである必要があります。event_wait_list に関連付けられたメモリは、処理が返った後に、解放ないし再利用することができます。
- eventobj
- このカーネルの実行を識別するイベントオブジェクトの出力先を指定します。イベントオブジェクトは一意であり、カーネルの実行を識別するために利用することができます。NULL を指定するとき、このカーネルの実行はイベントを生成しません。したがってそのような時には、特定のカーネルの実行(のインスタンス)に対し、実行を待機させるクエリまたはキューを実行できません。また、待機状態を参照することもできません。event_wait_list とイベントの引数が NULL でないとき、イベントの引数は event_wait_list 配列の要素を参照するべきではありません。
Notes
host_ptr + offset に設定される引数の値 ptr を用いて、バッファオブジェクトの領域からデータを読み込むために clEnqueueReadBuffer メソッドを呼び出すとき、host_ptr は CL_MEM_USE_HOST_PTR を用いて作られたバッファオブジェクトを読み込むときに指定される、メモリオブジェクトへのポインタです。これは未定義の動作を避けるために、次の条件を満たしている必要があります。
- 対象のバッファオブジェクトから作られた、バッファオブジェクトまたはメモリオブジェクト (buffer or image)を利用する全てのコマンドは、読み込みコマンドが実行されるよりも前に、実行を終了している必要があります。
- 対象のバッファオブジェクトから作られたバッファオブジェクトまたはメモリオブジェクトがマップされていない。
- 対象のバッファオブジェクトから作られたバッファオブジェクトまたはメモリオブジェクトは、読み込みコマンドが実行を終了するまで、他のあらゆるコマンド (command_queue) によって利用されない。
Return
実行に成功したとき、CL_SUCCESSを返します。それ以外のとき、次のうち1つのエラーを返します。
- CL_INVALID_COMMAND_QUEUE
- command_queue に無効な値が指定されたとき。
- CL_INVALID_KERNEL
- kernel に無効な値が指定されたとき。
- CL_INVALID_CONTEXT
- command_queue と関連付けられたコンテキストと buffer と関連付けられたコンテキストが同じでないとき。command_queue と関連付けられたコンテキストと event_wait_list 内のイベントと関連付けられたコンテキストが同じでないとき。
- CL_INVALID_MEM_OBJECT
- buffer に無効な値が指定されたとき。
- CL_INVALID_VALUE
- (offset, size) で指定された読み込み領域が、領域外(out of bounds)になるとき。ptr が NULL のとき。size が 0 のとき。
- 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_MISALIGNED_SUB_BUFFER_OFFSET
- buffer にサブバッファオブジェクトを指定していて、そのサブバッファオブジェクトを生成するときに指定した offset が、command_queue と関連付けられたデバイスの CL_DEVICE_MEM_BASE_ADDR_ALIGN と整列していないとき。
- CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST
- 読み書き操作がブロッキングされていて、event_wait_list に含まれるのいずれかのイベント実行状況が、負の整数値となるとき。
- CL_MEM_OBJECT_ALLOCATION_FAILURE
- buffer に関連付けられた、データを保存するためのメモリ領域の確保に失敗したとき。
- CL_INVALID_OPERATION
- clEnqueueReadBuffer を CL_MEM_HOST_WRITE_ONLY または CL_MEM_HOST_NO_ACCESS で生成された buffer 上で呼び出したとき。
- CL_OUT_OF_RESOURCES
- デバイス上でリソースの確保、割り当てに失敗したとき。
- CL_OUT_OF_HOST_MEMORY
- ホスト上でリソースの確保、割り当てに失敗したとき。