B.22. プログラムオブジェクト

B.22.1. clCreateProgramWithSource

表B.62 表:clCreateProgramWithSource

関数

cl_program

clCreateProgramWithSource (
    cl_context context,
    cl_uint count,
    const char **strings,
    const size_t *lengths,
    cl_int *errcode_ret
)

引数で指定したOpenCLコンテキスト でプログラムオブジェクトを生成。strings 配列内の文字列からなるソースコードを、 プログラムオブジェクト内にロードします。 contextと関連付けられたデバイスがプログラム オブジェクトと関連付けられる。文字列で指定され たソースコードは、OpenCL Cプログラムの ソース、ヘッダー、オンラインコンパイラを サポートするカスタムデバイスのための実装定義 ソースのいずれかです。

引数

context

有効なOpenCL
コンテキストを指定。

strings

ソースコードが
格納された文字列への
ポインタの配列を指定。
任意にソースコードの
文字列がNULL終端とす
ることができる。

lengths

(strings配列
内の)各文字列の文
字数を指定する配列。

lengthsの要素が0
のとき、対応する文
字列はNULL終端にな
っているものとします。
lengthsがNULLのと
き、strings引数内の
全ての文字列がNULL
終端になっているもの
とします。この配列が含
む各値は、終端文字を
除いた0より大きな
値となる。

errcode_ret

適切なエラーコード
が設定される
errcode_retが
NULLの場合、エラー
コードは戻されない。

成功した場合の戻り値

プログラム オブジェクトの作成 が成功すると、有効 な非ゼロのプログラム オブジェクトを戻し errcode_retに CL_SUCCESSを設定。

失敗した場合の戻り値

CL_INVALID_ CONTEXT

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

CL_INVALID_ VALUE

countがゼロの場合、
または文字列がNULL
値の場合。

CL_OUT_OF_ RESOURCES

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

CL_OUT_OF_ HOST_MEMORY

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

B.22.2. clCreateProgramWithBinary

表B.63 表:clCreateProgramWithBinary

関数

cl_program

clCreateProgramWithBinary (
    cl_context context,
    cl_uint num_devices,
    const cl_device_id *device_list,
    const size_t *lengths,
    const unsigned char **binaries,
    cl_int *binary_status,
    cl_int *errcode_ret
)

指定したOpenCLコンテキストについて プログラムオブジェクトを生成。binariesで 指定したバイナリビット列をそのプログラムオ ブジェクトにロードする。

引数

context

有効なOpenCLコン
テキストを指定。

device_list

context内のデバイ
ス一覧へのポインタを指定。

device_listにNULL
値を指定することはで
きない。

バイナリは一覧内のデ
バイス用にロードされる。

device_listで指定
したデバイスはプログ
ラムオブジェクトと関
連付けられる。
device_listで指定す
るデバイスは、context
と関連付けられる必要
がある。

num_devices

device_listで指定
したデバイスの数を指定。

lengths

device_listで指定
したデバイスのために
ロードされるプログラ
ムバイナリのバイトサ
イズの配列を指定。

binaries

device_listで指定
したデバイスのために
読み込まれるプログラ
ムバイナリへのポインタ
の配列を指定。
device_list[i]に
対応する各デバイスでは、
プログラムバイナリへ
のポインタは
binaries[i]、
バイナリの長さは
lengths[i]となる。

lengths[i]に0は指定
できない。また
binaries[i]にNULL
ポインタの指定はで
きない。

binary_status

device_list内の
各デバイスに対する
プログラムバイナリの
ロードが成否を戻す。

num_devices
エントリーの配列で、
device_list[i]で
指定したデバイスへの
バイナリのロードが
成功すると
binary_status[i]
にCL_SUCCESSが
設定される。

lengths[i]が0もし
くはbinaries[i]が
NULLの場合、
CL_INVALID_VALUE
が戻る。プログラムバ
イナリがデバイスに対
して有効なものでない
場合、CL_INVALID_
BINARYが戻る。
binary_statusに
NULL値を指定すると
無視される。

errcode_ret

適切なエラーコード
を戻す。
errcode_retが
NULL値のとき、
エラーコードは戻らない。

成功した場合の戻り値

有効な非ゼロ のプログラムオブジ ェクトを戻す。 errcode_retに CL_SUCCESSを設定。

失敗した場合の戻り値

CL_INVALID_ CONTEXT

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

CL_INVALID_ VALUE

device_listが
NULLの場合。または
num_devicesが0の場合。

CL_INVALID_ DEVICE

device_listで
指定されているOpenCL
デバイスがcontext
と関連付けられた
デバイスでない場合。

CL_INVALID_ VALUE

lengthsもしくは
binariesがNULLの
場合。または
lengths[i]のいず
れかが0か、
binaries[i]の
いずれかがNULL値
の場合。

CL_INVALID_ BINARY

いずれかのデバイス
でプログラムバイナリ
が有効なものでない
場合。binary_status
に各デバイスの状況
が戻る。

CL_OUT_OF_ RESOURCES

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

CL_OUT_OF_ HOST_MEMORY

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

B.22.3. clCreateProgramWithBuiltInKernels

表B.64 表:clCreateProgramWithBuiltInKernels

関数
cl_program
clCreateProgramWithBuiltInKernels (
    cl_context context,
    cl_uint num_devices,
    const cl_device_id *device_list,
    const char *kernel_names,
    cl_int *errcode_ret
)
 引数contextに対してプログラムオブジェ
クトを生成。組込みカーネルに関連した情報をプ
ログラムオブジェクトにロードする。
 引数
context
有効なOpenCLコン
テキストを指定。
num_devices
device_listにあ
るデバイスの個数を指定。
device_list
コンテキスト内の
デバイスリストを指す
ポインタ。devide_list
は非NULLの値となり
ます。組込みカーネルは
リストで指定されたデバ
イスに対してロードされ
ます。プログラムオブジ
ェクトに関連付けられた
デバイスはdevice_list
が指定したデバイスの
リストとなる。
device_listが指定す
るデバイスのリストはコ
ンテキストと関連付けら
れたデバイスとなる必要
がある。
kernel_names
セミコロン要素区
切りの、組込みカーネル
の名称のリスト。
 成功した場合の戻り値
 CL_SUCCESS
 失敗した場合の戻り値
CL_INVALID_
CONTEXT
contextが有効なコン
テキストでない場合。
CL_INVALID_
VALUE
device_listが
NULL値か、
num_devicesが0
の場合。
CL_INVALID_
VALUE
kernel_namesが
NULL値か、
kernel_namesが
device_listのいず
れのデバイスもサポー
トをしていない文字列
を含む場合。
CL_INVALID_
DEVICE
device_listに
リストされたデバイス
が、コンテキストに
関連付けられたデバイ
スのリストにない場合。
CL_OUT_OF_
RESOURCES
デバイス上のOpenCL
実装が必要とする
リソース確保に失敗
した場合。
CL_OUT_OF_
HOST_MEMORY
ホスト上のOpenCL
実装が必要とする
リソース確保に失敗
した場合。

B.22.4. clRetainProgram

表B.65 表:clRetainProgram

関数
cl_int clRetainProgram
(
    cl_program program
)
 programの参照カウントをインクリメント。
clCreateProgramは暗黙的なリテインをする。
 成功した場合の戻り値
 CL_SUCCESS
 失敗した場合の戻り値
CL_INVALID_
PROGRAM
programが有効な
プログラムオブジェクト
でない場合。
CL_OUT_OF_
RESOURCES
デバイス上のOpenCL
実装が必要とする
リソース確保に失敗
した場合。
CL_OUT_OF_
HOST_MEMORY
ホスト上のOpenCL
実装が必要とする
リソース確保に失敗
した場合。

B.22.5. clReleaseProgram

表B.66 表:clReleaseProgram

関数
cl_int
clReleaseProgram
(
    cl_program program
)
 programの参照カウントをデクリメント。programに
関連付けられた全てのカーネルオブジェクトが削除され
programの参照カウントが0になるとプログラムオブジェ
クトは削除される。
 成功した場合の戻り値
 CL_SUCCESS
 失敗した場合の戻り値
CL_INVALID_
PROGRAM
program引数が有効な
プログラムオブジェクト
でない場合。
CL_OUT_OF_
RESOURCES
デバイス上のOpenCL
実装が必要とする
リソース確保に失敗
した場合。
CL_OUT_OF_
HOST_MEMORY
ホスト上のOpenCL
実装が必要とする
リソース確保に失敗
した場合。

Copyright 2018-2019, by Masaki Komatsu