CriWare APIの呼び出しについて

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

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

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

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

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

CriWareApiクラスについて

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

CriWareApiクラスの使用方法

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

≪元のコード≫

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

≪CriWareApi使用時のコード≫

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

補足:

プリプロセッサ処理で「FCriWareApi::」を自動的に付加する仕組みも用意されています。
CriWareApi.hをインクルードする前にCRIWARE_DEFINE_COMPATIBLE_MACROをdefineすることで、「FCriWareApi::」を省くことも可能です。

≪修正後のコード≫

/* プリプロセッサ定義を追加 */
#define CRIWARE_DEFINE_COMPATIBLE_MACRO
#include "CriWareApi.h"
    ：
/* APIの呼び出しは元のコードのまま */
criAtomExPlayer_Start(player);
    ：

ハンドルの取得方法

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

≪AtomExプレーヤハンドル≫

• UAtomComponent::GetAtomExPlayer

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