B.16. イメージの読み込みと書き込み

Prev		Next

B.16.1. clEnqueueReadImageとclEnqueueWriteImage

Table B.44. 表：clEnqueueReadImageとclEnqueueWriteImage

関数
cl_int	clEnqueueReadImage ( cl_command_queue command_queue, cl_mem image, cl_bool blocking_read, const size_t origin, const size_t region, size_t row_pitch, size_t slice_pitch, void ptr, cl_uint num_events_in_wait_list, const cl_event event_wait_list, cl_event *event )
cl_int	clEnqueueWriteImage ( cl_command_queue command_queue, cl_mem image, cl_bool blocking_write, const size_t origin, const size_t region, size_t input_row_pitch, size_t input_slice_pitch, const void * ptr, cl_uint num_events_in_wait_list, const cl_event event_wait_list, cl_event event )
イメージオブジェクトまたはイメージ配列オブジェクトからホストメモリに読み込むコマンドを挿入。ホストメモリからイメージオブジェクトまたはイメージ配列オブジェクトへの書き込みを行うコマンドを挿入。
引数
command_queue	読み込みまたは、書き込みコマンドを挿入するコマンドキューを指定。 command_queueとimage は同じOpenCLコンテキスト上で生成される必要がある。
image	有効なイメージオブジェクトまたはイメージ配列オブジェクトを指定します。
blocking_read(read)または blocking_write(write)	読み込み操作をブロッキング、またはノンブロッキングで行うのかを指定。 blocking_readに CL_TRUEを指定すると、読み込みコマンドはブロッキングとなり、バッファデータを読み込んでptrが指すメモリ領域に複製し終わるまで、clEnqueueReadImage は戻らない。 blocking_readにCL_FALSE を指定すると、読み込みコマンドはノンブロッキングとなり、clEnqueueReadImageはノンブロッキング読み込みコマンドを挿入して戻る。読み込みコマンドが完了するまで、 ptrが指すバッファの内容は利用できない。event引数にはイベントオブジェクトが返され、読み込みコマンドの実行状況の確認に利用できます。読み込みコマンドが完了すると、ptrが指すバッファの内容をアプリケーションが利用できるようになる。書き込み操作をブロッキング、またはノンブロッキングで行うのかを指定。 blocking_write に CL_TRUE を指定すると、OpenCL実装は ptrが参照するデータを複製しコマンドキューに書き込み操作を挿入。 clEnqueueWriteImageが戻った後は、アプリケーションはptrが指すメモリを再利用できる。 blocking_writeに CL_FALSEを指定すると、 OpenCL実装はptrを使用してノンブロッキングで書き込みを行う。書き込みがノンブロッキングで行われるため、実装は直ちに戻る。呼び出しが戻った後も、ptrが指すメモリを再利用することはできない。event引数に戻されるイベントオブジェクトを利用し、書き込みコマンドの実行状況を確認できます。書き込みコマンドが完了すると、アプリケーションは ptrが指すメモリを再利用できるようになる。
origin	読み込みを行うイメージ内での (x, y, z) オフセットをピクセルで指定。 image が2Dイメージオブジェクトであるとき、origin[2] で指定する z 値は0でなければなりません。 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とはならない。
row_pitch(read)と input_row_pitch(write)	各行が使用する長さをバイトで指定。この値は、画素のバイトサイズwidth 以上となる必要がある。row_pitchに0を設定すると、画素のバイトサイズwidth に基づいて適切な長さが計算される。
slice_pitch(read) とinput_slice_pitch(write)	読み込み、または書き込まれる3Dイメージ内の3D領域の各2Dスライス、または1Dまたは2 Dイメージ配列の各イメージが使用する長さを指定(バイトで表す)。イメージが1Dまたは2Dの場合は、この引数は0となります。この引数は row_pitchheigth以上となります。 slice_pitch （またはinput_slice_pitch）に0を指定すると、 row_pitchheightに基づいて適切な長さが計算される。
ptr	読み込む、または書き込むイメージデータの保存先となるホストメモリバッファへのポインタを指定。
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配列の要素を参照すべきでない。
成功した場合の戻り値
CL_SUCCESS
失敗した場合の戻り値
CL_INVALID_ COMMAND_QUEUE		command_queueが有効なコマンドキューでない場合。
CL_INVALID_ CONTEXT		command_queueと imageに関連付けられた contextが同じでない場合。 command_queueとevent_ wait_list内のイベントに関連付けられたcontext が同じでない場合。
CL_INVALID_ MEM_OBJECT		imageが有効なイメージオブジェクトでない場合。
CL_INVALID_ VALUE		originとregionで指定された、読み込まれる、書き込まれる領域が、境界外にあるか、ptrがNULL値の場合。
CL_INVALID_ VALUE		originとregionの値が、 originとregionの規則を守っていない場合。
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		イメージの寸法（幅、高さ、行・スライスの長さ）がqueueに関連付けられたデバイスにサポートされていない場合。
CL_IMAGE_ FORMAT_NOT_ SUPPORTED		イメージ型式（image channel orderやデータ型）がqueueに関連付けられたデバイスにサポートされていない場合。
CL_MEM_OBJECT_ ALLOCATION_FAILURE		イメージに関連付けられたデータ保存領域のメモリの確保に失敗した場合。
CL_INVALID_ OPERATION		command_queueに関連付けられたデバイスがイメージをサポートしない場合。（CL_DEVICE_ IMAGE_SUPPORTがCL_FALSE）
CL_INVALID_ OPERATION		clEnqueueReadImage が、CL_MEM_HOST_ WRITE_ONLYまたは CL_MEM_HOST_NO_ ACCESSで生成されたイメージ上で呼びだされた場合。
CL_INVALID_ OPERATION		clEnqueueReadImage が、CL_MEM_HOST_ READ_ONLYまたは CL_MEM_HOST_NO_ ACCESSで生成されたイメージ上で呼びだされた場合。
CL_EXEC_STATUS_ ERROR_FOR_EVENTS_ IN_WAIT_LIST		読み込みと書き込み操作がブロッキングされ、event_wait_list にあるどのイベントの実行ステータスも負の整数値の場合。
CL_OUT_OF_ RESOURCES		デバイス上のOpenCL 実装が必要とするリソース確保に失敗した場合。
CL_OUT_OF_ HOST_MEMORY		ホスト上のOpenCL 実装が必要とするリソース確保に失敗した場合。

B.16.2. clEnqueueCopyImage

Table B.45. 表：clEnqueueCopyImage

関数
cl_int	clEnqueueCopyImage ( cl_command_queue command_queue, cl_mem src_image, cl_mem dst_image, const size_t src_origin, const size_t dst_origin, const size_t region, cl_uint num_events_in_wait_list, const cl_event event_wait_list, cl_event *event )
イメージオブジェクトの複製を行うコマンドを挿入。 src_imageおよびdst_imageには1D、 2D、3Dイメージオブジェクト、1D/2Dイメージ配列オブジェクトを指定でき以下の操作が可能です。 1Dイメージオブジェクトから1Dイメージオブジェクトへの複製 1Dイメージオブジェクトから2Dイメージオブジェクトの走査線への複製(逆もまた同様) 1Dイメージオブジェクトから3Dイメージオブジェクトの2D スライスの走査線への複製(逆もまた同様) 1Dイメージオブジェクトから1Dまたは2Dイメージ配列オブジェクトの特定イメージインデックスの走査線への複製 (逆もまた同様) 2Dイメージオブジェクトから2Dイメージオブジェクトへの複製 2Dイメージオブジェクトから3Dイメージオブジェクトの2D スライスへの複製(逆もまた同様) 2Dイメージオブジェクトから2Dイメージ配列オブジェクトの特定イメージインデックスへの複製(逆もまた同様) 1Dイメージ配列オブジェクトのイメージから1Dイメージ配列オブジェクトへの複製。 2Dイメージ配列オブジェクトのイメージから2Dイメージ配列オブジェクトへの複製。 3Dイメージオブジェクトから3Dイメージオブジェクトへの複製
引数
command_queue		複製コマンドを挿入するコマンドキューを指定。 command_queue、 src_image、 dst_imageと関連付けられたOpenCLコンテキストは同じとなる必要がある。
src_origin		1D, 2D, 3Dイメージ内での (x, y, z) オフセットをピクセルで指定。 2Dイメージ配列の（x, y）オフセットとイメージインデックスを指定。 1Dイメージ配列の（x）オフセットとイメージインデックスを指定。イメージが2Dイメージオブジェクトの場合、 src_origin[2]は0となる。 src_imageが1Dイメージオブジェクトの場合、 src_origin[1]と src_origin[2]は0となる。 src_imageが1Dイメージ配列オブジェクトの場合、src_origin[1] は1Dイメージ配列のイメージインデックス（添字）を記述する。 src_imageが2Dイメージ配列オブジェクトの場合、src_origin[2] は2Dイメージ配列のイメージインデックス（添字）を記述する。
dst_origin		1D, 2D, 3Dイメージ内での (x, y, z) オフセットをピクセルで指定。 2Dイメージ配列の（x, y）オフセットとイメージインデックスを指定。 1Dイメージ配列の（x）オフセットとイメージインデックスを指定。 dst_imageが2Dイメージオブジェクトの場合、 dst_origin[2]は0となる。 dst_imageが1Dイメージまたは1Dイメージバッファオブジェクトの場合、 dst_origin[1]と dst_origin[2]は0となる。 dst_imageが1Dイメージ配列オブジェクトの場合、 dst_origin[2]は0となる。 dst_imageが1Dイメージ配列オブジェクトの場合、 dst_origin[1]は1D イメージ配列のイメージインデックス（添字）を記述する。 dst_imageが2Dイメージ配列オブジェクトの場合、 dst_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とはならない。
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 内の要素を参照すべきでない。
成功した場合の戻り値
CL_SUCCESS
失敗した場合の戻り値
CL_INVALID_ COMMAND_QUEUE		command_queueが有効なコマンドキューでない場合。
CL_INVALID_ CONTEXT		command_queue、 src_image、 dst_image と関連付けられたコンテキストが同じでない場合。 command_queue と関連付けられたコンテキストとevent_wait_list 内のイベントと関連付けられたコンテキストが同じでない場合。
CL_INVALID_ MEM_OBJECT		src_image、 dst_imageが有効なイメージオブジェクトでない場合。
CL_IMAGE_ FORMAT_MISMATCH		src_imageと dst_imageが使用するイメージ形式が同じでない場合。
CL_INVALID_ VALUE		src_origin および src_origin + region が指す2Dもしくは 3D矩形領域が、 src_imageの範囲外の場合。 dst_originおよび dst_origin+region が指す2Dもしくは 3D矩形領域が、 dst_imageの範囲外の場合。
CL_INVALID_ VALUE		src_origin, dst_originとregion の値が規則に従わない場合。
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		src_imageまたは dst_imageのイメージの寸法（幅、高さ、行・スライスの長さ）がキューに関連づけられたデバイスにサポートされていない場合。
CL_IMAGE_ FORMAT_NOT_ SUPPORTED		src_imageまたは dst_imageのイメージ形式がキューに関連づけられたデバイスにサポートされていない場合。
CL_MEM_OBJECT_ ALLOCATION_FAILURE		src_imageまたは dst_imageと関連づけられたデータストアのメモリ領域の確保に失敗した場合。
CL_OUT_OF_ RESOURCES		デバイス上のOpenCL 実装が必要とするリソース確保に失敗した場合。
CL_OUT_OF_ HOST_MEMORY		ホスト上のOpenCL 実装が必要とするリソース確保に失敗した場合。
CL_INVALID_ OPERATION		command_queueに関連付けられたデバイスがイメージをサポートしない場合。
CL_MEM_ COPY_OVERLAP		src_imageとdst_ imageが同じイメージオブジェクトで、ソースと行き先の領域がオーバラップする場合。

B.16.3. clEnqueueFillImage

Table B.46. 表：clEnqueueFillImage

関数
cl_int	clEnqueueFillImage ( cl_command_queue command_queue, cl_mem image, const void fill_color, const size_t origin, const size_t region, cl_uint num_events_in_wait_list, const cl_event event_wait_list, cl_event *event )
イメージオブジェクトを指定した色彩に塗りつぶすコマンドをキューに挿入。 clEnguqueFillImageはカーネル/ホストによるメモリオブジェクトへの読み込み・書き込みについての使用情報や、イメージが生成された際に指定したcl_mem_flagsを無視します。
引数
command_queue		fillコマンドが挿入されるcommand-queue を指定。command-queue とimageが関連するOpenCL コンテキストは同じものとなる必要がある。
image		有効なイメージオブジェクトを指定。
fill_color		フィルカラー（塗りつぶす色）を指定。イメージチャネルデータ型が非正規符号付き・符号無し整数でない場合、フィルカラーは4 つの要素で構成するRGBA 浮動小数点色彩値となる。イメージチャネルデータ型が非正規符号付き整数型の場合、４要素符号付き整数となる。イメージチャネルデータ型が非正規符号無し整数型の場合、４要素符号無し整数となる。フィルカラーは適切なイメージチャネル型式に変換される。
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とはならない。
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内の要素を参照すべきでない。
成功した場合の戻り値
CL_SUCCESS
失敗した場合の戻り値
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		フィルカラーがNULL の場合。
CL_INVALID_ VALUE		originとregionで指定したフィルする領域が範囲外の場合。 ptrがNULLの場合。
CL_INVALID_ VALUE		originとregionの値が規則に従わない場合。
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_MEM_OBJECT_ ALLOCATION_FAILURE		データ格納領域のメモリ確保に失敗した場合。
CL_OUT_ OF_RESOURCES		デバイス上のOpenCL 実装が必要とするリソース確保に失敗した場合。
CL_OUT_ OF_HOST_MEMORY		ホスト上のOpenCL 実装が必要とするリソース確保に失敗した場合。

B.16.4. clEnqueueCopyImageToBuffer

Table B.47. 表：clEnqueueCopyImageToBuffer

関数
cl_int	clEnqueueCopyImageToBuffer ( cl_command_queue command_queue, cl_mem src_image, cl_mem dst_buffer, const size_t src_origin, const size_t region, size_t dst_offset, cl_uint num_events_in_wait_list, const cl_event event_wait_list, cl_event event )
イメージオブジェクトからバッファオブジェクトへの複製を行うコマンドを挿入。
引数
command_queue		複製コマンドを挿入するコマンドキューを指定。 command_queue、 src_image、 dst_buffer と関連付けられたOpenCL コンテキストは同じとなる必要がある。
src_image		複製元となる有効なイメージオブジェクトを指定します。
dst_buffer		複製先となる有効なバッファオブジェクトを指定します。
src_origin		1D, 2D, 3Dイメージ内での (x, y, z) オフセットをピクセルで指定。 2Dイメージ配列の（x, y）オフセットとイメージインデックスを指定。 1Dイメージ配列の（x）オフセットとイメージインデックスを指定。イメージが2Dイメージオブジェクトの場合、 src_origin[2]は0となる。 src_imageが1Dイメージオブジェクトの場合、 src_origin[1]と src_origin[2]は0となる。 src_imageが1Dイメージ配列オブジェクトの場合、src_origin[1]は1D イメージ配列のイメージインデックス（添字）を記述する。 src_imageが2Dイメージ配列オブジェクトの場合、src_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とはならない。
dst_offset		dst_bufferへのデータの複製を行なう際に、書き込み開始位置をどれだけずらすかを指定。 src_imageが3Dイメージオブジェクトの場合、複製領域のバイトサイズ (dst_cb) は widthheightdepth （画素あたりのバイトサイズ）で求められる。 src_imageが2Dイメージオブジェクトの場合、複製領域のバイトサイズ(dst_cb) はwidthheight（画素あたりのバイトサイズ）で求められる。 src_imageが2Dイメージ配列オブジェクトの場合、複製領域のバイトサイズ (dst_cb) はwidthheight* 配列サイズ（画素あたりのバイトサイズ）で求められる。 src_imageが1Dイメージオブジェクトまたは1Dイメージバッファオブジェクトの場合、複製領域のバイトサイズ (dst_cb) はwidth（画素あたりのバイトサイズ）で求められる。 src_imageが1Dイメージ配列オブジェクトの場合、複製領域のバイトサイズ (dst_cb) はwidth* 配列サイズ*（画素あたりのバイトサイズ）で求められる。
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内の要素を参照すべきでない。
成功した場合の戻り値
CL_SUCCESS
失敗した場合の戻り値
CL_INVALID_ COMMAND_QUEUE		command_queueが有効なコマンドキューでない場合。
CL_INVALID_ CONTEXT		command_queue、 src_image、 dst_bufferと関連付けられたコンテキストが同じでない場合 command_queueと関連付けられたコンテキストとevent_wait_list内のイベントと関連付けられたコンテキストが同じでない場合。
CL_INVALID_ MEM_OBJECT		src_imageが有効なイメージオブジェクトでない場合。 dst_bufferが有効なバッファオブジェクトでない場合。 src_imageがdst_buffer で生成された1Dイメージバッファオブジェクトの場合。
CL_INVALID_ VALUE		src_originおよび src_origin+regionが指す1D、2D、3D矩形領域が、src_imageの範囲外の場合。もしくは、dst_offset およびdst_offset+dst_cb が指す領域が、dst_buffer の範囲外の場合。
CL_INVALID_ VALUE		src_originとregion の値が規則に従わない場合。
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		dst_bufferがサブバッファオブジェクトで、このサブバッファオブジェクトを生成する際に指定したオフセットがcommand_queue と関連付けられたデバイスの CL_DEVICE_MEM_BASE_ ADDR_ALIGNにアラインされていない場合。
CL_INVALID_ IMAGE_SIZE		src_imageの寸法（幅、高さ、行・スライスの長さ）がcommand_queueと関連付けられたデバイスでサポートされていない場合。
CL_IMAGE_ FORMAT_NOT_ SUPPORTED		src_imageに対するイメージ型式（image channel orderやデータ型）がqueue に関連付けられたデバイスにサポートされていない場合。
CL_MEM_OBJECT_ ALLOCATION_FAILURE		src_imageもしくは dst_bufferと関連付けられたデータ保存領域のためのメモリの確保に失敗した場合。
CL_INVALID_ OPERATION		command_queueと関連付けられたデバイスがイメージ機能をサポートしていない（clGetDeviceInfo で取得できる CL_DEVICE_ IMAGE_SUPPORTが CL_FALSE である）場合。
CL_OUT_OF_ RESOURCES		デバイス上のOpenCL実装が必要とするリソース確保に失敗した場合。
CL_OUT_OF_ HOST_MEMORY		ホスト上のOpenCL実装が必要とするリソース確保に失敗した場合。

B.16.5. clEnqueueCopyBufferToImage

Table B.48. 表：clEnqueueCopyBufferToImage

関数
cl_int	clEnqueueCopyBufferToImage ( cl_command_queue command_queue, cl_mem src_buffer, cl_mem dst_image, size_t src_offset, const size_t dst_origin, const size_t region, cl_uint num_events_in_wait_list, const cl_event event_wait_list, cl_event event )
バッファオブジェクトからイメージオブジェクトへの複製を行うコマンドを挿入。
引数
command_queue		複製コマンドを挿入するコマンドキューを指定します。 command_queue、 src_buffer、 dst_imageと関連付けられた OpenCLコンテキストは同じとなる必要がある。
src_buffer		複製元となる有効なバッファオブジェクトを指定。
dst_image		複製先となる有効なイメージオブジェクトを指定。
src_offset		src_bufferから複製を行う際に、読み込み開始位置をどれだけずらすかを指定。
dst_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とはならない。 src_bufferから複製を行うとき、複製領域のバイトサイズ (src_cb) は、src_imageが3Dイメージオブジェクトである場合、widthheight depth（画素あたりのバイトサイズ）で求められる。 src_imageが2Dイメージオブジェクトである場合、 widthheight* （画素あたりのバイトサイズ）で求められる。 src_imageが2Dイメージ配列オブジェクトである場合、widthheight 配列サイズ（画素あたりのバイトサイズ）で求められる。 src_imageが1Dイメージまたは1Dイメージバッファオブジェクトである場合、width（画素あたりのバイトサイズ）で求められる。 src_imageが1Dイメージ配列オブジェクトである場合、width配列サイズ（画素あたりのバイトサイズ）で求められる。
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内の要素を参照すべきでない。
成功した場合の戻り値
CL_SUCCESS
失敗した場合の戻り値
CL_INVALID_ COMMAND_QUEUE		command_queueが有効なコマンドキューでない場合。
CL_INVALID_ CONTEXT		command_queue、 src_buffer、 dst_image と関連付けられたコンテキストが同じでない場合 command_queueと関連付けられたコンテキストとevent_wait_list内のイベントと関連付けられたコンテキストが同じでない場合。
CL_INVALID_ MEM_OBJECT		src_bufferが有効なバッファオブジェクトでない場合。 dst_imageが有効なイメージオブジェクトでない場合。 dst_imageがsrc_buffer から生成された1Dイメージバッファオブジェクトの場合。
CL_INVALID_ VALUE		dst_originおよび dst_origin + region が指す1D、2D、3D矩形領域が、dst_imageの範囲外の場合。 src_offsetおよび src_offset + src_cb が指す領域が、 src_bufferの範囲外の場合。
CL_INVALID_ VALUE		dst_originとregion の値が規則に従わない場合。
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		src_buffer がサブバッファオブジェクトで、このサブバッファオブジェクトを作成する際に指定したオフセットが command_queueと関連付けられたデバイスの CL_DEVICE_MEM_BASE_ ADDR_ALIGNにアラインされていない場合。
CL_INVALID_ IMAGE_SIZE		dst_imageの寸法（幅、高さ、行・スライスの長さ）がcommand_queue と関連付けられたデバイスでサポートされていない場合。
CL_IMAGE_ FORMAT_NOT_ SUPPORTED		dst_imageに対するイメージ型式（image channel orderやデータ型）がqueue に関連付けられたデバイスにサポートされていない場合。
CL_MEM_OBJECT_ ALLOCATION_FAILURE		src_bufferまたは dst_imageと関連付けられたデータ保存領域のためのメモリの確保に失敗した場合。
CL_INVALID_ OPERATION		command_queueと関連付けられたデバイスがイメージ機能をサポートしていない（CL_DEVICE_IMAGE_ SUPPORTがCL_FALSEである）場合。
CL_OUT_OF_ RESOURCES		デバイス上のOpenCL 実装が必要とするリソース確保に失敗した場合。
CL_OUT_OF_ HOST_MEMORY		ホスト上のOpenCL 実装が必要とするリソース確保に失敗した場合。