「clEnqueueMapBuffer/1.0」の版間の差分

バッファオブジェクトの領域からホストアドレス空間へのマップを行いマップされた領域へのポインタを返すコマンドを挿入します。

パラメータ

command_queue

マップコマンドを挿入するコマンドキューを指定します。

buffer

有効なバッファオブジェクトを指定します。command_queue と buffer は同じOpenCLコンテキスト上で作成されたものでなければなりません。

blocking_map

マップ操作を、ブロッキングで行うのかノンブロッキングで行うのかを指定します。

blocking_map に CL_TRUE を指定すると、buffer の指定した領域がマップできるようになるまで、clEnqueueMapBuffer は返りません。

blocking_map に CL_FALSE を指定すると、マップ操作はノンブロッキングとなり、clEnqueueMapBuffer が返すマップ領域はコマンドが完了するまで利用できません。event 引数にはイベントオブジェクトが返され、マップコマンドの実行状況の確認に利用できます。マップコマンドが完了すると、clEnqueueMapBuffer が返すポインタを利用してマップ領域の内容にアクセスできます。

map_flags

マップの設定を行うビットフィールドで、CL_MAP_READ を設定すると (offset, cb) で指定したバッファオブジェクトの領域のマップが読み込み用に行われ、CL_MAP_WRITE を設定すると (offset, cb) で指定したバッファオブジェクトの領域のマップが書き込み用に行われます。

offset

バッファオブジェクトのマップを行う際に、マップの開始位置をどれだけずらすかをバイトで指定します。

cb

マップする領域のサイズをバイトで指定します。

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 のとき、アプリケーションはコマンドの状況確認やコマンド完了待ちを行えなくなります。

errcode_ret

適切なエラーコードを返します。errcode_ret が NULL のとき、エラーコードは返されません。

返されるポインタは、offset 地点で始まる cb バイト以上のサイズの領域をマップします。この領域の範囲外へメモリアクセスの結果は未定義です。

エラー

マップ操作が成功すると、clEnqueueMapBuffer はマップ領域へのポインタを返し errcode_ret に CL_SUCCESS を設定します。そうでない場合は NULL を返して errcode_ret に以下のエラーのうちのひとつを設定します。

• CL_INVALID_COMMAND_QUEUE - command_queue が有効なコマンドキューでないとき。
• CL_INVALID_CONTEXT - command_queue と関連付けられたコンテキストと buffer と関連付けられたコンテキストが同じでないとき、あるいは command_queue と関連付けられたコンテキストと event_wait_list 内のイベントと関連付けられたコンテキストが同じでないとき。
• CL_INVALID_MEM_OBJECT - buffer が有効なバッファオブジェクトでないとき。
• CL_INVALID_VALUE - (offset, cb) で指定したマップ領域が範囲外のとき。あるいは map_flags に設定した値が適切でないとき。
• 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_MAP_FAILURE - 指定された領域のホストアドレス空間へのマップに失敗した時。このエラーは、CL_MEM_USE_HOST_PTR もしくは CL_MEM_ALLOC_HOST_PTR を指定して作成されたバッファオブジェクトでは発生し得ません。
• CL_MEM_OBJECT_ALLOCATION_FAILURE - buffer と関連付けられたデータ保存領域のためのメモリの確保に失敗したとき。
• CL_OUT_OF_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。

変更記録

脚注