Wwiseプラグイン XML 記述ファイル

Wwise のオープンアーキテクチャは、次の3種類のプラグインをサポートしています：サウンドを生成するソースプラグイン、サウンドを向上させるエフェクトプラグイン、Wwise 内でのソース管理ソフトウェア使用を可能にするソース管理プラグイン。

最初の2種のプラグインは、デフォルトプロパティ値を含めた一部のプラグイン設定を、コードの再コンパイルなしですばやく変更することができる XML プラグイン記述ファイルを使用します。Wwise プラグイン DLL は、複数のプラグインを含めることが可能ですが、各プラグインが関連 XML ファイルで記述されている必要があります。

各 Wwise プラグインDLL の XML 記述ファイルは、XML ファイルの拡張子以外は DLL と同じ名前である必要があります。例えば、DLLが "MyPlugin.dll" という名前である場合、プラグイン記述ファイルは "MyPlugin.xml" という名前でなければなりません。

XML ファイルのコンテンツ

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

プラグイン名
企業IDとプラグインID
各プラットフォームでサポートされる機能
以下のようなプロパティ定義：
- プロパティ名（コード内および永続化ファイル内でプロパティ識別に使用される文字列）
- プロパティタイプ
- RTPC サポート
- デフォルト値
- サウンドエンジンプロパティID（プロパティをサウンドエンジンプラグイン内のコードにバインド）
- 範囲の制限または列挙の制限
- 他プロパティへの依存
- ユーザーインターフェース記述エレメント
以下のようなインナーオブジェクトタイプ（Inner Object Type）の定義：
- インナーオブジェクトタイプ名（インナーオブジェクトタイプ識別に使用される文字列）
- インナーオブジェクトのプロパティ

XML 定義ファイルヘッダ

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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright (C) 2006 Audiokinetic Inc. -->

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

PluginModule 要素

<PluginModule>
    ...
</PluginModule>

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

WwiseObject 要素

    <EffectPlugin Name="Wwise Parametric EQ" CompanyID="0" PluginID="105" SupportsIsSendModeEffect="false" EngineDllName="EQ">
        ...
    </EffectPlugin>

EffectPlugin 要素は、シングルエフェクトプラグイン定義のためのメインタグで、SourcePlugin はソースプラグインの要素名です。

これらの要素には、3つの必須属性が含まれています：

Name （必須）：この文字列は、Wwise に表示されるプラグイン名を指定します。
CompanyID （必須）：この文字列は、以下の範囲を尊重する正の整数を表している必要があります：
- 64～255：社内で開発・使用されるプラグインに対して自由に使用することができます。外部配布用のプラグイン向けではありません。
- 256～4095：商用プラグイン用です。 Audiokinetic によってサードパーティーデベロッパに割り当てられます。この範囲内の値の割り当てを受けている場合は、64～255 の範囲の値の代わりに使用してください。それ以外の場合は、これらの値を使用しないでください。
- 0～63：利用不可。Audiokinetic 用です。
PluginID （必須）：この文字列は 0～65535 の範囲の正の整数でなければなりません。各 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 から 65535 の間の任意の PluginID を3つ選ぶことができます。数字が連続している必要はありません。

Caution: Audiokinetic 提供のサンプルプラグインをプラグインのベースにする場合（サンプルプラグイン）、CompanyID と PluginIDs を適切なものに変更することを忘れないようにしてください。公式 CompanyID が割り当てられている場合は、これを使用してください、それ以外の場合は、64 から 255 の間の数字を使用してください。この CompanyID に対して、同じ PluginID が繰り返されていないことを確認してください。

同じ CompanyID に対して、2つ以上の PluginID が同一である場合、Wwise は起動時にエラーメッセージを表示します。これが発生した場合は、新規プラグイン用に ID を変更してください。

Caution: 既存プラグインの CompanyID または PluginID を 決して変更しないでください。このプラグインを使用しているプロジェクトがプラグインの認識をしなくなります。CompanyID と PluginID は、ソースプラグインまたはエフェクトプラグインの各インスタンスと永続化され、ファイルがロードされた時に適切なプラグインのインスタンスを再作成するために使用されます。

CompanyID と PluginID 属性は、これらの関数に渡されたパラメータに対応してプラグインを識別します：

AkCreatePlugin() （エクスポート関数参照）
AK::SoundEngine::RegisterPlugin()

Note: DLL に複数のプラグインが実装されている場合、XML ファイルは複数の EffectPlugin と／または SourcePlugin エントリを含みます。

PluginInfo 要素

    <PlatformSupport>
           <Platform Name="Windows">
              <CanBeInsertOnBusses>true</CanBeInsertOnBusses>
              <CanBeInsertOnAudioObjects>true</CanBeInsertOnAudioObjects>
              <CanBeRendered>true</CanBeRendered>
              <CanBeInsertForFeedback>false</CanBeInsertForFeedback>
           </Platform>
           <Platform Name="Mac">
              <CanBeInsertOnBusses>true</CanBeInsertOnBusses>
              <CanBeInsertOnAudioObjects>true</CanBeInsertOnAudioObjects>
              <CanBeRendered>true</CanBeRendered>
              <CanBeInsertForFeedback>false</CanBeInsertForFeedback>
           </Platform>
           <Platform Name="iOS">
              <CanBeInsertOnBusses>true</CanBeInsertOnBusses>
              <CanBeInsertOnAudioObjects>true</CanBeInsertOnAudioObjects>
              <CanBeRendered>true</CanBeRendered>
              <CanBeInsertForFeedback>false</CanBeInsertForFeedback>
           </Platform>
           <Platform Name="XboxOne">
              <CanBeInsertOnBusses>true</CanBeInsertOnBusses>
              <CanBeInsertOnAudioObjects>true</CanBeInsertOnAudioObjects>
              <CanBeRendered>true</CanBeRendered>
              <CanBeInsertForFeedback>false</CanBeInsertForFeedback>
           </Platform>
           <Platform Name="PS4">
              <CanBeInsertOnBusses>true</CanBeInsertOnBusses>
              <CanBeInsertOnAudioObjects>true</CanBeInsertOnAudioObjects>
              <CanBeRendered>true</CanBeRendered>
              <CanBeInsertForFeedback>false</CanBeInsertForFeedback>
           </Platform>
      </PlatformSupport>

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

CanBeInsertOnBusses は、エフェクトのコントロールまたはマスターバスへの適用が可能かどうかを決定します。通常、サラウンドオーディオ構成をサポートするエフェクトを必要とします。
CanBeInsertOnAuxBusses は、エフェクトのコントロールまたはマスター AUX バスへの適用が可能かどうかを決定します。通常、サラウンドオーディオ構成をサポートするエフェクトを必要とします。CanBeInsertOnBusses が既に設定されている場合、エフェクトが既に AUX バス上で使用可能な状態です。
CanBeInsertOnAudioObjects は、エフェクトが SFX へのインサートとして適用可能かどうかを決定します（モノラルおよびステレオ処理の両方をサポートしている必要があります）。
CanBeRendered は、エフェクトがオフラインレンダリングに使用可能かどうかを決定します。
CanBeInsertForFeedback は、エフェクトがモーション SFX に適用可能かどうかを決定します。

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

Properties 要素

全てのエフェクトやソースプラグインで、プロパティやレファレンスを定義できます。プロパティやレファレンスに関する詳細は、プラグインプロパティやカスタムプロパティのXML記述をご覧ください。

インナーオブジェクト

InnerTypes セクションは、インスタンス化しプラグイン内で使用することができる Inner Object Type を定義します。InnerTypes セクション内で、複数の InnerType を定義することができます。各 InnerType は、一意の名前とプラグイン ID を持っている必要があります。InnerType セクションには、Properties セクションが含まれていて、ここでプラグインプロパティを定義するのと全く同じ方法でプロパティを定義することができます。

Inner Types は、プラグイン内のオブジェクトの複数インスタンスを持つ必要がある場合に実用的です。例えば、可変数の EQ バンドを持っている際に、EQ プラグインに対してInner Type Band を定義することができます。それぞれのバンドは、各バンドごとに異なる値で、同一プロパティ定義を持ちます。

<PluginModule>
    <EffectPlugin ...>
        <PluginInfo ...>
            ...
        </PluginInfo>
        <Properties>
            ...
        </Properties>
        <InnerTypes>
            <InnerType Name="Band" CompanyID="X" PluginID="Y">
                <Properties>
                    ...
                </Properties>
            </InnerType>
        </InnerTypes>
    </EffectPlugin>

Note: Inner Type のプロパティは、RTPC をサポートしません。従って、SupportRTPCType 属性と AudioEnginePropertyID エレメントを使用することはできません。

Note: InnerTypes は、ソースおよびエフェクトプラグイン内でのみサポートされます。

プラグインコードで Inner Type インスタンス（インナーオブジェクト）を操作するには、プラグインの初期化時に AK::Wwise::IAudioPlugin::SetPluginObjectStore() が呼び出される時に、フレームワークに提供される　 AK::Wwise::IPluginObjectStore ポインタを使用する必要があります。AK::Wwise::IPluginObjectStore インターフェースは、インナーオブジェクトを作成および削除するための機能を提供します。作成されたオブジェクトは、挿抜関数を使用して名前付きリストに格納される必要があります。

例えば、Band タイプのインナーオブジェクトを作成して、BandList に格納することが可能です：

    // Create a new band
    AK::Wwise::IPluginPropertySet* pBand = GetObjectStore()->CreateObject( L"Band" );

    // Insert the new band in the "BandList" (at the end)
    GetObjectStore()->InsertObject( L"BandList", (unsigned int)-1, pBand );

Note: インナーオブジェクトは、単一リスト内にのみ格納可能です。

以下のトピックを参照してください：

オブジェクトストアにインナーオブジェクトを追加すると、関連付けられた 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 ソースプラグインおよびエフェクトプラグインのトラブルシューティングガイドを参照してください。

このページはお役に立ちましたか？

サポートは必要ですか？

ご質問や問題、ご不明点はございますか？お気軽にお問い合わせください。

サポートページをご確認ください

あなたのプロジェクトについて教えてください。ご不明な点はありませんか。

プロジェクトを登録していただくことで、ご利用開始のサポートをいたします。

Wwiseからはじめよう

Wwise SDK 2017.1.9