SoundEffectInstance is an instance of a sound from a SoundEffect or a WaveBank. It can be played with 3D positional audio effects, volume and panning control, looping, and pause/resume control.
Note that the SoundEffectInstance does not copy the wave data and instead refers to the data 'owned' by the SoundEffect / WaveBank. Therefore, the parent object should be kept active until all sounds playing from it are finished.
Or created for an entry in a WaveBank (which is returned as a std::unique_ptr<SoundEffectInstance>):
It can optionally support 3D positional audio:
Or use 3D positional audio with reverb effects (if AudioEngine was created using AudioEngine_EnvironmentalReverb | AudioEngine_ReverbUseFilters):
Note if the instance was created without SoundEffectInstance_Use3D, then calls to Apply3D will result in a C++ exception being thrown.
See AudioListener, AudioEmitter
http://msdn.microsoft.com/en-us/library/windows/desktop/microsoft.directx_sdk.x3daudio.x3daudiocalculate.aspx
Note that the SoundEffectInstance does not copy the wave data and instead refers to the data 'owned' by the SoundEffect / WaveBank. Therefore, the parent object should be kept active until all sounds playing from it are finished.
Initialization
It can be created for an individual sound loaded as a SoundEffect (which is returned as a std::unique_ptr<SoundEffectInstance>)auto effect = soundEffect->CreateInstance();Or created for an entry in a WaveBank (which is returned as a std::unique_ptr<SoundEffectInstance>):
auto effect = wb->CreateInstance( 2 ); if ( !effect ) // Index not found in wave bank
It can optionally support 3D positional audio:
auto effect = soundEffect->CreateInstance( SoundEffectInstance_Use3D ); auto effect = wb->CreateInstance( 2, SoundEffectInstance_Use3D ); if ( !effect ) // Index not found in wave bank
Or use 3D positional audio with reverb effects (if AudioEngine was created using AudioEngine_EnvironmentalReverb | AudioEngine_ReverbUseFilters):
auto effect = soundEffect->CreateInstance( SoundEffectInstance_Use3D | SoundEffectInstance_ReverbUseFilters); auto effect = wb->CreateInstance( 2, SoundEffectInstance_Use3D | SoundEffectInstance_ReverbUseFilters); if ( !effect ) // Index not found in wave bank
Instance flags
This is a combination of flags. It defaults to SoundEffectInstance_Default.- SoundEffectInstance_Use3D - Required to use Apply3D
- SoundEffectInstance_ReverbUseFilters - Enables additional effects if the audio engine was created with AudioEngine_EnvironmentalReverb and optionally AudioEngine_ReverbUseFilters.
- SoundEffectInstance_NoSetPitch - If set, this instance cannot use SetPitch.
- There is also a SoundEffectInstance_UseRedirectLFE which is used internally by the library.
Playback control
- Play ( bool loop = false )
Starts the playback of the sound. If loops is set to true, it loops continuously either the entire buffer or using the authored loop points (if any). If paused, it resumes playback.
- Stop ( bool immediate = true )
Stops the playback of the voice. If immediate is true, the sound is immediately halted. Otherwise the current loop is exited (if looping) and any 'tails' are played. The sound still not completely stop playing until a future point so the state will remain "PLAYING" for a while.
- Resume ()
Resumes playback if the sound is PAUSED.
- Pause ()
Pauses the sound playback. Note that for a 'game' pause, you should use AudioEngine::Suspend() / Resume() instead of 'pausing' the sounds individually.
Volume and panning
- SetVolume ( float volume )
Sets playback volume. Playback defaults to 1.0
- SetPitch ( float pitch )
Sets a pitch-shift factor. Playback defaults to 1.0 (which is no pitch-shifting).
- SetPan ( float pan )
Sets a pan settings: -1.0 is fully left, 1.0 is fully right, and 0.0 is balanced.
Note that a C++ exception is thrown if attempting to 'pan' a sound that is not mono (i.e. one channel).
Positional 3D audio
DirectXTK for Audio uses X3DAudio for positional audio computations. To apply a 3D effect to a sound instance, you call Apply3D with the listener location (i.e. where the player/camera is located) and the emitter (i.e. where the sound source is located in 3D dimensions):AudioListener listener; listener.SetPosition( ... ); AudioEmitter emitter; emitter.SetPosition( ... ); effect->Apply3D( listener, emitter );
Note if the instance was created without SoundEffectInstance_Use3D, then calls to Apply3D will result in a C++ exception being thrown.
See AudioListener, AudioEmitter
Properties
- IsLooped ()
Returns true if the sound was played with looping enable.
- GetState ()
Returns STOPPED, PLAYING, or PAUSED.
Further reading
http://msdn.microsoft.com/en-us/library/windows/desktop/ee415714.aspxhttp://msdn.microsoft.com/en-us/library/windows/desktop/microsoft.directx_sdk.x3daudio.x3daudiocalculate.aspx