Table of Contents
Wwise SDK 2019.2.2
As a consequence of some of the new features in 2019.2, you will need to pay attention to a couple of things when migrating to Wwise 2019.2.
Because support for Visual studio 2013 was removed, getting precompiled versions of the sound engine's Windows runtime DLLs requires installing Wwise with the Windows SDK for Visual Studio 2017.
The Authoring is now built with Visual Studio 2019 instead of Visual Studio 2015. The Visual C++ Redistributable is the same for Visual Studio 2015, 2017 and 2019, so plug-in developers may work compile with any of those toolsets. Note that we refer to the Visual Studio 2019 toolset as vc160 based on Visual Studio's version (16). However, the official version of the toolset is vc142 to mark the compatibility with the Visual Studio 2015 toolset (vc140) and 2017 (vc141). Using the same rationale, we use vc150 to refer to vc141.
The Wwise SDK headers now require a valid C++11 to compile properly. See Platform Requirements for a list of supported compilers.
The encoding format for text files produced by the Wwise Authoring application is now UTF-8. The option to choose the encoding format between ANSI and Unicode has been removed. The built-in macro ContentFileFormat provided for pre/post-SoundBank generation has been deprecated and will be removed in the next version. In 2019.2, it will always provide the value "Unicode". The SoundBank generation settings passed to SoundFrame will also ignore AK::SoundFrame::SoundBankGenerationSettings::eContentTxtFileFormat, defaulting to AK::SoundFrame::SoundBankContentTxtFileFormat_UNICODE.
PluginInfo.json metadata file for soundbanks is now formatted differently. In fact, "Plugins" is now an array of maps instead of a map of maps with duplicate keys. Some JSON readers weren't able to properly parse the data in its previous format.
Reflecting the changes described in Memory Categories Replace and Expand Memory Pools, several related interfaces have been modified.
- Added debugging function AK::MemoryMgr::dRealloc as an instrumented counterpart to AK::MemoryMgr::Realloc.
- Replaced profiling functions AK::MemoryMgr::GetPoolStats and AK::MemoryMgr::GetPoolMemoryUsed with AK::MemoryMgr::GetCategoryStats and AK::MemoryMgr::GetGlobalStats.
- Modified return value of AK::MemoryMgr::Free and AK::MemoryMgr::Falign.
- Removed AkMemPoolId argument from profiling functions AK::MemoryMgr::StartProfileThreadUsage, and AK::MemoryMgr::StopProfileThreadUsage (allocations in all memory categories are collected for the specified thread).
- Removed pool-related functions AK::MemoryMgr::CreatePool, AK::MemoryMgr::DestroyPool, AK::MemoryMgr::GetNumPools, AK::MemoryMgr::GetMaxPools, AK::MemoryMgr::CheckPoolId, AK::MemoryMgr::GetPoolAttributes, AK::MemoryMgr::SetPoolName, and AK::MemoryMgr::GetPoolName.
- Removed block allocation functions AK::MemoryMgr::GetBlock, AK::MemoryMgr::ReleaseBlock, and AK::MemoryMgr::GetBlockSize.
- Removed debugging functions AK::MemoryMgr::CheckForOverwrite and AK::MemoryMgr::DumpToFile.
On other interfaces, due to the removal of pools:
- Modified AK::SoundEngine::LoadBank and AK::SoundEngine::UnloadBank: renamed "from memory" overloads to AK::SoundEngine::LoadBankMemoryView and AK::SoundEngine::LoadBankMemoryCopy for clarity.
- Removed AkCommSettings::uPoolSize.
- Removed AkInitSettings::uDefaultPoolSize, AkInitSettings::fDefaultPoolRatioThreshold, AkInitSettings::uPrepareEventMemoryPoolID, and AkInitSettings::uMonitorPoolSize.
- Removed AkPlatformInitSettings::fLEngineDefaultPoolRatioThreshold and AkPlatformInitSettings::uLEngineDefaultPoolSize.
- Removed AkStreamMgrSettings::uMemorySize.
- Removed AK::StreamMgr::GetPoolID.
If you are using a custom implementation of AK::IAkStdStream, you must implement a new function specified on the interface,
AK::IAkStdStream::WaitForPendingOperation(). This must block execution and only return once a pending I/O, if any, has completed, and return the new status of the stream.
Wwise 2019.2 includes exciting changes to Spatial Audio: this release streamlines the workflow, simplifies the integration and use of Spatial Audio features, and dramatically improves performance and scalability. Unfortunately these changes may be disruptive to existing projects and some features from 2019.1 do not correlate directly in 2019.2 and require a manual migration. This guide serves as a resource to aid users who would like to make the transition, and to provide context as to why we made these changes, and how they improve the overall experience.
A core pillar of Wwise is to empower sound designers and to reduce reliance on programmers, and so it is only natural to allow designers to configure Spatial Audio settings directly inside the Wwise authoring tool instead of in the game engine. The following properties have been added to both sound and bus objects in Wwise:
Early Reflections Aux Bus. Set the Auxiliary Bus that this sound should send to for early reflections processing. The bus must have the Wwise Reflect plug-in inserted as an effect in order to render the early reflections. Setting a valid early reflections bus will enable reflection processing for this sound in the Spatial Audio runtime. This field should be left blank for sound that should not generate early reflections.
- Note: This field may be left unassigned, and instead, the early reflections bus may be set on a per-game object basis via the new API AK::SpatialAudio::SetEarlyReflectionsAuxSend().
Early Reflections Send Volume. Set the send volume for the early reflections bus specified by Early Reflections Aux Bus.
- Note: The early reflections send volume may be set on a per-game object basis via the new API AK::SpatialAudio::SetEarlyReflectionsVolume(). The value passed to this function is combined with the volume set per-sound in the authoring tool.
Enable Diffraction. Enable diffraction processing for this sound. Checking this box will:
- Compute the diffraction paths between the sound emitter and the Spatial Audio listener - including paths passing through portals and across geometric edges.
- Set the obstruction value according to the diffraction coefficient.
- Set the diffraction built-in game parameter according to the diffraction coefficient.
- Use multi-positioning to pan and attenuate the sound, according to the calculated virtual sound positions. An important point here is that Spatial Audio configuration settings are now specified per-sound. Previously, it was not possible to have different settings for two sounds playing on the same game object. The only work-around was to create additional game objects with new emitter settings.
Now that we are able to specify settings directly in the project, the Spatial Audio runtime is able to know when a sound is playing on an object that defines Spatial Audio properties and therefore requires processing. With that, you can no longer register a game object as a “Spatial Audio Emitter”, and we have removed AkEmitterSettings as well. In an effort to make Spatial Audio more approachable and user friendly, there are fewer settings in the authoring tool now than there were in AkEmitterSettings. The following is a guide to migrating each field from AkEmitterSettings and where to set the new values in the Wwise project.
- name. No longer applicable, instead use the debug name when registering a game object to the sound engine.
- reflectAuxBusID. Now specified in the Wwise authoring tool on a per-sound basis. The early reflections bus is now defined in the general settings tab for both sounds and busses.
- reflectionMaxPathLength. No longer required. Spatial Audio is now able to access the attenuation curves specified by the sounds that have Spatial Audio settings, and the - maximum distance in the curve is used for reflection distance heuristics.
- reflectionsAuxBusGain. Now specified in the Wwise authoring tool on a per-sound basis. The early reflections send volume is now defined in the general settings tab for both sounds and busses.
- reflectionsOrder. The reflections order is now a global setting that is passed to the Spatial Audio init settings and no longer available on a per-game object basis. The new reflections engine in Wwise 2019.2 is not only much more efficient at processing higher-order reflections, but it does so in a way that is much less sensitive to the number of emitters in the scene. The reflections for all emitters are effectively calculated all at once, so specifying the reflection order per-emitter no longer makes sense.
- reflectorFilterMask. This feature has been removed from Wwise 2019.2 due to limited adoption and detrimental performance characteristics.
- roomReverbAuxBusGain. To change the send level to room aux busses, modify the game-defined send volume in the general settings tab in the authoring tool.
- diffractionMaxEdges. To enable diffraction on a specific sound, set the Enable Diffraction check box in the positioning tab of the authoring tool. The max edges parameter is now a global setting in Wwise 2019.2.
- diffractionMaxPaths. To enable diffraction on a specific sound, set the Enable Diffraction check box in the positioning tab of the authoring tool. The max paths parameter is now a compile-time constant in Wwise 2019.2.
- diffractionMaxPathLength. No longer required. Spatial Audio is now able to access the attenuation curves specified by the sounds that have Spatial Audio settings, and the maximum distance in the curve is used for the diffraction max path length.
- useImageSources. Effectively always true. Since it is possible to specify image sources per-game object this additional setting is not necessary and has been removed.
In Wwise 2019.1 and before, there were a number of APIs in Spatial Audio that were effectively duplicates of those found in the sound engine, but which applied specifically to game objects that were registered as a Spatial Audio emitter. Not only was it confusing, but we had no way of ensuring that the user called the correct API. In 2019.2, since it is no longer necessary to register an emitter, the following APIs have been removed.
- AK::SpatialAudio::SetPosition Replace with AK::SoundEngine::SetPosition
- AK::SpatialAudio::SetEmitterAuxSendValues Replace with AK::SoundEngine::SetGameObjectAuxSendValues
- AK::SpatialAudio::SetEmitterObstructionAndOcclusion Replace with AK::SoundEngine::SetObjectObstructionAndOcclusion
In most circumstances, users should remove any attenuation that was applied to a room bus in the Wwise Authoring Tool. It is no longer necessary to have attenuation on rooms objects, because Spatial Audio in Wwise 2019.2 now applies the distance of the entire path between the emitter and the listener, to the attenuation of the sound.
A common issue that users had with portals before Wwise 2019.2, was that the relative mix of two sounds with different attenuations was not consistent in the reverb that was transmitted through portals. For example, suppose both footsteps - a short attenuation, and gunfire - a long attenuation, play through the same portal. The sounds were mixed together at the location of the portal then re-spatialized at that same position. The sounds’ attenuations were evaluated using the distance between the emitter and the portal, which was only a portion of the total distance between the emitter and the listener - Spatial Audio relied on the portal’s attenuation to further attenuate the reverb. The result was that as the listener got further away from the portal, the relative volume of the two sounds remained the same instead of the footsteps decaying faster than the gunfire as the sound’s original attenuation curve dictated. Note that this was only an issue with the wet path - the direct path worked as expected.
In Spatial Audio for Wwise 2019.2, the problem is solved by effectively putting the portal’s “pickup” location at the same position as the listener. This way, the entire distance of the path between the sound source and the listener is applied to the attenuation curve of the sounds before mixing the sound into the room’s 3D bus. Attenuation applied to the portal (ie room bus) is no longer necessary, but may still be desired. An attenuation post-mix would serve to further reduce the volume of the reverb or apply additional filtering to the reverb that passes through the portal.
WwiseCLI has been deprecated in favor of WwiseConsole. WwiseCLI is still provided and works like before. Anything that you could do in WwiseCLI still can be done in WwiseConsole, it's just a matter of changing the syntax. It is recommended that you migrate to WwiseConsole because, going forward, new features will only be added to the WwiseConsole.
WwiseConsole is self-documented. Running it without parameters lists the supported operations. You can then display the Help for a specific operation. The documentation for WwiseConsole can be also found on the SDK documentation, and is available online and offline.
For example, to display the Help for generating SoundBanks:
WwiseConsole generate-soundbank --help
The standard syntax is:
WwiseConsole operation project --option1 valueOfOption1 --option2 valueOfOption2
Here are a few examples of the WwiseCLI syntax compared to the new WwiseConsole syntax.
Generate SoundBanks for platforms Windows and Linux only.
WwiseCLI C:\MyProject\MyProject.wproj -GenerateSoundBanks -Platform Windows -Platform Linux
WwiseConsole generate-soundbank C:\MyProject\MyProject.wproj --platform Windows Linux
Run a WAAPI server with verbose logging.
WwiseCLI C:\MyProject\MyProject.wproj -Waapi -Verbose
WwiseConsole waapi-server C:\MyProject\MyProject.wproj --verbose
Create new project which supports platforms Windows and Linux.
WwiseCLI C:\MyNewProject\MyNewProject -CreateNewProject -Platform Windows -Platform Linux
WwiseConsole create-new-project C:\MyNewProject\MyNewProject.wproj --platform Windows Linux