B.10. Context

B.10.1. clCreateContext

表B.16 表:clCreateContext

関数
cl_context
clCreateContext (
    const cl_context_properties *properties,
    cl_uint num_devices,
    const cl_device_id *devices,
    void (CL_CALLBACK *pfn_notify)
    (
        const char *errinfo,
        const void *private_info,
        size_t cb,
        void *user_data
    ),
    void *user_data,
    cl_int *errcode_ret
)
 コンテキストを生成。
 引数
properties
コンテキストのプロパティ名とそれに対応する値のリ
ストを指定。それぞれのプロパティ名には、対応する
値が続く。リストは0を終端とする。propertiesに
は NULLを指定できるが、どのプラットフォームが選
択されるかは実装に依存。
num_devices
devices引数に渡したデ
バイスの数を指定。
devices
OpenCLプラットフォーム
についてclGetDeviceIDs
)で取得したユニークなデ
バイス(またはclCreate
SubDevicesで取得したサ
ブデバイス)のリストへの
ポインタを指定。
pfn_notify
コールバック関数を登録。
このコールバック関数は、
コンテキスト内で発生した
エラーについての情報を通
知するために OpenCL実
装が使用。このコールバ
ック関数は、非同期的に
呼び出される。コールバ
ック関数がスレッドセーフ
であることを保証するの
は、アプリケーションの
責任となる。
errinfo
エラー文字列を指すポインタ。
private_info
and cb
 OpenCL実装が戻す
エラーをデバッグする
際に有用となる付加的
情報を記録するのに用
いるバイナリデータへ
のポインタ。
user_data
ユーザが与えたデータ
を指すポインタ。
user_data
pfn_notifyが呼び出さ
れた場合、user_data
引数として渡す。NULL
も指定可。
errcode_ret
適切なエラーコードを
戻す。errcode_retが
NULLの場合、エラーコ
ードは戻さない。
 成功した場合の戻り値
 生成したコンテキスト、
CL_SUCCESSをerrcode_
retに設定。
 失敗した場合の
errorcode_retの設定値
CL_INVALID_
PLATFORM
propertiesがNULLで
かつプラットフォームが
ひとつも選択されなかっ
た場合。properties内
で指定したプラットフォ
ームが有効なプラットフ
ォームでない場合。
CL_INVALID_
PROPERTY
properties内で指定
したコンテキストプロパ
ティ名がサポートされて
いるプロパティ名でない
場合。

サポートされているプロ
パティ名に対して指定し
た値が有効でない場合。
同じプロパティ名が重複
して指定されている場合。
CL_INVALID_
VALUE
devicesがNULLの場合。
CL_INVALID_
VALUE
num_devicesが0の場合。
CL_INVALID_
VALUE
pfn_notifyがNULL
でuser_dataがNULL
でない場合。
CL_INVALID_
DEVICE
devicesが有効でな
いデバイスを含む場合。
CL_DEVICE_
NOT_AVAILABLE
devices内のデバイス
が、clGetDeviceIDs
で返されたデバイスで
あるものの現在利用可
能でない場合。
CL_OUT_OF_
RESOURCES
デバイス上のOpenCL
実装が必要とするリ
ソース確保に失敗した
場合。
CL_OUT_OF_
HOST_MEMORY
ホスト上のOpenCL
実装が必要とするリ
ソース確保に失敗し
たとき。

B.10.2. cl_context_properties

表B.17 表:cl_context_properties

cl_context_
properties 列挙値
プロパティ値
詳細
CL_CONTEXT_
PLATFORM
cl_platform_id
使用するプラット
フォームを指定。

CL_CONTEXT_
INTEROP_USER_
SYNC
cl_bool


ユーザがOpenCL
と他のAPIの同期に
責任を持つか指定。
既定値はCL_FALSE。

B.10.3. clCreateContextFromType

表B.18 表:clCreateContextFromType

関数
cl_context
clCreateContextFromType (
    const cl_context_properties *properties,
    cl_device_type device_type,
    void (CL_CALLBACK *pfn_notify)
    (
        const char *errinfo,
        const void *private_info,
        size_t cb,
        void *user_data
    ),
    void *user_data,
    cl_int *errcode_ret
)
 使用する特定デバイスを識別するデバイス
型からOpenCLコンテキストを生成。
clGetDeviceIDsのdevice_typeに戻って
きたデバイスのみコンテキスト生成に使える。コ
ンテキストは、デバイスから生成されたサブデバ
イスは参照しない。
 引数
properties
コンテキストプロパ
ティの名称と対応する値
のリスト。各プロパティ
名は対応する値がすぐに
続く。
device_type
デバイス型を識別
するビットフィールド。
pfn_notify and user_data
clCreateContext
で詳細は記述済み。
errcode_ret
適切なエラーコード
を戻す。errcode_ret
がNULLの場合、エラー
コードは戻さない。
 成功した場合の
戻り値
 生成したコンテキスト、
CL_SUCCESSをerrcode_
retに設定。
 失敗した場合の
errcode_retの値
CL_INVALID_
PLATFORM
propertiesがNULLの
場合で、platformが
選択されていない場合。
propertiesで指定した
platformの値が有効な
プラットフォームでない場合。
CL_INVALID_
PROPERTY
プロパティ内のコンテ
キストのプロパティ名が
サポートされてない場合。
重複でプロパティ名が指
定された場合。
CL_INVALID_
VALUE
pfn_notifyがNULLで
user_dataがNULLでない場合。
CL_INVALID_
DEVICE_TYPE
device_typeが有効
な値でない場合。
CL_DEVICE_
NOT_AVAILABLE
propertiesで指定さ
れたdevice_typeやプ
ロパティ値にマッチする
デバイスが利用可能で
ない場合。
CL_DEVICE_
NOT_FOUND
propertiesで指定
されたdevice_typeや
プロパティ値にマッチす
るデバイスが見つからな
い場合。
CL_OUT_OF_
RESOURCES
デバイス上のOpenCL
実装が必要とするリソ
ース確保に失敗した場合。
CL_OUT_OF_
HOST_MEMORY
ホスト上のOpenCL
実装が必要とするリソ
ース確保に失敗した場合。

B.10.4. clRetainContext

表B.19 表:clRetainContext

関数
cl_int
clRetainContext
(
    cl_context context
)
 コンテキストの参照カウントをインク
リメント。
 成功した場合の戻り値
 CL_SUCCESS
 失敗した場合の戻り値
CL_INVALID_
CONTEXT
contextが有効な
OpenCLコンテキスト
でない場合。
CL_OUT_OF_
RESOURCES
デバイス上のOpenCL
実装が必要とするリソ
ース確保に失敗した場合。
CL_OUT_OF_
HOST_MEMORY
ホスト上のOpenCL
実装が必要とするリソ
ース確保に失敗した場合。

B.10.5. clReleaseContext

表B.20 表:clReleaseContext

関数
cl_int
clReleaseContext
(
    cl_context context
)
 コンテキストの参照カウントをデクリメント。
 成功した場合の戻り値
 CL_SUCCESS
 失敗した場合の戻り値
CL_INVALID_
CONTEXT
contextが有効なOpen
CLコンテキストでない場合。
CL_OUT_OF_
RESOURCES
デバイス上のOpenCL
実装が必要とするリソ
ース確保に失敗した場合。
CL_OUT_OF_
HOST_MEMORY
ホスト上のOpenCL
実装が必要とするリソ
ース確保に失敗した場合。

B.10.6. clGetContextInfo

表B.21 表:clGetContextInfo

関数

cl_int

clGetContextInfo (
    cl_context context,
    cl_context_info param_name,
    size_t param_value_size,
    void *param_value,
    size_t *param_value_size_ret
)

コンテキストについての情報の取得ができる。

引数

context

情報取得するOpenCL
コンテキストを指定。

param_name

取得する情報を指定
する列挙定数。

param_value

情報取得する結果が
戻るメモリ領域を指す
ポインタ。NULLの場合
は無視。

param_value_ size

param_valueが指す
メモリのバイトサイズを
指定。サイズは戻り値型
のサイズ以上となる必要
がある。

param_value_ size_ret

param_valueの実際
のバイトサイズを戻す。

成功した場合の戻り値

CL_SUCCESS

失敗した場合の戻り値

CL_INVALID_CONTEXT

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

CL_INVALID_ VALUE

param_nameがサポート
される値でない場合。
param_value_sizeが
指定するバイトサイズが
戻り値型より小さい場合
で、param_valueが
NULLでない場合。

CL_OUT_OF_ RESOURCES

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

CL_OUT_OF_ HOST_MEMORY

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

B.10.7. cl_context_info

表B.22 表:cl_context_info

cl_context_ info 

戻り値型

param_valueに
戻される情報

CL_CONTEXT_ REFERENCE_ COUNT 

cl_uint


コンテキストの参照
カウントを戻す。


CL_CONTEXT_ NUM_DEVICES

cl_uint
コンテキスト内のデ
バイスの個数を戻す。

CL_CONTEXT_ DEVICES 

cl_device_
id[]


コンテキスト内のデ
バイスのリストを戻す。


CL_CONTEXT_ PROPERTIES

cl_context_
properties[]

clCreateContext
または
clCreateContextFromType
で指定したproperties
引数を戻す。

contextを生成するの
に用いたproperties引数
がNULLでない場合、
OpenCL実装は指定した
properties引数の値を
戻す。

contextを生成するのに
用いたproperties引数
がNULLの場合、OpenCL
実装はparam_value_size_ret
を0にして戻すか、
param_valueが指すメモリ
領域でコンテキストプロパテ
ィの値を0にして戻す(0は
コンテキストプロパティの
リストの終端を示す)。

Copyright 2018-2019, by Masaki Komatsu