clEnqueueCopyImageToBuffer
提供: Tommy6
cl_int clEnqueueCopyImageToBuffer (cl_command_queue command_queue, cl_mem src_image, cl_mem dst_buffer, const size_t src_origin[3], const size_t region[3], size_t dst_offset cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)
-1.1() : OpenCL 1.1で削除
+1.1() : OpenCL 1.1で追加
イメージオブジェクト から バッファオブジェクト への複製を行うコマンドを挿入します。
パラメータ
- command_queue
- 複製コマンドを挿入するコマンドキューを指定します。command_queue、src_image、dst_buffer と関連付けられたOpenCLコンテキストは同じでなければなりません。
- src_image
- 複製元となる有効なイメージオブジェクトを指定します。
- dst_buffer
- 複製先となる有効なバッファオブジェクトを指定します。
- src_origin
- src_image 内のどの位置から読み込みを開始するのかの (x, y, z) オフセットをピクセルで指定します。src_image が2Dイメージオブジェクトであるとき、src_origin[2] で指定する z 値は0でなければなりません。
- region
- 複製を行う2Dもしくは3D矩形領域の (width, height, depth) をピクセルで指定します。src_image が2Dイメージオブジェクトであるとき、region[2] で指定する depth 値は1でなければなりません。
- dst_offset
- dst_buffer へ複製を行う際に、書き込み開始位置をどれだけずらすかを指定します。src_image が3Dイメージオブジェクトであるとき、複製領域のバイトサイズ (dst_cb) は width*height*depth*画素あたりのバイトサイズ で求められます。また、src_image が2Dイメージオブジェクトであるとき、複製領域のバイトサイズ (dst_cb) は width*height*画素あたりのバイトサイズ で求められます。
- num_events_in_wait_list
- event_wait_list で指定したイベントオブジェクトの数を指定します。
- event_wait_list
- このコマンドが実行される前に完了していなければならないイベントを指定します。event_wait_list が NULL のとき、このコマンドはどのイベントの完了待ちも行いません。event_wait_list が NULL のとき、num_events_in_wait_list は 0 でなければなりません。event_wait_list が NULL ではないとき、event_wait_list が指す各イベントは有効でなければならず、また num_events_in_wait_list は0より大きな値でなければなりません。event_wait_list に指定したイベントは同期点としてふるまいます。event_wait_list 内のイベントと関連付けられたOpenCLコンテキストと command_queue と関連付けられたOpenCLコンテキストは同じでなければなりません。
- event
- この複製コマンドを識別するイベントオブジェクトが返され、コマンド完了の確認やコマンド完了待ちを行えます。event が NULL のとき、アプリケーションはコマンドの状況確認やコマンド完了待ちを行えなくなります。代わりとして、clEnqueueBarrier を使えます。
エラー
実行が成功した場合、clEnqueueCopyImageToBuffer は CL_SUCCESS を返します。そうでない場合は以下のエラーのうちひとつを返します。
- CL_INVALID_COMMAND_QUEUE - command_queue が有効なコマンドキューでないとき。
- CL_INVALID_CONTEXT - command_queue、src_image、dst_buffer と関連付けられたコンテキストが同じでないとき、あるいは command_queue と関連付けられたコンテキストと event_wait_list 内のイベントと関連付けられたコンテキストが同じでないとき。
- CL_INVALID_MEM_OBJECT - src_image が有効なイメージオブジェクトでないとき。あるいは dst_buffer が有効なバッファオブジェクトでないとき。
- CL_IMAGE_FORMAT_MISMATCH - src_image と dst_image が使用するイメージ形式が同じでないとき。
- CL_INVALID_VALUE - src_origin および src_origin + region が指す2Dもしくは3D矩形領域が、src_image の範囲外のとき。もしくは、dst_offset および dst_offset + dst_cb が指す領域が、dst_buffer の範囲外のとき。
- CL_INVALID_VALUE - src_image が2Dイメージオブジェクトで、dst_origin[2] が0でないもしくは region[2] が1でないとき。
- 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 内のイベントオブジェクトが有効なものでないとき。
- +1.1(CL_MISALIGNED_SUB_BUFFER_OFFSET - dst_buffer がサブバッファオブジェクトで、このサブバッファオブジェクトを作成する際に指定したオフセットが command_queue と関連付けられたデバイスの CL_DEVICE_MEM_BASE_ADDR_ALIGN にアラインされていないとき。)
- +1.1(CL_INVALID_IMAGE_SIZE - src_image の寸法(幅、高さ、行・スライスの長さ)が command_queue と関連付けられたデバイスでサポートされていないとき。)
- CL_MEM_OBJECT_ALLOCATION_FAILURE - src_image もしくは dst_buffer と関連付けられたデータ保存領域のためのメモリの確保に失敗したとき。
- CL_INVALID_OPERATION - command_queue と関連付けられたデバイスがイメージ機能をサポートしていない(clGetDeviceInfo で取得できる CL_DEVICE_IMAGE_SUPPORT が CL_FALSE である)とき。
- +1.1(CL_OUT_OF_RESOURCES - デバイス上でのリソース確保に失敗したとき。)
- CL_OUT_OF_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。
変更記録
脚注
―――― Version 1.1, The OpenCL Specification
より翻訳