「clEnqueueReadBuffer」の版間の差分

提供: Tommy6
移動: 案内、 検索
細
8行: 8行:
  
 
{{翻訳|
 
{{翻訳|
−
[[バッファオブジェクト]]からホストメモリへの読み込みを行うコマンドを挿入します。
 
−
 
 
{{ChangeNote|1.1}}
 
{{ChangeNote|1.1}}
 +
 +
[[バッファオブジェクト]]からホストメモリへの読み込みを行うコマンドを挿入します。
  
 
== パラメータ ==
 
== パラメータ ==
19行: 19行:
 
;blocking_read
 
;blocking_read
 
:読み込み操作を、ブロッキングで行うのかノンブロッキングで行うのかを指定します。
 
:読み込み操作を、ブロッキングで行うのかノンブロッキングで行うのかを指定します。
−
:''blocking_read'' に [[CL_TRUE]] を指定すると、読み込みコマンドはブロッキングとなり、バッファデータを読み込んで ''buffer'' が指すメモリ領域に複製し終わるまで、[[clEnqueueReadBuffer]] は返りません。
+
:''blocking_read'' に [[CL_TRUE]] を指定すると、読み込みコマンドはブロッキングとなり、バッファデータを読み込んで ''ptr'' が指すメモリ領域に複製し終わるまで、[[clEnqueueReadBuffer]] は返りません。
 +
:''blocking_read'' に [[CL_FALSE]] を指定すると、読み込みコマンドはノンブロッキングとなり、[[clEnqueueReadBuffer]] はノンブロッキング読み込みコマンドを挿入して返ります。読み込みコマンドが完了するまで、''ptr'' が指すバッファの内容は利用できません。''event'' 引数にはイベントオブジェクトが返され、読み込みコマンドの実行状況の確認に利用できます。読み込みコマンドが完了すると、''ptr'' が指すバッファの内容をアプリケーションが利用できるようになります。
 +
;offset
 +
:バッファオブジェクトから読み込みを行う際に、読み込み開始位置をどれだけずらすかをバイトで指定します。
 +
;cb
 +
:読み込むデータのサイズをバイトで指定します。
 +
;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
 +
:この読み込みコマンドを識別するイベントオブジェクトが返され、コマンド完了の確認やコマンド完了待ちを行えます。''event'' が NULL のとき、アプリケーションはコマンドの状況確認やコマンド完了待ちを行えなくなります。
  
 
== エラー ==
 
== エラー ==
−
コンテキストの作成が成功すると、[[clCreateContext]] は有効な非ゼロのコンテキストを返し ''errcode_ret'' に CL_SUCCESS を設定します。そうでない場合は NULL を返して ''errcode_ret'' に以下のエラーのうちのひとつを設定します。
+
実行が成功した場合、[[clEnqueueReadBuffer]] は CL_SUCCESS を返します。そうでない場合は以下のエラーのうちひとつを返します。
−
* CL_INVALID_PLATFORM - ''properties'' が NULL でかつプラットフォームがひとつも選択されなかったとき。または、''properties'' 内で指定したプラットフォームが有効なプラットフォームでないとき。
+
* CL_INVALID_COMMAND_QUEUE - ''command_queue'' が有効なコマンドキューでないとき。
−
* {{ChangeMinus|1.1|CL_INVALID_VALUE}}{{ChangePlus|1.1|CL_INVALID_PROPERTY}} - ''properties'' 内で指定したコンテキストプロパティ名がサポートされているプロパティ名でないとき。または、サポートされているプロパティ名に対して指定した値が有効でないとき。または、同じプロパティ名が重複して指定されているとき。
+
* CL_INVALID_CONTEXT - ''command_queue'' と関連付けられたコンテキストと ''buffer'' と関連付けられたコンテキストが同じでないとき、あるいは ''command_queue'' と関連付けられたコンテキストと ''event_wait_list'' 内のイベントと関連付けられたコンテキストが同じでないとき。
−
* CL_INVALID_VALUE - ''devices'' が NULL のとき。
+
* CL_INVALID_MEM_OBJECT - ''buffer'' が有効なバッファオブジェクトでない時。
−
* CL_INVALID_VALUE - ''num_devices'' が0のとき。
+
* CL_INVALID_VALUE - (''offset'', ''cb'') で指定した読み込み領域が範囲外のとき。あるいは ''ptr'' が NULL のとき。
−
* CL_INVALID_VALUE - ''pfn_notify'' が NULL で ''user_data'' が 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_DEVICE - ''devices'' に有効でないデバイスが含まれているとき。{{ChangeMinus|1.1|または、指定したプラットフォームと関連付けられたものでないとき。}}
+
* {{ChangePlus|1.1|CL_MISALIGNED_SUB_BUFFER_OFFSET - ''buffer'' がサブバッファオブジェクトで、サブバッファオブジェクトを作成する際に指定したオフセットが ''command_queue'' と関連付けられたデバイスの CL_DEVICE_MEM_BASE_ADDR_ALIGN にアラインされていないとき。}}
−
* CL_DEVICE_NOT_AVAILABLE - ''devices'' 内のデバイスが、[[clGetDeviceIDs]] で返されたデバイスであるものの現在利用可能でないとき。
+
* {{ChangePlus|1.1|CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST - 読み込みコマンドがブロッキングで、かつ ''event_wait_list'' 内のイベントのいずれかの実行状況が負の整数値のとき。}}
 +
* CL_MEM_OBJECT_ALLOCATION_FAILURE - ''buffer'' と関連付けられたデータ保存操作のためのメモリ確保に失敗した時。
 
* {{ChangePlus|1.1|CL_OUT_OF_RESOURCES - デバイス上でのリソース確保に失敗したとき。}}
 
* {{ChangePlus|1.1|CL_OUT_OF_RESOURCES - デバイス上でのリソース確保に失敗したとき。}}
 
* CL_OUT_OF_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。
 
* CL_OUT_OF_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。

2014年2月10日 (月) 00:01時点における版

OpenCL > OpenCLマニュアル > OpenCLランタイム > OpenCLランタイムAPI > メモリオブジェクト > clEnqueueReadBuffer

cl_int clEnqueueReadBuffer (cl_command_queue command_queue, cl_mem buffer, cl_bool blocking_read, 　　　　　　　　　　　　　　　　　　size_t offset, size_t cb, void *ptr, 　　　　　　　　　　　　　　　　　　cl_uint num_events_in_wait_list, const cl_event *event_wait_list, cl_event *event)

-1.1() : OpenCL 1.1で削除

+1.1() : OpenCL 1.1で追加

バッファオブジェクトからホストメモリへの読み込みを行うコマンドを挿入します。

パラメータ

command_queue
読み込みコマンドを挿入するコマンドキューを指定します。command_queue と buffer は同じOpenCLコンテキスト上で作成されたものでなければなりません。
buffer
有効なバッファオブジェクトを指定します。
blocking_read
読み込み操作を、ブロッキングで行うのかノンブロッキングで行うのかを指定します。
blocking_read に CL_TRUE を指定すると、読み込みコマンドはブロッキングとなり、バッファデータを読み込んで ptr が指すメモリ領域に複製し終わるまで、clEnqueueReadBuffer は返りません。
blocking_read に CL_FALSE を指定すると、読み込みコマンドはノンブロッキングとなり、clEnqueueReadBuffer はノンブロッキング読み込みコマンドを挿入して返ります。読み込みコマンドが完了するまで、ptr が指すバッファの内容は利用できません。event 引数にはイベントオブジェクトが返され、読み込みコマンドの実行状況の確認に利用できます。読み込みコマンドが完了すると、ptr が指すバッファの内容をアプリケーションが利用できるようになります。
offset
バッファオブジェクトから読み込みを行う際に、読み込み開始位置をどれだけずらすかをバイトで指定します。
cb
読み込むデータのサイズをバイトで指定します。
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
この読み込みコマンドを識別するイベントオブジェクトが返され、コマンド完了の確認やコマンド完了待ちを行えます。event が NULL のとき、アプリケーションはコマンドの状況確認やコマンド完了待ちを行えなくなります。

エラー

実行が成功した場合、clEnqueueReadBuffer は 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) で指定した読み込み領域が範囲外のとき。あるいは ptr が 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 内のイベントオブジェクトが有効なものでないとき。
  • +1.1(CL_MISALIGNED_SUB_BUFFER_OFFSET - buffer がサブバッファオブジェクトで、サブバッファオブジェクトを作成する際に指定したオフセットが command_queue と関連付けられたデバイスの CL_DEVICE_MEM_BASE_ADDR_ALIGN にアラインされていないとき。)
  • +1.1(CL_EXEC_STATUS_ERROR_FOR_EVENTS_IN_WAIT_LIST - 読み込みコマンドがブロッキングで、かつ event_wait_list 内のイベントのいずれかの実行状況が負の整数値のとき。)
  • CL_MEM_OBJECT_ALLOCATION_FAILURE - buffer と関連付けられたデータ保存操作のためのメモリ確保に失敗した時。
  • +1.1(CL_OUT_OF_RESOURCES - デバイス上でのリソース確保に失敗したとき。)
  • CL_OUT_OF_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。

変更記録

脚注



―――― Version 1.1, The OpenCL Specification より翻訳
「http://wiki.tommy6.net/index.php?title=clEnqueueReadBuffer&oldid=829」から取得