clEnqueueMapImage/1.0
void *clEnqueueMapImage (cl_command_queue command_queue, cl_mem image, cl_bool blocking_map, cl_map_flags map_flags, const size_t origin[3], const size_t region[3], 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 の指定した領域がマップされるまで、clEnqueueMapImage は返りません。
- blocking_map に CL_FALSE を指定すると、マップ操作はノンブロッキングとなり、clEnqueueMapImage が返すマップ領域はコマンドが完了するまで利用できません。event 引数にはイベントオブジェクトが返され、マップコマンドの実行状況の確認に利用できます。マップコマンドが完了すると、clEnqueueMapImage が返すポインタを利用してマップ領域の内容にアクセスできます。
- map_flags
- マップの設定を行うビットフィールドで、CL_MAP_READ を設定すると (origin, region) で指定したイメージオブジェクトの領域のマップが読み込み用に行われ、CL_MAP_WRITE を設定すると (origin, region) で指定したイメージオブジェクトの領域のマップが書き込み用に行われます。
- origin
- マップされる2Dもしくは3D矩形領域の (x, y, z) オフセットをピクセルで指定します。image が2Dイメージオブジェクトであるとき、origin[2] で指定する z 値は0でなければなりません。
- region
- マップされる2Dもしくは3D矩形領域の (width, height, depth) をピクセルで指定します。image が2Dイメージオブジェクトであるとき、region[2] で指定する depth 値は1でなければなりません。
- image_row_pitch
- マップされる領域での走査線の長さをバイトで返します。非 NULL の値を指定しなければなりません。
- image_slice_pitch
- マップされる領域での2Dスライスの長さをバイトで返します。image が2Dイメージオブジェクトでこの引数が NULL でないとき、0が返されます。image が3Dイメージオブジェクトであるとき、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
- このマップコマンドを識別するイベントオブジェクトが返され、コマンド完了の確認やコマンド完了待ちを行えます。event が NULL のとき、アプリケーションはコマンドの状況確認やコマンド完了待ちを行えなくなります。
- errcode_ret
- 適切なエラーコードを返します。errcode_ret が NULL のとき、エラーコードは返されません。
解説
返されたポインタは、2Dイメージオブジェクトであれば origin で始まる image_row_pitch*region[1] + region[0] ピクセル以上のサイズの領域、3Dイメージオブジェクトであれば origin で始まる image_slice_pitch*region[2] + image_row_pitch*region[1] + region[0] ピクセル以上のサイズの領域をマップします。この領域の範囲外へのメモリアクセスの結果は未定義です。
イメージオブジェクトが mem_flags に CL_MEM_USE_HOST_PTR を指定して作成したものであるとき、以下が適用されます:
- clCreateImage2D、clCreateImage3D に指定した host_ptr 内のマップ領域のビット列が、clEnqueueMapImage 完了時点で最新であることが保証されます。
- clEnqueueMapImage が返すポインタの値は、イメージオブジェクトを作成する際に指定した host_ptr から派生します。
マップされたイメージオブジェクトは、clEnqueueUnmapMemObject を利用してマップの解除を行います。
エラー
マップ操作が成功すると、clEnqueueMapImage はマップ領域へのポインタを返し errcode_ret に CL_SUCCESS を設定します。そうでない場合は NULL を返して errcode_ret に以下のエラーのうちのひとつを設定します。
- CL_INVALID_COMMAND_QUEUE - command_queue が有効なコマンドキューでないとき。
- CL_INVALID_CONTEXT - command_queue と関連付けられたコンテキストと image と関連付けられたコンテキストが同じでないとき、あるいは command_queue と関連付けられたコンテキストと event_wait_list 内のイベントと関連付けられたコンテキストが同じでないとき。
- CL_INVALID_MEM_OBJECT - image が有効なイメージオブジェクトでないとき。
- CL_INVALID_VALUE - (origin, origin + region) で指定したマップ領域が範囲外のとき。あるいは map_flags に設定した値が適切でないとき。
- CL_INVALID_VALUE - image が2Dイメージオブジェクトで、origin[2] が0でないもしくは region[2] が1でないとき。
- CL_INVALID_VALUE - image_row_pitch が NULL のとき。
- CL_INVALID_VALUE - image が3Dイメージオブジェクトで、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_MAP_FAILURE - 指定された領域のホストアドレス空間へのマップに失敗した時。このエラーは、CL_MEM_USE_HOST_PTR もしくは CL_MEM_ALLOC_HOST_PTR を指定して作成されたイメージオブジェクトでは発生し得ません。
- CL_MEM_OBJECT_ALLOCATION_FAILURE - image と関連付けられたデータ保存領域のためのメモリの確保に失敗したとき。
- CL_INVALID_OPERATION - command_queue と関連付けられたデバイスがイメージ機能をサポートしていない（clGetDeviceInfo で取得できる CL_DEVICE_IMAGE_SUPPORT が CL_FALSE である）とき。
- CL_OUT_OF_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。
変更記録
脚注
