クライアントとアプリケーションの生存サイクル

CAPI を使いアプリケーションで何らかをなすのであれば、まずはじめに client を作成します。同様に、アプリケーションの終了前にはクライアントを開放しましょう。この節では以上作成と開放について詳述します。

クライアントの作成

CAPI を機能させるため、クライアントオブジェクトを作成します。クライアントオブジェクトとは、<オブジェクト, 型, プログラムの属する空間> を表し、ある一つのアプリケーションから複数のクライアントオブジェクト ―つまり複数のFabricアプリケーションを作成することができます。とはいえ、大抵のFabricアプリケーションでは一つのクライアントで十分でしょう。

クライアントオブジェクトの作成には以下のどれかの関数を呼びます:

// Creating a client object - C
FEC_ClientRef FEC_ClientCreate(
  FEC_ClientReportCallback reportCallback,
  void *reportUserdata,
  ...
 );

// Creating a client object - C++
FabricCore::Client::Client(
  ReportCallback reportCallback,
  void *reportUserdata,
  ...
  );

必須引数 guarded とは配列アクセスを保護（境界チェック）するかどうかを示す真偽値です。このフラグを true に設定すると実行時パフォーマンスの若干の低下と引き換えに、配列境界外へのアクセスの際にエラーを提供できます。

任意の引数、 reportCallback, reportUserdata を与えると、FabricCore でreport文を表示するようC関数が呼ばれます。このような report文は、通常 KLコードでの report 呼び出しの結果、あるいは実行時のエラー（例えば境界外アクセスエラー）の結果です。この関数はプロトタイプ prototype を必要とします:

// Report callback function prototype - C and C++
void ReportCallbackFunction(
  void *reportUserdata,
  char const *stringData,
  uint32_t stringLength
  );

reportUserdata へ与える値は、提供されるコールバック関数の第一引数として渡されます。 stringData, stringLength パラメータは report内容の C文字列（改行 ―newlineを含めない）とその文字列の長さを示します。

reportCallback を指定しない場合（あるいは NULL を渡す場合）、Fabric Core は report文を標準出力へ出力します。

Aside from creating clients using the constructor or Client::Create clients can also be created as singleton. To save memory and manage a single unique client you can also use the Client::GetSingleton method:

// Creating a singleton client object - C++
Client client = FabricCore::Client::GetSingleton(
  ReportCallback reportCallback,
  void *reportUserdata,
  ...
  );

クライアントの解放

クライアントの使用後には開放しなければなりません。クライアントは参照カウントされるオブジェクトなので、C++ ではスコープ外に外れると自動で解放されます。Cでは、『手動』で FEC_RefRelease() を呼びクライアントを開放します。

クライアントの操作

クライアントを作成したのであれば、 client API functions を使用した操作が可能になります。

APIレファレンス - C

APIレファレンス - C++ もあります。

FEC_ClientRef

CAPI クライアントへの参照. クライアントを FEC_ClientCreate() で作成するとこれら参照を返す. 最終的には FEC_RefRelease() により解放する.

FEC_ReportSource

Fabric Core よりやってくる report行のソースタイプ. 以下のうちのいずれか:

• FEC_ReportSource_System
• FEC_ReportSource_System

FEC_ClientSetReportSourceMask() 関数を使用し、以上の値をビットマスク（あるいはアンマスク）として扱う. 以下についてもどうようにマスクとして扱う.

• FEC_ReportSource_NONE
• FEC_ReportSource_ALL

FEC_ReportLevel

Fabric Coreからのreport行の重大度レベル（severity level）. 以下のうちのいずれか:

• FEC_ReportLevel_Error
• FEC_ReportLevel_Warning
• ``FEC_ReportLevel_Info ``
• FEC_ReportLevel_Debug

FEC_ClientReportCallback

クライアントに関連づいたreportコールバック関数の型. このような関数は以下の様なプロトタイプを持たねばならない:

void ClientReportCallback(
  void *reportUserdata,
  FEC_ReportSource source,
  FEC_ReportLevel level,
  char const *lineCStr,
  uint32_t lineSize
  );

FEC_ClientRef FEC_ClientCreate(FEC_ClientReportCallback reportCallback, void *reportUserdata, int guarded, int traceOperators, FEC_ClientOptimizationType optimizationType)

新規の FabricプラットフォームCoreクライアント を作成する

パラメータ:

• reportCallback – Fabric Engine core からの report文を受けるコールバック関数
• reportUserdata – report文のユーザデータ; reportCallback に渡す
• guarded – KLでの配列アクセスによる境界外エラー例外を送信するかどうか
• trapOnThrow – KLから例外が送信された際トラップするかどうか
• traceOperators – オペレータへ自動トレースreport文を追加するかどうか
• optimizationType – クライアントでのKL最適化方式

戻り値:

新しいクライアントへの参照, ただしエラー時には FEC_NULL_REF

FEC_ClientRef FEC_ClientBind(FEC_ClientReportCallback reportCallback, void *reportUserdata, char const *contextID)

既存のクライアントを与えらたクライアントIDにバインドする. 複数のCAPIプログラムから同一のクライアント ―― Fabric Engine Core を同じ状態で作業可能となる.

パラメータ:

• contextID – (C string) バインドするコンテクストID. このクライアントのコンテクストIDは, FEC_ClientGetContextID() 関数により取得

戻り値:

与えられたコンテクストIDの既存クライアントへの新しい参照, ただしエラー時には FEC_NULL_REF

FEC_ClientRef FEC_ClientGetSingleton(FEC_ClientReportCallback reportCallback, void *reportUserdata)

The Fabric Core can maintain a singleton instance of a Client for sharing between multiple Fabric Core users. The first time this function is called a Client instance will be created and any subsequent calls will return a handle to this same instance. The CreateOptions are only used if this is the first call to GetSingleton(), if the singleton already exists then this parameter is ignored.

戻り値:A new reference to the singleton client object.

FEC_ClientRef FEC_ClientInvalidateSingleton()

This function will invalidate the Core’s reference to the singleton Client so that the next call to GetSingleton() will return a new Client object. Any outstanding references to the previous singleton Client will continue to work and it will only be destroyed when there are no references left.

void FEC_ClientSetReportCallback(FEC_ClientRef clientRef, FEC_ClientReportCallback reportCallback, void *reportUserdata)

クライアントの reportコールバックを設定. 既存コールバックが存在しても上書き. reportCallback へ NULL を渡してもクライアントへの reportコールバックは発火しない.

パラメータ:

• clientRef – クライアントを示す
• reportCallback – 新しい reportコールバック
• reportUserdata – コールバック発火時そのコールバックへと渡すユーザデータ

void FEC_ClientEnableRuntimeLogging(FEC_ClientRef clientRef)

そのクライアントでの実行時のロギングを有効にする. 実行時ロギングとは, KLプログラムのreport文によりひき起こされ, クライアントへの「reportコールバック」として発火する. ディフォルトでこの実行時ロギングは有効.

パラメータ:

• clientRef – クライアントを示す

void FEC_ClientDisableRuntimeLogging(FEC_ClientRef clientRef)

そのクラアントでの実行時ロギングを無効にする. 実行時ロギングとは, KLプログラムのreport文によりひき起こされ, クライアントへの「reportコールバック」として発火する. ディフォルトでこの実行時ロギングは有効.

パラメータ:

• clientRef – クライアントを示す

void FEC_ClientSetReportSourceMask(

FEC_ClientRef clientRef,

FEC_ReportSource sourceMask()

)

Coreより来る report行にソースマスクを設定. つまり「ユーザreport文」のみ受け取ることが可能になる.

注釈

クライアント終了と共にreport行のフィルタも発生しえます。終了とはいえ通常 Core がこのフィルタを行う余地はあります。

void FEC_ClientSetReportLevelMax(

FEC_ClientRef clientRef,

FEC_ReportLevel levelMax()

)

Coreより来る report行に最大重大度レベルを設定, これにより特定のレベルのみ ―errorとwarningのみ受け取り info と debug をreport行からフィルタしてしまうといったことが可能.

注釈

クライアント終了と共にreport行のフィルタも発生しえます。終了とはいえ通常 Core がこのフィルタを行う余地はあります。

char const *FEC_ClientGetContextID(FEC_ClientRef clientRef)

クライアントに紐付いたコンテクストIDをC文字列として取得. FEC_ClientBind() の呼び出しの際に使用し, そのクライアントへの新規の参照を得る.

パラメータ:

• clientRef – クライアントを示す

戻り値:

クライアントID（C文字列）

void FEC_ClientStartInstrumentation(FEC_ClientRef clientRef)

クライアントの計測（instrumentation）を開始. 既に計測セッションを開始している場合, この関数により計測を再始動.

パラメータ:

• clientRef – クライアントを示す

FEC_Variant FEC_ClientStopInstrumentation_Variant(FEC_ClientRef clientRef, char const *resultType)

クライアントの計測をストップ, 計測結果を戻す. 結果のフォーマットは resultType に依る, 以下のうちいずれかを指定 “timing”, “simpleTiming”, “simpleTimingNoExternal”, “raw”.

パラメータ:

• clientRef – クライアントを示す
• resultType – 結果のフォーマット

戻り値:

計測データ（variant型）

void FEC_ClientLoadExtension(FEC_ClientRef clientRef, char const *extName, int reload)

エクステンションを読み込む（ただし未読み込みの場合）

パラメータ:

• clientRef – クライアントを示す
• extName – 読み込むエクステンションの名前（C文字列）
• reload – true に設定した場合, KLコードをディスクから再読み込み掛ける.

void FEC_ClientRegisterExtensions(FEC_ClientRef clientRef, char const *pathname)

指定したディレクトリ以下のエクステンションを登録

パラメータ:

• clientRef – クライアントを示す
• pathname – エクステンションを検索するパス名

void FEC_ClientExportExtension(FEC_ClientRef clientRef, char const *extNameCString, char const *outputFile)

エクステンションを難読化した形式で指定のファイルへとエクスポート

パラメータ:

• clientRef – クライアントを示す
• extNameCString – エクスポートするエクステンション名
• outputFile – 作成するファイル名
• compress – 出力ファイルを圧縮するか, 平テキストのママか

void FEC_ClientSetLogWarnings(FEC_ClientRef clientRef, int logWarnings)

クライアントで生起する警告をログするかどうか Core に伝達. クライアントによって警告が非推奨な挙動となっている場合がある. ディフォルトで警告は『ログされない』

パラメータ:

• clientRef – クライアントを示す
• logWarnings – 警告をログするか

FEC_ClientStatusCallback

クライアントに紐づくステータスコールバック関数の型; FEC_ClientSetStatusCallback() 参照. このような関数は以下のプロトタイプを持つ:

void ClientStatusCallback(
void *userdata,
char const *destData, uint32_t destLength,
char const *payloadData, uint32_t payloadLength
  );

void FEC_ClientSetStatusCallback(FEC_ClientRef clientRef, FEC_ClientStatusCallback callback, void *userdata)

クライアントに紐づくステータスコールバックを設定. KLコードがクライアントへとステータスメッセージを戻すやりとりを行う際に, このステータスコールバックを使用する。

パラメータ:

• clientRef – クライアントを示す
• callback – 設定するステータスコールバック
• userdata – ステータスコールバックが呼ばれる際, 渡すユーザデータ

void *FEC_ClientGetStatusUserdata(FEC_ClientRef clientRef)

クライアントに紐づく, ステータスユーザデータを戻す。 FEC_ClientSetStatusCallback() によって指定する最後の値

パラメータ:

• clientRef – クライアントを示す

戻り値:

クライアントに紐づくステータスユーザデータ

void FEC_ClientQueueStatusMessage(FEC_ClientRef clientRef, char const *destCString, char const *payloadCString)

ステータスメッセージを Queue する。ステータスメッセージは, カレントクライアントIDをもつ全クライアント（与えられるクライアントも含む）へ送られる。これにより, ごく簡単な非同期通信機構 ――<同じクライアントを示す参照を複数持った, 同じプロセス> 上の複数のパート間での非同期通信を達成できる。

パラメータ:

• clientRef – クライアントを示す
• destCString – ステータスコールバックに渡す宛先（C文字列）
• payloadCString – ステータスコールバックへ渡す「荷物」（文字列）

void FEC_ClientValidateLicense()

即時にライセンスの評価を強制。ライセンスをディスクに保存した後のライセンスの再評価等に使用する。ライセンスの確認結果をクライアントのロガーへ送り, ステータスコールバックヘライセンスデータを送る。

パラメータ:

• clientRef – クライアントを示す

void FEC_ClientHasCommercialLicense()

現在使用しているライセンスが支払い済の商用ライセンスであれば true を戻す。ライセンスが無効であれば常に false を戻す

パラメータ:

• clientRef – クライアントを示す

void FEC_SetStandaloneLicense(char const *licenseCString)

ローカルライセンスを設定

パラメータ:

• licenseCString – RLMフォーマットのライセンス

void FEC_FlagUserInteraction()

Notify the Core of user activity.

void FEC_ClientEnableBackgroundTasks(FEC_ClientRef clientRef)

クライアントでのバックグラウンドでのタスク実行を有効にする。アプリケーションのロードが完了した後に一度だけ呼ぶ。この関数を呼ばない場合, バックグラウンドタスクは実行『されない』。（バックグラウンドでのKL最適化など）クライアント作成後に即呼ぶことも可能だが, 起動し操作可能になるまでの時間が長くなる

パラメータ:

• clientRef – クライアントを示す

int FEC_ClientIsBackgroundOptimizationInProgress(FEC_ClientRef clientRef)

KLコードの最適化の現在の進捗をチェック

パラメータ:

• clientRef – クライアントを示す

戻り値:

最適化進行中であれば非ゼロ, それ以外はゼロ

void FEC_ClientAdoptCurrentGLContext(FEC_ClientRef clientRef)

*FIXME*.

パラメータ:

• clientRef (FEC_ClientRef) – クライアントを示す

void FEC_ClientIdle(FEC_ClientRef clientRef)

クライアントのメインスレッドがアイドルであるか Fabric Engine Core に問い合わせる。定期的にこれを呼び出すことで, Coreにコールバックの対応機会を与える。さもなければ次に Core を呼び出す時までコールバックが放置される

パラメータ:

• clientRef (FEC_ClientRef) – クライアントを示す

void FEC_ClientSupportsGPUCompute(FEC_ClientRef clientRef)

Fabric Engine core から見たハードウェアがGPUコンピュートをサポートするかどうか, サポートしていれば true を戻す

パラメータ:

• clientRef (FEC_ClientRef) – クライアントを示す

APIレファレンス - C++

APIレファレンス - C もあります。

type FabricCore::ClientOptimizationType

KLのバックグラウンド最適化のモードを示すタイプ, Clientコンストラクタによりクライアントを作成する際に指定する。以下の3つのうちのどれか:

FabricCore::ClientOptimizationType_Background

バックグラウンドでの最適化 (ディフォルト)

FabricCore::ClientOptimizationType_Synchronous

KLコードの同期最適化。 プログラムの立ち上がりが遅くなるが, 最適化されたコードを即つかえる

FabricCore::ClientOptimizationType_None

KLコードの最適化を行わない

class FabricCore::Client : public FabricCore::Ref

Client GetSingleton(ReportCallback reportCallback, void *reportUserdata, CreateOptions const *createOptions)

The Fabric Core can maintain a singleton instance of a Client for sharing between multiple Fabric Core users. The first time this function is called a Client instance will be created and any subsequent calls will return a handle to this same instance. The CreateOptions are only used if this is the first call to GetSingleton(), if the singleton already exists then this parameter is ignored.

戻り値:A new reference to the singleton client object.

void registerExtensions(char const *pathnameCStr)

指定したディレクトリ以下のエクステンションを登録

パラメータ:pathname – エクステンションを検索するパス名