|
Wwise SDK 2023.1.8
|
このページは、プラグインのモデルをアクセスしたり修正したりする方法を説明します。モデルは、以下の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 が自動的にリクエストされます。それ以外の場合、例えばフロントエンドを作成するときなどは、それをリクエストする必要があります。
 | 注釈: m_propertySet 変数のライフタイムは、プラグインインスタンスのライフタイムと同じです。 インスタンスを、複数のプラグインインスタンスをまたいで保存しないでください。 また、このサービスを、バックエンドとフロントエンドクラスの両方でリクエストできます。 |
プロパティ値のノティフィケーション
Wwise ユーザーは、直接ダイアログ内のコントロールを介して、または、undo/redo（元に戻す／やり直し）コマンドを使用して、プロパティ値を変更することができます。 ユーザーがプロパティ値を変更したときに、AK::Wwise::Plugin::Notifications::PropertySet::NotifyPropertyChanged() が、あなたのプラグインでコールされます。こうすれば、この変更に基づいて、例えばカスタムデータやプロパティレンジの依存性など、ほかのプロパティ値を適合させることができます。また、このときにあなたのダイアログが表示されていれば、コントロールの有効化・無効化など、ダイアログ内で実行するアクションを指定できます。
| 注釈: XMLは、ルールに基づいた依存性のディスクリプションを許容しています。詳細は、Plug-in XML 依存関係 を参照してください。 |
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 記述ファイル ）で指定したプロパティ名に対応します。以下はこのメソッドのサンプル実装です：
特定のプロパティで、On/OffやYes/Noなどを意味するブールプロパティやカーブタイプの列挙などの数値以外の値があったり、 一部 の値が特別の意味を有する場合は、AK::Wwise::Plugin::PropertyDisplayName::DisplayNamesForPropValues() メソッドの実装においてプロパティの可能な値の一部または全てで、表示させるカスタムテキストを、指定できます。RTPCグラフビューで、Y軸のそれらの値にカスタムテキストを使います。
| 注釈:
|
次のサンプルコードでは、プラグインリソースから名前が取得されています：