clCreateBuffer/1.0
cl_mem clCreateBuffer (cl_context context, cl_mem_flags flags, size_t size, void *host_ptr, cl_int *errcode_ret)
バッファオブジェクトを作成します。
パラメータ
- context
- 有効なOpenCLコンテキストを指定します。
- flags
- バッファオブジェクトを確保するのに使用されるメモリ領域やバッファオブジェクトがどのように使われるのかを指定するビットフィールドです。有効な値は以下のとおりです。
cl_mem_flags 解説 CL_MEM_READ_WRITE メモリオブジェクトはカーネルによって読み書きされます。この設定がデフォルトになります。 CL_MEM_WRITE_ONLY カーネルからメモリオブジェクトに書き込みはされますが、読み込みはされません。 カーネル内での CL_MEM_WRITE_ONLY を指定して作成したバッファ/イメージオブジェクトからの読み込みについては未定義です。
CL_MEM_READ_ONLY カーネルはメモリオブジェクトからの読み込みのみを行います。 CL_MEM_READ_ONLY を指定して作成したバッファ/イメージオブジェクトへのカーネル内からの書き込みについては未定義です。
CL_MEM_USE_HOST_PTR このフラグは、host_ptr が NULL でないときのみ有効です。このフラグは、アプリケーションが OpenCL 実装に対して、host_ptr が指すメモリをメモリオブジェクトの保存領域として用いるよう求めていることを意味します。 OpenCL 実装は、host_ptr が指す領域に保存されているバッファの内容をデバイスメモリにキャッシュできます。このキャッシュされた複製は、デバイスでカーネルを実行する際に用いることができます。
同じ host_ptr あるいは重複する領域に対して作成された複数のバッファオブジェクトに対して操作を行う OpenCL コマンドの結果は未定義です。
CL_MEM_ALLOC_HOST_PTR このフラグは、アプリケーションが OpenCL 実装に対して、ホストがアクセス可能なメモリ領域からメモリを確保するよう求めていることを意味します。 CL_MEM_ALLOC_HOST_PTR と CL_MEM_USE_HOST_PTR は相互に排他的です。
CL_MEM_COPY_HOST_PTR このフラグは、host_ptr が NULL でないときのみ有効です。このフラグは、アプリケーションが OpenCL 実装に対して、メモリオブジェクトのメモリを確保し host_ptr が指すメモリからデータを複製するよう求めていることを意味します。 CL_MEM_COPY_HOST_PTR と CL_MEM_USE_HOST_PTR は相互に排他的です。
CL_MEM_COPY_HOST_PTR は CL_MEM_ALLOC_HOST_PTR と一緒に指定して、ホストがアクセス可能なメモリに確保した cl_mem オブジェクトの内容を初期化できます。
- size
- 確保するバッファオブジェクトのサイズをバイトで指定します。
- host_ptr
- アプリケーションが確保済みのバッファデータを指します。host_ptr が指すバッファのサイズは size 以上の大きさでなければなりません。
- errcode_ret
- 適切なエラーコードを返します。errcode_ret が NULL のとき、エラーコードは返されません。
エラー
バッファオブジェクトの作成が成功すると、clCreateBuffer は有効な非ゼロのバッファオブジェクトを返し errcode_ret に CL_SUCCESS を設定します。そうでない場合は NULL を返して errcode_ret に以下のエラーのうちのひとつを設定します。
- CL_INVALID_CONTEXT - context が有効なOpenCLコンテキストでないとき。
- CL_INVALID_VALUE - flags に指定した値が有効なものでないとき。
- CL_INVALID_BUFFER_SIZE - size が 0 のとき。もしくは size が context 内のデバイスの CL_DEVICE_MAX_MEM_ALLOC_SIZE の値より大きいとき。
- CL_INVALID_HOST_PTR - host_ptr が NULL で CL_MEM_USE_HOST_PTR もしくは CL_MEM_COPY_HOST_PTR が flags に指定されているとき。もしくは、CL_MEM_COPY_HOST_PTR や CL_MEM_USE_HOST_PTR が設定されていないのに host_ptr が NULL でないとき。
- CL_MEM_OBJECT_ALLOCATION_FAILURE - バッファオブジェクトのメモリを確保するのに失敗したとき。
- CL_OUT_OF_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。
変更記録
脚注
