|
Wwise SDK 2023.1.9
|
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
- Dialog Dimensions
- Letting Wwise Retrieve your Dialog Resources
- How to Add Regular Controls to Your Dialogs
- How to Add Wwise Property Controls to Your Dialogs
- Example
- Testing Your Plug-in's Dialogs
- Troubleshooting
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:
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:
| 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:
"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:
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:
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:
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:
CaptionFaderSuperRange
 | 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:
FaderSuperRange
| 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:
FaderSuperRange
| 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:
FaderSuperRange
| 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:
FaderSuperRange
| 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:
- 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:
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:
FaderSuperRange
| 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:
CaptionEdit
It is used to align the text displayed by the control.
FontSize
Format:
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:
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:
| 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:
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.
Troubleshooting
Help is available in Wwise Source and Effect Plug-in Troubleshooting Guide if you run into any problem.
Was this page helpful?
Need Support?
Questions? Problems? Need more info? Contact us, and we can help!
Visit our Support pageTell us about your project. We're here to help.
Register your project and we'll help you get started with no strings attached!
Get started with Wwise