API体系

本プラグインのAPI体系は基本的にネイティブSDKに準じたものとなります。
ネイティブSDK向けのAPIリファレンスやサンプルも併せてご参照ください。

ここでは、ネイティブAPIとC#向けAPIの対応関係や、ネイティブAPIと利用方法が異なるAPIについて説明します。

ネイティブAPIとC#APIの対応関係

モジュール名とクラス定義

CRIWAREのネイティブAPIはいくつかのモジュールに分類されており、そのモジュール名と操作の内容から関数名を定義しています。
C#向けAPIにおいては各モジュール毎にクラスを定義しており、そのメンバーとしてメソッドが存在します。

また、CRIWAREのクラスはすべてCriWare名前空間以下に定義されます。

CriBool criAtomExAcf_GetCategoryInfo(CriUint16 index, CriAtomExCategoryInfo* info)	// ネイティブAPI

bool CriWare.CriAtomExAcf.GetCategoryInfo(ushort index, out CriAtomExCategory.Info info)	// C#向けAPI

また、情報の受け渡しに利用する構造体も関連するクラスのメンバーとして定義されます。

オブジェクトインスタンス

CRIWAREではネイティブAPIにおいても一部モジュールを生成/破棄が可能なオブジェクトとして取り扱います。

C#向けAPIにおいても同様にオブジェクトインスタンスとして対応しています。
このとき、いくつかの関数は例外的な命名がある点にご留意ください。

  • *_Create関数はコンストラクタとして定義されます
  • オブジェクトの破棄を行う関数は元の名前に関わらずDisposeメソッドとして定義されます
    • *_Destroy
    • criAtomExVoicePool_Free
    • criAtomExAcb_Release
    • etc...

コールバック

CRIWAREでのコールバック登録APIは関数ポインタを引数としてとります。

criErr_SetCallback(CriErrCbFunc cbf)  // ネイティブAPI

CriWare.CriErr.SetCallback(delegate*unmanaged[Cdecl]<NativeString, uint, uint, IntPtr, void> cbf) // C#向けAPI

コールバックオブジェクト

C#からのコールバック利用を補助するため、コールバック登録APIと対となるメンバープロパティを用意しています。

CriErr.CbFunc CriErr.Callback {get;}

上記プロパティから取得できるコールバックオブジェクトがもつEventメンバーに対して、event構文での購読/解除が可能です。

CriErr.Callback.Event += OnErrorCallback;

また、コールバックオブジェクトは共通インターフェイスICallback<TArgs>を実装しています。

スレッド制約

CRIWAREからのコールバックは、多くの場合CRIWARE内部の独自スレッドから呼び出されます。
一方で、C#向けのゲームエンジンやUIフレームワークのAPIは、フレームワークが立ち上げた特定のスレッドから呼び出す必要があります。
このため、CRIWAREに登録したコールバック処理から直接ゲームエンジン/UIフレームワークのAPIを呼び出すことはできません。

上述の共通インターフェイスICallback<TArgs>に対する拡張メソッドを実装することで、 スレッドの移譲を含む任意の処理を追加実装できます。
サンプルプロジェクトSampleExtensionsも併せてご確認ください。

マクロ

ネイティブSDKでは、C言語向けヘッダ内でのマクロとして提供されているAPIが存在します。
(関数形式マクロや定数の定義など)
これらの一部はC#向けAPIとしての提供がありませんが、利用上必須となるAPIについては対応済みです。

初期化/終了API

CRIWAREではライブラリの利用前後に初期化/終了を明示的に行う必要があります。
ADXのネイティブAPIでは機種固有のAPIを利用して初期化/終了を行う必要がありますが、
C#向けプラグインでは以下の初期化/終了メソッドを用意しています。

マルチプラットフォーム向けのアプリケーションでADXの初期化を行う場合、
上記メソッドの利用をご検討ください。

独自の型定義

CRIWAREネイティブでの表現とC#での表現で内部構造が大きく異なる型がいくつか存在します。
APIの呼び出し時に型の構造を変換することも可能ですが、変換の処理自体やヒープへのデータ確保がパフォーマンスへの影響を与えます。
本プラグインでは、より効率的な呼び出しを行うために、C#本来の型に代わって独自の値型を利用している部分があります。

引数文字列

CRIWAREのAPIに引数として渡す文字列はArgString型として受けています。 ArgString型はstringからのキャストを持っており、通常通りstringを渡すと文字コード変換が行われます。

また、byte配列として文字列を構築した場合や、UTF8文字列リテラルを利用する場合は文字コード変換が不要です。
このようなケースではArgString型の引数にSpan<T>/ReadOnlySpan<T>/`IntPtrを指定することで文字コード変換を回避できます。

メンバー文字列

CRIWAREのAPIから取得した構造体のメンバーとして文字列が与えられる場合、NativeString型として定義されます。
構造体の他メンバーのみのアクセスの場合マネージド文字列への変換は不要であるため、構造体の取得時点では変換を行っていません。
NativeStringに対するToString()の呼び出しや、stringへのキャスト時点で、ヒープアロケーションを伴う変換が行われます。

bool

bool型に代わってNativeBool型を定義しています。
アロケーションなしにboolとの双方向のキャストが可能です。

メンバー配列

構造体内に固定長配列が定義されている場合、InlineArray1<T>等の値型として定義しています。
配列長ごとに別々の型として定義しており、内部構造はdotnet8以降でのInlineArrayと同様です。
Span<T>への変換を介して内容のアクセスができます。