B.14. バッファオブジェクトのマップ

B.14.1. clEnqueueMapBuffer

表B.36 表:clEnqueueMapBuffer

関数
void *
clEnqueueMapBuffer (
    cl_command_queue command_queue,
    cl_mem buffer,
    cl_bool blocking_map,
    cl_map_flags map_flags,
    size_t offset,
    size_t size,
    cl_uint num_events_in_wait_list,
    const cl_event *event_wait_list,
    cl_event *event,
    cl_int *errcode_ret
)
 バッファオブジェクトの領域からホストアドレ
ス空間へのマップを行いマップされた領域へのポ
インタを戻すコマンドを挿入。
 引数
command_queue
マップコマンドを
挿入するコマンドキュー
を指定。
blocking_map
マップ操作をブロッキング
またはノンブロッキング
で行うかを指定。

blocking_mapに
CL_TRUE を指定する場
合、bufferの指定した
領域がマップされるまで
clEnqueueMapBuffer
は戻らない。

blocking_mapに
CL_FALSEを指定する
場合、マップ操作は
ノンブロッキングとなり
clEnqueueMapBuffer
が戻すマップ領域は
コマンドが完了するまで
使用できない。

event引数にはイベント
オブジェクトが戻され
マップコマンドの実行
状況の確認に使用できる。
マップコマンドが完了し
た後は、
clEnqueueMapBuffer
が戻すポインタを使用
してマップ領域の内容
にアクセスが可能となる。
map_flags
マップの設定を行
うビットフィールド。
buffer
有効なバッファオ
ブジェクトを指定。
command_queueと
buffer は同じOpenCL
コンテキスト上で作成さ
れている必要がある。
size
マップする領域の
サイズをバイトで指定
します。
offset
バッファオブジェ
クトのマップを行う際に、
マップの開始位置をどれ
だけずらすかをバイト
で指定。
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_wait_listと関
連付けられたメモリは、関
数が完了の後に、再利用
または解放できる。
event
このコマンドを識別す
るイベントオブジェク
トが戻され、コマンド
完了の確認やコマンド
完了待機をする。event
がNULLの場合、アプリケ
ーションはコマンドの状
況確認やコマンド完了待
ちを行えない。代わりに、
clEnqueueBarrier
WithWaitListを使うこ
とができる。
event_wait_listと
event引数がNULLでない
場合、event引数はevent_
wait_list配列の要素を
参照すべきでない。
errcode_ret
適切なエラーコードを
戻す。errcode_retが
NULLの場合、エラーコ
ードは戻さない。
 成功した場合の戻り値
 マップ操作が成功
すると、clEnqueueMapBuffer
はマップ領域へのポインタ
を返し errcode_ret
に CL_SUCCESS を設定
します。
 失敗した場合の戻り値
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_MISALIGNED_
SUB_BUFFER_OFFSET
bufferがサブバッフ
ァオブジェクトで、この
サブバッファオブジェク
トを生成する際に指定し
たオフセットが
command_queueと関連
付けられたデバイスの
CL_DEVICE_MEM_BASE_
ADDR_ALIGNにアライン
されていない場合。
CL_MAP_
FAILURE
指定された領域のホス
トアドレス空間へのマップ
に失敗した場合。このエ
ラーは、CL_MEM_USE_
HOST_PTRまたはCL_MEM_
ALLOC_HOST_PTRを指定
して生成したバッファオブ
ジェクトでは発生しない。
CL_EXEC_STATUS_
ERROR_FOR_EVENTS_
IN_WAIT_LIST
マップ操作がブロッキン
グで、event_wait_list
内のイベントのいずれか
の実行状況が負の整数値
の場合。
CL_MEM_OBJECT_
ALLOCATION_FAILURE
バッファに関連付けられ
たデータ記憶域に用いるメ
モリ領域を確保するのに失
敗した場合。
CL_INVALID_
OPERATION
バッファがCL_MEM_HOST_
WRITE_ONLYで生成された場合。

CL_MEM_HOST_NO_ACCESS
とCL_MAP_READが
map_flagsに設定された場合。

バッファがCL_MEM_
HOST_READ_ONLY、
またはCL_MEM_HOST_NO_
ACCESSとCL_MAP_WRITE
で生成された場合。

CL_MAP_WRITE_
INVALIDATE_REGION
がmap_flagsに設定された場合。
CL_OUT_OF_
RESOURCES
デバイス上のOpenCL
実装が必要とするリソー
ス確保に失敗した場合。
CL_OUT_OF_
HOST_MEMORY
ホスト上のOpenCL
実装が必要とするリソ
ース確保に失敗した場合。

Copyright 2018-2019, by Masaki Komatsu