Integration Details - Environments and Game-defined Auxiliary Sends

Introduction

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.

In the game, each game object may be routed to 0 to AK_MAX_AUX_PER_OBJ (4) Auxiliary Busses at a time. 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 GAME_OBJECT_ID_HUMAN game object is 50% in the Auxiliary Bus "Hangar" and the Auxiliary Bus "Hangar" is attenuated at 90%, then the sounds emitted by this game object will go into its Effects at 45% (0.50f * 0.90).

Handling the game-defined auxiliary sends is done using the following functions:

Dynamic Auxiliary Bus routing: Dynamically Sending To Auxiliary Busses.

Auxiliary Sends and Listener Game Objects

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 SetListeners() or 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 listenerID.

Note: It is important to fill out the listenerID field in the AkAuxSendValue structure. Leaving it uninitialized will result in undefined behaviour.

Using IDs or Strings (Unicode or ANSI)

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.

Enabling ID Usage

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.

Working with IDs

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.

/////////////////////////////////////////////////////////////////////////////////////////////////////
//
// Audiokinetic Wwise generated include file. Do not edit.
//
/////////////////////////////////////////////////////////////////////////////////////////////////////

#ifndef __WWISE_IDS_H__
#define __WWISE_IDS_H__

namespace AK
{
    namespace EVENTS
    {
        enum
        {
            PLAY_ENGINE = 7,
            PLAY_FOOTSTEP = 3,
            PLAY_HELLO = 6,
            PLAY_MARKERS_TEST = 1007392764,
            STOP_ENGINE = 8,
        };
    } // namespace EVENTS

    namespace AUX_BUSSES
    {
        static const AkUniqueID HANGAR_ENV = 2112490296U;
        static const AkUniqueID TUNNEL_ENV = 2112490296U;
    } // namespace AUX_BUSSES

} // namespace AK

#endif // __WWISE_IDS_H__

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.

Example: String Conversion (Unicode Version)

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.

AkAuxBusID AK::SoundEngine::GetIDFromString( const wchar_t * in_pszString );

Dynamically Sending To Auxiliary Busses.

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 bus 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. The maximum number of auxiliary busses that a game object can route to is set to AK_MAX_AUX_PER_OBJ (4). For every auxiliary bus in which a game object is sent to, a control value must be set representing the percentage of 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: Even if the maximum of environments for a given game object is set to AK_MAX_AUX_PER_OBJ (4), it is possible for more than AK_MAX_AUX_PER_OBJ environments to be applied to an object for a very short amount of time. This can happen when the sound engine is interpolating environments to avoid glitches that can occur when changing too quickly from one environment to another. AK_MAX_AUX_PER_OBJ can be lower than (4) on some smaller platforms.

Example: Setting the Environments of a Main Character Using Unicode Strings

Setting Hangar Aux bus to 100%.

const AkGameObjectID GAME_OBJECT_ID_HUMAN = 200;
#define NUM_ENVIRONMENT 1

AkAuxSendValue aEnv[NUM_ENVIRONMENT];
aEnv[0].listenerID = AK_INVALID_GAME_OBJECT; // Use the same set of listeners assigned via the SetListeners/SetDefaultListeners API.
aEnv[0].auxBusID = GetIDFromString( L"Hangar" );
aEnv[0].fControlValue = 1.0f; // 1.0f stands for 100%, the control value ranges from 0 to 1.

AK::SoundEngine::SetGameObjectAuxSendValues( GAME_OBJECT_ID_HUMAN, aEnv, NUM_ENVIRONMENT );

Example: Setting the Environments of a Main Character Using IDs Setting Hangar to 75% and Tunnel to 25%.

const AkGameObjectID GAME_OBJECT_ID_HUMAN = 200;
#define NUM_ENVIRONMENT 2

AkAuxSendValue aEnv[NUM_ENVIRONMENT];
aEnv[0].listenerID = AK_INVALID_GAME_OBJECT; // Use the same set of listeners assigned via the SetListeners/SetDefaultListeners API.
aEnv[1].listenerID = AK_INVALID_GAME_OBJECT; 
aEnv[0].auxBusID = AK::AUX_BUSSES::HANGAR_ENV;
aEnv[1].auxBusID = AK::AUX_BUSSES::TUNNEL_ENV;
aEnv[0].fControlValue = 0.75f; // 0.75 stands for 75%, the control value ranges from 0 to 1.
aEnv[1].fControlValue = 0.25f; // 0.25 stands for 25%, the control value ranges from 0 to 1.

AK::SoundEngine::SetGameObjectAuxSendValues( GAME_OBJECT_ID_HUMAN, aEnv, NUM_ENVIRONMENT );

Using the control values, it is possible to make sounds go smoothly from one environment to another.

Example: Setting No Aux Send.

const AkGameObjectID GAME_OBJECT_ID_HUMAN = 200;

AK::SoundEngine::SetGameObjectAuxSendValues( GAME_OBJECT_ID_HUMAN, NULL, 0 );

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.

Example: Assigning an Aux Send to an Alternate Listener Game Gbject to Simulate an Acoustic Portal

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.

const AkGameObjectID GAME_OBJECT_ID_HUMAN = 200;
const AkGameObjectID GAME_OBJECT_ID_PORTAL = 201;
#define NUM_ENVIRONMENT 1

AkAuxSendValue aEnv[NUM_ENVIRONMENT];
aEnv[0].listenerID = GAME_OBJECT_ID_PORTAL; // Target game object ID for this aux send.
aEnv[0].auxBusID = AK::AUX_BUSSES::TUNNEL_ENV_PORTAL; // Target aux bus ID for this aux send.
aEnv[0].fControlValue = 1.0f;

AK::SoundEngine::SetGameObjectAuxSendValues( GAME_OBJECT_ID_HUMAN, aEnv, NUM_ENVIRONMENT );

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.

Setting Main Output Level (or Dry level)

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).

Example: Assigning an Aux Send to an Alternate Listener Game Gbject to Simulate an Acoustic Portal

const AkGameObjectID GAME_OBJECT_ID_HUMAN = 200;

// Setting the main character sounds dry level to 45%
AK::SoundEngine::SetGameObjectOutputBusVolume( GAME_OBJECT_ID_HUMAN, 0.45f );

Tip: To simulate a sound so far away that the listener can only hear its reverberations, set the dry level to 0%.

Setting Auxiliary Bus Volume

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.

See also:

Was this page helpful?

Need Support?

Questions? Problems? Need more info? Contact us, and we can help!

Visit our Support page

Tell us about your project. We're here to help.

Get started with Wwise

Wwise SDK 2017.1.9