Wwise SDK 2024.1.1

A Windows DLL plug-in can contain resources for the dialog that is displayed in Wwise when the user edits the plug-in's properties. This is true both for source plug-ins and effect plug-ins.

This page is dedicated to the details regarding those dialog resources such as the expected dimensions of the dialogs, how to include various types of controls in your dialog and how to bind those controls to your plug-in's properties.

Refer to the following sections for details:

How to Create Dialog Resources for Your Plug-in

In the Microsoft Development Environment, use the Dialog Editor to add a Dialog resource to your Wwise Plug-in DLL project. You can then add controls using the tools in the Dialog Editor part of the Toolbox window. For more details, refer to Creating Resource Files for Your Plug-in.

Dialog Dimensions

Effect plug-ins can be edited in Wwise in the Effect Settings tab of the Effect Editor. Source plug-ins can be edited either in the Contents Editor or in the Property Editor.

The dialogs displayed in the Effect Editor and the Property Editor can be fairly large, while the ones displayed in the Contents Editor are restricted to a smaller form factor in order to fit nicely in that view.

Note: As explained in Dialog Acquisition, your implementations of AK::Wwise::Plugin::GUIWindows::GetDialog() and AK::Wwise::Plugin::GUIWindows::WindowProc() should check the AK::Wwise::Plugin::GUIWindows::eDialog parameter to know which dialog they are being called for.

Dimensions for Dialogs in the Property Editor and the Effect Editor

It is recommended that the Property Editor dialog for source plug-ins, and the Effect Editor dialog for source and Effect plug-ins, do not exceed 525 dialog units wide and 325 units high. The dialog unit values can be found in the Resource Editor of Visual Studio.

Note that dialog units translate to different pixel sizes depending on the following factors:

Windows Display Settings: The size of text, apps, and other items. Usually set between 100% and 200%. Windows may automatically set this value based on the size and resolution of the monitor
Wwise User Interface Font Size: Defined in the User Preferences dialog, font size can range from 8 to 10. A larger font size translates to a larger dialog size.

It is important to try your plug-in on different setups to ensure the editor(s) fit on smaller screens, such as a laptop screen.

Caution: If the dialog is too big it will be cropped and the user might not see all the controls.

Tip: While your dialog is selected in the Microsoft Development Environment Dialog Editor, the dimensions of your dialog are displayed, in dialog units, at the far right of the status bar.

Dimensions for Dialogs in the Content Editor

For source plug-ins, the Content Editor dialog should be a maximum of 194 dialog units wide, and exactly 13 units high.

Caution: If the dialog is too big it will be cropped and the user might not see all the controls.

Tip: While your dialog is selected in the Microsoft Development Environment Dialog Editor, the dimensions of your dialog are displayed, in dialog units, at the far right of the status bar.

Letting Wwise Retrieve your Dialog Resources

Refer to Dialog Acquisition for information about AK::Wwise::Plugin::GUIWindows::GetResourceHandle() and AK::Wwise::Plugin::GUIWindows::GetDialog() which are functions you must implement for Wwise to find your dialog resources.

How to Add Regular Controls to Your Dialogs

You can add regular controls such as static controls, edit controls, checkboxes, push buttons, radio buttons and group controls directly in the Microsoft Development Environment Dialog Editor using the corresponding tools in the Dialog Editor section of the Toolbox. These controls will be automatically subclassed by Wwise so they have the same look as similar controls elsewhere in the application.

Note: A notable exception is the dropdown/combobox control, which is not automatically subclassed. If you need a dropdown control in your dialog, use the Combo custom control instead. Refer to "Class" Control Attribute for more information.

Note: When a property supports RTPCs, the RTPC widget is automatically displayed with controls that are bound to that property. Refer to Properties Element for more information regarding how to enable RTPCs on properties.

How to Bind Regular Controls to Properties

Checkboxes and radio buttons can be associated to your plug-in's properties so these are updated when the user acts on the controls, and vice-versa, without extra code on your side.

To do so, you must create a "populate table" using macros defined in AK/Wwise/Plugin.h:

AK_WWISE_PLUGIN_GUI_WINDOWS_BEGIN_POPULATE_TABLE(PropertyTable)
    AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM(IDC_CHECK_SWEEPFREQ, szSweepFreq)
    AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM(IDC_RADIO_FREQSWEEPLIN, szSweepFreqType)
    (... insert other items here...)
AK_WWISE_PLUGIN_GUI_WINDOWS_END_POPULATE_TABLE()

You start with the AK_WWISE_PLUGIN_GUI_WINDOWS_BEGIN_POPULATE_TABLE() macro, which has a single parameter, an identifier for the table. It must be a valid C++ identifier, and must be unique within the scope where it is defined. This is the same identifier you will use when setting the populate table out parameter in your implementation of AK::Wwise::Plugin::GUIWindows::GetDialog() (Refer to Dialog Acquisition for more information).

You then use the AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM() macro to associate controls to properties. Each control that must be bound to a property needs an AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM() entry in the table. The first parameter of this macro is the ID of the control in your dialog. The second parameter is the name of the property, as defined in your plug-in's XML definition file. Refer to Properties Element for more information on property names.

Checkboxes can be associated to properties of type bool. Property value true corresponds to a checked control, while property value false corresponds to an unchecked control.

Radio buttons can be associated to properties of type int32. Each radio button in a control group corresponds to a specific value. The first radio button in the group corresponds to value 0, the second to value 1, the third to value 2, and so on. Two things must be carefully set for the radio buttons to work as expected: The radio buttons' tab order, and control grouping.

To view the tab order while editing your dialog in the Microsoft Development Environment Dialog Editor, open the Format menu, and choose Tab Order. Numbers corresponding to the tab order will appear near each control. To change that order, click on the control that should be first, then on the control that should be second, and so on, until all controls are ordered as needed. When you are done, return to the Format menu and choose Tab Order again to turn that option off.

To group controls together, set the Group property of the first radio button to True in the Properties window of the Microsoft Development Environment. Set the Group property to False for the other radio buttons of the same group.

Refer to the Microsoft Development Environment documentation for more information regarding tab order, control groups, and the Dialog Editor in general.

Once all the AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM() entries are defined, use the AK_WWISE_PLUGIN_GUI_WINDOWS_END_POPULATE_TABLE() macro to end the declaration of your populate table.

Tip: You can put this declaration in the same CPP file as your AK::Wwise::Plugin::GUIWindows::GetDialog() implementation, since that's the only place you will need to access it.

How to Add Wwise Property Controls to Your Dialogs

To integrate Wwise dialog controls (such as Captions, Sliders and Faders) into your dialog, use static text control placeholders with a specially coded caption text. This text needs to be have the following form:

Class=[Classname];Prop=[Propname];[Attribute1]=[Value1];[Attribute2]=[Value2];[...]

Tip: To make it easier to view the layout of the dialog controls, set Border to True in the Properties of the static placeholders in the Microsoft Development Environment Dialog Editor. Refer to Example for an example.

Let's look at these attributes in detail:

"Class" Control Attribute

The Class attribute is mandatory. It identifies the type of control to be inserted in the dialog to replace the static placeholder. This attribute has the following format:

Class=[Classname]

where [Classname] can be one of:

Caption: Read-only text display

The static control in your resources should be exactly 13 units high, and be wide enough to accomodate the longest text it might contain.
Combo: Dropdown list

The static control in your resources should be exactly 13 units high, and be wide enough to hold the longest text it might contain.
Edit: editable text

The static control in your resources should be exactly 13 units high, and be wide enough to hold the longest text it might contain. A property of type "string" should be bound to this control.
Fader: Volume fader
Spinner: Integer numeric editor with spinner control

The static control in your resources should be exactly 13 units high, and be wide enough to hold the biggest value it might contain.
SuperRange: Numeric editor with horizontal slider

The static control in your resources should be exactly 13 units high, and be wide enough to hold the biggest value it might contain.

Note: Each of these controls supports various optional attributes to adapt their behavior to the particular needs of each property. Refer to Other Control Attributes for more information.

"Prop" Control Attribute

The Prop attribute lets you bind a control to one of your plug-in's properties. This attribute has the following format:

Prop=[Propname]

where [PropName] specifies the name of the property the control should be bound to. That name is the same name that is specified in the plug-in's XML definition file (Refer to Properties Element for more information).

This attribute is optional. If it is not specified, the control will still be created but it will not be bound to a property. For example you could use a Caption control to display some text you would set on the control using SetWindowText().

Caution: Controls that are bound to properties set the text they display based on the value of their property. Never explicitly set the window text on these controls.

Caution: When creating a control that is not bound to a property, be sure to leave the control's text intact until after the dialog is fully created. If you change the control's text too early, for example while handling the WM_INITDIALOG message in the AK::Wwise::Plugin::GUIWindows::WindowProc() method, the Class attribute set in the resource text will not be available when required, and Wwise will not be able to create the appropriate control.

Other Control Attributes

Apart from the Class and Prop attributes mentioned above, some controls support other attributes that let you tune the controls to the requirements of each property.

Decimals

Format:

Decimals=[Number]

where [Number] is the number of digits to display after the decimal point. This value must be a non-negative integer number. If set to 0, then no decimal digits and no point will be displayed.

This attribute can be used on the following types of controls when they are bound to a numeric property:

Caption
Fader
SuperRange

Warning: This attribute is deprecated. It must be defined in the plugin description XML at /PluginModule/{EffectPlugin or SourcePlugin}/Properties/Property/UserInterface[Decimals]. Refer to UserInterface for more information.

Min

Format:

Min=[Number]

where [Number] is the minimum value that can be entered in this control. This value can be an integer or decimal number, depending on the type of property the control is bound to.

This attribute can be used on the following types of controls when they are bound to a numeric property:

Fader
SuperRange

Warning: This attribute is deprecated. It must be defined in the plugin description XML at /PluginModule/{EffectPlugin or SourcePlugin}/Properties/Property/Restrictions/ValueRestriction/Range/Min. Refer to UserInterface for more information.

Max

Format:

Max=[Number]

where [Number] is the maximum value that can be entered in this control. This value can be an integer or decimal number, depending on the type of property the control is bound to.

This attribute can be used on the following types of controls when they are bound to a numeric property:

Fader
SuperRange

Mid

Format:

Mid=[Number]

where [Number] is the anchor point of the small slider that appears at the bottom of a SuperRange control. This value can be an integer or decimal number, depending on the type of property the control is bound to.

This attribute can be used on the following type of control:

SuperRange

Step

Format:

Step=[Number]

where [Number] is the amount by which the numeric value changes when moving a slider. This value can be an integer or decimal number, depending on the type of property the control is bound to.

This attribute can be used on the following types of controls when they are bound to a numeric property:

Fader
SuperRange

Warning: This attribute is deprecated. It must be defined in the plugin description XML at /PluginModule/{EffectPlugin or SourcePlugin}/Properties/Property/UserInterface[Step]. Refer to UserInterface for more information.

Fine

Format:

Fine=[Number]

where [Number] is the amount by which the numeric value changes when moving a slider while holding the SHIFT key. This value can be an integer or decimal number, depending on the type of property the control is bound to.

This attribute can be used on the following types of controls when they are bound to a numeric property:

Fader
SuperRange

Warning: This attribute is deprecated. It must be defined in the plugin description XML at /PluginModule/{EffectPlugin or SourcePlugin}/Properties/Property/UserInterface[Fine]. Refer to UserInterface for more information.

UIMin

Format:

UIMin=[Number]

where [Number] is the minimum value that can initially be set by using the slider. If this value is greater than the one specified with the Min attribute, then the user can force it to a lower value by entering a value that is smaller than the one specified by this attribute, thus enlarging the range of the control.

This value can be an integer or decimal number, depending on the type of property the control is bound to.

Tip: The purpose of this attribute is to make the initial range of the control's slider more usable in cases where the property range is really big. If one of your properties has a big theoretical range, but in general users will use a more restricted range, use the Min/Max attributes to set the real range, and the UIMin/UIMax attributes to set the initial range of the slider.

This attribute can be used on the following type of controls when they are bound to a numeric property:

SuperRange

Warning: This attribute is deprecated. It must be defined in the plugin description XML at /PluginModule/{EffectPlugin or SourcePlugin}/Properties/Property/UserInterface[UIMin]. Refer to UserInterface for more information.

UIMax

Format:

UIMax=[Number]

where [Number] is the maximum value that can initially be set by using the slider. If this value is lower than the one specified with the Max attribute, then the user can force it to a larger value by entering a value that is larger than the one specified by this attribute, thus enlarging the range of the control.

This value can be an integer or decimal number, depending on the type of property the control is bound to.

This attribute can be used on the following type of controls when they are bound to a numeric property:

SuperRange

Warning: This attribute is deprecated. It must be defined in the plugin description XML at /PluginModule/{EffectPlugin or SourcePlugin}/Properties/Property/UserInterface[UIMax]. Refer to UserInterface for more information.

Options

Format:

Options=[Value1]:[Text1],[Value2]:[Text2],...,[ValueN]:[TextN]

where [ValueX] is a possible value of your numeric property, and [TextX] is the text to be associated with that value in the control. The string contains "value:text" pairs separated by commas, and each pair contains a numeric value and associated text separated by a colon. For example:

Boolean property: "0:Off,1:On"
Numeric property seen as an enumeration: "0:Low Pass,1:High Pass,2:Band Pass"

Note: For bool properties, use 0 for false and 1 for true on the value side of a value/text pair.

This attribute can be used on the following type of control:

Combo

It is used to define the contents of the dropdown list. Only the values that appear in the Options attribute can be set by the Wwise user with a Combo control.

Note: The format of the Options attribute is the same as that of the AK::Wwise::Plugin::PropertyDisplayName::DisplayNamesForPropValues() method. Refer to Property Display Names and Values for more information.

Warning: This attribute is deprecated. The options must be defined in the plugin description XML at /PluginModule/{EffectPlugin or SourcePlugin}/Properties/Property/Restrictions/ValueRestriction/Enumeration/Value[DisplayName] for each of the values in the enumeration. Refer to UserInterface for more information.

SliderType

Format:

SliderType=[integer value]

Refer to UserInterface for the SliderType values

This attribute can be used on the following types of controls when they are bound to a numeric property:

Fader
SuperRange

Warning: This attribute is deprecated. It must be defined in the plugin description XML at /PluginModule/{EffectPlugin or SourcePlugin}/Properties/Property/UserInterface[SliderType]. Refer to UserInterface for more information.

Align

Format:

Align=[Left|Center|Right]

This attribute can be used on the following types of control:

Caption
Edit

It is used to align the text displayed by the control.

FontSize

Format:

FontSize=[0|1]

where the number means:

0 (Default): Standard font
1: Large font

This attribute can be used on the following type of control:

Caption

It is used to specify the font size of the text displayed by the control.

TimeDisplay

Format:

TimeDisplay=[0|1|2]

where the number means:

0 (Default): No special time formatting.
1: Use the MM:SS.mmm (Minutes, seconds, milliseconds) format. Minimum value is -59:59.999, maximum value is 59:59.999.
2: Use the HH:MM:SS.mmm (Hours, minutes, seconds, milliseconds) format. There is no minimum or maximum value in this case.

This attribute can be used on the following type of control when it is bound to a property of type int32 that represents milliseconds:

Caption

Refer to Properties Element for more information on property types.

Example

The following is a sample dialog resource for an effect plug-in, as viewed in the Microsoft Development Environment Dialog Editor:

The following is the dialog resource code, showing the exact caption text used for the various static placeholders in the dialog:

IDD_MYPLUGIN DIALOGEX 0, 0, 217, 187
STYLE DS_SETFONT | DS_FIXEDSYS | WS_CHILD
FONT 8, "MS Shell Dlg", 0, 0, 0x0
BEGIN
    LTEXT           "Class=Caption;Prop=Name",IDC_NAME,8,8,78,13,WS_BORDER
    LTEXT           "Class=Caption;Prop=Duration;Align=1;TimeDisplay=1;FontSize=1",
                    IDC_DURATION,90,8,78,13,WS_BORDER
    LTEXT           "Class=Caption;Prop=OutputLevel;Align=2;Decimals=1",
                    IDC_OUTPUTLEVEL_CAPTION,172,8,36,13,WS_BORDER
    LTEXT           "Class=Caption",IDC_CUSTOM_CAPTION,8,24,200,13,WS_BORDER
    CONTROL         "Enable Feedback",IDC_CHECK_FEEDBACKENABLED,"Button",
                    BS_AUTOCHECKBOX | WS_TABSTOP,8,46,70,10
    LTEXT           "Feedback",IDC_STATIC_FEEDBACK,19,62,32,8
    LTEXT           "Class=SuperRange;Prop=Feedback;Min=0;Mid=0;Max=100;UIMin=0;UIMax=10;Step=0.5;Fine=0.1;Decimals=1",
                    IDC_RANGE_FEEDBACK,58,60,60,13,WS_BORDER
    LTEXT           "Interpolation:",IDC_INTERPOLATION_STATIC,8,86,45,8
    CONTROL         "Linear",IDC_RADIO_LINEAR,"Button",BS_AUTORADIOBUTTON | 
                    WS_GROUP,11,97,35,10
    CONTROL         "Logarithmic",IDC_RADIO_LOG,"Button",BS_AUTORADIOBUTTON,
                    11,108,54,9
    LTEXT           "Loop count",IDC_STATIC,8,132,36,8
    LTEXT           "Class=Spinner;Prop=LoopCount;Min=1;Max=32767",
                    IDC_LOOP_COUNT_SPINNER,53,129,65,13,WS_BORDER
    LTEXT           "Type",IDC_STATIC,8,164,17,8
    LTEXT           "Class=Combo;Prop=WaveType;Options=0:Sine,1:Triangular,2:Square,3:Sawtooth,4:White Noise,5:Pink Noise",
                    IDC_COMBO_WAVETYPE,34,161,84,13,WS_BORDER | WS_TABSTOP
    LTEXT           "Class=Fader;SliderType=1;Prop=OutputLevel;Min=-96.3;Max=0;Decimals=2",
                    IDC_LEVEL_FADER,167,43,37,124,WS_BORDER
    CTEXT           "OutputLevel",IDC_VOLUME_STATIC,161,171,48,8,
                    SS_CENTERIMAGE
END

Warning: Some attributes in this code sample are deprecated: Decimals, Step, Fine, SliderType, Mid, UIMin, UIMax. Refer to UserInterface for more information.

In this example, the Enable Feedback checkbox and the Interpolation radio buttons need to be bound to properties, so the .cpp file for the plug-in defines the following table, which is returned by the plug-in's implementation of AK::Wwise::Plugin::GUIWindows::GetDialog():

constexpr auto szFeedbackEnabled = u8"FeedbackEnabled";
constexpr auto szInterpolation = u8"Interpolation";
 
// Bind non static text UI controls to properties
AK_WWISE_PLUGIN_GUI_WINDOWS_BEGIN_POPULATE_TABLE(MyPopTable)
    AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM(IDC_CHECK_FEEDBACKENABLED, szFeedbackEnabled)
    AK_WWISE_PLUGIN_GUI_WINDOWS_POP_ITEM(IDC_RADIO_LINEAR, szInterpolation)
AK_WWISE_PLUGIN_GUI_WINDOWS_END_POPULATE_TABLE()
 
(...)
 
bool MyPlugin::GetDialog(
    AK::Wwise::Plugin::eDialog in_eDialog,
    UINT& out_uiDialogID,
    PopulateTableItem*& out_pTable) const
{
    if (in_eDialog == SettingsDialog)
    {
        out_uiDialogID = IDD_DELAY_BIG;
        out_pTable = MyPopTable;
        return true;
    }
 
    return false;
}

Finally, here is the dialog as seen by the Wwise user in the Effect Editor:

Testing Your Plug-in's Dialogs

Effect Editor dialog (effect plug-ins only)

To view your dialog in Wwise:

Go to the Views menu, and choose Effect Editor
In the Effect dropdown list, choose your effect plug-in. If your plug-in doesn't appear in the list, refer to the Wwise Source and Effect Plug-in Troubleshooting Guide.

The dialog for your effect plug-in should now appear in the Effect Editor. Refer to the Wwise documentation for more information regarding the usage of effects.

Contents Editor dialog (source plug-ins only)

To view your dialog in Wwise:

Right-click on Actor-Mixer Hierarchy then choose New Child > Sound SFX. This creates a new Sound.
Double-click on the new Sound to inspect it
In the Contents Editor, click on the Add Source button and choose your plug-in in the list. If your plug-in doesn't appear in the list, refer to the Wwise Source and Effect Plug-in Troubleshooting Guide.

The dialog for your source plug-in should now appear in the Contents Editor.

Property Editor dialog (source plug-ins only)

To view your dialog in Wwise:

Right-click on Actor-Mixer Hierarchy then choose New Child > Sound SFX. This creates a new Sound.
Double-click on the new Sound to inspect it.
In the Contents Editor, click on the Add Source button and choose your plug-in in the list. If your plug-in doesn't appear in the list, refer to the Wwise Source and Effect Plug-in Troubleshooting Guide.
Double-click on the small dialog that appears for your plug-in.

The Property Editor should now be displaying your plug-in's dialog.