Wwise SDK 2022.1.16

このページでは、Windowsグラフィカルユーザーインターフェース（GUI）の実装に関わる様々な要素について説明します。

注釈: Wwise Authoringアプリケーションは、macOSで稼働させるために、オープンソースプロジェクトWineに基づいたブリッジレイアCrossoverを使います。 Windows用にGUI実装を作成すれば、同じ実装がこのソリューションを通してmacOSでも動きます。

プラグインのプロパティにバインドされたコントロール機能のある、特定タイプのダイアログを、Wwiseがインスタンス化できるように、基底クラス AK::Wwise::Plugin::GUIWindows が実装メソッドを提供します。また、あなたのプラグインビューインスタンスに向けられたWindowsイベントに対し、プラグインが行動できるように、標準Win32ウィンドウプロシージャ（"WindowProc"）が提供されます。

Wwise Authoringアプリケーションが以下のようにあなたのプラグインGUIをインスタンス化します。

Wwiseが AK::Wwise::Plugin::GUIWindows::GetDialog() をコールして、特定タイプのダイアログがインスタンス化されるのを、プラグインがリクエストします（ダイアログアクイジション参照）。
もしプラグインのフロントエンドが、そのダイアログタイプに対応していれば、プラグインがそのタイプに対応するリソースダイアログIDを返し、さらに、どのコントロールIDが、プロパティセットのどのプロパティキーに対応するのかを、Wwiseに伝えるプロパティバインディング表（プラグインXMLで定義、詳細は Wwiseプラグイン XML 記述ファイル参照）があれば、それも返します。
そのダイアログは、プラグインが提供するリソースハンドルを使い、Wwiseによってインスタンス化されます（リソースハンドル参照）。
Windows が、WM_INITDIALOGなどのイベントで、WindowProcをコールし始めます。

以下のセクションで、メソッドごとの実装方法を説明します。

MFCを使う

WindowsのWwise Authoring GUIは、Microsoft Foundation Classes (MFC)を使ってビルドされています。プラグインにMFCを使用するかどうかは任意ですが、使う場合は、ライブラリの初期化が必要です。これを提供するのは、サービス AK::Wwise::Plugin::PluginMFCWindows です。ほかよりも先に初期化されるように、必ず最初の基底クラスにしてください。

class FrontendSourcePluginMFC
:   public AK::Wwise::Plugin::PluginMFCWindows<>
,   public AK::Wwise::Plugin::GUIWindows
{};

注釈: あなたのプラグインのバックエンド部分では、MFCやその他のGUI関連ライブラリを必要としないはずなので、この基底クラスから派生 させないでください 。

リソースハンドル

リソースハンドルは、タイプ HINSTANCE で、 .rc ファイルからコンパイルされたリソースデータを保持するあなたの動的ライブラリに対応しています。Microsoft Visual Studioを使って作成することができ、あなたのカスタムダイアログや、そのコンテンツを保持しています。リソースファイルの作成方法など、詳細は、 Microsoftドキュメンテーションを参照してください。

デフォルトの実装では、MSVCリンカーがインジェクトしたbuiltinの、モジュールインスタンスが提供されています。

// GUIWindows.h
// Acquire the module instance from the Microsoft linker
extern "C" IMAGE_DOS_HEADER __ImageBase;
 
virtual HINSTANCE GetResourceHandle() const
{
    return (HINSTANCE)&__ImageBase;
}

あなたのダイアログリソースを所有するのが、別のモジュールでない限り、この関数を実装する必要はありません。

リソースファイル（ .rc ）を作成するには、 Creating Resource Files for Your Plug-in を参照してください。

ダイアログアクイジション

現在、Wwiseが AK::Wwise::Plugin::eDialog で定義するダイアログは、2タイプあります:

SettingsDialog: Source EditorやEffect Editorのために使われる、メインのプラグインダイアログ
ContentsEditorDialog: SourceプラグインがContents Editorだけで使う、小さいダイアログ

続いて、Wwiseに返されたダイアログが、提供されたリソースハンドルを使ってインスタンス化されます。プロパティを、あなたのダイアログ中のコントロールに紐づけるために、プラグインのXML定義にあるプロパティ名に、コントロールIDをマッピングした表が使われます。この表は、以下のようにマクロを使って作成されます:

constexpr auto propertyKey = u8"MyProperty";
 
AK_WWISE_PLUGIN_GUI_WINDOWS_BEGIN_POPULATE_TABLE(PropertyTable)
    AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM(IDC_MYPROPERTY_EDIT, propertyKey)
AK_WWISE_PLUGIN_GUI_WINDOWS_END_POPULATE_TABLE()

この例で、表（table）はコントロールのIDC_MYPROPERTY_EDIT（.rcファイルに伴うresource.h fileより）を、プロパティのMyPropertyにマッピングしますが、このプロパティはプラグインのXML定義で定義されたプロパティに連動する必要があります。

これで変数PropertyTableがインスタンス化され、それをWwise AuthoringアプリケーションにGetDialog()で転送します:

bool FrontendSourcePlugin::GetDialog(
    AK::Wwise::Plugin::eDialog in_eDialog,
    UINT& out_uiDialogID,
    AK::Wwise::Plugin::PopulateTableItem*& out_pTable) const
{
    switch (in_eDialog)
    {
    case SettingsDialog:
        out_uiDialogID = IDD_SOURCEPLUGIN_SETTINGS;
        out_pTable = ToneGenProp;
        return true;
 
    case ContentsEditorDialog:
        out_uiDialogID = IDD_SOURCEPLUGIN_CONTENTS;
        out_pTable = nullptr;
        return true;
    }
 
    return false;
}

この関数でfalseを返すと、ダイアログがインスタンス化されないだけで、その代わりにデフォルトのものがインスタンス化されます。

あなたのダイアログで使える具体的なコントロールや、それらをプロパティにバインドする方法など、詳細な説明については Wwise プラグインのダイアログリファレンスを参照してください。

WindowProcを通したWindowsイベントハンドリング

UIが変更されたときにコントロールを有効・無効にするなど、指定したアクションが起きるようにするには、受信したウィンドウメッセージを AK::Wwise::Plugin::GUIWindows::WindowProc() 関数で解釈します:

// Standard window function allowing the user to intercept whatever message is of interest when implementing UI behavior.
bool FrontendSourcePlugin::WindowProc(
    AK::Wwise::Plugin::eDialog in_eDialog,
    HWND in_hWnd,
    UINT in_message,
    WPARAM in_wParam,
    LPARAM in_lParam,
    LRESULT& out_lResult)
{
    if ( in_message == WM_INITDIALOG )
    {
        // Perform anything you need to do on dialog window initialization ...
    }
 
    // For example, catch window command actions (only for the main dialog) to enable/disable controls
    else if ( in_eDialog == SettingsDialog && in_message == WM_COMMAND )
    {
        // Notification code
        switch ( HIWORD( in_wParam ) )
        {
        case BN_CLICKED:
            // Check which button was clicked
            switch ( LOWORD( in_wParam ) )
            {
            case IDC_CHECK_SWEEPFREQ:
                // Verify if check box was enabled
                if ( IsDlgButtonChecked( in_hWnd, IDC_CHECK_SWEEPFREQ ) == BST_CHECKED )
                {
                    // Enable some controls ...
                }
                else if ( IsDlgButtonChecked( in_hWnd, IDC_CHECK_SWEEPFREQ ) == BST_UNCHECKED )
                {
                    // Disable some controls ...
                }
                break;
            }
        } // End switch hi word (notification code)
 
    } // End command window event
 
    // Return false to let the parent window deal with the message.
    // Return true for messages you don't want the parent window to handle.
 
    return false;
}

プラグインのヘルプを表示させる

Wwiseユーザーがプラグインのダイアログタイトルバーにある'?'アイコンをクリックすると、プラグインのフロントエンドで、 AK::Wwise::Plugin::GUIWindows::Help() がコールされます。ヘルプを実装するには、HTMLHelp、WinHelp、サードパーティのヘルプブラウザなど、様々なツールを使えます。関数は、表示させるウィンドウの親として使用可能なウィンドウハンドルを、受け取ります。 AK::Wwise::Plugin::eDialog パラメータが、Wwiseユーザーが開いているダイアログに合った、具体的なヘルプトピックを選択できるようにしてくれます。Helpリクエストにあなたが応対した場合は、この関数は true を返し、それ以外では false を返して、代わりにWwiseがPlug-in Manager関連のHelpトピックを表示します。

注釈: 前述の通り、ソースプラグインにはダイアログが2つあります。あなたのソースプラグインで、2つのダイアログ用に別々のヘルプトピックがあれば、 AK::Wwise::Plugin::eDialog パラメータを利用してください。

HTMLヘルプを使うソースプラグインで、そのファイルへのパスがMFCによって提供される例を、以下に示します:

// Implement online help when the user clicks on the "?" icon
bool FrontendSourcePluginMFC::Help(HWND in_hWnd, AK::Wwise::Plugin::eDialog in_eDialog) const
{
    AFX_MANAGE_STATE( ::AfxGetStaticModuleState() );
 
    DWORD dwTopic = ONLINEHELP::Tone_Generator_Settings;
    if ( in_eDialog == AK::Wwise::Plugin::ContentsEditorDialog )
        dwTopic = ONLINEHELP::Tone_Generator_ContentsEditor;
 
    ::HtmlHelp(
        NULL, // <<< Must be NULL to launch on the correct parent window
        AfxGetApp()->m_pszHelpFilePath,
        HH_HELP_CONTEXT,
        dwTopic
    );
 
    return true;
}

注意: AK::Wwise::Plugin::GUIWindows::Help() メソッドが、AfxGetApp()->HtmlHelp() を呼び出してはいけません。 Helpウィンドウを誤った親ウィンドウで起動してしまい、フローティングビューが予期しない動作を起こすためです。代わりに、上の例で示されているように、 HtmlHelp() を NULL ウィンドウハンドルで使用するようにしてください。