Integration Details - Environments and Game-defined Auxiliary Sends

Introduction

Note: Starting from Wwise 2012.2 Wwise introduced the concept of "Game-defined Auxiliary Sends". This new feature absorbed the functionalities of what was previously designed as "Environments". The same features are available using the new very similar API that was mostly renamed. While most of the documentation has been updated, any place in the documentation referring to Environments should be interpreted as "Game-defined Auxiliary sends".

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:

• Hangar
• Tunnel
• ...and others as useful for 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 as any environment. When a sound is not in an environment(not router to any aux bus), it plays normally, that is, 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, where 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 in the environmental effect at 45% ( 0.50f * 0.90 ).

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

• AK::SoundEngine::SetGameObjectAuxSendValues()
• AK::SoundEngine::SetGameObjectOutputBusVolume()
• AK::SoundEngine::GetIDFromString()

Dynamic auxiliary bus routing: Dynamically Sending To Auxiliary Busses.

Using IDs or Strings (Unicode or Ansi)

The SDK provides you with two ways of accessing items inside a bank, 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, 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, allowing 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].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].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.

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: Setting the Main Character Sounds Main Output Level to 45%

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:

• Concept: Environments and Game-defined Auxiliary Sends
• Obstruction and Occlusion in Environments
• AK::SoundEngine::SetGameObjectAuxSendValues()
• AK::SoundEngine::SetGameObjectOutputBusVolume()
• AK::SoundEngine::GetIDFromString()