Wwise SDK 2023.1.8

ユーザーがプラグインのプロパティを編集するときにWwiseに表示されるダイアログのリソースを、Windows DLLプラグインに入れておくことができます。これは、ソースプラグインおよびエフェクトプラグインの両方に当てはまります。

このページは、そのようなダイアログリソースの詳細を説明するもので、予想されるダイアログの大きさ、様々な種類のコントロールをダイアログに入れ込む方法、そのようなコントロールをプラグインのプロパティにバインドする方法、などを紹介します。

詳細は、以下のセクションを参照してください:

プラグインのダイアログリソース作成方法

Microsoft Development Environment では、Dialog Editor を使用して、Dialog リソースを Wwise Plug-in DLL プロジェクトに追加します。次に、Toolbox ウィンドウの Dialog Editor 部分にあるツールを使用してコントロールを追加します。詳細は Creating Resource Files for Your Plug-in を参照してください。

ダイアログサイズ

エフェクトプラグインは、Wwise の Effect Editor にある Effect Settings タブから編集可能です。ソースプラグインは、Contents Editor または Property Editorより編集可能です。

Effect Editor と Property Editor に表示されるダイアログはかなり大きい可能性がありますが、Contents Editor に表示されるダイアログは、ビューにうまくフィットするよう、より小型のファクタに制限されています。

注釈: ダイアログアクイジションで説明されているように、AK::Wwise::Plugin::GUIWindows::GetDialog() と AK::Wwise::Plugin::GUIWindows::WindowProc() の実装は、AK::Wwise::Plugin::GUIWindows::eDialog パラメータをチェックしてどのダイアログのために呼び出されているのかを認識する必要があります。

Property Editor および Effect Editor のダイアログサイズ

ソースプラグインのProperty Editorダイアログと、ソースプラグインやEffectプラグインのEffect Editorダイアログの推奨サイズは、幅525ダイアログユニット以下、高さ325ユニット以下です。ダイアログユニットの数値は、Visual StudioのResource Editorに記載されています。

なお、ダイアログユニットからピクセルサイズへの換算率は、以下の要因によって異なります。

Windowsの表示設定: テキスト、アプリ、その他アイテムのサイズ設定。通常は100から200まで。モニターの大きさや解像度に応じて、Windowsが自動的に値を設定することもあります。
Wwiseユーザーインターフェースのフォントサイズ: User Preferencesダイアログで定義し、フォントサイズの範囲は8から10までです。フォントサイズが大きいほど、ダイアログサイズは大きくなります。

あなたのプラグインを様々なセットアップで試し、エディタ画面が、ノートブックパソコンなどの小さな画面にも収まることを確認してください。

注意: ダイアログが大きすぎるとクロップされ、ユーザーは全てのコントロールを参照できない可能性があります。

Tip: ダイアログが、Microsoft Development Environment Dialog Editorで選択されている間、ダイアログのサイズがステータスバーの右端にダイアログ単位で表示されます。

Content Editor 内ダイアログのサイズ

ソースプラグインの場合、Content Editor ダイアログは最大幅194ダイアログ単位、高さは厳密に13単位である必要があります。

注意: ダイアログが大きすぎるとクロップされ、ユーザーは全てのコントロールを参照できない可能性があります。

Wwiseにダイアログリソースを取得させる方法

ダイアログリソースを見つけるために Wwise に対して実装する必要のある関数、AK::Wwise::Plugin::GUIWindows::GetResourceHandle() とAK::Wwise::Plugin::GUIWindows::GetDialog() についての情報はダイアログアクイジションを参照してください。

レギュラーコントロールをダイアログに追加する方法

静的コントロール、エディットコントロール、チェックボックス、プッシュボタン、ラジオボタン、グループコントロールなどのレギュラーコントロールを、Toolbox の Dialog Editor セクションにある対応ツールを使用して、Microsoft Development Environment Dialog Editor に直接追加することができます。これらのコントロールは、アプリケーション内の類似コントロールと同じ外観になるよう、Wwise によって自動的にサブクラス化されます。

注釈: 特筆すべき例外として、ドロップダウン／コンボボックスコントロールがあり、これは自動的にサブクラス化されません。ダイアログにドロップダウンコントロールが必要な場合は、代わりに Combo カスタムコントロールを使用してください。詳細は "Class" コントロール属性を参照してください。

注釈: プロパティが RTPC をサポートしている場合、このプロパティにバインドされたコントロールで、RTPC ウィジェットが自動的に表示されます。プロパティに対して RTPC を有効にする方法に関する詳細は、 Properties 要素を参照してください。

標準コントロールをプロパティにバインドする方法

コードを追加する必要なく、プラグインのプロパティにチェックボックスおよびラジオボタンを関連付けることができ、ユーザーがコントロールに何か動作を加えた時に、またはその逆で、これらは更新されます。

これを実行するには、AK/Wwise/Plugin.h で定義されているマクロを使用して "populate table" を作成する必要があります：

単一パラメータ、テーブルの識別子を持っている AK_WWISE_PLUGIN_GUI_WINDOWS_BEGIN_POPULATE_TABLE() マクロから開始します。これは、有効な C++識別子である必要があり、定義されている範囲内で一意でなければなりません。 AK::Wwise::Plugin::GUIWindows::GetDialog() の実装でポピュレートテーブルの out パラメータを設定する時に使用する識別子と同じです（詳細はダイアログアクイジションを参照してください）。

次に AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM() マクロを使い、コントロールとプロパティを関連付けます。プロパティにバインドする必要のあるコントロールは、必ず表に AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM() の項目として入れます。このマクロの最初のパラメータは、このコントロールの、あなたのダイアログ中におけるIDです。 2つ目のパラメータはプロパティ名で、あなたのプラグインのXML定義ファイルで定義されたものです。プロパティ名の詳細は、 Properties 要素を参照してください。

チェックボックスは、bool 型のプロパティに関連付けることができます。プロパティ値 true は、チェックが入ったコントロール、プロパティ値 false は、チェックが入っていないコントロールに対応しています。

ラジオボタンは、int32 型のプロパティに関連付けることができます。コントロールグループの各ラジオボタンは、特定の値に対応しています。グループの最初のラジオボタンは、値0に対応、2番目は値1、3番目は値2という風に対応しています。ラジオボタンが期待通りに作用するには、ラジオボタンのタブオーダーとコントロールのグループ化の2事項を慎重に設定しなければなりません。

Microsoft Development Environment Dialog Editor でダイアログ編集中にタブオーダーを表示するには、Format メニューを開き、Tab Order を選びます。各コントロールの近くに、タブオーダーに対応する数字が表示されます。順序を変更するには、最初に来るべきコントロールをクリック、2番目に来るべきコントロールをクリックというように、すべてのコントロールが希望の順序になるまで、この操作を続けます。終了したら、Format メニューへ戻り、Tab Order を再び選び、このオプションをオフにします。

コントロールをグループ化するには、Microsoft Development EnvironmentのProperties ウィンドウで、最初のラジオボタンの Group プロパティを True に設定します。同じグループの他のラジオボタンでは、Group プロパティを False に設定します。

タブオーダー、コントロールグループおよび Dialog Editor 一般に関する詳細は、Microsoft Development Environment のドキュメンテーションをご参照ください。

すべての AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM() エントリが定義されたら、AK_WWISE_PLUGIN_GUI_WINDOWS_END_POPULATE_TABLE() マクロを使用してポピュレートテーブルの宣言を終了します。

Tip: AK::Wwise::Plugin::GUIWindows::GetDialog() の実装と同じ CPP ファイルにこの宣言を置き、これにアクセスする必要のある唯一の場所とすることができます。

ダイアログに Wwise プロパティコントロールを追加する方法

（Caption、Slider、Faderのような）Wwise ダイアログコントロールをダイアログに統合するには、特別にコード化されたキャプションテキストと静的テキストコントロールのプレースホルダを使用します。このテキストは、次のような形式を持っている必要があります：

Tip: ダイアログコントロールのレイアウト表示をより容易にするには、Microsoft Development Environment Dialog Editor の静的プレースホルダの Properties において Border を True に設定してください。例は、例を参照してください。

これらの属性を詳しく見てみましょう：

"Class" コントロール属性

Class 属性は必須です。これは、静的プレースホルダを置き換えるためにダイアログに挿入されるコントロールのタイプを識別します。この属性は、次の形式を持っています：

ここで、[Classname] は以下のいずれかになります：

Caption: 読み取り専用テキスト表示

リソースの静的コントロールは、正確に13ユニットの高さで、最長のテキストを収容するのに十分な幅である必要があります。
Combo: ドロップダウンリスト

リソースの静的コントロールは、正確に13ユニットの高さで、最長のテキストを収容するのに十分な幅である必要があります。
Edit: 編集可能テキスト

リソースの静的コントロールは、正確に13ユニットの高さで、最長のテキストを収容するのに十分な幅である必要があります。"string（文字列）" 型プロパティはこのコントロールにバインドする必要があります。
Fader: ボリュームフェーダ
Spinner: スピナーコントロール付き整数の数値エディタ

リソースの静的コントロールは、正確に13ユニットの高さで、最大値を収容するのに十分な幅である必要があります。
SuperRange: 横スライダー付き数値エディタ

リソースの静的コントロールは、正確に13ユニットの高さで、最大値を収容するのに十分な幅である必要があります。

注釈: これらの各コントロールは、それぞれのプロパティの特定のニーズに合わせてビヘイビアを適合させるために、様々なオプション属性をサポートしています。詳細は、その他のコントロール属性を参照してください。

"Prop" コントロール属性

Prop 属性により、プラグインのプロパティのいずれかにコントロールをバインドすることができます。この属性は、次の形式を持っています：

[PropName] ではコントロールがバインドされるべきプロパティの名前が指定されます。この名前は、プラグインのXML定義ファイルで指定されている名前と同じです（詳細は Properties 要素を参照）。

この属性は、オプションです。これが指定されていなくても、コントロールは作成されますが、プロパティにバインドされません。例えば、SetWindowText() を使用してコントロールに設定したテキストの一部を、Caption コントロールで表示することができます。

注意: プロパティにバインドされているコントロールは、プロパティの値に基づいて、表示するテキストを設定します。これらのコントロールにウィンドウテキストを明示的に設定しないでください。

注意: プロパティにバインドされていない コントロールを作成する場合には、ダイアログが完全に作成される後まで、コントロールのテキストをそのままにしておいてください。例えば、AK::Wwise::Plugin::GUIWindows::WindowProc() メソッドでの WM_INITDIALOG メッセージ処理中など、コントロールのテキスト変更をあまりに早く行うと、リソーステキストに設定されている Class 属性を必要な時に使用することができず、Wwise が適切なコントロールを作成することができません。

その他のコントロール属性

一部のコントロールは、上記の Class および Prop 属性の他に、コントロールを各プロパティの要件に調整する属性をサポートしています。

Decimals

形式:

ここで、[Number] は、小数点以下に表示する桁数です。この値は、非負の整数でなければなりません。0に設定されている場合は、小数点以下の数字および小数点は表示されません。

この属性は、次のコントロールタイプで使用可能ですが、数値のプロパティにバインドされる必要があります：

Caption
Fader
SuperRange

警告: この属性は非推奨です。これは、/PluginModule/{EffectPlugin または SourcePlugin}/Properties/Property/UserInterface[Decimals] でプラグイン記述のXMLにて定義される必要があります。詳細は UserInterface を参照してください。

Min

形式:

ここで、[Number] は、このコントロールに入力可能な最小値です。この値は、コントロールがバインドされているプロパティのタイプによって、整数または小数を指定できます。

この属性は、次のコントロールタイプで使用可能ですが、数値のプロパティにバインドされる必要があります：

Fader
SuperRange

警告: この属性は非推奨です。これは、/PluginModule/{EffectPlugin または SourcePlugin}/Properties/Property/Restrictions/ValueRestriction/Range/Min でプラグイン記述のXMLにて定義される必要があります。詳細は UserInterface を参照してください。

Max

形式:

ここで、[Number] は、このコントロールに入力可能な最大値です。この値は、コントロールがバインドされているプロパティのタイプによって、整数または小数を指定できます。

この属性は、次のコントロールタイプで使用可能ですが、数値のプロパティにバインドされる必要があります：

Fader
SuperRange

警告: この属性は非推奨です。これは、/PluginModule/{EffectPlugin または SourcePlugin}/Properties/Property/Restrictions/ValueRestriction/Range/Max でプラグイン記述のXMLにて定義される必要があります。詳細は UserInterface を参照してください。

Mid

形式:

ここで、 [Number] は、 SuperRange の下部に表示される小さなスライダのアンカーポイントです。この値は、コントロールがバインドされているプロパティのタイプによって、整数または小数を指定できます。

この属性は、次のタイプのコントロールで使用可能です。

SuperRange

警告: この属性は非推奨です。これは、/PluginModule/{EffectPlugin または SourcePlugin}/Properties/Property/UserInterface[Mid] でプラグイン記述のXMLにて定義される必要があります。詳細は UserInterface を参照してください。

Step

形式:

ここで、 [Number] は、スライダを移動する際に数値変化が起こる数量です。この値は、コントロールがバインドされているプロパティのタイプによって、整数または小数を指定できます。

この属性は、次のコントロールタイプで使用可能ですが、数値のプロパティにバインドされる必要があります：

Fader
SuperRange

警告: この属性は非推奨です。これは、/PluginModule/{EffectPlugin または SourcePlugin}/Properties/Property/UserInterface[Step] でプラグイン記述のXMLにて定義される必要があります。詳細は UserInterface を参照してください。

Fine

形式:

ここで、[Number] は、Shift キーを押しながらスライダを移動する際に数値変化が起こる数量です。この値は、コントロールがバインドされているプロパティのタイプによって、整数または小数を指定できます。

この属性は、次のコントロールタイプで使用可能ですが、数値のプロパティにバインドされる必要があります：

Fader
SuperRange

警告: この属性は非推奨です。これは、 /PluginModule/{EffectPlugin または SourcePlugin}/Properties/Property/UserInterface[Fine]でプラグイン記述のXMLにて定義される必要があります。詳細は UserInterface を参照してください。

UIMin

形式:

ここで、[Number] は、スライダを使用して最初に設定可能な最小値です。この値が、 Min 属性で指定された値より大きい場合、ユーザーは、この属性により指定された値より小さい値を入力して、より低い値に強制し、コントロールの範囲を拡大することが可能です。

この値は、コントロールがバインドされているプロパティのタイプによって、整数または小数を指定できます。

Tip: この属性の目的は、プロパティ範囲がとても大きい場合に、コントロールのスライダ初期範囲をより使いやすくすることです。プロパティのいずれかが大きな理論的範囲を持っているが、一般的にユーザーはより制限された範囲を使用する場合には、Min/Max 属性を使用して real 範囲を、 UIMin/UIMax 属性を使用して、スライダの初期範囲を設定してください。

この属性は、次のコントロールタイプで使用可能ですが、数値のプロパティにバインドされる必要があります：

SuperRange

警告: この属性は非推奨です。これは、/PluginModule/{EffectPlugin または SourcePlugin}/Properties/Property/UserInterface[UIMin] でプラグイン記述のXMLにて定義される必要があります。詳細は UserInterface を参照してください。

UIMax

形式:

ここで、 [Number] は、スライダを使用して最初に設定可能な最大値です。この値が、Max 属性で指定された値より小さい場合、ユーザーは、この属性により指定された値より大きい値を入力して、より大きな値に強制し、コントロールの範囲を拡大することが可能です。

この値は、コントロールがバインドされているプロパティのタイプによって、整数または小数を指定できます。

この属性は、次のコントロールタイプで使用可能ですが、数値のプロパティにバインドされる必要があります：

SuperRange

警告: この属性は非推奨です。これは、/PluginModule/{EffectPlugin または SourcePlugin}/Properties/Property/UserInterface[UIMax] でプラグイン記述のXMLにて定義される必要があります。詳細は UserInterface を参照してください。

Options

形式:

ここで、[ValueX] は可能な数値プロパティの値であり、[TextX] は、コントロールのその値に関連付けられるテキストです。文字列には、コンマで区切られた "value:text（値：テキスト）" のペアが含まれており、各ペアにはコロンで区切られた数値と関連テキストが含まれています。例：

ブール型(Boolean)プロパティ："0:Off,1:On"
列挙型の数値プロパティ："0:Low Pass,1:High Pass,2:Band Pass"

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

この属性は、次のタイプのコントロールで使用可能です。

Combo

これは、ドロップダウンリストのコンテンツを定義するために使用されます。Options 属性に表示される値のみが、Combo コントロールで Wwise ユーザーによって設定可能です。

注釈: Options 属性の形式は、AK::Wwise::Plugin::PropertyDisplayName::DisplayNamesForPropValues() メソッドの形式と同じです。詳細は、プロパティの表示名と値を参照してください。

警告: この属性は非推奨です。オプションは、/PluginModule/{EffectPlugin または SourcePlugin}/Properties/Property/Restrictions/ValueRestriction/Enumeration/Value[DisplayName] でプラグイン記述のXMLにて、列挙型の値ごとに定義される必要があります。詳細は UserInterface を参照してください。

SliderType

形式:

SliderType 値については、UserInterface を参照してください。

この属性は、次のコントロールタイプで使用可能ですが、数値のプロパティにバインドされる必要があります：

Fader
SuperRange

警告: この属性は非推奨です。これは、/PluginModule/{EffectPlugin または SourcePlugin}/Properties/Property/UserInterface[SliderType] でプラグイン記述のXMLにて定義される必要があります。詳細は UserInterface を参照してください。

Align

形式:

この属性は、次のタイプのコントロールで使用可能です。

Caption
Edit

コントロールによって表示されるテキストを整列させるために使用されます。

FontSize

形式:

ここで数字は以下を意味します：

0（デフォルト）：標準フォント
1：ラージフォント

この属性は、次のタイプのコントロールで使用可能です。

Caption

コントロールにより表示されるテキストのフォントサイズを指定するために使用されます。

TimeDisplay

形式:

ここで数字は以下を意味します：

0 （デフォルト）：特殊な時刻形式なし。
1：MM:SS.mmm（分、秒、ミリ秒）形式を使用。最小値は-59:59.999、最大値は59:59.999。
2：HH:MM:SS.mmm（時間、分、秒、ミリ秒）を使用。この場合には最小および最大値はなし。

この属性は、次のタイプのコントロールで使用可能です、ただし、このコントロールがミリ秒を表す int32 タイプのプロパティにバインドされている必要があります。

Caption

プロパティタイプの詳細については Properties 要素を参照してください。

例

以下は、Microsoft Development Environment Dialog Editor で表示される、エフェクトプラグインのサンプルダイアログリソースです：

以下は、ダイアログリソースコードです、ダイアログ内の様々な静的プレースホルダに使用される正確なキャプションテキストを表示しています：

警告: このコードの属性の一部は非推奨です：Decimal、Step、Fine、SliderType、Mid、 UIMin、UIMax。詳細は UserInterface を参照してください。

この例では、プラグインの AK::Wwise::Plugin::GUIWindows::GetDialog() 実装によって返される、プラグインの .cpp ファイルが次のテーブルを定義できるよう、Enable Feedback チェックボックスと Interpolation ラジオボタンがプロパティにバインドされている必要があります：

最後に、Effect EditorでWwise ユーザーによって見られるダイアログです：

プラグインのダイアログをテストする方法

Effect Editor ダイアログ（エフェクトプラグインのみ）

Wwiseでダイアログを表示するには：

Views メニューに移動し、Effect Editor を選択します。
Effect ドロップダウンメニューから、エフェクトプラグインを選択します。リストに選択したいプラグインが表示されない場合は、Wwise ソースプラグインおよびエフェクトプラグインのトラブルシューティングガイドを参照してください。

これで、Effect Editor にエフェクトプラグインのダイアログが表示されるはずです。エフェクトの使用に関する詳細については、Wwise ドキュメンテーションを参照してください。

Contents Editor ダイアログ（ソースプラグインのみ）

Wwiseでダイアログを表示するには：

Actor-Mixer Hierarchy を右クリックし、New Child > Sound SFX を選択します。これにより新規 Sound が作成されます。
新規 Sound をダブルクリックして、点検します。
Contents Editor で、Add Source ボタンをクリックしリストからプラグインを選択します。リストに選択したいプラグインが表示されない場合は、Wwise ソースプラグインおよびエフェクトプラグインのトラブルシューティングガイドを参照してください。

これで、Contents Editor にソースプラグインのダイアログが表示されるはずです

Property Editor ダイアログ（ソースプラグインのみ）

Wwiseでダイアログを表示するには：

Actor-Mixer Hierarchy を右クリックし、New Child > Sound SFX を選択します。これにより新規 Sound が作成されます。
新規 Sound をダブルクリックして、点検します。
Contents Editor で、Add Source ボタンをクリックしリストからプラグインを選択します。リストに選択したいプラグインが表示されない場合は、Wwise ソースプラグインおよびエフェクトプラグインのトラブルシューティングガイドを参照してください。
プラグイン用に表示される小さなダイアログをダブルクリックします。

これで、Property Editor がプラグインのダイアログを表示するはずです。