Wwise SDK 2023.1.3

このページは、プラグインのモデルをアクセスしたり修正したりする方法を説明します。モデルは、以下の2つの要素で成り立っています:

Property Set と呼ばれる標準モデルは、プラグインのXML定義で完全に説明されていて、 AK::Wwise::Plugin::RequestPropertySet が提供するコンポーネントでアクセスできます。特定のデータタイプに限定されていますが、保存、ロード、元に戻す、やり直しの自動処理を提供し、GUIコントロールのモデルとしてバインドも提供します。
Custom Data と呼ばれるカスタムモデルは、より複雑なデータを表すためにプラグインに任意で追加できますが、制限事項として、Property Setの自動処理に関しては意図的に実装する必要があります。この制限事項は、手動で更新する必要があるGUIコントロールも対象です。

Property Set

Property Setインスタンスは、メンバー変数の m_propertySet として、 AK::Wwise::Plugin::RequestPropertySet リクエストインターフェースの派生でプラグインに提供されます。 AK::Wwise::Plugin::AudioPlugin::GetBankParameters などの関数で、XMLで定義したプロパティの値をアクセスし、バンクの値を書くことができます（詳細はサウンドバンクの生成を参照）。最も一般的なタイプのためのアクセサは明示的に提供されますが、XMLで指定のタイプと一致しないアクセサタイプの使用は、未定義の動作です。

使いやすいように、プラグインクラスが AK::Wwise::Plugin::AudioPlugin の派生の場合は、 AK::Wwise::Plugin::RequestPropertySet が自動的にリクエストされます。それ以外の場合、例えばフロントエンドを作成するときなどは、それをリクエストする必要があります。

class MySourcePlugin
:   public AK::Wwise::Plugin::AudioPlugin
{
public:
    bool GetBankParameters(
         const GUID& in_guidPlatform,
         AK::Wwise::Plugin::DataWriter& in_dataWriter) const override
    {
        bool result = true;
        // Access the property set
        int32_t value = m_propertySet.GetInt32(in_guidPlatform, "PropertyKey");
        // Write the value into the sound bank
        result &= in_dataWriter.WriteInt32(value);
        return result;
    }
};

注釈: m_propertySet 変数のライフタイムは、プラグインインスタンスのライフタイムと同じです。インスタンスを、複数のプラグインインスタンスをまたいで保存しないでください。また、このサービスを、バックエンドとフロントエンドクラスの両方でリクエストできます。

プロパティ値のノティフィケーション

Wwise ユーザーは、直接ダイアログ内のコントロールを介して、または、undo/redo（元に戻す／やり直し）コマンドを使用して、プロパティ値を変更することができます。ユーザーがプロパティ値を変更したときに、AK::Wwise::Plugin::Notifications::PropertySet::NotifyPropertyChanged() が、あなたのプラグインでコールされます。こうすれば、この変更に基づいて、例えばカスタムデータやプロパティレンジの依存性など、ほかのプロパティ値を適合させることができます。また、このときにあなたのダイアログが表示されていれば、コントロールの有効化・無効化など、ダイアログ内で実行するアクションを指定できます。

注釈: XMLは、ルールに基づいた依存性のディスクリプションを許容しています。詳細は、Plug-in XML 依存関係を参照してください。

class MySourcePlugin
:   public AK::Wwise::Plugin::AudioPlugin
{
public:
    void NotifyPropertyChanged(
         const GUID& in_guidPlatform,
         const char* in_szPropertyName) override
    {
        if (strcmp(in_szPropertyName, "PropertyKey") == 0)
        {
            // Access the property set
            int32_t value = 0;
            if (m_propertySet.GetValueInt32(in_guidPlatform, in_szPropertyName, value))
            {
                // Do something with the value
            }
        }
        else if (strcmp(in_szPropertyName, "OtherPropertyKey") == 0)
        {
            // ...
        }
    }
};

Custom Data

あなたのプラグインが、カーブやグラフなど複雑なデータを使う場合は、そのようなタイプのデータを表現するために、プロパティセットでは不十分かもしれません。複雑なタイプのデータを取り扱うために、カスタムデータのメカニズムがあります。カスタムデータの要件は、以下の通りです:

XMLデータとして、ロードと保存のメカニズムを実装、例えばバイナリファイルへのパス、base64コンテンツ、など。
このデータが変更されたときに、サウンドエンジンにリロードできるように、Wwiseに通知します
サウンドエンジンプラグインのパラメータとして、サウンドバンクに書き込むシリアル化関数を実装します。

これらを達成するには、以下の指定インターフェースを実装します:

AK::Wwise::Plugin::CustomData : あなたのカスタムデータをWwiseプロジェクトにロードして保存するために必要な、インターフェースを提供します
AK::Wwise::Plugin::RequestHost : Authoringに通知する関数を提供します (AK::Wwise::Plugin::Host::NotifyInternalDataChanged())

注釈: プラグインが、自身のカスタムデータを完全にコントロールするので、このようなタイプのデータは、プラグインのXMLで何も定義しないでください。

Custom Dataを提供する

プラグインデータを提供するには、 AK::Wwise::Plugin::CustomData::GetPluginData を実装します。カスタムパラメータのIDを定義する必要がありますが、それは、 AK::IAkPluginParam::SetParam をコールしたときに、このプラグインのサウンドエンジン部分にある、このデータを読むために使うIDに対応する必要があります。

カスタムデータの初期化と永続化

カスタムデータはプラグインインスタンスが所有しますが、永続性のために、プロジェクトにロードして保存しておく必要があります。プロジェクトをソースコントロールで管理するときにマージ処理をしやすいように、複雑なデータはできるだけ多く、可能な限りプレインXMLを使って表すことが強く推奨されます。より複雑なデータを保存するには、整理してbase64にするか、プロジェクトルートへの相対パスがXMLエレメントとして永続化されるようなファイルを保存します。

永続化を実施するための関数は AK::Wwise::Plugin::CustomData が提供します:

AK::Wwise::Plugin::CustomData::InitFromWorkunit() が、カスタムデータをunmarshallするために使う AK::Wwise::Plugin::XmlReader を受信します。
AK::Wwise::Plugin::CustomData::Save() が、カスタムデータをmarshallするために使う AK::Wwise::Plugin::XmlWriter を受信します。

プラグインインスタンスのカスタムデータを、プロジェクトのWork Unitに保存することができれば、インスタンス化して間もなく、プロジェクトロード中に InitFromWorkunit がコールされます。Authoringによってカスタムデータプラグインを初期化する方法が、状況に応じて、ほかに2通りあります。相互に排他的な方法で、初期化時にどちらか一方だけがコールされます。

AK::Wwise::Plugin::CustomData::InitToDefault() は、Authoringが新インスタンスを初期化するとき、または保存データがないとき
AK::Wwise::Plugin::CustomData::InitFromInstance() は、ユーザーがプラグインインスタンスを複製したとき、またはプラグインインスタンスが削除されたとき、またはredoが実行されたとき。

注釈: プラグインコードが、そのデータのバージョン管理を担うので、カスタムデータにバージョン情報を追加することが、強く推奨されます。プラグインが、ロード可能または不可能なデータのバージョンを認識していることを確認し、クラッシュやデータ破損の発生を避けるようにしてください。

Custom Data Notification

特定のデータが変更されてそのデータを保存、またはサウンドエンジンに転送するときに、Wwiseに通知するには、 AK::Wwise::Plugin::Host::NotifyInternalDataChanged() 関数を使います。ノティフィケーションを、データのサブセットに制限するには、ParamIDを指定します。ここでは、この内部データユニットを"複雑なプロパティ"と呼びます。また、 AK::IAkPluginParam::ALL_PLUGIN_DATA_ID を使って、全てのデータが変更されたと指定することもできます。

注釈: XMLで宣言してProperty Setが扱ったプロパティには、NotifyInternalDataChangedを使わないでください。 AK::Wwise::Plugin::PropertySet のセッター関数を使えば、ノティフィケーションが自動的に行われます。

ユーザーがカスタムプロパティを修正して、プラグインがNotifyInternalDataChangedをコールするときに、プラグインのサウンドエンジン部分に転送されるデータブロックを取得するために、Wwiseは AK::Wwise::Plugin::CustomData::GetPluginData メソッドをコールします。サウンドエンジンプラグインはこのブロックを、NotifyInternalDataChangedで指定したParamIDで AK::IAkPluginParam::SetParam 経由で受領します。

注釈: もしカスタムプロパティを使うのであれば、 AK::IAkPluginParam::SetParam と AK::Wwise::Plugin::CustomData::GetPluginData にある、 AK::IAkPluginParam::ALL_PLUGIN_DATA_ID をハンドルする必要があります。少なくとも1回、プラグインを最初にプレイするときに使います。

プロパティの表示名と値

いわゆる"ユーザーフレンドリー"な名前を各プロパティに関連付けるには、Propertyタグの"DisplayName"属性を指定します（詳細は Properties 要素を参照してください）。ただし、状況に応じて意味が変わるようなダイナミックなプロパティの場合は、 AK::Wwise::Plugin::PropertyDisplayNames インターフェースを実装して、プロパティと値の名前を指定できます。

ディスプレイ名は、ユーザーインターフェースの複数の場所で表示されます。具体的にはRTPC Manager、Multi Editor、プロパティ変更のあとのundo/redoコマンドのEditメニューなどです。

AK::Wwise::Plugin::PropertyDisplayName::DisplayNameForProp の in_pszPropertyName パラメータは、プラグインのXML定義ファイル（ Wwiseプラグイン XML 記述ファイル）で指定したプロパティ名に対応します。以下はこのメソッドのサンプル実装です：

bool MySourcePlugin::DisplayNameForProp(
    const char* in_pszPropertyName,
    char* out_pszDisplayName,
    uint32_t in_unCharCount) const
{
    if (strcmp(in_pszPropertyName, "Frequency") == 0)
    {
        strncpy(out_pszDisplayName, "Frequency (KHz)", in_unCharCount);
        return true;
    }
    return false;
}

特定のプロパティで、On/OffやYes/Noなどを意味するブールプロパティやカーブタイプの列挙などの数値以外の値があったり、一部の値が特別の意味を有する場合は、AK::Wwise::Plugin::PropertyDisplayName::DisplayNamesForPropValues() メソッドの実装においてプロパティの可能な値の一部または全てで、表示させるカスタムテキストを、指定できます。RTPCグラフビューで、Y軸のそれらの値にカスタムテキストを使います。

注釈: AK::Wwise::Plugin::PropertyDisplayName::DisplayNamesForPropValues() がビルドする文字列のフォーマットは、あなたのダイアログのCombo Boxコントロールに指定できる"Options"属性のフォーマットと同じです（詳細は Wwise プラグインのダイアログリファレンスを参照してください）。文字列にコンマ区切りの値とテキストのペアが含まれ、各ペアに、コロン区切りの数値とテキストが入っています。例：

ブール型(Boolean)プロパティ："0:Off,1:On"
列挙型の数値プロパティ："0:Low Pass,1:High Pass,2:Band Pass"
特別な意味を持ついくつかの値を使用する数値プロパティ： "-100:Left,0:Center,100:Right"

bool プロパティの場合、値／テキストのペアの値側で、false に 0、 true に1を使用してください。

次のサンプルコードでは、プラグインリソースから名前が取得されています：

// Allow Wwise to retrieve a user friendly name for that property's value (for example, RTPCs).
bool MySourcePlugin::DisplayNamesForPropValues(
    const char * in_pszPropertyName,
    char * out_pszValuesName,
    uint32_t in_unCharCount
) const
{
    if (strcmp(in_pszPropertyName, szSmoothMode) == 0)
    {
        strncpy(out_pszValuesName, "0:LowRes,1:HiRes", in_unCharCount);
        return true;
    }
 
    return false;
}