clEnqueueUnmapMemObject/1.0
cl_int clEnqueueUnmapMemObject (cl_command_queue command_queue, cl_mem memobj, void *mapped_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で追加
メモリオブジェクトのマップされた領域のマップ解除を行うコマンドを挿入します。
パラメータ
- command_queue
- 有効なコマンドキューを指定します。
- memobj
- 有効なメモリオブジェクトを指定します。command_queue と memobj と関連付けられたOpenCLコンテキストは同じでなければなりません。
- 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 のとき、アプリケーションはコマンドの状況確認やコマンド完了待ちを行えなくなります。
解説
clEnqueueMapBuffer および clEnqueueMapImage はメモリオブジェクトのマップカウントをインクリメントします。メモリオブジェクトのマップカウントの初期値は0です。同じメモリオブジェクトに対して clEnqueueMapBuffer もしくは clEnqueueMapImage を複数回呼び出すと、呼び出し回数に応じてこのマップカウントがインクリメントされます。clEnqueueUnmapMemObject はメモリオブジェクトのマップカウントをデクリメントします。
clEnqueueMapBuffer および clEnqueueMapImage はマップされたメモリオブジェクトの領域に対する同期点として振る舞います。
メモリオブジェクトのマップされた領域に対してアクセスするOpenCLコマンドの振る舞い
書き込みのためにマップされた（clEnqueueMapBuffer もしくは clEnqueueMapImage の map_flags 引数に CL_MAP_WRITE を指定した）メモリオブジェクトの領域の内容は、この領域のマップ解除が行われるまで未定義であると考えられます。デバイス上で実行されるカーネルによる、書き込みのためにマップされたメモリ領域への読み書きは未定義です。
複数のコマンドキューが、メモリオブジェクの同じ領域もしくは重複する領域を読み込みのためにマップ（map_flags = CL_MAP_READ）できます。デバイス上で実行されるカーネルが、読み込みのためにマップされたメモリ領域の内容を読み込むこともできます。デバイス上で実行されるカーネルが、マップされたメモリ領域に対して行う書き込みの振る舞いは未定義です。メモリオブジェクトの重複する領域に対する、書き込みのためのマッピング（もしくはアンマッピング）は未定義です。
メモリオブジェクトのマップされた領域に対して、書き込みもしくは複製を行うコマンドを挿入するOpenCL関数の振る舞いは未定義です。
エラー
実行が成功した場合、clEnqueueUnmapMemObject は CL_SUCCESS を返します。そうでない場合は以下のエラーのうちひとつを返します。
- CL_INVALID_COMMAND_QUEUE - command_queue が有効なコマンドキューでないとき。
- CL_INVALID_MEM_OBJECT - memobj が有効なメモリオブジェクトでないとき
- CL_INVALID_CONTEXT - command_queue と関連付けられたコンテキストと memobj と関連付けられたコンテキストが同じでないとき、あるいは command_queue と関連付けられたコンテキストと event_wait_list 内のイベントと関連付けられたコンテキストが同じでないとき。
- CL_INVALID_VALUE - mapped_ptr が、memobj に対して clEnqueueMapBuffer もしくは clEnqueueMapImage が返した有効なポインタでないとき。
- 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_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。
変更記録
脚注
