clCreateImage2D
cl_mem clCreateImage2D (cl_context context, cl_mem_flags flags, const cl_image_format *image_format, size_t image_width, size_t image_height, size_t image_row_pitch, void *host_ptr, cl_int *errcode_ret)
-1.1() : OpenCL 1.1で削除
+1.1() : OpenCL 1.1で追加
2Dのイメージオブジェクトを作成します。
パラメータ
- 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_width
- イメージの幅をピクセルで指定します。1以上の値でなければなりません。
- image_height
- イメージの高さをピクセルで指定します。1以上の値でなければなりません。
- image_row_pitch
- 走査線の長さをバイトで指定します。host_ptr が NULL のときは、0を指定しなければならず、NULL でないときは、0もしくは image_width*画素のバイトサイズ 以上の値を指定できます。host_ptr が NULL ではなく、かつ image_row_pitch = 0 であるとき、image_row_pitch には image_width*画素のバイトサイズ を設定したものとして扱われます。iamge_row_pitch に0以外の値を指定するとき、その値は画素のバイトサイズの倍数でなければなりません。
- host_ptr
- アプリケーションが確保済みのイメージデータを指します。host_ptr が指すイメージのサイズは image_row_pitch*image_height 以上の大きさでなければなりません。各画素のバイトサイズは2のべきでなければなりません。host_ptr が指すイメージデータは、走査線が連続して順番に並んだ状態で保存されているものです。各走査線は、画素が順番に並んだ状態で保存されているものです。
- errcode_ret
- 適切なエラーコードを返します。errcode_ret が NULL のとき、エラーコードは返されません。
エラー
バッファオブジェクトの作成が成功すると、clCreateImage2D は有効な非ゼロのイメージオブジェクトを返し errcode_ret に CL_SUCCESS を設定します。そうでない場合は NULL を返して errcode_ret に以下のエラーのうちのひとつを設定します。
- CL_INVALID_CONTEXT - context が有効なOpenCLコンテキストでないとき。
- CL_INVALID_VALUE - flags に指定した値が有効なものでないとき。
- CL_INVALID_IMAGE_FORMAT_DESCRIPTOR - image_format に指定した値が有効なものでないとき。もしくは image_format が NULL のとき。
- CL_INVALID_IMAGE_SIZE - image_width が0もしくは context 内のどのデバイスの CL_DEVICE_IMAGE2D_MAX_WIDTH の値よりも大きいとき。あるいは、image_height が0もしくは context 内のどのデバイスの CL_DEVICE_IMAGE2D_MAX_HEIGHT の値よりも大きいとき。あるいは、image_row_pitch の値が上記の引数解説で示されている条件に合致していないとき。
- 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_IMAGE_FORMAT_NOT_SUPPORTED - image_format に指定したイメージ形式がサポートされていないとき。
- CL_MEM_OBJECT_ALLOCATION_FAILURE - イメージオブジェクトのメモリを確保するのに失敗したとき。
- CL_INVALID_OPERATION - context 内に、イメージ機能をサポートするデバイスが存在しない（CL_DEVICE_IMAGE_SUPPORT が CL_FALSE である）とき。
- +1.1(CL_OUT_OF_RESOURCES - デバイス上でのリソース確保に失敗したとき。)
- CL_OUT_OF_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。
変更記録
脚注
