clEnqueueReadImage
提供: Tommy6
cl_int clEnqueueReadImage (cl_command_queue command_queue, cl_mem image, cl_bool blocking_read, const size_t origin[3], const size_t region[3], size_t row_pitch, size_t slice_pitch, void *ptr, 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で追加
2Dもしくは3Dイメージオブジェクトからホストメモリへの読み込みを行うコマンドを挿入します。
パラメータ
- command_queue
- 読み込みコマンドを挿入するコマンドキューを指定します。command_queue と image は同じOpenCLコンテキスト上で作成されたものでなければなりません。
- image
- 有効な2Dもしくは3Dイメージオブジェクトを指定します。
- blocking_read
- 読み込み操作を、ブロッキングで行うのかノンブロッキングで行うのかを指定します。
- blocking_read に CL_TRUE を指定すると、読み込みコマンドはブロッキングとなり、バッファデータを読み込んで ptr が指すメモリ領域に複製し終わるまで、clEnqueueReadImage は返りません。
- blocking_read に CL_FALSE を指定すると、読み込みコマンドはノンブロッキングとなり、clEnqueueReadImage はノンブロッキング読み込みコマンドを挿入して返ります。読み込みコマンドが完了するまで、ptr が指すバッファの内容は利用できません。event 引数にはイベントオブジェクトが返され、読み込みコマンドの実行状況の確認に利用できます。読み込みコマンドが完了すると、ptr が指すバッファの内容をアプリケーションが利用できるようになります。
- origin
- 読み込みを行うイメージ内での (x, y, z) オフセットをピクセルで指定します。image が2Dイメージオブジェクトであるとき、origin[2] で指定する z 値は0でなければなりません。
- region
- 読み込みを行う2Dもしくは3D矩形領域の (width, height, depth) をピクセルで指定します。image が2Dイメージオブジェクトであるとき、region[2] で指定する depth 値は1でなければなりません。
- row_pitch
- 各行が使用する長さをバイトで指定します。この値は、画素のバイトサイズ*width 以上でなければなりません。row_pitch に0を指定すると、画素のバイトサイズ*width に基づいて適切な長さが計算されます。
- slice_pitch
- 読み込みを行う3Dイメージ内の3D領域の各2Dスライスが使用する長さをバイトで指定します。image が2Dイメージオブジェクトである時、この値は0でなければなりません。この値は、row_pitch*heigth 以上でなければなりません。slice_pitch に0を指定すると、row_pitch*height に基づいて適切な長さが計算されます。
- ptr
- 読み込んだイメージデータの保存先となるホストメモリバッファへのポインタを指定します。
- 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 のとき、アプリケーションはコマンドの状況確認やコマンド完了待ちを行えなくなります。
エラー
実行が成功した場合、clEnqueueReadImage は CL_SUCCESS を返します。そうでない場合は以下のエラーのうちひとつを返します。
- CL_INVALID_COMMAND_QUEUE - command_queue が有効なコマンドキューでないとき。
- CL_INVALID_CONTEXT - command_queue と関連付けられたコンテキストと image と関連付けられたコンテキストが同じでないとき、あるいは command_queue と関連付けられたコンテキストと event_wait_list 内のイベントと関連付けられたコンテキストが同じでないとき。
- CL_INVALID_MEM_OBJECT - image が有効なイメージオブジェクトでないとき。
- CL_INVALID_VALUE - origin と region で指定した読み込み領域が範囲外のとき。あるいは ptr が NULL のとき。
- CL_INVALID_VALUE - image が2Dイメージオブジェクトで origin[2] が0でない、あるいは region[2] が1でない、あるいは slice_pitch が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 内のイベントオブジェクトが有効なものでないとき。
- +1.1(CL_INVALID_IMAGE_SIZE - image の寸法（幅、高さ、行・スライスの長さ）が command_queue と関連付けられたデバイスでサポートされていないとき。)
- CL_MEM_OBJECT_ALLOCATION_FAILURE - image と関連付けられたデータ保存領域のためのメモリの確保に失敗したとき。
- CL_INVALID_OPERATION - command_queue と関連付けられたデバイスがイメージ機能をサポートしていない（clGetDeviceInfo で取得できる CL_DEVICE_IMAGE_SUPPORT が CL_FALSE である）とき。
- +1.1(CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST - 読み込みコマンドがブロッキングで、かつ event_wait_list 内のイベントのいずれかの実行状況が負の整数値のとき。)
- +1.1(CL_OUT_OF_RESOURCES - デバイス上でのリソース確保に失敗したとき。)
- CL_OUT_OF_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。
変更記録
脚注
―――― Version 1.1, The OpenCL Specification
より翻訳
