Wwise SDK 2023.1.9

A frontend class offers platform or toolkit-specific methods that allow to implement a graphical user interface. You need to create a class derived from a frontend class such as AK::Wwise::Plugin::GUIWindows.

#include <AK/Wwise/Plugin.h>
 
class FrontendSourcePlugin
:   public AK::Wwise::Plugin::GUIWindows
{
public:
    FrontendSourcePlugin();
 
    // AK::Wwise::Plugin::GUIWindows
    HINSTANCE GetResourceHandle() const override;
 
    bool GetDialog(
        AK::Wwise::Plugin::eDialog in_eDialog,
        UINT& out_uiDialogID,
        AK::Wwise::Plugin::PopulateTableItem*& out_pTable
    ) const override;
 
    bool WindowProc(
        AK::Wwise::Plugin::eDialog in_eDialog,
        HWND in_hWnd,
        uint32_t in_message,
        WPARAM in_wParam,
        LPARAM in_lParam,
        LRESULT& out_lResult
    ) override;
 
    bool Help(HWND in_hWnd, eDialog in_eDialog) const override;
};
 
AK_ADD_PLUGIN_CLASS_TO_CONTAINER(
    MyPlugin,               // Add to container "MyPlugin"
    FrontendSourcePlugin,   // Class to add to the container
    SoundEngineSourcePlugin // Sound engine plug-in to which this plug-in corresponds
);

The frontend is responsible for:

Providing a way for users to change the values of your plug-in's properties.
Displaying a GUI for the Contents Editor (sources only).
Displaying any monitoring data gathered from profiling during playback of your plug-in.
Determining what happens when a Wwise user accesses help for your plug-in.

See Implementing a Windows Frontend for information on implementing a Windows frontend.

See Plug-in First Time Creation Notice for information on adding a notice for your plug-in to be displayed at first instantiation.

Note: The only Wwise Authoring platform that currently supports a graphical user interface (GUI) is Windows, which is also used on macOS by running through Crossover, a bridge layer based on the open source project Wine.

Monitoring in Authoring

Monitoring is the process of observing the state of an audio plug-in during its playback.

When the Authoring application is profiling a game or playing sounds locally, Authoring plug-in instances can choose to receive monitoring data of all the playing instances that are using its parameters. It can use the monitoring data to control GUI elements such as VU meters and static text. For example, a plug-in could provide information on intermediate signal processing state for metering, or performance metrics such as the memory usage to be displayed to the user.

This section covers the Authoring side of monitoring. Refer to the Monitoring in the Sound Engine for details on the serialization and sending process.

Receiving Monitoring Data

Monitoring data is received by the Authoring part of the plug-in. Here are the steps of this process:

Receiving: The Authoring part of the plug-in receives monitoring data through the method AK::Wwise::Plugin::Notifications::Monitor::NotifyMonitorData(), which must be implemented from the AK::Wwise::Plugin::Notifications::Monitor interface component. The monitoring data received is an array of AK::Wwise::Plugin::MonitorData. Each MonitorData element corresponds to a playing instance that was posted on a certain game object. This array may be filtered by the Authoring application to provide only context-relevant instances to the plug-in frontend.
Deserialization: The implementation of NotifyMonitorData should deserialize the monitoring data to extract the information needed for each MonitorData instance. This information can then be used to update GUI controls that inform the user on the plug-in state.

Note: AK::Wwise::Plugin::Notifications::Monitor::NotifyMonitorData() is called on the main UI thread of the Authoring, therefore long running jobs should be avoided so as to not cause the application to become unresponsive.

The following code example shows how to implement NotifyMonitorData and deserialize the monitoring data:

class FrontendSourcePlugin
:   public AK::Wwise::Plugin::GUIWindows
,   public AK::Wwise::Plugin::Notifications::Monitor
{ /*...*/ };
 
void FrontendSourcePlugin::NotifyMonitorData(
    AkTimeMs in_iTimeStamp,
    const AK::Wwise::Plugin::MonitorData* in_pMonitorDataArray,
    unsigned int in_uMonitorDataArraySize,
    bool in_bIsRealtime) override
{
    // == Deserialize the monitoring data
    // Using the first instance as reference for the number of channels
    AkUInt32 uNumChannels = *((AkUInt32 *) in_pMonitorDataArray[0].pData);
 
    for (unsigned int i = 0; i < in_uMonitorDataArraySize; ++i)
    {
        AkUInt32 * pData = (AkUInt32 *) in_pMonitorDataArray[i].pData;
        AkUInt32 uInstanceNumChannels = *pData++;
        if (uInstanceNumChannels != uNumChannels)
            continue; // Different from reference, ignore
 
        AkReal32 fChannelPeaks[MAX_NUM_CHANNELS];
        memcpy( fChannelPeaks, pData, uNumChannels * sizeof( AkReal32 ) );
 
        // Do something with the peak, e.g., update meters
        ...
    }
}

It can be challenging to support multiple MonitorData instances when providing metering content or per-instance statistics. To simplify requirements, you may ignore some elements from the MonitoringData array depending on edge cases, such as when some elements have a different speaker configuration. You may also choose to aggregate the monitoring data, such as by taking the maximum value out of the levels reported in each element when metering.

Object processors are a derivative of audio plug-ins that process buffers belonging to distinct objects, and so provide monitoring data for multiple objects in a single MonitorData. Because the monitoring data is opaque to Wwise, MonitorData cannot provide information on objects: it is up to the implementer of the serialization strategy to include this information in the monitoring data, if it is relevant. Moreover, this means that unlike in the Sound Engine part of the plug-in, the Authoring plug-in type is not different for an object processor and the format of the monitoring data is a contract between the Sound Engine and the Authoring part of the plug-in. For more information on object processors, refer to Creating Sound Engine Object Processor Plug-ins.

Reacting to Changes in Wwise

Some notification handler methods are provided by various services to allow your plug-in to react to context changes in Wwise. For example, you can be notified of changes to properties managed by the property set (see Property Value Notification for more details). This section describes some of those notifications that are most relevant for the frontend part of your plug-in.

The Wwise User Changes the Current Platform

When Wwise users change the current platform using a list or a keyboard shortcut, instances of your plug-in can be notified if they request the host service by deriving AK::Wwise::Plugin::RequestHost. Your plug-in can then implement the AK::Wwise::Plugin::NotificationsHost::NotifyCurrentPlatformChanged() method. This allows your dialog to adapt itself to the new current platform if it is being displayed.

AkTimeMs

AkInt32 AkTimeMs

Time in ms.

Definition: AkTypes.h:56

AK.Wwise::Plugin::eDialog

eDialog

Definition: PluginDef.h:137

Plugin.h

Wwise Authoring Plug-ins - Main include file.

AK.Wwise::Plugin::V1::GUIWindows::GetResourceHandle

virtual HINSTANCE GetResourceHandle() const

Retrieves the plug-in's HINSTANCE used for loading resources.