clGetSupportedImageFormats/1.0
cl_int clGetSupportedImageFormats (cl_context context, cl_mem_flags flags, cl_mem_object_type image_type, cl_uint num_entries, cl_image_format *image_formats, cl_uint *num_image_formats)
イメージメモリオブジェクトに関する以下の情報を指定したときにOpenCL実装がサポートするイメージ形式の一覧を取得できます。
- OpenCLコンテキスト
- イメージ型 - 2Dもしくは3Dイメージ
- イメージオブジェクトの領域確保に関する情報
パラメータ
- 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 オブジェクトの内容を初期化できます。
- image_format
- 確保する領域内に置くイメージの形式を指定する記述子へのポインタを指定します。詳しくは、cl_image_format をご覧ください。
- image_type
- イメージ型を指定します。CL_MEM_OBJECT_IMAGE2D もしくは CL_MEM_OBJECT_IMAGE3D でなければなりません。
- num_entries
- image_formats が指すメモリ領域に返すことのできるエントリの数を指定します。
- image_formats
- サポートされているイメージ形式の一覧が返されるメモリ領域へのポインタを指定します。返されるエントリは、OpneCL実装がサポートする cl_image_format 構造体です。
- num_image_formats
- context および flags で指定した条件でサポートされるイメージ形式の数を返します。num_image_formats が NULL のときは無視されます。
解説
サポートされるイメージ形式の最小要件
clGetDeviceInfo で得られる CL_DEVICE_IMAGE_SUPPORT が CL_TRUE であるとき、CL_DEVICE_MAX_READ_IMAGE_ARGS、CL_DEVICE_MAX_WRITE_IMAGE_ARGS、CL_DEVICE_IMAGE2D_MAX_WIDTH、CL_DEVICE_IMAGE2D_MAX_HEIGHT、CL_DEVICE_IMAGE3D_MAX_WIDTH、CL_DEVICE_IMAGE3D_MAX_HEIGHT、CL_DEVICE_IMAGE3D_MAX_DEPTH、CL_DEVICE_MAX_SAMPLERS に実装が設定する値は、clGetDeviceInfo に記載されている最小値以上でなければなりません。加えて、OpenCL実装は以下のイメージ形式をサポートしなければなりません。
読み込みのみ可能な2Dおよび3Dイメージオブジェクトがサポートするイメージ形式の最小要件は次の通りです。
| image_num_channels | image_channel_order | image_channel_data_type |
|---|---|---|
| 4 | CL_RGBA | |
| 4 | CL_BGRA |
読み書き可能もしくは書き込みのみ可能な2Dイメージオブジェクトがサポートするイメージ形式の最小要件は次の通りです。
| image_num_channels | image_channel_order | image_channel_data_type |
|---|---|---|
| 4 | CL_RGBA | |
| 4 | CL_BGRA |
エラー
実行が成功すると、clGetSupportedImageFormats は CL_SUCCESS を返します。context が有効なOpenCLコンテキストでないとき、CL_INVALID_CONTEXT を返します。flags もしくは image_type に指定した値が有効なものでないとき、もしくは num_entries が0で image_formats が NULL でないとき、CL_INVALID_VALUE を返します。
変更記録
脚注
