関数

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
実装が必要とするリソ
ース確保に失敗した場合。