WaveBank is a container class for an XACT-style wave bank that contains individual waves packaged together for more efficient loading and memory management. Sounds in the wave bank can then be played back as one-shot sounds or via SoundEffectInstance.
See XWBTool
For exception safety, it is recommended you make use of the C++ RAII pattern and use a std::unique_ptr or std::shared_ptr
Note that in-memory banks may still be loading the wave data asynchronously after the return of this constructor. You can see if the wave data has completed loading by calling IsPrepared (). If you call Play or CreateInstance before the wave data has loaded, then the thread will wait until the load is complete before returning.
If the wave bank contains 'entry friendly names', you can also use them to trigger a one-shot:
You can also make use of the C/C++ header generated by XWBTool or XACTBLD3 to avoid 'magic numbers' in your code:
Note a C++ exception is thrown if attempting to play a one-shot sound from a streaming wavebank.
If the specified index or name is not found, then no one-shot is played and there is no C++ exception thrown.
To play a sound with positional 3D audio:
If the wave bank contains 'entry friendly names', you can also use them to create an instance:
You can also make use of the C/C++ header generated by XWBTool or XACTBLD3 to avoid 'magic numbers' in your code:
Note a C++ exception is thrown if attempting to create a sound instance from a streaming wavebank.
If the specified index or name is not found, then CreateInstance returns a 'nullptr'. Client code should be sure to check for this condition. This is done because typically games do not consider missing audio content to be a fatal error during development.
See SoundEffectInstance.
Care needs to be taken to ensure that any referenced WaveBank is not deleted while a source voice is actively playing back content from it or has pending buffers referencing it.
XAudio 2.7 on Windows Vista or later via the legacy DirectX End-User Runtime Redistribution (aka DirectSetup) supports PCM, MS-ADPCM, and xWMA (created by xwmaencode.exe in the legacy DirectX SDK).
XAudio on Xbox One supports PCM, MS-ADPCM, and xWMA. Xbox One exclusive app developers can also make use of XMA2 (created by xmaencode.exe in the Xbox One XDK).
XACT-style wave banks support 8-bit and 16-bit PCM (i.e. not 32-bit IEEE float PCM), MS-ADPCM, xWMA, and XMA2 content.
http://msdn.microsoft.com/en-us/library/windows/desktop/dd757713.aspx
http://msdn.microsoft.com/en-us/library/windows/desktop/dd743663.aspx
http://msdn.microsoft.com/en-us/library/windows/desktop/dd757714.aspx
http://msdn.microsoft.com/en-us/library/bb203879(v=xnagamestudio.40).aspx
See XWBTool
Initialization
std::unique_ptr<WaveBank> wb( new WaveBank( audEngine.get(), L"wavebank.xwb" ) );
For exception safety, it is recommended you make use of the C++ RAII pattern and use a std::unique_ptr or std::shared_ptr
Note that in-memory banks may still be loading the wave data asynchronously after the return of this constructor. You can see if the wave data has completed loading by calling IsPrepared (). If you call Play or CreateInstance before the wave data has loaded, then the thread will wait until the load is complete before returning.
Play one-shot sounds
To play a sound in the bank as a 'fire and forget' sound:wb->Play( 2 );
If the wave bank contains 'entry friendly names', you can also use them to trigger a one-shot:
wb->Play( "Bang" );You can also make use of the C/C++ header generated by XWBTool or XACTBLD3 to avoid 'magic numbers' in your code:
#include "wavebank.h"
wb->Play( XACT_WAVEBANK_WAVEBANK_BANG );Note a C++ exception is thrown if attempting to play a one-shot sound from a streaming wavebank.
If the specified index or name is not found, then no one-shot is played and there is no C++ exception thrown.
Playing the sound
To play a sound with full control, looping, pitch-shifting, volume control, and/or pan settings:auto effect = wb->CreateInstance( 2 ); if ( !effect ) // Index not found in wave bank
To play a sound with positional 3D audio:
auto effect = wb->CreateInstance( 2, SoundEffectInstance_Use3D | SoundEffectInstance_ReverbUseFilters); if ( !effect ) // Index not found in wave bank
If the wave bank contains 'entry friendly names', you can also use them to create an instance:
auto effect = wb->CreateInstance( "Bang" ); if ( !effect ) // Name not found in wave bankauto effect = wb->CreateInstance( "Bang", SoundEffectInstance_Use3D | SoundEffectInstance_ReverbUseFilters); if ( !effect ) // Name not found in wave bank
You can also make use of the C/C++ header generated by XWBTool or XACTBLD3 to avoid 'magic numbers' in your code:
#include "wavebank.h"auto effect = wb->CreateInstance( XACT_WAVEBANK_WAVEBANK_BANG ); if ( !effect ) // Index not found in wave bankauto effect = wb->CreateInstance( XACT_WAVEBANK_WAVEBANK_BANG, SoundEffectInstance_Use3D | SoundEffectInstance_ReverbUseFilters); if ( !effect ) // Index not found in wave bank
Note a C++ exception is thrown if attempting to create a sound instance from a streaming wavebank.
If the specified index or name is not found, then CreateInstance returns a 'nullptr'. Client code should be sure to check for this condition. This is done because typically games do not consider missing audio content to be a fatal error during development.
See SoundEffectInstance.
Properties
- IsPrepared ()
Returns true if the WaveBank has completed loading the wave data. For streaming buffers, they are always prepared after the constructor returns (only the metadata is loaded into memory).
- IsInUse ()
Returns true if the WaveBank is currently playing as a one-shot or there are SoundEffectInstances referencing it.
- IsStreamingBank ()
Returns true if the wave bank is a streaming type, false if it is an in-memory wave bank.
- SampleSizeInBytes ( index )
Returns the size of the wave data in bytes. This will return 0 if the index is invalid.
- SampleDuration ( index )
Returns the wave data duration in samples. Divide it by the wave format's nSamplesPerSec to convert it to seconds. This does not include any loops. This will return 0 if the index is invalid.
- GetFormat ( index, WAVEFORMATEX* wfx, size_t maxsize )
Fills out a WAVEFORMATEX structure that describes the wave data format. This will return nullptr if the index is invalid, otherwise it returns a pointer to wfx. Since the format can be variable length, the caller provides the buffer and maxsize. At least 64 bytes is recommended as this is large enough to contain WAVEFORMAT, PCMWAVEFORMAT, WAVEFORMATEX, ADPCMWAVEFORMAT with coefficients, WAVEFORMATEXTENSIBLE, or a XMA2WAVEFORMATEX.
char formatBuff[ 64 ]; auto wfx = reinterpret_cast<WAVEFORMATEX*>( formatBuff ); wb->GetFormat( 2, wfx, 64 );
Note the 'loop' parameter is only needed for XMA2 wave bank entries
- Find ( const char* name )
Returns the index, or -1 if not found or if there are no entry friendly names present in the wave bank.
Low-level access
FillSubmitBuffer is used internally, but can also be used when implementing your own XAudio2 source voices using the low-level interface access. Note that LoopCount is set to 0 by this function and should be set to a non-zero value by the caller. If looping is not desired, be sure to set LoopBegin and LoopLength to zero as well.Care needs to be taken to ensure that any referenced WaveBank is not deleted while a source voice is actively playing back content from it or has pending buffers referencing it.
Content support
XAudio 2.8 on Windows 8.x and Windows phone support PCM and MS-ADPCM formats (created by adpcmencode.exe in the Windows 8.x SDK or the legacy DirectX SDK).XAudio 2.7 on Windows Vista or later via the legacy DirectX End-User Runtime Redistribution (aka DirectSetup) supports PCM, MS-ADPCM, and xWMA (created by xwmaencode.exe in the legacy DirectX SDK).
XAudio on Xbox One supports PCM, MS-ADPCM, and xWMA. Xbox One exclusive app developers can also make use of XMA2 (created by xmaencode.exe in the Xbox One XDK).
XACT-style wave banks support 8-bit and 16-bit PCM (i.e. not 32-bit IEEE float PCM), MS-ADPCM, xWMA, and XMA2 content.
Further reading
http://msdn.microsoft.com/en-us/library/windows/desktop/dd757712.aspxhttp://msdn.microsoft.com/en-us/library/windows/desktop/dd757713.aspx
http://msdn.microsoft.com/en-us/library/windows/desktop/dd743663.aspx
http://msdn.microsoft.com/en-us/library/windows/desktop/dd757714.aspx
http://msdn.microsoft.com/en-us/library/bb203879(v=xnagamestudio.40).aspx