B.17. イメージオブジェクトのマッピング

Prev		Next

B.17.1. clEnqueueMapImage

Table B.49. 表：clEnqueueMapImage

関数
void *	clEnqueueMapImage ( cl_command_queue command_queue, cl_mem image, cl_bool blocking_map, cl_map_flags map_flags, const size_t origin, const size_t region, size_t image_row_pitch, size_t image_slice_pitch, cl_uint num_events_in_wait_list, const cl_event event_wait_list, cl_event event, cl_int *errcode_ret )
イメージオブジェクトの領域からホストアドレス空間へのマップを行いマップされた領域へのポインタを戻すコマンドを挿入。
引数
command_queue		マップコマンドを挿入するコマンドキューを指定。
image		有効なイメージオブジェクトを指定。command_queueと imageと関連付けられた OpenCLコンテキストは同じとなる必要がある。
blocking_map		マップ操作を、ブロッキングで行うのかノンブロッキングで行うのかを指定。 blocking_mapにCL_TRUEを指定すると、imageの指定した領域がホストアドレス空間にマップされるまでclEnqueue MapImageは戻らない。アプリケーションはclEnqueue MapImageから戻るポインタを使用してマップされた領域にアクセスできる。 blocking_mapにCL_FALSEを指定すると、マップ操作はノンブロッキングとなり、 clEnqueueMapImageが戻すマップ領域はコマンドが完了するまで利用できません。 event引数にはイベントオブジェクトが返され、マップコマンドの実行状況の確認に利用できる。マップコマンドが完了すると、clEnqueue MapImageが戻すポインタを利用してマップ領域の内容にアクセスできる。
map_flags		マップの設定を行うビットフィールド。
origin		1D、2D、3Dイメージ内の (x,y,z)オフセットをピクセルで指定。 2Dイメージ配列内の(x,y) オフセットとイメージインデックスを指定。 1Dイメージ配列内の(x)オフセットとイメージインデックスを指定。イメージが2Dイメージオブジェクトの場合、 origin[2]は0となる。イメージが1Dイメージまたは1Dイメージバッファオブジェクトの場合、 origin[1]とorigin[2] は0となる。イメージが1Dイメージ配列オブジェクトの場合、 origin[1]は1Dイメージ配列のインデックス（添字）を記述する。イメージが2Dイメージ配列オブジェクトの場合、 origin[2]は2Dイメージ配列のインデックス（添字）を記述する。
region		1D、2D、3D矩形領域の (width, height, depth) をピクセルで定義。 2D矩形領域の(width, height)をピクセルで定義し、2Dイメージ配列のイメージ個数の定義。 1D矩形領域の(width)をピクセルで定義し、1Dイメージ配列のイメージ個数を定義。イメージが2Dイメージオブジェクトの場合、 region[2]は1となる。イメージが1Dイメージまたは、1Dイメージバッファオブジェクトの場合、 region[1]とregion[2] は1となる。イメージが1Dイメージ配列オブジェクトの場合、 region[2]は1となる。 regionの値は0とはならない。
image_row_ pitch		マップされる領域での走査線の長さをバイトで返します。非NULLの値を指定する必要がある。
image_slice_ pitch		マップされる領域での3Dイメージの2Dスライスのサイズ、または1D/2Dイメージ、 1D/2Dイメージ配列のサイズをバイトで戻す。 imageが2Dイメージオブジェクトでこの引数がNULLでない場合、 0が戻される。 imageが3Dイメージオブジェクト、1D/2Dイメージ配列である場合、 image_slice_pitch には非NULLの値を指定する必要がある。
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の場合、アプリケーションはコマンドの状況確認やコマンド完了待ちができなくなる。 event_wait_listと eventがNULLでない場合、eventはevent_ wait_list配列の要素を参照すべきでない。 clEnqueueBarrier WithWaitListを代わりに使うことができる。 event_wait_listと event引数NULLでない場合、event引数は event_wait_list内の要素を参照すべきでない。
errcode_ret		適切なエラーコードを返します。 errcode_retがNULL の場合、エラーコードは返されません。
成功した場合の戻り値
マップ操作が成功すると、 clEnqueueMapImage はマップ領域へのポインタを返し errcode_ret に CL_SUCCESS を設定します。
失敗した場合の戻り値
CL_INVALID_ COMMAND_QUEUE		command_queue が有効なコマンドキューでない場合。
CL_INVALID_ CONTEXT		command_queue とimageに関連付けられたcontextが同じでない場合。 command_queueと event_wait_list 内のeventsに関連付けられたcontext が同じでない場合。
CL_INVALID_ MEM_OBJECT		imageが有効なイメージオブジェクトでない場合。
CL_INVALID_ VALUE		(origin, origin+region)で与えられるマップされた領域が範囲外である場合。 map_flagsに指定された値が有効でない場合。
CL_INVALID_ VALUE		originとregionの値が規則に従わない場合。
CL_INVALID_ VALUE		image_row_pitch がNULLの場合。
CL_INVALID_ VALUE		イメージが3Dイメージ、1D/2Dイメージ配列オブジェクトのいずれかで、 image_slice_pitch がNULLの場合。
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_INVALID_ IMAGE_SIZE		イメージの寸法（幅、高さ、行・スライスの長さ）がcommand_queue と関連付けられたデバイスでサポートされていない場合。
CL_IMAGE_ FORMAT_NOT_ SUPPORTED		イメージ型式（image channel orderやデータ型）が queueに関連付けられたデバイスにサポートされていない場合。
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		command_queueに関連付けられるデバイスがイメージをサポートしない場合。
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 実装が必要とするリソース確保に失敗した場合。

B.17.2. cl_map_flags

Table B.50. 表：cl_map_flags

cl_map_flags	詳細
CL_MAP_READ	このフラグはメモリオブジェクト内でマップされた領域が読み込み用にマップされることを指定。 clEnqueueMap {Buffer \| Image} コマンドが完了した際に、 clEnqueueMap {Buffer \| Image} が戻すポインタは、マップされた領域の最新ビットを持つことを保証します。
CL_MAP_WRITE	このフラグはメモリオブジェクト内でマップされた領域が書き込み用にマップされることを指定。 clEnqueueMap {Buffer \| Image} コマンドが完了した際に、clEnqueueMap {Buffer \| Image} が戻すポインタは、マップされた領域の最新ビットを持つことを保証します。
CL_MAP_WRITE_ INVALIDATE_REGION	このフラグはメモリオブジェクト内でマップされた領域が書き込み用にマップされることを指定。マップされた領域が上書きされる際には、マップされる領域の内容は捨てられる。このフラグによって、 clEnqueueMap {Buffer \| Image} コマンドが完了した際に、 clEnqueueMap {Buffer \| Image} が戻すポインタは、マップされた領域の最新ビットを持つことを保証しなくなります。 CL_MAP_READまたはCL_MAP_WRITEと CL_MAP_WRITE_ INVALIDATE_ REGIONは相互排他の関係を持ちます。