Wwise SDK 2022.1.18
|
ユーザーがプラグインのプロパティを編集するときに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プラグインのEffect Editorダイアログの推奨サイズは、幅525ダイアログユニット以下、高さ325ユニット以下です。ダイアログユニットの数値は、Visual StudioのResource Editorに記載されています。
なお、ダイアログユニットからピクセルサイズへの換算率は、以下の要因によって異なります。
あなたのプラグインを様々なセットアップで試し、エディタ画面が、ノートブックパソコンなどの小さな画面にも収まることを確認してください。
注意: ダイアログが大きすぎるとクロップされ、ユーザーは全てのコントロールを参照できない可能性があります。 |
Tip: ダイアログが、Microsoft Development Environment Dialog Editorで選択されている間、ダイアログのサイズがステータスバーの右端にダイアログ単位で表示されます。 |
ソースプラグインの場合、Content Editor ダイアログは最大幅194ダイアログ単位、高さは厳密に13単位である必要があります。
注意: ダイアログが大きすぎるとクロップされ、ユーザーは全てのコントロールを参照できない可能性があります。 |
Tip: ダイアログが、Microsoft Development Environment Dialog Editorで選択されている間、ダイアログのサイズがステータスバーの右端にダイアログ単位で表示されます。 |
ダイアログリソースを見つけるために 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 ファイルにこの宣言を置き、これにアクセスする必要のある唯一の場所とすることができます。 |
(Caption、Slider、Faderのような)Wwise ダイアログコントロールをダイアログに統合するには、特別にコード化されたキャプションテキストと静的テキストコントロールのプレースホルダを使用します。このテキストは、次のような形式を持っている必要があります:
Tip: ダイアログコントロールのレイアウト表示をより容易にするには、Microsoft Development Environment Dialog Editor の静的プレースホルダの Properties において Border を True に設定してください。例は、 例 を参照してください。 |
注釈: プロパティが RTPC をサポートしている場合、このプロパティにバインドされたコントロールで、RTPC ウィジェットが自動的に表示されます。プロパティに対して RTPC を有効にする方法に関する詳細は、 Properties 要素 を参照してください。 |
これらの属性を詳しく見てみましょう:
Class
属性は必須です。これは、静的プレースホルダを置き換えるためにダイアログに挿入されるコントロールのタイプを識別します。この属性は、次の形式を持っています:
ここで、[Classname] は以下のいずれかになります:
Caption:
読み取り専用テキスト表示 Combo:
ドロップダウンリスト Edit:
編集可能テキスト Fader:
ボリュームフェーダ Spinner:
スピナーコントロール付き整数の数値エディタ SuperRange:
横スライダー付き数値エディタ 注釈: これらの各コントロールは、それぞれのプロパティの特定のニーズに合わせてビヘイビアを適合させるために、様々なオプション属性をサポートしています。詳細は、その他のコントロール属性 を参照してください。 |
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/ real 範囲を、 UIMin/ |
この属性は、次のコントロールタイプで使用可能ですが、数値のプロパティにバインドされる必要があります:
SuperRange
警告: この属性は非推奨です。これは、/PluginModule/{EffectPlugin または SourcePlugin}/Properties/Property/UserInterface[UIMin] でプラグイン記述のXMLにて定義される必要があります。詳細は UserInterface を参照してください。 |
UIMax
形式:
ここで、 [Number] は、スライダを使用して最初に設定可能な最大値です。この値が、Max
属性で指定された値より小さい場合、ユーザーは、この属性により指定された値より大きい値を入力して、より大きな値に強制し、コントロールの範囲を拡大することが可能です。
この値は、コントロールがバインドされているプロパティのタイプによって、整数または小数を指定できます。
Tip: この属性の目的は、プロパティ範囲がとても大きい場合に、コントロールのスライダ初期範囲をより使いやすくすることです。プロパティのいずれかが大きな理論的範囲を持っているが、一般的にユーザーはより制限された範囲を使用する場合には、Min/ real 範囲を、 UIMin/ |
この属性は、次のコントロールタイプで使用可能ですが、数値のプロパティにバインドされる必要があります:
SuperRange
警告: この属性は非推奨です。これは、/PluginModule/{EffectPlugin または SourcePlugin}/Properties/Property/UserInterface[UIMax] でプラグイン記述のXMLにて定義される必要があります。詳細は UserInterface を参照してください。 |
Options
形式:
ここで、[ValueX] は可能な数値プロパティの値であり、[TextX] は、コントロールのその値に関連付けられるテキストです。文字列には、コンマで区切られた "value:text(値:テキスト)" のペアが含まれており、各ペアにはコロンで区切られた数値と関連テキストが含まれています。例:
注釈: 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
形式:
ここで数字は以下を意味します:
この属性は、次のタイプのコントロールで使用可能です。
Caption
コントロールにより表示されるテキストのフォントサイズを指定するために使用されます。
TimeDisplay
形式:
ここで数字は以下を意味します:
この属性は、次のタイプのコントロールで使用可能です、ただし、このコントロールがミリ秒を表す 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 ユーザーによって見られるダイアログです:
Wwiseでダイアログを表示するには:
これで、Effect Editor にエフェクトプラグインのダイアログが表示されるはずです。エフェクトの使用に関する詳細については、Wwise ドキュメンテーションを参照してください。
Wwiseでダイアログを表示するには:
これで、Contents Editor にソースプラグインのダイアログが表示されるはずです
Wwiseでダイアログを表示するには:
これで、Property Editor がプラグインのダイアログを表示するはずです。
問題が発生した場合には、Wwise ソースプラグインおよびエフェクトプラグインのトラブルシューティングガイド から Help がご利用可能です。