Wwise SDK 2024.1.9

In Wwise 2021.1, we introduced a new API for the Authoring part of plug-ins that included several changes. この移行ガイドで、その変更点や、新しいAPIを使うためのプラグインのコードの更新方法を説明します。

注釈: Authoringプラグインの新APIは、<Wwise>/SDK/include/AK/Wwise/Plugin の下にあります。

新機能

2021.1では、いくつかの目的を念頭に、プラグインAPIが書き直されました。主な目的は、後方互換性のサポートを強化することと、プラグインの作成要件を最小限に抑えることで、バックエンドとフロントエンド間の実装の懸念点を分離させ、より良いデフォルト設計を提供しています。この目的を達成するために、以下を行いました:

プラグインのバックエンドとフロントエンドは別々なので、1つのバックエンドが複数のフロントエンドに対して存在することがあります。Wwiseの観点では、バックエンドはモデル管理やバンク生成に関連する役割を担い、フロントエンドはグラフィカルユーザーインターフェース（GUI）やユーザーへのモニタリングフィードバックの提供などを担当します。また、コマンドラインのセッションという観点では、分離させることで、プラグインのバックエンド部分だけをインスタンス化すれば良いので、パフォーマンスに良い影響を与えます。フロントエンドを提供しない場合は、デフォルトのものがランタイムに生成されます。
AK::Wwise::IAudioPlugin クラスは、いくつかの小さいインターフェースに分割され、それぞれにバージョンがついています。プラグインは、サービスインスタンスをリクエストし、指定したインターフェースを実装することで、Authoringアプリケーションに対してサービスをリクエストしたり提供したりできるようになりました。典型的なプラグインは依存性が少なくなり、Authoringアプリケーションが使用中のインターフェースのバージョンを把握しているので、旧バージョン用にアダプタを実装すれば、今後のWwiseバージョンにも対応できます。また、インターフェースのサポートを終了したときに、ユーザーに非対応のプラグインの情報を伝えることができます。こうした設計の結果、プラグイン開発者は、Wwiseの新しいバージョンに対応するためのプラグイン更新回数を減らせます。
AuthoringプラグインAPIは、C APIベースのアーキテクチャを採用しているので、Windows SDK VARIANT のような、ツールセットやプラットフォーム専用のストラクチャに依存しません。プラグイン動的ライブラリが、シンプルなC定義のストラクチャを公開し、プラグインごとに、そのコンポーネントの概要と実装へのポインタを提供します。便宜上、オリジナルAPIの機能を再現するC++ APIが、これらの下位レベルのストラクチャを、コンパイル時につくり出します。
プラグインの登録が簡素化され、1つのライブラリの全プラグインのディスクリプタを入れたストラクチャである、プラグインコンテナというコンセプトの一部となっています。コンテナにプラグインクラスを追加すると、このグローバルコンテナの構築時にプラグインのサウンドエンジン部分が自動登録されます。少数のマクロだけでAuthoringプラグインを公開することができるので、詳しくは Library Plug-in Container セクションを参照してください。

前述の新機能のほかに、明確性を高めるために変更した関数もいくつかあります。

注釈: プラグインのSound Engine部分の設計はこれと異なり、以前のバージョンからのアプローチをそのまま引き継いでいます。

APIの変更、削除

すでに使われないと判断されたいくつかのメソッドを、2021.1ではAPIから削除しました。ほかにも、削除されずに、名前を変更したり引数を変更したりして、より明確で使いやすいものに修正されたメソッドもあります。

AK::Wwise::IAudioPlugin::SetPluginPropertySet() : 削除されました（廃止）
AK::Wwise::IAudioPlugin::SetPluginObjectStore() : 削除されました（廃止）
AK::Wwise::IAudioPlugin::SetPluginObjectMedia() : 削除されました（廃止）
AK::Wwise::IAudioPlugin::Destroy() : 削除されました（廃止）
AK::Wwise::IAudioPlugin::IsPlayable() : 削除されました（不使用）
AK::Wwise::IAudioPlugin::GetPluginMediaConverterInterface() : 削除。スタンドアロンインターフェースの AK::Wwise::Plugin::MediaConverter に置き換えました。
AK::Wwise::IAudioPlugin::CopyInto() -> AK::Wwise::Plugin::CustomData::InitFromInstance() : 名前を変更し、引数を変更しました。ロジックを逆にしたので、相互排他的なほかの Init メソッドに類似します。
AK::Wwise::IAudioPlugin::Load() -> AK::Wwise::Plugin::CustomData::InitFromWorkunit() : 名前を変更
AK::Wwise::IAudioPlugin::Delete() -> AK::Wwise::Plugin::CustomData::OnDelete() : 名前を変更

以前は任意でないポインター引数があり、リファレンスに変更されたメソッドは、ここに記載されていません。

Changes to Plug-in Registration

In the original API, the Authoring part of the plug-in registered itself by calling AK::Wwise::RegisterWwisePlugin, which made the plug-in inject g_pAKPluginList into the loaded WwiseSoundEngine DLL.

In the new API, Wwise Authoring manages the registration process. Plug-in dynamic libraries now expose plug-ins as entries listed in a plug-in container that Wwise Authoring retrieves with the exported GetPluginContainer${ContainerName} function. Each plug-in entry in the container is an instance of ak_wwise_plugin_info that describes an Authoring plug-in and associates an Authoring plug-in class with a corresponding Sound Engine plug-in class.

As a result of this change, the Sound Engine plug-in part can no longer use the single AkCreatePlugin instantiation function. Instead, it must define one AK::Registration instance per plug-in, typically using the AK_IMPLEMENT_PLUGIN_FACTORY macro. A plug-in registration requires dedicated factory functions, so porting an AkCreatePlugin function requires it to be split into plug-in specific functions, for example CreatePlugin1FX, CreatePlugin1Params, CreatePlugin2Source, CreatePlugin2Params, and so on.

Refer to Library Plug-in Container for instructions on how to set up the plug-in container in the Authoring plug-in part.

簡単なプラグインをポートする

AuthoringプラグインAPIの提供する機能のうち、あなたのプラグインが使うのは、その一部分でしかない可能性が高いです。以下の機能ごとのセクションで、それぞれの変更点をまとめてあるので、プラグインのAPIの使い方に応じて該当するセクションを参照してください。AuthoringプラグインAPIのさらに上級の機能については、リクエストの一般的なユースケースを参照してください。

注釈: このセクションでは、2021.1より前のAPIを「オリジナルAPI」と呼び、2021.1以降のものを「新API」と呼んでいます。

AudioPlugin

オリジナルAPIでは AK::Wwise::IAudioPlugin インターフェースにAuthoringプラグインAPIの全機能が入っていました。各メソッドの実装を空にするには、 AK::Wwise::DefaultAudioPluginImplementation をサブクラスにするだけで済みましたが、それでもクラスに不要なメソッドが定義された状態で入っていました。

新APIにも似たような AK::Wwise::Plugin::AudioPlugin インターフェースがありますが、そのメソッドは、 AK::Wwise::Plugin::AudioPlugin::GetBankParameters() だけです。もしあなたのプラグインがシンプルで、典型的なプロパティをSoundBankに書き込んでいるような場合は、このインターフェースの実装だけで充分です。また、このインターフェースを実装すれば、実装クラスがバックエンドクラスであることが分かります（一方、フロントエンドクラスは、フロントエンドを実装するセクションで説明します）。

オリジナルAPIクラスと新APIクラスの違いが少ないのは、確かです:

オリジナルAPI

// MyAudioPlugin.h
 
class MyAudioPlugin: public AK::Wwise::DefaultAudioPluginImplementation
{
  IPluginPropertySet* m_pPSet = nullptr;
public:
  void Destroy() override { delete this; }
  void SetPluginPropertySet(IPluginPropertySet* in_pPSet) override;
  bool GetBankParameters(const GUID & in_guidPlatform, AK::Wwise::IWriteData* in_pDataWriter) const override;
};

新API

// MyAudioPlugin.h
 
class MyAudioPlugin : public AK::Wwise::Plugin::AudioPlugin
{
public:
  bool GetBankParameters(
    const GUID& in_guidPlatform,
    AK::Wwise::Plugin::DataWriter& in_dataWriter
  ) const override;
};

よく見ると、未実装のメソッドは、 GetBankParameters 1つしかありません。また、 AK::Wwise::IAudioPlugin::Destroy() 関数は不要で、理由は、インストールもデストロイ（破壊）も、完全にプラグインAPIで対応できるからです。リソースを解放するには、標準C++デストラクタを使います。

Property Setを使う

前セクションのコード例を見て、関数 AK::Wwise::IAudioPlugin::SetPluginPropertySet() が削除されたのに気付いたかもしれません。実は、あなたの代わりに AK::Wwise::Plugin::AudioPlugin インターフェースがプロパティセットコンポーネントを リクエスト してくれるので、この関数が不要になったのです。 AK::Wwise::Plugin::RequestPropertySet をサブクラスとすることで、 AK::Wwise::Plugin::AudioPlugin インターフェースが、プラグインのディスクリプションに PropertySet コンポーネント要件を追加してくれ、これはプラグインをインスタンス化するときに、Authoringアプリケーションが満たしてくれます。また、メンバー変数の m_propertySet が追加されますが、これはインスタンス化のときに、自動的に PropertySet コンポーネントインスタンスに設定されます。そうすると、このメンバー変数を手作業で作成して、それに対するsetterを実装する手間が省けます。

おかげで GetBankParameters だけの単純なAuthoringプラグインを実装するのが簡単になりました:

オリジナルAPI

// MyAudioPlugin.cpp
 
void MyAudioPlugin::SetPluginPropertySet(IPluginPropertySet* in_pPSet)
{
  m_pPSet = in_pPSet;
}
 
bool MyAudioPlugin::GetBankParameters(const GUID & in_guidPlatform, AK::Wwise::IWriteData* in_pDataWriter) const
{
  CComVariant varProp; m_pPSet->GetValue(in_guidPlatform, L"Placeholder", varProp);
  in_pDataWriter->WriteReal32(varProp.fltVal);
 
  return true;
}

新API

// MyAudioPlugin.cpp
 
bool MyAudioPlugin::GetBankParameters(const GUID& in_guidPlatform, AK::Wwise::Plugin::DataWriter& in_dataWriter) const
{
  in_dataWriter.WriteReal32(m_propertySet.GetReal32(in_guidPlatform, "Placeholder"));
 
  return true;
}

主な違い:

DataWriter 引数は、任意でないため（NULLとすることは不可）リファレンスとなりました
プロパティセットは、継承メンバー変数の m_propertySet を通してアクセスされます
AK::Wwise::Plugin::PropertySet::GetReal32() に渡されるプロパティ名の文字列のタイプが、 LPCWSTR (const wchar_t*) でなく、 const char* になりました。
AK::Wwise::Plugin::DataWriter との一貫性の確保のため、プロパティのタイプ（ここではReal32）が、 AK::Wwise::Plugin::PropertySet アクセサのメソッドシグニチャで明示的に指定されます。

以上の変更点のおかげで、この関数が、より単純で、安全で、ポートしやすくなりました。

フロントエンドを実装する

AK::Wwise::Plugin::AudioPlugin の実装で、SoundBank生成の最低限の実装が提供されます。ただし、プラグインのこの部分だけを提供すると、表示させるカスタムGUIがないので、AuthoringアプリケーションがMulti-Editorビューと似たGUIを生成します。

すでに触れたとおり、 AudioPlugin クラスはAuthoringプラグインのバックエンドを表しているので、コマンドラインのコンテキスト（GUI抜き）で使え、カスタムデータ管理やカスタムステート管理が実装されます。カスタムGUIを表示させるには、同じプラグイン識別子にアタッチする新しいクラスを作成する必要があります。このクラスは、バックエンドクラスとは別にインスタンス化します。

フロントエンドクラスは、フロントエンドインターフェースをサブクラスとすることで実装します。GUIの性質上、プラットフォーム別に設定することが可能です。このため、フロントエンド関連の旧メソッドの移動先である、 AK::Wwise::Plugin::GUIWindows インターフェースを、WindowsでカスタムプラグインGUIを提供するサブクラスとすることができます。

class MyFrontend : public AK::Wwise::Plugin::GUIWindows
{
public:
  bool GetDialog(
    AK::Wwise::Plugin::eDialog in_eDialog,
    uint32_t& out_uiDialogID,
    AK::Wwise::Plugin::PopulateTableItem*& out_pTable
  ) const;
 
  bool WindowProc(
    AK::Wwise::Plugin::eDialog in_eDialog,
    HWND in_hWnd,
    uint32_t in_message,
    WPARAM in_wParam,
    LPARAM in_lParam,
    LRESULT& out_lResult
  );
 
  bool Help(
    HWND in_hWnd,
    AK::Wwise::Plugin::eDialog in_eDialog,
    const char* in_szLanguageCode
  );
};

注釈: MFCを使う予定であれば、最初に AK::Wwise::Plugin::PluginMFCWindows も、サブクラスとするべきです。グローバル CWinApp を、あなたのライブラリ用に初期化する役割を担ってくれます。

eDialog と PopulateTableItem のコピーが AK::Wwise::Plugin 名前空間に追加されました。 PopulateTableItem の場合は関連マクロも更新され、以下の通りフロントエンドのインターフェースとの関係性が反映されています:

AK_BEGIN_POPULATE_TABLE() -> AK_WWISE_PLUGIN_GUI_WINDOWS_BEGIN_POPULATE_TABLE()
AK_POP_ITEM() -> AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM()
AK_END_POPULATE_TABLE() -> AK_WWISE_PLUGIN_GUI_WINDOWS_END_POPULATE_TABLE()

詳細は、標準コントロールをプロパティにバインドする方法を参照してください。

フロントエンドクラスで、 AK::Wwise::Plugin::AudioPlugin をサブクラスに してはいけなく 、プロパティ値の調整や、SoundBank生成結果に影響するような操作など、バックエンド関連のロジックを実装してもいけません。フロントエンドが担う役割は、プロパティやモニタリングデータをユーザーに分かりやすい形式で表示したり、ユーザー入力に基づいてプラグインモデルを更新したりすることだけです。

もしユーザー提供の値をバックエンド側で調整する必要がなければ、フロントエンドは単純に、 AK::Wwise::Plugin::RequestPropertySet をサブクラスにすることで、 PropertySet コンポーネントをリクエストできます。一方、バックエンドが、ダイナミックなプロパティレンジを実装するなど、プロパティ値の調整を行う場合は、これをバックエンドで実装してください。

もしバックエンドが、フロントエンドで必要とするような実装を提供する場合は、 AK::Wwise::Plugin::RequestLinkBackend をサブクラスとすることで、 LinkBackend サービスをリクエストできます。フロントエンドクラスに対し、 m_backend インスタンスが提供され、このインスタンスが、バインドされているバックエンドインスタンスを表します。

逆も可能で、バックエンドが AK::Wwise::Plugin::RequestLinkFrontend をサブクラスとすることで、 LinkFrontend をリクエストできます。 LinkFrontend が大きく違うのは、1つのバックエンドに対し、複数のフロントエンドが可能だということで、継承された m_frontend インスタンスは、このため、フロントエンドのアレイを表します。アレイのサイズを取得するには GetArray メソッドを使い、便利な ForEach 関数もあります。

リクエストの一般的なユースケース

PropertySet コンポーネントは、一般的に AK::Wwise::Plugin::AudioPlugin::GetBankParameters() というコンテキストで必要となるので、暗黙に AK::Wwise::Plugin::AudioPlugin インターフェースがリクエストしますが、ほかのコンポーネントやサービスは任意で、それを個別にリクエストするには、利用可能な AK::Wwise::Plugin::Request[...] クラスのどれかをサブクラスとします（ Requestコンポーネントとサービスを参照）。プラグインがAuthoringアプリケーションに実装を提供する場合は、インターフェースにプレフィックス Request を付けません。その一例が、 AK::Wwise::Plugin::Source 、 AK::Wwise::Plugin::SinkDevices 、 AK::Wwise::Plugin::PropertyDisplayName などです。

以下はオリジナルAPIの一般的なユースケース一覧と、新APIで同じ機能を入手するためにリクエストする必要のある、該当サービスです。

モニタリングデータ

プラグインのカウンターパートであるサウンドエンジンが送信するモニタリングデータは、 NotifyMonitorData メソッドで受領します。このメソッドを、ノティフィケーションインターフェースに移動しました。このメソッドを実装するには、 AK::Wwise::Plugin::Notifications::Monitor をサブクラスとします。

AK::Wwise::Plugin::Notifications::Monitor インターフェースの実装方法については、 Authoringにおけるモニタリングを参照してください。

プラグインのライセンス

オリジナルAPIでライセンシング用のカスタムハンドラを提供するには、 AK::Wwise::IAudioPlugin::GetLicenseStatus の実装が必要でした。このファンクションが別のインターフェースに移動され、このメソッドを実装するには、サブクラス AK::Wwise::Plugin::License 。

AK::Wwise::Plugin::License の実装方法については、ライセンス管理を参照してください。

オブジェクトメディアとメディアコンバータ

メディアとしてハンドルするプラグインデータとして、ソース変換プロセス中にエンコードできるオーディオファイルなどが典型的ですが、 AK::Wwise::IAudioPlugin::SetPluginObjectMedia() や、 AK::Wwise::IAudioPlugin::GetPluginMediaConverterInterface() を実装することで、対応できます。これらと、メディアオブジェクトの管理を、 AK::Wwise::Plugin::ObjectMedia に集約しました。オブジェクトメディアメソッドは、プラグインクラス内で直接実装します。メディアコンバータは引き続き任意ですが、別のインターフェースとして実装します: AK::Wwise::Plugin::MediaConverter 。

これらのインターフェースの使い方は、オーディオプラグインにメディアを追加するを参照してください。

カスタムプラグインデータ

PropertySetコンポーネントやObjectMediaコンポーネントで管理されていないプラグインデータは、全て共通インターフェース AK::Wwise::Plugin::CustomData に集約されました。ほとんどのメソッドは変わっていませんが、 CopyInto が書き換えられ、ロジックが逆になりました。

AK::Wwise::IAudioPlugin::GetPluginData() -> AK::Wwise::Plugin::CustomData::GetPluginData()
AK::Wwise::IAudioPlugin::InitToDefault() -> AK::Wwise::Plugin::CustomData::InitToDefault()
AK::Wwise::IAudioPlugin::CopyInto() -> AK::Wwise::Plugin::CustomData::InitFromInstance()
AK::Wwise::IAudioPlugin::Load() -> AK::Wwise::Plugin::CustomData::InitFromWorkunit()
AK::Wwise::IAudioPlugin::Save() -> AK::Wwise::Plugin::CustomData::Save()
AK::Wwise::IAudioPlugin::Delete() -> AK::Wwise::Plugin::CustomData::OnDelete()

3つの Init 関数は相互排他的であり、プラグインを初期化したときに、ロードしたときのコンテキストによって3つのうちの1つがコールされます。

これらのメソッドを実装するには、 AK::Wwise::Plugin::CustomData インターフェースをサブクラスとします。 CustomData インターフェースの実装方法については、 Custom Dataを提供するを参照してください。

注釈: 提供されたインスタンスを、オリジナルAPIでは AK::Wwise::IAudioPlugin::CopyInto() を通して初期化していたのに対し、AK::Wwise::Plugin::CustomData::InitFromInstance() は、その引数から、そのインスタンスを初期化します。

Custom Dataを使うプラグインを、2021.1 Authoring Plug-in APIにポートするときに、ロジックの逆転を適用することを忘れないでください。

AK.Wwise::Plugin::eDialog

eDialog

Definition: PluginDef.h:137

AK.Wwise::Plugin::V1::DataWriter

Interface used to write data during sound bank generation.

Definition: HostDataWriter.h:245

AK.Wwise::Plugin::V1::GUIWindows::GetDialog

virtual bool GetDialog(eDialog in_eDialog, uint32_t &out_uiDialogID, PopulateTableItem *&out_pTable) const

Retrieves the plug-in dialog parameters.

Definition: GUIWindows.h:280

AK.Wwise::Plugin::V1::DataWriter::WriteReal32