B.12. バッファオブジェクト

B.12.1. clCreateBuffer

表B.29 表:clCreateBuffer

関数
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の項目を
参照ください。フラグの値
を0にした場合のデフォルト
値はCL_MEM_READ_WRITE
です。
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_mem_flags>>
の項目を参照のこと。
CL_INVALID_
BUFFER_SIZE
sizeが0の場合。
指定されたsizeが
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_
RESOURCES
デバイス上のOpenCL
実装が必要とするリソー
ス確保に失敗した場合。
CL_OUT_OF_
HOST_MEMORY
ホスト上のOpenCL実
装が必要とするリソー
ス確保に失敗した場合。

B.12.2. cl_mem_flags

表B.30 cl_mem_flags

cl_mem_flags
詳細
CL_MEM_
READ_WRITE

このフラグはメモリオ
ブジェクトがカーネル
によって読み書きされ
ることを指定。この設定
がデフォルトです。

CL_MEM_
WRITE_ONLY
このフラグはカーネル
がメモリオブジェクト
に書き込みをするが、
読み込みはされないこ
とを指定。

カーネル内で
CL_MEM_WRITE_ONLY
を指定して生成したバッ
ファ・イメージオブジェ
クトからの読み込み処理
は未定義となります。

CL_MEM_READ_WRITEと
CL_MEM_WRITE_ONLYは
相互に相いれない。
(相互排他的)
CL_MEM_
READ_ONLY
このフラグはカーネル
がメモリオブジェクト
への読み込み専用であ
ることを指定。
CL_MEM_READ_ONLYを
指定し生成したバッファ
・イメージオブジェクト
へのカーネル内での書
き込みについては未定義
となります。

CL_MEM_READ_WRITE
または、
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と
一緒に指定して、ホスト
がアクセス可能なメモリ
(例:PCIeメモリ)に
確保したcl_memオブジ
ェクトの内容を初期化
できます。
CL_MEM_HOST_
WRITE_ONLY
このフラグはメモリ
オブジェクトにホスト
が書き込むのみできる
ことを指定。(読み込
みまたはマップによる)

ホストからの書き込み
アクセスを最適化する
ことに使うことができる。
CL_MEM_HOST_
READ_ONLY

このフラグはメモリ
オブジェクトをホスト
が読み込むのみできる
ことを指定。(読み込
みまたはマップによる)

CL_MEM_HOST_
WRITE_ONLYと
CL_MEM_HOST_
READ_ONLYは相互
に相いれない。(相互排他的)

CL_MEM_HOST_
NO_ACCESS


このフラグはメモ
リオブジェクトをホ
ストが読み書きしな
いことを示す。

CL_MEM_HOST_
WRITE_ONLY
またはCL_MEM_HOST_
READ_ONLY
とCL_MEM_HOST_
NO_ACCESSは相互
に相いれない。(相互排他的)

Copyright 2018-2019, by Masaki Komatsu