Table of Contents
Wwise SDK 2021.1.1
This page documents how the model of a plug-in can be accessed and modified. The model is composed of two elements:
- A standard model called a Property Set that is completely described by the XML definition of the plug-in that can be accessed with the component provided by
AK::Wwise::Plugin::RequestPropertySet. This is limited to certain types of data, but offers automatic handling for saving, loading, undoing and redoing changes as well as binding as the model for GUI controls.
- A custom model called the Custom Data that can optionally be added to your plug-in to represent more complex data, with the limitation that operations that are automatic for the Property Set need to be implemented explicitly. This limitation also extends to GUI controls that need to be updated manually.
A Property Set instance is provided to the plug-in as a member variable
m_propertySet when deriving the
AK::Wwise::Plugin::RequestPropertySet request interface. In functions such as
AK::Wwise::Plugin::AudioPlugin::GetBankParameters, you can access the values for properties defined in the XML to write the values in the bank (for more information, refer to Generating SoundBanks). Accessors for the most common types are provided explicitly, but using an accessor type that does not match the type specified in the XML is undefined behavior.
For your convenience,
AK::Wwise::Plugin::RequestPropertySet is automatically requested when the plug-in class is derived from
AK::Wwise::Plugin::AudioPlugin. In other cases, such as creating a frontend, it must be requested.
Note: The lifetime of the
Wwise users can change property values either directly through a control in the dialog, or by using the undo/redo commands. When a user changes a property value,
AK::Wwise::Plugin::PropertySetNotifications::NotifyPropertyChanged() is called on your plug-in. This way, it is possible for adapting the value of other properties based on this change, e.g., custom data and property range dependencies. Also, if your dialog is being displayed at that time, you can specify actions to be performed in the dialog such as enabling or disabling controls.
|Note: The XML allows describing dependencies based on rules. See Plug-in XML Dependencies for more details.|
If your plug-in uses complex data such as curves, graphs, and so on, the property set will likely be insufficient to represent this type of data. However, a custom data mechanism is provided to handle this type of complex data. The requirements for custom data are the following:
- Implement a loading and saving mechanism as XML data, e.g., path to a binary file, base64 content, etc.
- Notify Wwise when this data changes for it to be reloaded in the Sound engine
- Implement a serializing function for writing into Sound Banks as parameters for the Sound Engine plug-in.
These can be accomplished by implementing specific interfaces:
AK::Wwise::Plugin::CustomData: Provides the necessary interface for loading and saving your custom data in the Wwise project
AK::Wwise::Plugin::RequestHost: Provides functions to notify the Authoring (
|Note: The plug-in has full control over its custom data, hence you should not define anything in the plug-in's XML for this type of data.|
The plug-in data can be provided by implementing
AK::Wwise::Plugin::CustomData::GetPluginData. Custom parameter IDs need to be defined and must correspond to the ones used for reading this data in the sound engine part of the plug-in when
AK::IAkPluginParam::SetParam is called.
The custom data is owned by the plug-in instance and must be loaded and saved to the project for persistence. It is strongly suggested, when possible, to use plain XML to represent as much of the complex data as possible to ease the merging process when projects are under source control. It is still possible to save more complex data by marshalling it to base64 or by saving a file for which the relative path to the project root is persisted as an XML element.
The functions to implement for persistence are provided by
AK::Wwise::Plugin::XmlReaderused to unmarshall the custom data
AK::Wwise::Plugin::XmlWriterused to marshall the custom data
If a plug-in instance's custom data is successfully saved in a project's Work Unit,
InitFromWorkunit will be called during project loading, soon after its instantiation. There are two other ways custom data plug-ins can be initialized by Authoring, depending on the circumstances. These are mutually exclusive; only one will be called at instantiation.
AK::Wwise::Plugin::CustomData::InitToDefault()when Authoring initializes a new instance, or no saved data is available
AK::Wwise::Plugin::CustomData::InitFromInstance()when the user duplicates a plug-in instance, when the plug-in instance is deleted, or an redo is performed.
|Note: The plug-in code is responsible for handling the versioning of its data, so it is strongly suggested to add versioning information in your custom data. Make sure your plug-in knows what versions of the data it can or cannot load to avoid crashes and data corruption.|
To inform Wwise that your particular data has changed so that this data can be saved or transferred to the sound engine, use the
AK::Wwise::Plugin::Host::NotifyInternalDataChanged() function. You can specify a ParamID to limit the notification to a subset of your data. We will refer to this internal data unit as a "complex property". You can also use
AK::IAkPluginParam::ALL_PLUGIN_DATA_ID to specify that all your data has changed.
Note: Do not use NotifyInternalDataChanged for properties declared in the XML and handled by the Property Set. The notification is done automatically when setter functions from
When the user modifies custom properties and the plug-in calls NotifyInternalDataChanged, Wwise will call its
AK::Wwise::Plugin::CustomData::GetPluginData method to obtain the data block that will be transferred to the sound engine part of the plug-in. The sound engine plug-in will receive the block through
AK::IAkPluginParam::SetParam with the ParamID specified in NotifyInternalDataChanged.
Note: If you use custom properties, you must handle
A "user-friendly" name can be associated to each property by specifying the "DisplayName" attribute in the Property tag (see Properties Element for more details). However, if you have dynamic properties that take a different meaning depending on context, you can implement the
AK::Wwise::Plugin::PropertyDisplayNames interface and specify display names for properties and named values.
Display names are displayed in several places in the user interface. These include the RTPC Manager, the Multi Editor, the edit menu for the undo/redo commands after a property change, and so on.
in_pszPropertyName parameter in
AK::Wwise::Plugin::PropertyDisplayName::DisplayNameForProp corresponds to the property name specified in the plug-in's XML definition file (Wwise Plug-in XML Description Files). Here is a sample implementation of this method:
If a certain property has non-numeric values, such as a boolean property that means On/Off or Yes/No, or an enumeration for a curve type, or if some values have a special meaning, you can specify custom text to be displayed for some or all of the property's possible values in your implementation of the
AK::Wwise::Plugin::PropertyDisplayName::DisplayNamesForPropValues() method. The custom text will be used in the RTPC graph view for those values on the Y axis.
Note: The format of the string that is built by
In the sample code below, the name is retrieved from the plug-in's resources: