B.15. イメージオブジェクト

B.15.1. clCreateImage

表B.37 表:clCreateImage

関数
cl_mem
clCreateImage (
    cl_context context,
    cl_mem_flags flags,
    const cl_image_format *image_format,
    const cl_image_desc *image_desc,
    void *host_ptr,
    cl_int *errcode_ret
)
 1Dイメージ、1Dイメージバッファ、
1Dイメージ配列、2Dイメージ、
2Dイメージ配列、3Dイメージオブジェクトを生成。
 引数
context
有効なOpenCL
コンテキスト。
flags
生成されるイメー
ジメモリオブジェクト
の割当・確保に使うメ
モリ領域と使用情報を
指定するビットフィー
ルド。

CL_MEM_OBJECT_
IMAGE1D_BUFFERを除
いた全てのイメージ型
に対して、指定された
フラグの値が0の場合、
デフォルト値はCL_MEM_
READ_WRITEとなります。

CL_MEM_OBJECT_
IMAGE1D_BUFFERのイメ
ージ型に対して、CL_MEM_
READ_WRITE、CL_MEM_
READ_ONLY、CL_MEM_
WRITE_ONLYがフラグに指
定されない場合、バッファ
に関連付けられたメモリア
クセス修飾子から継承されます。

CL_MEM_USE_HOST_
PTR、CL_MEM_ALLOC_
HOST_PTR、 CL_MEM_
COPY_HOST_PTRはフラグ
に指定できませんが、
バッファに関連付けられた
メモリ修飾子からの継承
ができます。

CL_MEM_HOST_
WRITE_ONLY、CL_MEM_
HOST_READ_ONLY、
CL_MEM_HOST_NO_
ACCESSがフラグに指定
されていない場合、
バッファに関連付けられ
たメモリアクセス修飾子
から継承されます。


フラグについては
<<cl_mem_flags>>
を参照ください。
image_format
確保する領域内に格納
するイメージ形式プロ
パティを記述する構造
体へのポインタを指定。

<<cl_image_format>>
を参照ください。
image_desc
確保する領域内に格
納するイメージの型
と次元数を記述する
構造体へのポインタ
を指定。

<<cl_image_desc>>
を参照ください。
host_ptr
アプリケーション
が確保済みのイメージ
データを指すポインタ
を指定。

3Dイメージまたは2D
イメージ配列に対して、
host_ptrが指定する
イメージデータは2D画
像スライスが連続して
順番に並んだ状態で格
納されます。各2Dイメー
ジは走査線が連続して順番
に並んだものです。各走
査線は、画素が順番に並
んだ状態で保存される。

2Dイメージに対しては、
host_ptrが指定する
イメージデータは走査線
が連続して順番に並んだ
状態で格納されます。
各走査線は、画素が順番
に並んだ状態で保存される。

1Dイメージ配列に対して
は、host_ptrが指定す
るイメージデータは1Dイ
メージが順番に並んだ状
態で格納されます。各1D
イメージまたは1Dイメー
ジバッファは画素が順番に
並んだ状態の単一走査線となります。

<<host_ptr>>を参照
ください。
errcode_ret
適切なエラーコード
を戻す。errcode_ret
がNULLの場合、エラー
コードは戻らない。
 成功した場合の戻り値
 CL_SUCCESS
 失敗した場合の戻り値
CL_INVALID_
CONTEXT
contextが有効な
OpenCLコンテキスト
でない場合。
CL_INVALID_
VALUE
flagsに指定した値が
有効でない場合。
CL_INVALID_IMAGE_
FORMAT_DESCRIPTOR
image_formatに指定
した値が有効でない場合。
またはimage_formatが
NULLの場合。
CL_INVALID_
IMAGE_DESCRIPTOR
image_descに指定し
た値が有効でない場合。
またはimage_descが
NULLの場合。
CL_INVALID_
IMAGE_SIZE
コンテキスト内の全て
のデバイスに対して、
image_descで指定した
イメージの次元数が、
最大イメージ次元数を超
えた場合。
CL_INVALID_
HOST_PTR
host_ptrがNULLの
場合で、CL_MEM_USE_
HOST_PTRまたはCL_
MEM_COPY_HOST_PTR
のいずれかのflagsが
設定されている場合。

host_ptrがNULLでな
い場合で、CL_MEM_
COPY_HOST_PTRまたは
CL_MEM_USE_HOST_
PTRのいずれかのflags
が設定されていない場合。
CL_INVALID_
VALUE
1Dイメージバッファを生成、
バッファオブジェクトを
CL_MEM_WRITE_ONLYで
生成、flagsをCL_MEM_
READ_WRITEまたはCL_
MEM_READ_ONLYに設定
した場合。

バッファオブジェクトを
CL_MEM_READ_ONLYを
生成、flagsをCL_MEM_
READ_WRITEまたはCL_
MEM_WRITE_ONLYにする
か、flagsをCL_MEM_
USE_HOST_PTR、CL_MEM_
ALLOC_HOST_PTR、 CL_
MEM_COPY_HOST_PTRの
いずれかに設定した場合。
CL_INVALID_
VALUE
1Dイメージバッファを
生成、バッファオブジ
ェクトをCL_MEM_HOST_
WRITE_ONLYで生成、
flagsをCL_MEM_HOST_
READ_ONLYに設定した場合。

バッファオブジェクト
をCL_MEM_HOST_
READ_ONLYで生成、
flagsを CL_MEM_
HOST_WRITE_ONLYに
設定した場合。

バッファオブジェクトを
CL_MEM_HOST_NO_
ACCESSで生成、flags
をCL_MEM_HOST_READ_
ONLYまたはCL_MEM_
HOST_WRITE_ONLYに
設定した場合。
CL_IMAGE_FORMAT_
NOT_SUPPORTED
image_formatがサポ
ートされてない場合。
CL_MEM_OBJECT_
ALLOCATION_FAILURE
イメージオブジェクト
のメモリ領域の確保に
失敗した場合。
CL_INVALID_
OPERATION
イメージをサポートす
るデバイスがコンテキ
ストに存在しない場合。
(CL_DEVICE_IMAGE_
SUPPORTがCL_FALSE)
CL_OUT_OF_
RESOURCES
デバイス上のOpenCL
実装が必要とするリソー
ス確保に失敗した場合。
CL_OUT_OF_
HOST_MEMORY
ホスト上のOpenCL実
装が必要とするリソー
ス確保に失敗した場合。

B.15.2. イメージデータのバッファ

表B.38 表:host_ptrバッファサイズ

イメージ型
host_ptrが指すバッファのサイズ

CL_MEM_OBJECT_IMAGE1D


>= image_row_pitch

CL_MEM_OBJECT_IMAGE1D_BUFFER
>= image_row_pitch

CL_MEM_OBJECT_IMAGE2D


>= image_row_pitch
* image_height

CL_MEM_OBJECT_IMAGE3D
>= image_slice_pitch
* image_depth

CL_MEM_OBJECT_IMAGE1D_ARRAY

>= image_slice_pitch
* image_array_size

CL_MEM_OBJECT_IMAGE2D_ARRAY


>= image_slice_pitch
* image_array_size

B.15.3. cl_image_format

表B.39 表:cl_image_format

 cl_image_format
     typedef struct _cl_image_format {
          cl_channel_order    image_channel_order;
          cl_channel_type     image_channel_data_type;
     } cl_image_format;

表B.40 表:image_channel_order

 channel_orderに
指定可能な列挙値
CL_R, CL_Rx または CL_A
CL_INTENSITY.
この型式は
image_channel_data_type
= CL_UNORM_INT8,
CL_UNORM_INT16,
CL_SNORM_INT8,
CL_SNORM_INT16,
CL_HALF_FLOAT
または CL_FLOATの
場合のみ使えます。

CL_LUMINANCE.
この型式は
image_channel_data_type
= CL_UNORM_INT8,
CL_UNORM_INT16,
CL_SNORM_INT8,
CL_SNORM_INT16,
CL_HALF_FLOAT
または CL_FLOATの
場合のみ使えます。

CL_RG, CL_RGx または CL_RA
CL_RGB または CL_RGBx.
この型式は
image_channel_data_type
= CL_UNORM_SHORT_565,
CL_UNORM_SHORT_555また
は CL_UNORM_INT_101010
の場合のみ使えます。

CL_RGBA
CL_ARGB, CL_BGRA
この型式は
image_channel_data_type
= CL_UNORM_INT8,
CL_SNORM_INT8,
CL_SIGNED_INT8
または CL_UNSIGNED_INT8
の場合のみ使えます。

表B.41 表:image_channel_data_type

イメージチャネルのデータ型
詳細

CL_SNORM_INT8
各チャネル要素は、
正規化符号付8ビット整数値。

CL_SNORM_INT16

各チャネル要素は、
正規化符号付16ビット整数値。

CL_UNORM_INT8

各チャネル要素は、
正規化符号無8ビット整数値。
CL_UNORM_INT16
各チャネル要素は、
正規化符号無16ビット整数値。




CL_UNORM_SHORT_565
正規化5-6-5 3チャネル
RGBイメージ。チャネル配置
は、CL_RGBまたはCL_RGBx
となる必要がある。
CL_UNORM_SHORT_555
正規化x-5-5-5 4チャネル
xRGBイメージ。チャネル配置は、
CL_RGBまたはCL_RGBxとなる
必要がある。
CL_UNORM_INT_101010
正規化x-10-10-10 4チャネル
xRGBイメージ。チャネル配置は、
CL_RGBまたはCL_RGBxとなる
必要がある。

CL_SIGNED_INT8
各チャネル要素は、
非正規化符号付8ビット整数値。

CL_SIGNED_INT16

各チャネル要素は、
非正規化符号付16ビット整数値。
CL_SIGNED_INT32
各チャネル要素は、
非正規化符号付32ビット整数値。
CL_UNSIGNED_INT8
各チャネル要素は、
非正規化符号無8ビット整数値。
CL_UNSIGNED_INT16

各チャネル要素は、
非正規化符号無16ビット整数値。
CL_UNSIGNED_INT32
各チャネル要素は、
非正規化符号無32ビット整数値。


CL_HALF_FLOAT


各チャネル要素は、
16ビット半精度浮動小数点値。

CL_FLOAT

各チャネル要素は、
単精度浮動小数点値。


B.15.4. イメージ記述子

表B.42 表:cl_image_desc

 cl_image_desc
     typedef struct _cl_image_desc {
          cl_mem_object_type  image_type,
          size_t              image_width;
          size_t              image_height;
          size_t              image_depth;
          size_t              image_array_size;
          size_t              image_row_pitch;
          size_t              image_slice_pitch;
          cl_uint             num_mip_levels;
          cl_uint             num_samples;
          cl_mem              buffer;
     } cl_image_desc;
image_typeは(文字通り)
イメージ型を記述し、
CL_MEM_OBJECT_IMAGE1D、
CL_MEM_OBJECT_IMAGE1D_BUFFER、CL_MEM_OBJECT_IMAGE1D_ARRAY、
CL_MEM_OBJECT_IMAGE2D、
CL_MEM_OBJECT_IMAGE2D_ARRAY、
CL_MEM_OBJECT_IMAGE3Dの
いずれかとなる必要がある。
image_width
イメージの幅(ピクセルで表す)。

2Dイメージと2Dイメージ
配列に対して、イメージ
幅は
>=1、
<=CL_DEVICE_IMAGE2D_
MAX_WIDTHとなる。

3Dイメージに対して、
イメージ幅は、
>=1、
<= CL_DEVICE_IMAGE3D_
MAX_WIDTH
となる。

1Dイメージバッファに
対して、イメージ幅は
>=1、
<= CL_DEVICE_IMAGE_
MAX_BUFFER_SIZE
となる。

1Dイメージと1Dイメージ配列
に対して、イメージ幅は
>=1、
<= CL_DEVICE_IMAGE_
MAX_BUFFER_SIZE
となる。
image_height
イメージの高さ(ピクセル
で表す)を指定。これはイメ
ージが2D、3Dまたは2Dイメ
ージ配列の場合に限り使わ
れる。

2Dイメージまたはイメージ
配列に対して、イメージの
高さは
>=1、
<= CL_DEVICE_IMAGE2D_
MAX_HEIGHTとなる。

3Dイメージに対して、
イメージの高さは
>=1、
<= CL_DEVICE_IMAGE3D_
MAX_HEIGHTとなる。
image_depth
イメージの奥行き(ピクセ
ルで表す)。これはイメージ
が3Dイメージの場合に使われ
る。値は
>= 1、
<= CL_DEVICE_IMAGE3D_
MAX_DEPTH
となる。
image_array_size
イメージ配列内のイメージ
の個数。イメージが1D、2Dイ
メージ配列の場合に限り使わ
れる。値は、
>= 1、
<= CL_DEVICE_IMAGE_
MAX_ARRAY_SIZEとなる。

B.15.5. clGetSupportedImageFormats

表B.43 表:clGetSupportedImageFormats

関数

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コンテキスト ・イメージ型 - 1Dまたは2Dまたは3Dイメージ、1D イメージバッファ、1D/2Dイメージ配列 ・イメージオブジェクトの領域確保に関する情報

引数

context

イメージオブジェクト
を生成する有効なOpenCL
コンテキストを指定。

flags

イメージオブジェクトの
割当に使うメモリ領域や、
バッファオブジェクトの使
用情報を指定するビット
フィールド。

image_type

イメージ型を記述。
CL_MEM_OBJECT_IMAGE1D、
CL_MEM_OBJECT_IMAGE1D_BUFFER、
CL_MEM_OBJECT_IMAGE2D、
CL_MEM_OBJECT_IMAGE3D、
CL_MEM_OBJECT_IMAGE1D_ARRAY
または
CL_MEM_OBJECT_IMAGE2D_ARRAY
の指定ができる。

num_entries

image_formatsが指す
メモリ領域に戻せるエントリの
個数を指定。

image_formats

サポートするイメージ形式
の一覧が戻されるメモリ領域
へのポインタを指定。戻され
るエントリは、OpenCL実装
がサポートする
cl_image_format構造体。
image_formatsがNULLの場
合は無視される。

num_image_ formats

contextおよびflags
で指定した条件でサポート
されるイメージ形式の数を戻
す。num_image_formats
がNULLの場合は無視される。

成功した場合の戻り値

CL_SUCCESS

失敗した場合の戻り値

CL_INVALID_ CONTEXT

contextが有効な
OpenCLコンテキストで
ない場合。

CL_INVALID_ VALUE

flagsもしくはimage_type
に指定した値が有効なもので
ない場合。num_entries
が0でimage_formatsが
NULLでない場合。

CL_OUT_ OF_RESOURCES

デバイス上のOpenCL実装
が必要とするリソース確保
に失敗した場合。

CL_OUT_OF_ HOST_MEMORY

ホスト上のOpenCL実装
が必要とするリソース確保
に失敗した場合。

B.15.6. サポートするイメージ型式

image_num_channels
image_channel_order


image_channel_
data_type


4
CL_RGBA
CL_UNORM_INT8
CL_UNORM_INT16
CL_SIGNED_INT8
CL_SIGNED_INT16
CL_SIGNED_INT32
CL_UNSIGNED_INT8
CL_UNSIGNED_INT16
CL_UNSIGNED_INT32
CL_HALF_FLOAT
CL_FLOAT
4

CL_BGRA


CL_UNORM_INT8

Copyright 2018-2019, by Masaki Komatsu