|
Wwise SDK 2023.1.8
|
Audio Device Plug-in Interface Implementation
Audio device plug-ins are the endpoints of the audio processing chain. Natural Audio devices are the OS sound systems, but there can be more possible outputs if additional hardware or drivers allow it. The role of the sink plug-in is to take the final mixed audio samples and transfer them to the device, in the format the device understands.
Sound Engine Component
On the sound engine side, writing an audio device plug-in consists of implementing the AK::IAkSinkPlugin interface. Only the functions specific to this interface are covered there. Refer to Creating Sound Engine Plug-ins for information about interface components shared with other plug-in types ( AK::IAkPlugin interface). Also refer to the provided AkSink plug-in for sample code (Samples).
An audio device is always specified through the plug-in it is using (Audio Device ShareSet) and a specific device ID. This device ID has no meaning for the Wwise sound engine, it is for the sole purpose of the plug-in implementor to discriminate devices where many of the same type exists. It is passed by the game through the AkOutputSettings::idDevice parameter used in AK::SoundEngine::Init and AK::SoundEngine::AddOutput. For example, an audio device plug-in which would access Windows' audio devices could probably see many Windows' devices on a particular computer.
If your device doesn't need to discriminate between multiple devices, you can ignore that parameter. However, if you need to implement this, be aware that you MUST also support the "default device" concept, which is selected when the idDevice parameter is 0. Whether the first available device or a specific device is selected when receiving 0 is up to the plug-in programmer.
Sink plug-ins can register an extra static function to support enumeration of available audio devices. The purpose of this function is to fill the possible devices a user can select in the authoring tool as well as to allow device enumeration at run-time through calls to AK::SoundEngine::GetDeviceList. This function is optional. If not implemented, it is expected that the plug-in will initialize to a "default" output when required. If necessary, the additional static function should be provided after the plug-in parameter creation function. For more information on other static functions to provide for plug-in creation, see Creating Sound Engine Plug-ins.
Below is an example implementation of device enumeration for a fictitious sink plug-in, MyPlugin. Note that functions and classes in the MyPlugin namespace are placeholders for actual plug-in implementations.
The plug-in device enumeration will be called by Wwise with the maximum number of devices to fill and a pre-allocated array of AkDeviceDescription. The maximum length of the device name is AK_MAX_PATH (256 characters). You must modify the count (io_maxNumDevices) to reflect the number of device descriptions correctly filled. If the provided device description array pointer is null, the count should still be modified to reflect the number of device descriptions that would be filled, so that the caller can allocate an appropriate amount of memory for out_deviceDescriptions.
 | Note: This sound engine implementation replaces the previous authoring only plug-in equivalent AkGetSinkPluginDevices so that device enumeration can be implemented for all supported platforms and can be called at run-time through AK::SoundEngine::GetDeviceList. |
| Note: This function will be compiled on all platforms. To handle platform specific device enumeration, one should use the appropriate macros (e.g. AK_WIN, AK_LINUX, etc.) and return AK_NotImplemented on platforms for which no implementation is defined. |
Authoring DLL for an Audio Device Plug-in
As with any other plug-in, sink plug-ins need an authoring DLL counterpart. Please refer to Authoring Plug-in Library Format for the basic setup of the Wwise authoring component common to all plug-ins.
| Note: AkGetSinkPluginDevices is now deprecated, see the Sound Engine Component section above to implement device enumeration. |
Testing your Audio Device Plug-in
After implementing the Wwise part of the plug-in (Writing the Authoring Part of an Audio Plug-in) and the sound engine part, you can test your plug-in following these steps:
- In your Wwise Project, create an Audio Device ShareSet using your new plug-in. Give the ShareSet a unique name.
- Generate you banks.
- Make sure your plug-in was registered in your game code. See Sound Engine Plug-ins Overview.
- Specify your audio device ID to be used in the initialization parameters of the sound engine. The ID in the AkOutputSettings is the hash of the name of the Audio Device ShareSet in the project, as given by
AK::SoundEngine::GetIDFromString.
For example:
Alternatively, you can use your Audio Device plug-in with AK::SoundEngine::AddOutput.
You can test device enumeration for your plug-in with AK::SoungEngine::GetDeviceList.
For more information, refer to the following sections:
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