Effect Parameters

To set or retrieve parameters of sound effects, you must first obtain the appropriate interface to the buffer that contains the effect. The following interfaces give you access to parameters of the DMOs supplied with DirectX Audio.

• IDirectSoundFXChorus8
• IDirectSoundFXCompressor8
• IDirectSoundFXDistortion8
• IDirectSoundFXEcho8
• IDirectSoundFXFlanger8
• IDirectSoundFXGargle8
• IDirectSoundFXI3DL2Reverb8
• IDirectSoundFXParamEq8
• IDirectSoundFXWavesReverb8

To retrieve an effect interface, pass DMUS_PATH_BUFFER_DMO as the dwStage parameter to IDirectMusicAudioPath8::GetObjectInPath or IDirectMusicSegmentState8::GetObjectInPath. If the audiopath contains more than one buffer, dwBuffer must be the index of the buffer. For information on the index numbers of buffers in standard audiopaths, see the audiopath types under Standard Audiopaths.

The following sample code retrieves an interface for the gargle effect on a buffer created from an audiopath configuration. It then uses this interface to change a parameter of the effect.

// g_p3DAudioPath is a valid IDirectMusicAudioPath8 pointer
// obtained from IDirectMusicPerformance8::CreateAudioPath. 
// To simplify the example, error-handling is omitted.
 
HRESULT      hr;
IDirectSoundFXGargle8* pEffectDMO;
DSFXGargle     FXParams;
 
hr = g_p3DAudioPath->GetObjectInPath(DMUS_PCHANNEL_ALL,
    DMUS_PATH_BUFFER_DMO, 0,
    GUID_All_Objects, 0, IID_IDirectSoundFXGargle8,
    (LPVOID*) &pEffectDMO);
 
hr = pEffectDMO->GetAllParameters(&FXParams);
FXParams.dwRateHz  = DSFXGARGLE_RATEHZ_MIN; 
hr = pEffectDMO->SetAllParameters(&FXParams);
 

If your application is managing its own DirectSound buffers, you need to ensure that changes in effect parameters take place immediately. For efficiency, DirectSound processes 100 milliseconds of sound data in a buffer, starting at the play cursor, before IDirectSoundBuffer8::Play is called. This can happen after any of the following calls:

• IDirectSoundBuffer8::Unlock
• IDirectSoundBuffer8::Stop
• IDirectSoundBuffer8::SetCurrentPosition
• IDirectSoundBuffer8::SetFX

If you call any of these methods and then change effect parameters, the new parameters will not be heard until the preprocessed data has been played. To avoid this situation, do one of the following:

• Write data to the buffer after effect parameters have been changed, not before.
• Call Stop or SetCurrentPosition on the buffer to force preprocessing after you have set the parameters.