clCreateSubBuffer
cl_mem clCreateSubBuffer (cl_mem buffer, cl_mem_flags flags, cl_buffer_create_type buffer_create_type, const void *buffer_create_info, cl_int *errcode_ret)
既存のバッファオブジェクトから、サブバッファオブジェクトと呼ばれる新しいバッファオブジェクトを作成します。
パラメータ
- buffer
- 有効なバッファオブジェクトを指定します。サブバッファオブジェクトは指定できません。
- 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_WRITE_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 オブジェクトの内容を初期化できます。
- buffer_create_type
- 作成するバッファオブジェクトの種類を指定します。buffer_create_type に指定できる値および、これに対応して buffer_create_info に指定する記述子は以下の通りです。
buffer_create_type 解説 CL_BUFFER_CREATE_TYPE_REGION buffer の特定の領域を使用するバッファオブジェクト作成します。 buffer_create_info には、以下の構造体へのポインタを指定します:
typedef struct _cl_buffer_region { size_t origin; size_t size; } cl_buffer_region;
(origin, size) は、buffer 内で確保する領域のオフセットと大きさをバイトで指定するものです。
buffer が、CL_MEM_USE_HOST_PTR を指定して作成したものであるとき、返されるバッファオブジェクトの host_ptr は、host_ptr+origin です。
返されるバッファオブジェクトは、buffer のために確保された保存領域を参照し、この保存領域内の (origin, size) で指定した区画を指します。
(origin, size) で指定した区画が、buffer の境界を越えているとき、errcode_ret に CL_INVALID_VALUE を返します。
buffer と関連付けられたコンテキスト内のどのデバイスの CL_DEVICE_MEM_BASE_ADDR_ALIGN にも origin の値がアラインされていないとき、errcode_ret にCL_MISALIGNED_SUB_BUFFER_OFFSET を返します。
- errcode_ret
- 適切なエラーコードを返します。errcode_ret が NULL のとき、エラーコードは返されません。
注意
同じ値を設定した記述子を指す値を buffer、flags、buffer_create_type、buffer_create_info に指定して clCreateSubBuffer を複数回呼び出すと、実装は参照カウントを適切にインクリメントしたうえで、同じ cl_mem オブジェクトを返すことがあります。
複数のサブバッファオブジェクトへの読み書きを行う OpenCL コマンドにおいて、これらサブバッファオブジェクトが同じバッファオブジェクトを使用して clCreateSubBuffer で作成され、各サブバッファオブジェクトが使用する領域が他のサブバッファオブジェクトと重複したものであるとき、結果は未定義です。バッファオブジェクトおよび同じバッファオブジェクトを使用して clCreateSubBuffer で作成したサブバッファオブジェクトへの読み書きを行う OpenCL コマンドの結果は未定義です。ただし、OpenCL コマンドが読み込みのみであれば、いずれも場合も定義通りに動作します。
エラー
バッファオブジェクトの作成が成功すると、clCreateSubBuffer は有効な非ゼロのバッファオブジェクトを返し errcode_ret に CL_SUCCESS を設定します。そうでない場合は NULL を返して errcode_ret に以下のエラーのうちのひとつを設定します。
- CL_INVALID_MEM_OBJECT - buffer が有効なバッファオブジェクトもしくはサブバッファオブジェクトでないとき。
- CL_INVALID_VALUE - flags に指定した値が有効なものでないとき。
- CL_INVALID_VALUE - buffer_create_type に指定した値が有効なものでないとき。
- CL_INVALID_VALUE - buffer_create_info に指定した値が有効なものでない、もしくは NULL のとき。
- CL_OUT_OF_RESOURCES - デバイス上でのリソース確保に失敗したとき。
- CL_OUT_OF_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。
変更記録
- OpenCL 1.1
- 追加
脚注