General Information
Types of Banks
Two types of banks exist for every project: the Initialization bank and SoundBanks.
Initialization Bank
There is only one initialization bank for each project. It is automatically created when Wwise generates the SoundBanks and is named "Init.bnk". This special bank contains general project information, including:
- Bus hierarchy
- States
- Switches
- RTPCs
- Environmental FX
The initialization bank is language-independent, so only one is generated for all languages.
The initialization bank must be the first bank loaded when starting a game. If it is not loaded first, the SoundBanks may not load. The initialization bank cannot be unloaded if any other SoundBank is still loaded. The initialization bank is loaded in the same way as the SoundBanks.
|
Note: Loading the initialization bank for a project that uses source, effect, or codec plug-ins will fail if these plug-ins have not been previously registered with the sound engine. Refer to Integration Details - Plug-Ins and Integrating Codec Plug-Ins for information concerning plug-in registration. |
SoundBanks
Each SoundBank may contain:
- Event definitions
- Sound structure information (sound, container, music object, actor-mixer, and so on)
- Media:
- Sound data (for in-memory sounds)
- Pre-fetched sound data (for zero-latency streamed sounds)
- References to streamed audio files (file ID)
After the initialization bank has been loaded, SoundBanks can be loaded and unloaded anytime during the game. It is your responsibility to ensure that the bank containing an event is loaded before the event is triggered. If an event is posted before its corresponding bank is loaded, the event will not execute.
|
Caution: SoundBanks require information that is stored in the initialization bank. Therefore, your game must use an initialization bank and SoundBanks that are generated from the same Wwise project. |
Using IDs or Strings (Unicode or Ansi)
The SDK provides two ways of accessing items inside a bank, using strings or using IDs. There are a few things that you should consider before deciding which option to use in your game, including:
- The importance of having reader-friendly code
- The use of strings in other areas of your development environment
- CPU usage
- Memory usage
Using Strings
- Makes code more readable, which makes it suitable for development.
- Appropriate for development environments that normally use strings.
- A small amount of CPU is required to convert strings to the IDs used by sound engine. However, most games will not notice the difference in CPU usage unless thousands of stings are converted per game frame.
- Strings are not stored in the sound engine, so if the strings are already used in the game engine, then no additional memory will be used. If, however, the game doesn't use strings, then some memory will be used on the game side to store the strings before they are converted.
Using IDs
- Code is less readable which makes it more difficult to troubleshoot problems during development.
- Doesn't require any additional CPU usage because the sound engine uses IDs internally.
- Doesn't require any additional memory.
In most cases, you can get away with using strings, but if your game is very squeezed in terms of memory and CPU, you might want to consider using IDs.
String Conversion
The IDs of all Wwise objects that are available to the game (banks, events, game syncs, and so on) are computed by hashing their lowered-case name into a 32 bit integer.
|
Tip: In Wwise, selecting the "Generate SoundBank content files" option on the SoundBanks tab of the Project Settings dialog box will create a corresponding text file for each bank, that enumerates the names and IDs of all the objects that it contains. Refer to the Wwise Help for a description of the SoundBank project settings. |
The method AK::SoundEngine::GetIDFromString() performs run-time conversion of a string into an ID. It is case-insensitive: the input string is converted to lowercase, then the hashing function is applied.
Example: Using Unicode Strings
Let's say that you want to post an event that is identified by its name. You can use the overload of AK::SoundEngine::PostEvent() that has a string as its first argument.
|
|
Note: The sound engine internally converts the unicode string to an ID, and then calls the overload of PostEvent() that has an ID as its first argument. All methods of the SDK that have both string and ID overloads work like that, except the AK::SoundEngine::LoadBank() overloads, because they involve device I/O. This is explained in section Identifying Banks. |
AkGameObjectID gameObj = 3; AK::SoundEngine::RegisterGameObj( gameObj ); AkPlayingID playingID = AK::SoundEngine::PostEvent( L"Play_Sound_01", // Name of the event (not case sensitive). gameObj // Associated game object ID );
Enabling ID Usage
To work directly with IDs, without having to convert the strings into IDs at run-time, the banks should be generated with the "Generate header file" option selected. This option is located on the SoundBanks tab of the Project Settings dialog box in Wwise. The header file, named Wwise_IDs.h, contains all the required IDs and needs to be included in your game. It is updated each time the banks are generated.
For more information on generating banks in Wwise, refer to the Wwise Help.
Here is an example of a very simple .h file generated by Wwise:
// // Audiokinetic Wwise generated include file. Do not edit. // #ifndef __WWISE_IDS_H__ #define __WWISE_IDS_H__ namespace AK { namespace EVENTS { static const AkUniqueID PLAY_SOUND_01 = 2580655723U; static const AkUniqueID PLAY_SOUND_02 = 2580655720U; static const AkUniqueID PLAY_SOUND_03 = 2580655721U; } // namespace EVENTS namespace BANKS { static const AkUniqueID INIT = 1355168291U; static const AkUniqueID BANK_01 = 1576947084U; static const AkUniqueID BANK_02 = 1819748216U; } // namespace BANKS } // 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 bank, event, state, switch, and so on.
|
|
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. |
Example: Using IDs
Let's say you want to post an event by using its ID. The generated header file "Wwise_IDs.h" must be included. Simply use the PostEvent() overload that uses an ID as its first argument.
#include "Wwise_IDs.h" // ... AkGameObjectID gameObj = 3; AK::SoundEngine::RegisterGameObj( gameObj ); AkPlayingID playingID = AK::SoundEngine::PostEvent( AK::EVENTS::PLAY_SOUND_01, // Unique ID of the event gameObj // Associated game object ID );
Identifying Banks
Like all other Wwise objects in the game, banks are identified by IDs that are generated by hashing their name. Loading and unloading banks always involve access to an I/O device at some point.
Loading Banks From Memory
One of the AK::SoundEngine::LoadBank() overloads uses a pointer and a size. It should be used when you want to perform I/O on your side, and then just tell the sound engine that you want it to prepare its content. The pointer must be valid until the bank is unloaded.
The bank ID is stored in banks. The memory overload of AK::SoundEngine::LoadBank() parses it and returns it to you. You must keep it in order to unload the bank (using the ID overload of AK::SoundEngine::UnloadBank()).
Loading Banks From File System
The Wwise sound engine never accesses I/O directly. All its requests for I/O are executed through the Stream Manager, whose interface is defined as AK::IAkStreamMgr (see Streaming / Stream Manager). This module can be overridden, but Audiokinetic's default implementation further defines an abstraction for low-level access to I/O transfers and file system, and the Low-Level IO module, whose interface is defined as AK::IAkLowLevelIO and is specific to Audiokinetic's implementation of AK::IAkStreamMgr. A default implementation of the Low-Level IO is provided, but it is meant to be replaced by your own, especially to resolve file location (see Low-Level I/O).
The Stream Manager and Low-Level IO define 2 overloads to open files, one by string, and another by ID. Similarly, the sound engine API provides overloads of LoadBank() that use strings, or IDs. The version of AK::IAkLowLevelIO::Open() that ends up being called by the sound engine depends on which overload of LoadBank() was used by the game. It also depends on whether the SoundBanks were generated with the "Use SoundBank names" option that is located on the SoundBanks tab of the Project Settings dialog box. Refer to the Wwise Help for a description of the SoundBank project settings.
Using SoundBank Names
One of the settings available in Wwise for generating SoundBanks is the "Use SoundBank names" option. It affects how banks are loaded in the sound engine, regarding I/O and file system.
|
Warning: When using the default implementation of the Low-Level IO provided in the SDK (CAkDefaultLowLevelIO, see Default Low-Level I/O Implementation), the following limitations apply:
However, when using the file package-based Low-Level IO (CAkFilePackageLowLevelIO, see Sample File Package Low-Level I/O Implementation Walkthrough), you may use both overloads of LoadBank(), regardless of the "Use SoundBank names" setting. |
Not Selecting the "Use SoundBank Names" Option
When the option is not selected, Wwise generates bank files with names that have the following format:
- ID.bnk.
where "ID" is a numeric, 32-bit ID generated by hashing the bank's name (see AK::SoundEngine::GetIDFromString()).
In this mode, banks refer to other banks internally using their IDs (their names are not stored in the banks that reference them). Therefore, all calls to AK::IAkLowLevelIO::Open() that are issued from a PrepareEvent() command use the ID version. It is the responsibility of the Low-Level IO to resolve this ID into a valid file descriptor.
Within the ID version of AK::IAkLowLevelIO::Open(), the default implementation of the Low-Level IO provided in the SDK (CAkDefaultLowLevelIO, see Default Low-Level I/O Implementation) creates a string with the ID, appends ".bnk", and calls the native File Open method specific to the platform (see Basic File Location).
|
|
Tip: The bank IDs are available in the header file Wwise_IDs.h - see section Enabling ID Usage. |
Selecting the "Use SoundBank Names" Option
When the option is selected, Wwise generates the bank files with their original name, appending the .bnk extension.
Banks store the names of other banks they reference. When the sound engine's Bank Manager needs to load another bank from I/O, following a PrepareEvent() command, it uses the string version of AK::IAkLowLevelIO::Open(). The string version of AK::IAkLowLevelIO::Open() receives the name of the bank, concatenated with the ".bnk" extension. It is the responsibility of the Low-Level IO to prepend the path of the location of the bank, or to perform any transformation required, before accessing the platform's file system.
Banks generated with the "Use SoundBank Names" option are slightly bigger, because they must store the names of the banks they reference, not just their ID.
|
|
Note: Generated bank names on disk, and their IDs, are enumerated in the file SoundBanksInfo.xml - see section SoundBanksInfo.xml. |
|
|
Tip: In the string overload of UnloadBank(), strings are converted to IDs internally, and then the ID overload is called. It is possible to load a bank with the string overload, keep the associated bank ID that was returned, and later use this ID to unload the bank. |
.
Language-Specific ("Voice" and "Mixed") Soundbanks
When Wwise creates a language-specific SoundBank, it generates a file with the same ID/file name for every language that has language-specific data. These special language files are stored in a separate language-specific directory. However, there is no flag in the bank load methods of the sound engine API (LoadBank()) to specify from which language-specific directory the file needs to be opened. File location is intended to be resolved by the Low-Level IO or the Stream Manager if you choose to override it.
The Stream Manager API exposes methods for creating streams (for file I/O) which include a flag that specifies language specificity. This flag is propagated down to the Low-Level IO. Refer to File System Flags for more information.
Since the sound engine's Bank Manager does not know if the soundbanks that need to be loaded contain language-specific data, it always asks the Stream Manager to search for the file in the language-specific directory first (bIsLanguageSpecific is True). If the process fails, the Bank Manager tries again, but this time it asks the Stream Manager to search in the common directory (bIsLanguageSpecific is False).
Refer to File Location Resolving for a discussion on file location. You might also want to read the section that describes the default implementation (Basic File Location) for a tip on how to avoid opening a soundbank file in the wrong location.
Streamed Audio Files
Banks always store the ID of streamed audio files they reference. When the sound engine wants to start the playback of a source that is streamed, it gets the ID from the bank and calls the ID overload of the Stream Manager. This ends up calling the ID overload of AK::IAkLowLevelIO::Open(). The default implementation of the Low-Level IO creates a string with the ID, and concatenates an extension that corresponds to the format of the file. If you want a copy of your streamed files to be created using this naming scheme and then stored in the Generated SoundBanks directory, use the "Copy Streamed Files" option on the SoundBanks tab of Project Settings dialog box. This operation is defined as a post-generation step. So, it is performed immediately following the generation of your SoundBanks. Refer to the Wwise Help for a complete description of the SoundBank project settings.
SoundBanksInfo.xml
Every time banks are generated in Wwise, a file named SoundBanksInfo.xml is created for each platform, directly in the SoundBank path. It is an XML file that describes all the files needed by the sound engine for a given project.
Its content is pretty self-explanatory. The first section (StreamedFiles) enumerates all the streamed audio files, specifying their ID, their original name, their language and their full path. The second section (SoundBanks) does the same for bank files. Furthermore, each bank lists the streamed audio files it references.
Loading Banks
For a complete description of the bank loading APIs, refer to Loading Banks.