Wwise SDK 2023.1.8

Wwiseオープンアーキテクチャは、以下のような様々な種類のプラグインに対応しています:

オーディオプラグイン、例えば:
- サウンドを生成する、ソースプラグイン
- サウンドを変換させる、エフェクトプラグイン
- 何らかの媒体にサウンドを出力する、シンク（sink）プラグイン
Wwise内のソースコントロールソフトウェアの使用を可能にする、ソースコントロールプラグイン

オーディオプラグインのモデルは、XMLファイル形式で記述されます。このため、プラグインのプロパティのデフォルト値など、設定内容を簡単に変えることができ、コードを再コンパイルする必要はありません。プラグインが提供するカスタムGUIがない場合は、このモデルで記述したプロパティはWwiseのプロパティ表という形式で、デフォルトのグラフィカルインターフェースを提供するためにも使われます。

XMLファイルの概要

XML 記述ファイルには、以下のような Wwise プラグインのいくつかのアスペクトに関する情報が含まれています：

プラグイン名
Company IDとプラグインID。詳しくは Wwise プラグインID を参照。
各プラットフォームがサポートする機能
以下を含むプロパティの定義:
- プロパティ名（コードや永続化ファイルでプロパティを識別するための文字列）
- プロパティのタイプ
- RTPCサポート
- デフォルト値
- サウンドエンジンプロパティID（このプロパティをサウンドエンジンプラグインのコードにバインドする）
- 範囲制限や、列挙制限
- ほかのプロパティへの依存
- ユーザーインターフェース説明エレメント
以下を含むInner Object Typesの定義:
- Inner Object Type名（inner object typeを識別するための文字列）
- Inner Objectプロパティ

wp.py development tool を使うと、デフォルトのXMLファイルが提供され、あなたが作成時に提供した情報が入力されています。詳細は Creating Audio Plug-ins を参照してください。

注釈: Wwiseのプラグイン動的ライブラリに、複数のプラグインを含めることができ（ Authoring Plug-in Library Format 参照）、各プラグインを、それぞれ1つの関連XMLファイルで記述する必要があります。

XMLファイルのファイル名

各Wwiseプラグイン動的ライブラリのXML記述ファイルの名前は、XMLファイル拡張子やlibプレフィックスを除き、動的ライブラリと同じとします。

例えば、動的ライブラリ名が "MyPlugin.dll" または "libMyPlugin.dylib" であれば、プラグイン記述ファイルの名前は、必ず "MyPlugin.xml" とします。

例：XML定義ファイル

以下は、単純なプラグイン XML 定義ファイルの例です。

XML記述ファイルの詳細

XML ファイルの様々な部分を詳しく見てみましょう。

XML 定義ファイルヘッダ

XML ファイルのヘッダ部分を詳しく見てみましょう。

すべての XML ファイルの最初の行では、XMLバージョンとエンコーディングが定義されます。ここでは、XMLバージョンは1.0で、エンコーディングは UTF-8 です。Wwise プラグイン記述ファイルの最初の行も、これと全く同様である必要があります。2行目は XML コメントになりますが、ここでは著作権表示です。必要に応じて、XML ファイルの色々な場所にコメントを導入することができます。

PluginModule 要素

このドキュメント内に記載されているメイン XML 要素は、 PluginModule という名前で、ファイルで定義されている様々なプラグインのための全情報を囲んでいます。

プラグインタイプのエレメント

In the category of Audio plug-ins, there are four possible plug-in type elements:

SourcePlugin
EffectPlugin
SinkPlugin
MetadataPlugin

The EffectPlugin element is the main element for the definition of a single effect plug-in, while SourcePlugin, SinkPlugin and MetadataPlugin are the element names for source plug-ins, sink plug-ins and metadata plug-ins, respectively.

注釈: 動的ライブラリで複数のプラグインを実装している場合は、XMLファイルに複数のプラグインエレメントが含まれます。動的ライブラリは、1つのタイプのオーディオプラグインに限定されていません。

エレメントには、3つの必須の属性が含まれます:

Name (必須): Wwiseで表示されるプラグインの表示名を、この文字列で指定します。
CompanyID (必須): この文字列は、必ず範囲0～4095の正の整数とします（ wwiseplugin_xml_id_specification 参照）
PluginID (必須): この文字列は、必ず範囲0～32767の正の整数とします。各 PluginID は、指定された CompanyID に対して一意である必要があります。

2つの任意の属性を、指定することができます:

SupportsIsSendModeEffect (任意): （Effectプラグインに限定）このブール値は、初期化の部分で AK::IAkEffectPluginContext::IsSendModeEffect() のクエリを行うことで、プラグインがセンドモードに対応しているかどうかを示します。 IsSendModeEffect() がtrueを返すと、プラグインは、ドライシグナルを出力せずに、ドライレベルのプロパティを無視します。
EngineDllName (任意): この文字列値は、ゲームのランタイム時にロードするSound Engine動的ライブラリの名前をオーバーライドします（デフォルトで、XMLと同じ名前となります）。 EngineDllName を指定する場合は、あなたのSound Engineの静的ライブラリと動的ライブラリが、同じ名前を共有するようにしてください。DLL/so ファイルをプラグインに提供することは必須で、これにより、UnityやUnreal 4などの商用ゲームエンジンでサポートされるようになります。Authoringプラグインの動的ライブラリの名前は、あなたのXMLファイル名に対応する必要があるので、影響を受けません。

Company IDとPlug-in ID

Wwiseは数値IDを使い、プラグインモデルの定義と、プラグインの実装を関連付けます。これらのIDは、各プラグインのXML記述と、プラグインライブラリのプラグイン記述子で提供されます。

CompanyID は、あなたの組織に対するIDです。3つの対象範囲に分かれます:

0-63: Audiokinetic専用 、使えません。
64-255: 自由に使用できる範囲 、社内用。この範囲のCompany IDは社外に配信してはいけません。
256-4095: 制限のある範囲 、商用プラグイン用。 Audiokineticによって公式サードパーティデベロッパに割り当てられます。この範囲内の値の割り当てを受けている場合は、64～255 の範囲の値の代わりに使用してください。それ以外の場合は、これらの値を使用しないでください。

PluginID は0-32767の範囲の固有の数値IDで、1つの組織内の1つのプラグインに割り当てられます。

例えば、社内だけで使うプラグインを開発する場合は、64から255の範囲から CompanyID を1つと、0から32767の範囲からPluginIDを3つ、自由に選べます。連続した数字である必要はありません。

CompanyIDとPluginIDを、Sound Engineプラグインのdeclarationマクロである AK_IMPLEMENT_PLUGIN_FACTORY に渡す必要があります。

注意: 重要な注意点:

すでに存在するプラグインのCompanyIDやPluginIDは、 絶対に 変更しないでください。このプラグインを使用しているプロジェクトがプラグインの認識をしなくなります。CompanyIDとPluginIDは各プラグインインスタンスで永続化され、ファイルをロードしたときに正しいプラグインのインスタンスを再現するために、使われます。
もし同じCompanyIDで、同じPluginIDのものが2つ以上あれば、起動時にWwiseがエラーメッセージを表示します。これが発生した場合は、新規プラグイン用に ID を変更してください。
Audiokineticが提供するサンプルプラグイン（サンプルプラグイン）をベースにしたプラグインであれば、CompanyIDやPluginIDを適切な値に変更することを、忘れないでください。公式 CompanyID が割り当てられている場合は、これを使用してください、それ以外の場合は、64 から 255 の間の数字を使用してください。この CompanyID に対して、同じ PluginID が繰り返されていないことを確認してください。

IDの詳細は Wwise プラグインID を参照してください。

PluginInfoエレメント

PluginInfo/PlatformSupport セクションは、プラグインにサポートされているプラットフォームを定義します。これは、1つ以上の Platform 要素を含むことが可能で、それぞれのタグは各プラットフォームのプラグインにサポートされる様々な機能を指定します。次のような機能を指定可能です：

CanBeInsertOnBusses は、エフェクトのコントロールまたはマスターバスへの適用が可能かどうかを決定します。通常、サラウンドオーディオ構成をサポートするエフェクトを必要とします。
CanBeInsertOnAuxBusses は、エフェクトを、コントロールバスやマスターAUXバスに適用できるかどうかを決定します。通常、サラウンドオーディオ構成をサポートするエフェクトを必要とします。なお、すでに CanBeInsertOnBusses が設定されていれば、このエフェクトはすでにAuxバスで利用可能になっています。
CanBeInsertOnAudioObjects は、エフェクトが SFX へのインサートとして適用可能かどうかを決定します（モノラルおよびステレオ処理の両方をサポートしている必要があります）。
CanBeRendered は、エフェクトがオフラインレンダリングに使用可能かどうかを決定します。
CanSendMonitorData は、エフェクトがモニタリングデータを送信できるかどうかを決定します。詳細は AK::Wwise::Plugin::Notifications::Monitor::NotifyMonitorData を参照してください。
CanBeSourceOnSound は、ソースプラグインがサウンドのソースとなれるのかどうかを決定します。
CanBeInsertEndOfPipeline は、エフェクトを追加できるのがオーディオパイプラインの最後、つまり最上位Audio Busの最終エフェクトの設定位置（Audiokinetic専用）に対応する場所だけなのかを、決定します。

お使いのプラグインは、Wwise 内で指定されたプラットフォーム上でのみ利用可能になります。

サポートするすべてのプラットフォームを個別に挙げる代わりに、プラットフォームとして"Any"を追加することもできます。ただしその場合は、このプラグインはWwiseの全プラットフォームに対応しているものとして公表され、対応するランタイムライブラリをプラグインが提供していくても、ユーザーはプラットフォームにポートするまで、気付かないことになります。

Metadata PluginInfo Element

For a metadata plug-in, it is important to set the MenuPath="Metadata" attribute to the PluginInfo node as such:

Propertiesエレメント

オーディオプラグインごとに、プロパティやリファレンスを定義できます。プロパティやレファレンスに関する詳細は、 Properties XML Description をご覧ください。

Innerオブジェクト

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インスタンス（Inner Object）に手を加えるには、あなたのプラグインクラスで AK::Wwise::Plugin::RequestObjectStore を派生させて、 AK::Wwise::Plugin::ObjectStore m_objectStore メンバーを使い、このサービスをリクエストする必要があります。 AK::Wwise::Plugin::ObjectStore インターフェースが、インナーオブジェクトの作成や削除の関数を提供します（ AK::Wwise::Plugin::ObjectStore::CreatePropertySet と、 AK::Wwise::Plugin::ObjectStore::DeletePropertySet ）。 Inner Objectのプロパティを変更するには、PropertySetインターフェースを使います（ Property Set を参照）。

オブジェクト作成時に、名前を付けたリストに保存する必要があり、インサーション関数（ AK::Wwise::Plugin::ObjectStore::InsertPropertySet ）と削除関数（ AK::Wwise::Plugin::ObjectStore::RemovePropertySet ）を使います。例えば、Band タイプのインナーオブジェクトを作成して、BandList に格納することが可能です：

注釈: インナーオブジェクトは、一度に1つのリストにしか格納できません。

プロジェクトワークユニットの永続性は、Wwise により自動的に処理されます。一方、SoundBank内や、Sound Engineデータ用の、インナーオブジェクトのシリアル化は、あなたが実装する必要があります。 AK::Wwise::Plugin::CustomData::GetPluginData と AK::Wwise::Plugin::AudioPlugin::GetBankParameters の中のインナーオブジェクトをシリアル化する必要があります。

オブジェクトストアにインナーオブジェクトを追加すると、関連付けられた Undo（アンドゥ）メカニズムが Wwise 内に自動的に作成されます。ご自分で、アンドゥシステムを実装する必要はありません。ただし、Undoイベントを正しくサポートするために、ユーザーインターフェースの更新は、フレームワークからノティフィケーションを受け取ったときだけにしてください。

Inner ObjectのNotification

インターフェース AK::Wwise::Plugin::NotificationsObjectStore がインナーオブジェクト関連のノティフィケーションイベントに反応できるように、オーバーライドできるハンドラを提供します。これらは、ユーザーの操作や、Undoイベントや、WAAPIコールなどにもトリガーされるモデルの変更で、主にカスタムGUIエレメントを更新するためのものです。

例えば AK::Wwise::Plugin::ObjectStore::InsertPropertySet をコールしたあとは、すぐにUIを更新してはいけません。プラグインに通知 AK::Wwise::Plugin::NotificationsObjectStore::NotifyInnerObjectAddedRemoved が呼び出されるのを待ってください。この通知は、リストへのオブジェクトの追加または削除を知らせるものです。

同様に、インナーオブジェクトのプロパティ値が変更されたときにコールされる AK::Wwise::Plugin::NotificationsObjectStore::NotifyInnerObjectPropertyChanged に、反応することができます。