CriWare APIの呼び出し

CriWare APIの呼び出しについて

AtomライブラリやManaライブラリのAPIをアプリケーションのC/C++ソースから呼び出す場合、以下の点に留意する必要があります。

DLL化によるメモリ空間の分離

PC版のUnreal Engineは、モジュールごとにDLLが作成される構造になっています。

CRIWARE Unreal Engineプラグインを組み込んだエディタやアプリケーションをビルドすると、CriWareRuntime.dllが作成されます。
CriWareRuntime.dllは、ロード時にAtomライブラリやManaライブラリを自動的に初期化します。
（ CriWareRuntime.dll には /Engine/Source/ThirdParty/CriWare 以下のライブラリがスタティックリンクされます。）

上記とは別に、ユーザが独自に作成したモジュールで /Engine/Source/ThirdParty/CriWare 以下のライブラリをリンクしてdllを作ってしまうと、CriWareRuntime.dllとは異なるメモリ空間にAtomライブラリやManaライブラリがマップされる形になります。
PC環境では CriWareRuntime.dll と アプリケーションDLLを別々に動作させることが一応は可能ですが、ゲーム機向けにビルドする場合やモノリシックビルド（1つのexeで出力）すると、DLLごとに分離されていたメモリ空間が1つになり正常に動作しなくなってしまいます。

CriWareApiクラスについて

上記問題への対策として、CRIWARE Unreal Engineプラグインでは、CriWareRuntime.dll内で初期化されたライブラリのAPIを呼び出すための特殊なエントリポイント「 CriWareApiクラス 」を用意しています。
CriWareApiクラスを経由してAtom／Manaライブラリを操作することで、CRIWARE Unreal Engineプラグインとアプリケーションとが同一のメモリ空間に配置されたライブラリをシェアすることが可能です。

CriWareApiクラスの使用方法

CriWareApi.hをインクルードし、Atom／Mana APIを呼び出す際に「FCriWareApi::」を付けることで、CriWareRuntimeモジュール内のAtom／Mana APIが呼び出されます。
通常のAtomライブラリのAPI呼び出しコードと、CriWareApi使用時のコードの比較を以下に示します。

≪元のコード≫

#include <cri_atom_ex.h>
    ：
criAtomExPlayer_Start(player);
    ：

≪CriWareApi使用時のコード≫

/* インクルードヘッダを変更 */
#include "CriWareApi.h"
    ：
/* FCriWare::を付加 */
FCriWareApi::criAtomExPlayer_Start(player);
    ：

補足:

「FCriWareApi::」を省略する方法も用意されています。
「FCriWareApi::」を省略するにはCriWareApiNativeStyleAlias.hをインクルードします。

≪修正後のコード≫

#include "CriWareApiNativeStyleAlias.h"
    ：
/* APIの呼び出しは元のコードのまま */
criAtomExPlayer_Start(player);
    ：

ハンドルの取得方法

AtomComponentやManaComponentが使用するAtomExプレーヤハンドルやManaプレーヤハンドルは、以下のAPIで取得可能です。

≪AtomExプレーヤハンドル≫

• UAtomComponent::GetAtomExPlayer

≪Manaプレーヤハンドル≫

• UManaComponent::GetManaPlayer

これらの関数で取得したハンドルをCriWareApiクラスのAPIで操作することで、AtomComponentやManaComponentにユーザ独自の設定を追加することが可能です。

Next:最適化