Wwise SDK 2023.1.8

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.

Property Set

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 m_propertySet variable is the same as the lifetime of the plug-in instance. Do not store this instance across plug-in instances. You can also request this service both in your backend and your frontend class.

Property Value Notification

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::Notifications::PropertySet::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.

Custom Data

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 (AK::Wwise::Plugin::Host::NotifyInternalDataChanged())

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.

Providing Custom 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.

Initializing and Persisting Custom Data

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::CustomData:

AK::Wwise::Plugin::CustomData::InitFromWorkunit() receives a AK::Wwise::Plugin::XmlReader used to unmarshall the custom data
AK::Wwise::Plugin::CustomData::Save() receives a AK::Wwise::Plugin::XmlWriter used 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.

Custom Data Notification

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 AK::Wwise::Plugin::PropertySet are used.

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 AK::IAkPluginParam::ALL_PLUGIN_DATA_ID in AK::IAkPluginParam::SetParam and AK::Wwise::Plugin::CustomData::GetPluginData. It will be used at least once, when the plug-in is played the first time.

Property Display Names and Values

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.

The 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 AK::Wwise::Plugin::PropertyDisplayName::DisplayNamesForPropValues() is the same as that of the "Options" attribute you can specify on Combo Box controls in your dialog (Refer to Wwise Plug-in Dialog Reference for more information). The string contains value/text pairs separated by commas, and each pair contains the numeric value and the 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"
Numeric property with some values that have a special meaning: "-100:Left,0:Center,100:Right"

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

In the sample code below, the name is retrieved from the plug-in's resources:

AK.Wwise::Plugin::V1::DataWriter

Interface used to write data during sound bank generation.

Definition: HostDataWriter.h:245

AK.Wwise::Plugin::V1::Notifications::PropertySet_::NotifyPropertyChanged

virtual void NotifyPropertyChanged(const GUID &in_guidPlatform, const char *in_pszPropertyName)

This function is called by Wwise when a plug-in property changes.

Definition: HostPropertySet.h:2414

AK.Wwise::Plugin::V1::DataWriter::WriteInt32

bool WriteInt32(int32_t in_value)

Writes a 32-bit signed integer value.