Wwise SDK 2024.1.1
|
Wwiseオープンアーキテクチャは、以下のような様々な種類のプラグインに対応しています:
オーディオプラグインのモデルは、XMLファイル形式で記述されます。このため、プラグインのプロパティのデフォルト値など、設定内容を簡単に変えることができ、コードを再コンパイルする必要はありません。プラグインが提供するカスタムGUIがない場合は、このモデルで記述したプロパティはWwiseのプロパティ表という形式で、デフォルトのグラフィカルインターフェースを提供するためにも使われます。
XML 記述ファイルには、以下のような Wwise プラグインのいくつかのアスペクトに関する情報が含まれています:
wp.py development tool を使うと、デフォルトのXMLファイルが提供され、あなたが作成時に提供した情報が入力されています。詳細は Creating Audio Plug-ins を参照してください。
注釈: Wwiseのプラグイン動的ライブラリに、複数のプラグインを含めることができ( Authoring Plug-in Library Format 参照)、各プラグインを、それぞれ1つの関連XMLファイルで記述する必要があります。 |
各Wwiseプラグイン動的ライブラリのXML記述ファイルの名前は、XMLファイル拡張子やlibプレフィックスを除き、動的ライブラリと同じとします。
例えば、動的ライブラリ名が "MyPlugin.dll" または "libMyPlugin.dylib" であれば、プラグイン記述ファイルの名前は、必ず "MyPlugin.xml" とします。
以下は、単純なプラグイン XML 定義ファイルの例です。
XML ファイルの様々な部分を詳しく見てみましょう。
XML ファイルのヘッダ部分を詳しく見てみましょう。
すべての XML ファイルの最初の行では、XMLバージョンとエンコーディングが定義されます。ここでは、XMLバージョンは1.0で、エンコーディングは UTF-8
です。Wwise プラグイン記述ファイルの最初の行も、これと全く同様である必要があります。2行目は XML コメントになりますが、ここでは著作権表示です。必要に応じて、XML ファイルの色々な場所にコメントを導入することができます。
このドキュメント内に記載されているメイン XML 要素は、 PluginModule
という名前で、ファイルで定義されている様々なプラグインのための全情報を囲んでいます。
In the category of Audio plug-ins, there are four possible plug-in type elements:
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で表示されるプラグインの表示名を、この文字列で指定します。 wwiseplugin_xml_id_specification
参照) 2つの任意の属性を、指定することができます:
SupportsIsSendModeEffect
(任意): (Effectプラグインに限定)このブール値は、初期化の部分で AK::IAkEffectPluginContext::IsSendModeEffect()
のクエリを行うことで、プラグインがセンドモードに対応しているかどうかを示します。 IsSendModeEffect()
がtrueを返すと、プラグインは、ドライシグナルを出力せずに、ドライレベルのプロパティを無視します。 EngineDllName
(任意): この文字列値は、ゲームのランタイム時にロードするSound Engine動的ライブラリの名前をオーバーライドします(デフォルトで、XMLと同じ名前となります)。 EngineDllName
を指定する場合は、あなたのSound Engineの静的ライブラリと動的ライブラリが、同じ名前を共有するようにしてください。DLL/so ファイルをプラグインに提供することは必須で、これにより、UnityやUnreal 4などの商用ゲームエンジンでサポートされるようになります。Authoringプラグインの動的ライブラリの名前は、あなたのXMLファイル名に対応する必要があるので、影響を受けません。 Wwiseは数値IDを使い、プラグインモデルの定義と、プラグインの実装を関連付けます。 これらのIDは、各プラグインのXML記述と、プラグインライブラリのプラグイン記述子で提供されます。
CompanyID
は、あなたの組織に対するIDです。3つの対象範囲に分かれます:
PluginID
は0-32767の範囲の固有の数値IDで、1つの組織内の1つのプラグインに割り当てられます。
例えば、社内だけで使うプラグインを開発する場合は、64から255の範囲から CompanyID
を1つと、0から32767の範囲からPluginIDを3つ、自由に選べます。連続した数字である必要はありません。
CompanyIDとPluginIDを、Sound Engineプラグインのdeclarationマクロである AK_IMPLEMENT_PLUGIN_FACTORY
に渡す必要があります。
注意: 重要な注意点:
|
IDの詳細は Wwise プラグインID を参照してください。
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の全プラットフォームに対応しているものとして公表され、対応するランタイムライブラリをプラグインが提供していくても、ユーザーはプラットフォームにポートするまで、気付かないことになります。
For a metadata plug-in, it is important to set the MenuPath="Metadata" attribute to the PluginInfo node as such:
オーディオプラグインごとに、プロパティやリファレンスを定義できます。プロパティやレファレンスに関する詳細は、 Properties XML Description をご覧ください。
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イベントを正しくサポートするために、ユーザーインターフェースの更新は、フレームワークからノティフィケーションを受け取ったときだけにしてください。
インターフェース AK::Wwise::Plugin::NotificationsObjectStore
がインナーオブジェクト関連のノティフィケーションイベントに反応できるように、オーバーライドできるハンドラを提供します。これらは、ユーザーの操作や、Undoイベントや、WAAPIコールなどにもトリガーされるモデルの変更で、主にカスタムGUIエレメントを更新するためのものです。
例えば AK::Wwise::Plugin::ObjectStore::InsertPropertySet
をコールしたあとは、すぐにUIを更新してはいけません。 プラグインに通知 AK::Wwise::Plugin::NotificationsObjectStore::NotifyInnerObjectAddedRemoved
が呼び出されるのを待ってください。 この通知は、リストへのオブジェクトの追加または削除を知らせるものです。
同様に、インナーオブジェクトのプロパティ値が変更されたときにコールされる AK::Wwise::Plugin::NotificationsObjectStore::NotifyInnerObjectPropertyChanged
に、反応することができます。
問題が発生した場合は、Wwise ソースプラグインおよびエフェクトプラグインのトラブルシューティングガイド を参照してください。