Wwise SDK 2022.1.18
|
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:
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.
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. |
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:
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. |
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. |
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.
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. |
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:
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. |
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:
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. |
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. |
Let's look at these attributes in detail:
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:
where [Classname] can be one of:
Caption:
Read-only text display Combo:
Dropdown list Edit:
editable text Fader:
Volume fader Spinner:
Integer numeric editor with spinner control SuperRange:
Numeric editor with horizontal slider 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. |
The Prop
attribute lets you bind a control to one of your plug-in's properties. This attribute has the following format:
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. |
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:
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:
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:
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
Warning: This attribute is deprecated. It must be defined in the plugin description XML at /PluginModule/{EffectPlugin or SourcePlugin}/Properties/Property/Restrictions/ValueRestriction/Range/Max. Refer to UserInterface for more information. |
Mid
Format:
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
Warning: This attribute is deprecated. It must be defined in the plugin description XML at /PluginModule/{EffectPlugin or SourcePlugin}/Properties/Property/UserInterface[Mid]. Refer to UserInterface for more information. |
Step
Format:
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:
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:
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/ to set the real range, and the UIMin/ 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:
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.
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/ to set the real range, and the UIMin/ 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[UIMax]. Refer to UserInterface for more information. |
Options
Format:
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:
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:
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:
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:
where the number means:
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:
where the number means:
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.
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:
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()
:
Finally, here is the dialog as seen by the Wwise user in the Effect Editor:
To view your dialog in Wwise:
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.
To view your dialog in Wwise:
The dialog for your source plug-in should now appear in the Contents Editor.
To view your dialog in Wwise:
The Property Editor should now be displaying your plug-in's dialog.
Help is available in Wwise Source and Effect Plug-in Troubleshooting Guide if you run into any problem.
Questions? Problems? Need more info? Contact us, and we can help!
Visit our Support pageRegister your project and we'll help you get started with no strings attached!
Get started with Wwise