clBuildProgram
cl_int clBuildProgram (cl_program program, cl_uint num_devices, const cl_device_id *device_list, const char *options,
void (CL_CALLBACK *pfn_notify)(cl_program program, void *user_data), void *user_data)
-1.1() : OpenCL 1.1で削除
+1.1() : OpenCL 1.1で追加
program と関連付けられたOpenCLコンテキスト内の全てもしくは特定のデバイス用の実行可能プログラムを、プログラムソースもしくはバイナリからビルド（コンパイルとリンク）します。OpenCL では、プログラムソースもしくはバイナリを使用して実行可能プログラムをビルドできます。clBuildProgram は clCreateProgramWithSource あるいは clCreateProgramWithBinary を呼び出して作成した program に対して使用しなければなりません。
パラメータ
- program
- 有効なプログラムオブジェクトを指定します。
- num_devices
- device_list 引数に渡したデバイスの数を指定します。
- device_list
- program と関連付けられたデバイスのリストへのポインタを指定します。deivce_list が NULL のとき、program と関連付けられたすべてのデバイス用の実行可能プロうグラムがビルドされます。deivce_list が NULL でないとき、このリストで指定されたデバイス用の実行可能プログラムがビルドされます。
- options
- 実行可能プログラムをビルドする際に適用するビルドオプションを指定する +1.1(NULL 終端)文字列へのポインタを指定します。サポートされるオプションについては以下の節にあります。
- pfn_notify
- コールバック関数を登録します。アプリケーションがコールバック関数を登録すると、実行可能プログラムがビルドされたときに、登録した関数が成功失敗に関わらず呼び出されます。pfn_notify が NULL でないとき、clBuildProgram はビルドの完了を待つ必要が無くなりすぐに返ることができます。pfn_notify が NULL のとき、clBuildProgram はビルドが完了するまで返りません。このコールバック関数は非同期的に呼び出されます。コールバック関数がスレッドセーフであることを確実にするのは、アプリケーションの責任です。このコールバック関数に対するパラメータは以下のとおりです。
- user_data
- ユーザが与えたデータへのポインタです。
- user_data
- pfn_notify が呼び出されたときに、user_data 引数として渡されます。NULL を指定することもできます。
ビルドオプション
ビルドオブションは、プリプロセッサオプション、組み込み数学機能に関するオプション、最適化やその他様々なオプションを制御するオプションに分類されます。本仕様では、実行可能プログラムをオンラインもしくはオフラインでビルドする際に OpenCL コンパイラがサポートしなければならない標準オプションセットを定義しています。このオプションは、ベンダやプラットフォーム依存のオプションで拡張できます。
プリプロセッサオプション
実際のコンパイルの前に各プログラムソースに適用されるOpenCLプリプロセッサを制御するオプションです。
-D name- name を定義「1」のマクロとして事前定義します。
-D name=definition- definition の内容はトークン化され、'#define' ディレクティブを第3翻訳フェーズで扱う時と同様に処理されます。 特に、改行文字が埋め込まれているとそこで定義が打ち切られます。
-D オプションは、clBuildProgram に指定した options 引数内での並びの順に処理されます。
-I dir- dir を、ヘッダファイルを検索する際の対象ディレクトリの一覧に加えます。
組み込み数学機能に関するオプション
浮動小数点演算に関するコンパイラのふるまいを制御します。これらのオプションは、処理速度と正確性とのトレードオフになります。
-cl-single-precision-constant- 倍精度浮動小数点定数を単精度浮動小数点定数として扱います。
-cl-denorms-are-zero- 単精度および倍精度非正規化数をどのように扱うかを制御するオプションです。このオプションを指定すると、単精度非正規化数を0に丸めることができ、倍精度浮動小数点数がサポートされている場合はこちらも0に丸めることができます。このオプションは、パフォーマンスに関して求める要件をコンパイラに伝えることを意図しており、OpenCLコンパイラはデバイスが単精度（もしくは倍精度）非正規化数をサポートしているときに非正規化数を0に丸めないという選択が可能です。
- このオプションは、デバイスが単精度非正規化数をサポートしていない―CL_DEVICE_SINGLE_FP_CONFIG に CL_FP_DENORM ビットが立っていない―とき、単精度浮動小数点数に関しては無視されます。
- このオプションは、デバイスが倍精度浮動小数点数をサポートしていないもしくは倍精度浮動小数点数をサポートしているが倍精度非正規化数をサポートしていない―CL_DEVICE_DOUBLE_FP_CONFIG に CL_FP_DENORM ビットが立っていない―とき、倍精度浮動小数点数に関しては無視されます。
- このフラグは、スカラおよびベクトル単精度浮動小数点変数とこれら浮動小数点変数へのプログラム内での演算処理にのみ適用されます。イメージオブジェクトからの読み込みやイメージオブジェクトへの書き込みには適用されません。
最適化オプション
様々な種類の最適化を制御するオプションです。最適化フラグを有効にすると、コンパイラはコンパイル時間や場合によってはプログラムのデバッグのしやすさと引き換えに、パフォーマンスおよび/もしくはコードサイズの改善を試みます。
-cl-opt-disable- すべての最適化を無効にするオプションです。既定では最適化は有効化されています。
-cl-strict-aliasing- コンパイラに対し、厳密な別名規則に則っていると仮定することを許可します。
エラー
実行が成功した場合、clBuildProgram は CL_SUCCESS を返します。そうでない場合は以下のエラーのうちひとつを返します。
- CL_INVALID_PROGRAM - program が有効なプログラムオブジェクトでないとき。
- CL_INVALID_VALUE - device_list が NULL で num_devices が 0 より大きいとき。あるいは、device_list が NULL でなく num_devices が 0 のとき。
- CL_INVALID_VALUE - pfn_notify が NULL で user_data が NULL でないとき。
- CL_INVALID_DEVICE - device_list にリストされたOpenCLデバイスが program に関連付けられたデバイスのリスト内にないとき。
- CL_INVALID_BINARY - clCreateWithProgramBinary を使用して作成した program について、device_list 内のデバイス用の有効なプログラムバイナリがないとき。
- CL_INVALID_BUILD_OPTIONS - options に指定したビルドオプションが有効でないとき。
- CL_INVALID_OPERATION - この呼び出しより前に program に対して行われた clBuildProgram の呼び出しでの、device_list 内のいずれかのデバイスについての実行可能プログラムのビルドが完了していないとき。
- CL_COMPILER_NOT_AVAILABLE - program が clCreateProgramWithSource を使用して作成されたもので、コンパイラが利用可能でないとき。
- CL_BUILD_PROGRAM_FAILURE - 実行可能プログラムのビルドに失敗したとき。このエラーは、ビルドが完了するまで clBuildProgram が返らないときに返されます。
- +1.1(CL_OUT_OF_RESOURCES - デバイス上でのリソース確保に失敗したとき。)
- CL_OUT_OF_HOST_MEMORY - ホスト上でのリソース確保に失敗したとき。
変更記録
脚注
