Table of Contents
Wwise SDK 2019.2.2
Wwise game-defined auxiliary sends are a way to easily apply one or more environmental effects on sounds based on their location in the game. The option "Use game-defined auxiliary sends" must have been set in the object properties or in the object it inherits its properties from.
Using Wwise, a sound designer can define multiple environments to be used in a game. For example, those environments could be:
- a hangar
- a tunnel
- or any others useful to the game
Each environment could represent an environmental reverb Effect with a different set of parameters. Each environment would be then represented by an Auxiliary Bus in the Wwise project.
Initially, each game object is supposed to be in a location that is not defined by any environment. When a sound is not in an environment (not routed to any Auxiliary Bus), it plays normally. In other words, without any environmental Effects.
All sounds that are in the same Auxiliary Bus are mixed together before having the Effects applied. A different volume can be set for every game object.
Note: The values used in the API range from 0 to 1, representing a percentage of the full volume. 0 stands for 0% and 1 stands for 100%. When volumes are applied in more than one place, the resulting values are multiplied. For example, if the
Handling the game-defined auxiliary sends is done using the following functions:
Dynamic Auxiliary Bus routing: Dynamically Sending To Auxiliary Busses.
Every instance of a bus in the Wwise sound engine is associated with a game object. When we create an aux send, we create a listener-emitter association in the sound engine, with a specific aux bus as the target. The positions of the emitter and listener game objects are used in the source and target audio node to spatialize the sound (if the sound is set to 3D in the authoring tool). When defining an aux send, it is often desirable to use the same listener for the target aux bus as has already been assigned for the direct output of the source audio node – that is the listener(s) that have been assigned via
SetDefaultListeners(). To facilitate this behaviour, and to avoid having to remember which game object has already been associated to which listener, one may simply pass
AK_INVALID_GAME_OBJECT as the
Note: It is important to fill out the
The SDK provides you with two ways of accessing items inside a SoundBank, using strings or using IDs. Using strings makes code more readable and is suitable during development, or when working in an environment that normally uses strings. Using IDs avoids Wwise from having to hash the names at runtime.
To work with IDs the banks must be generated with the "Generate header file" option in the Generate SoundBanks dialog box in Wwise. The definition file, named Wwise_IDs.h, contains all the required IDs. It is updated at each bank generation.
For more information on generating banks in Wwise, refer to the Wwise Help.
|Caution: When working with IDs, it is important to keep the .h file up-to-date when new banks are generated. Otherwise ID mismatches and/or compilation errors may occur.|
Here is an example of a very simple header file generated by Wwise:
Code snippet must be fixed.
Header files generated by Wwise usually contain much more information than the one above. This is because entries are added for every event, state, switch, busses, and so on.
It is also possible to use a hybrid of the two methods. For example, you can work with strings but use IDs to access the environments.
The following method performs run-time conversion of unicode strings into IDs. This allows you to make a one time look-up in the string table per environment, and then use the ID.
Dynamically driving the aux bus routing is done using the
AK::SoundEngine::SetGameObjectAuxSendValues() function. The first parameter of the function is the game object ID to which the game-defined aux bus routing will be applied. The second and third parameters represent an array of structure of type
AkAuxSendValue and the number of Auxiliary Busses to send to. If the sound does not have the option "Use game-defined auxiliary sends" enabled, then no environments will be applied to this game object. For every Auxiliary Bus to which a game object is sent, a control value must be set representing the percentage application of the environment. The control value is a value ranging from 0.0f to 1.0f, where 0 represents no send and 1 represents 100% send.
|Note: When you change the auxiliary sends of an object, the sound engine interpolates environments to avoid glitches. Thus, in a given frame, an object may be connected to more Auxiliary Busses that you would expect.|
Setting Hangar Aux bus to 100%.
Example: Setting the Environments of a Main Character Using IDs Setting Hangar to 75% and Tunnel to 25%.
Using the control values, it is possible to make sounds go smoothly from one environment to another.
|Tip: The total of the aux sends values do not have to equal 100%. For instance, to set only a light environmental effect on a game object, you could set the game object to be 25% in one environment.|
|Caution: The Wwise sound engine does not limit the number of Auxiliary Busses to be sent to at one time. That means that it is possible to request that many environmental FX be processed at the same time. Some environmental FX can take up a lot of the CPU and having too many running at the same time can cause a performance drop. Therefore, it is your responsibility to prevent situations in which, for example, 64 sounds play at the same time, each with their own environment.|
In the following example, we have registered a game object that is used to simulate an acoustic portal in 3D space. The game object represents an environment that neither the sound, nor the main listener are inside. Setting the
listenerID field to a valid game object ID creates an emitter-listener association in a similar manner to
SetListeners(), however it applies to an auxiliary output from an audio node, whereas
SetListeners() applies to the direct output. The audio node that sends audio is controlled by setting the "Use game-defined auxiliary sends" flag in the authoring tool. To visualize how setting
listenerID creates an instance of the bus specified by
auxBusID on the game object
listenerID, see the voice graph tab in the advanced profiler of the Wwise authoring tool.
In this example, the
AK::AUX_BUSSES::TUNNEL_ENV_PORTAL aux bus should be set to “Enable Positioning” and positioning type 3D in the Wwise authoring tool, so that is can also emit sound in the 3D simulation.
As well as changing the Auxiliary Busses to which a game object belongs, you can also reduce its dry component by using the
AK::SoundEngine::SetGameObjectOutputBusVolume() function. This function can be used to simulate obstruction. Every game object has initially a dry level set to 100% (1.0f) (unless specified otherwise in the sound object properties).
|Tip: To simulate a sound so far away that the listener can only hear its reverberations, set the dry level to 0%.|
The volume applied at the output of Auxiliary Busses can be driven just like any other bus volume using the Volumes sliders in the authoring tool, States, RTPCS, and more.