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

B.17.1. clEnqueueMapImage

表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

表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は相互排他
の関係を持ちます。

Copyright 2018-2019, by Masaki Komatsu