|
Wwise SDK 2019.1.11
|
Wwise のオープンアーキテクチャは、次の3種類のプラグインをサポートしています：サウンドを生成するソースプラグイン、サウンドを向上させるエフェクトプラグイン、Wwise 内でのソース管理ソフトウェア使用を可能にするソース管理プラグイン。
最初の2種のプラグインは、デフォルトプロパティ値を含めた一部のプラグイン設定を、コードの再コンパイルなしですばやく変更することができる XML プラグイン記述ファイルを使用します。Wwise プラグイン DLL は、複数のプラグインを含めることが可能ですが、各プラグインが関連 XML ファイルで記述されている必要があります。
各 Wwise プラグインDLL の XML 記述ファイルは、XML ファイルの拡張子以外は DLL と同じ名前である必要があります。例えば、DLLが "MyPlugin.dll" という名前である場合、プラグイン記述ファイルは "MyPlugin.xml" という名前でなければなりません。
XML ファイルのコンテンツ
XML 記述ファイルには、以下のような Wwise プラグインのいくつかのアスペクトに関する情報が含まれています：
- プラグイン名
- Company IDとプラグインID。詳しくは Wwise プラグインID を参照。
- 各プラットフォームがサポートする機能
-
以下を含むプロパティの定義:
- プロパティ名（コードや永続化ファイルでプロパティを識別するための文字列）
- プロパティのタイプ
- RTPCサポート
- デフォルト値
- サウンドエンジンプロパティID（このプロパティをサウンドエンジンプラグインのコードにバインドする）
- 範囲制限や、列挙制限
- ほかのプロパティへの依存
- ユーザーインターフェース説明エレメント
-
以下を含むInner Object Typesの定義:
- Inner Object Type名（inner object typeを識別するための文字列）
- Inner Objectプロパティ
例：XML定義ファイル
以下は、単純なプラグイン XML 定義ファイルの例です。
XML ファイルの様々な部分を詳しく見てみましょう。
XML 定義ファイルヘッダ
XML ファイルのヘッダ部分を詳しく見てみましょう。
すべての XML ファイルの最初の行では、XMLバージョンとエンコーディングが定義されます。ここでは、XMLバージョンは1.0で、エンコーディングは UTF-8 です。Wwise プラグイン記述ファイルの最初の行も、これと全く同様である必要があります。2行目は XML コメントになりますが、ここでは著作権表示です。必要に応じて、XML ファイルの色々な場所にコメントを導入することができます。
PluginModule 要素
このドキュメント内に記載されているメイン XML 要素は、 PluginModule という名前で、ファイルで定義されている様々なプラグインのための全情報を囲んでいます。
EffectPlugin タグと SourcePlugin 要素
EffectPlugin 要素は、シングルエフェクトプラグイン定義のためのメインタグで、SourcePlugin はソースプラグインの要素名です。
これらの要素には、3つの必須属性が含まれています：
-
Name（必須）：この文字列は、Wwise に表示されるプラグイン名を指定します。 -
CompanyID（必須）：この文字列は、以下の範囲を尊重する正の整数を表している必要があります：- 64～255：社内で開発・使用されるプラグインに対して自由に使用することができます。 外部配布用のプラグイン向けではありません。
- 256～4095：商用プラグイン用です。 Audiokinetic によってサードパーティーデベロッパに割り当てられます。この範囲内の値の割り当てを受けている場合は、64～255 の範囲の値の代わりに使用してください。それ以外の場合は、これらの値を使用しないでください。
- 0～63：利用不可。Audiokinetic 用です。
-
PluginID(mandatory): This string must be a positive integer in the range 0-32767. 各 PluginID は、指定された CompanyID に対して一意である必要があります。 -
SupportsIsSendModeEffect（オプション）：（エフェクトプラグインのみ）この bool 型値は、初期化部分で AK::IAkEffectPluginContext::IsSendModeEffect() を照会することにより、プラグインがセンドモードをサポートしているかどうかを示します。IsSendModeEffect() が true を返した場合、プラグインはドライ信号を出力するべきではなく、ドライレベルのプロパティを無視する必要があります。 -
EngineDllName(オプション): このstring値は、ゲームのランタイムでどの動的ライブラリをロードするかを示します。デフォルトでは、XMLにあるものと同じです。DLL/so ファイルをプラグインに提供することは必須で、これにより、UnityやUnreal 4などの商用ゲームエンジンでサポートされるようになります。これは、XMLの横あるDLLと異なるもので、こちらにはすべての Property Pages UI が含まれ、ゲームには含みたくないものであることに注意してください。
例えば、社内使用目的のみでソースプラグイン2つおよびエフェクトプラグイン1つを開発している場合、64 から 255 の間の任意の CompanyID および 0 から 32767 の間の任意の PluginID を3つ選ぶことができます。数字が連続している必要はありません。
 |
注意: Audiokinetic 提供のサンプルプラグインをプラグインのベースにする場合（samplecode_plugins）、CompanyID と PluginIDs を適切なものに変更することを忘れないようにしてください。公式 CompanyID が割り当てられている場合は、これを使用してください、それ以外の場合は、64 から 255 の間の数字を使用してください。この CompanyID に対して、同じ PluginID が繰り返されていないことを確認してください。 |
同じ CompanyID に対して、2つ以上の PluginID が同一である場合、Wwise は起動時にエラーメッセージを表示します。これが発生した場合は、新規プラグイン用に ID を変更してください。
|
注意: 既存プラグインの CompanyID または PluginID を 決して変更しないでください。このプラグインを使用しているプロジェクトがプラグインの認識をしなくなります。CompanyID と PluginID は、ソースプラグインまたはエフェクトプラグインの各インスタンスと永続化され、ファイルがロードされた時に適切なプラグインのインスタンスを再作成するために使用されます。 |
CompanyID と PluginID 属性は、これらの関数に渡されたパラメータに対応してプラグインを識別します：
-
AkCreatePlugin()（エクスポート関数 参照） -
AK::SoundEngine::RegisterPlugin()
 |
注釈: DLL に複数のプラグインが実装されている場合、XML ファイルは複数の EffectPlugin と／または SourcePlugin エントリを含みます。 |
PluginInfo 要素
PluginInfo/PlatformSupport セクションは、プラグインにサポートされているプラットフォームを定義します。これは、1つ以上の Platform 要素を含むことが可能で、それぞれのタグは各プラットフォームのプラグインにサポートされる様々な機能を指定します。次のような機能を指定可能です：
-
CanBeInsertOnBussesは、エフェクトのコントロールまたはマスターバスへの適用が可能かどうかを決定します。通常、サラウンドオーディオ構成をサポートするエフェクトを必要とします。 -
CanBeInsertOnAuxBussesは、エフェクトのコントロールまたはマスター AUX バスへの適用が可能かどうかを決定します。通常、サラウンドオーディオ構成をサポートするエフェクトを必要とします。CanBeInsertOnBusses が既に設定されている場合、エフェクトが既に AUX バス上で使用可能な状態です。 -
CanBeInsertOnAudioObjectsは、エフェクトが SFX へのインサートとして適用可能かどうかを決定します（モノラルおよびステレオ処理の両方をサポートしている必要があります）。 -
CanBeRenderedは、エフェクトがオフラインレンダリングに使用可能かどうかを決定します。
お使いのプラグインは、Wwise 内で指定されたプラットフォーム上でのみ利用可能になります。
サポートするすべてのプラットフォームを個別に挙げる代わりに、プラットフォームとして"Any"を追加することもできます。ただしその場合は、このプラグインはWwiseの全プラットフォームに対応しているものとして公表され、対応するランタイムライブラリをプラグインが提供していくても、ユーザーはプラットフォームにポートするまで、気付かないことになります。
Properties 要素
全てのエフェクトやソースプラグインで、プロパティやレファレンスを定義できます。プロパティやレファレンスに関する詳細は、 プラグインプロパティやカスタムプロパティのXML記述 をご覧ください。
インナーオブジェクト
InnerTypes セクションは、インスタンス化しプラグイン内で使用することができる Inner Object Type を定義します。InnerTypes セクション内で、複数の InnerType を定義することができます。各 InnerType は、一意の名前とプラグイン ID を持っている必要があります。InnerType セクションには、Properties セクションが含まれていて、ここでプラグインプロパティを定義するのと全く同じ方法でプロパティを定義することができます。
Inner Types は、プラグイン内のオブジェクトの複数インスタンスを持つ必要がある場合に実用的です。例えば、可変数の EQ バンドを持っている際に、EQ プラグインに対してInner Type Band を定義することができます。それぞれのバンドは、各バンドごとに異なる値で、同一プロパティ定義を持ちます。
|
注釈: Inner Type のプロパティは、RTPC をサポートしません。従って、SupportRTPCType 属性と AudioEnginePropertyID エレメントを使用することはできません。 |
|
注釈: InnerTypes は、ソースおよびエフェクトプラグイン内でのみサポートされます。 |
プラグインコードで Inner Type インスタンス（インナーオブジェクト）を操作するには、プラグインの初期化時に AK::Wwise::IAudioPlugin::SetPluginObjectStore() が呼び出される時に、フレームワークに提供される AK::Wwise::IPluginObjectStore ポインタを使用する必要があります。AK::Wwise::IPluginObjectStore インターフェースは、インナーオブジェクトを作成および削除するための機能を提供します。作成されたオブジェクトは、挿抜関数を使用して名前付きリストに格納される必要があります。
例えば、Band タイプのインナーオブジェクトを作成して、BandList に格納することが可能です：
|
注釈: インナーオブジェクトは、単一リスト内にのみ格納可能です。 |
以下のトピックを参照してください：
オブジェクトストアにインナーオブジェクトを追加すると、関連付けられた Undo（アンドゥ）メカニズムが Wwise 内に自動的に作成されます。ご自分で、アンドゥシステムを実装する必要はありません。しかし、アンドゥイベントを正常にサポートするために、フレームワークからの通知受信時にのみユーザーインターフェースを更新する必要があります。例えば、 IPluginObjectStore 上に InsertObject を呼び出した後には、UI を直ちに更新しないでください。プラグインに通知 AK::Wwise::IAudioPlugin::NotifyInnerObjectAddedRemoved が呼び出されるのを待ってください。この通知は、リストへのオブジェクトの追加または削除を知らせるものです。この通知は、ユーザーまたは Undo メカニズムからのアクションにより発行されます。
また、インナーオブジェクト内でプロパティ値が変化した時に呼び出される AK::Wwise::IAudioPlugin::NotifyInnerObjectPropertyChanged もご参照ください。
プロジェクトワークユニットの永続性は、Wwise により自動的に処理されます。ただし、SoundBank 内および Sound Engine データのインナーオブジェクトのシリアル化を実装する必要があります。AK::Wwise::IAudioPlugin::GetPluginData および AK::Wwise::IAudioPlugin::GetBankParameters 内のインナーオブジェクトをシリアル化してください。
トラブルシューティング
問題が発生した場合は、Wwise ソースプラグインおよびエフェクトプラグインのトラブルシューティングガイド を参照してください。