Using Effects in DirectMusic

DirectX provides support for effects processing of sounds by DirectX Media Objects (DMOs). A standard set of effects is available to every DirectX application. Other DMOs can be registered on the system.

All the standard DMOs can process 8-bit or 16-bit PCM data, as well as 32-bit floating-point formats, with one or two channels at any sample rate supported by DirectSound. Waves reverberation does not support 8-bit samples.

Effects are attached to DirectSound buffers in audiopaths. To add, remove, or modify effects at run time, an application must obtain an interface to the buffer and use the DirectSound API.

If you are playing segments authored in DirectMusic Producer with audiopath configurations, any effects are set up when you create the audiopath from the configuration object. A standard audiopath might also contain effects. However, in some cases you may prefer to implement an effect on a custom audiopath at run time or add an effect to a standard audiopath. For example, you might want to add an effect to a standard audiopath so that you can apply the effect to standard WAV or MIDI files.

To apply an effect to an audiopath, you must first obtain an IDirectSoundBuffer8 interface to a buffer on the path. Then set one or more effects on that buffer by using IDirectSoundBuffer8::SetFX.

To learn how to obtain a buffer interface, see Retrieving Objects from an Audiopath. For information on how to identify standard audiopath buffers in the call to GetObjectInPath, see the audiopath types under Standard Audiopaths.

The following example code sets a standard audiopath, retrieves a buffer from the path, and sets an echo effect on the buffer:

HRESULT SetEchoEffect(IDirectMusicPerformance8 *pPerformance,
    IDirectMusicAudioPath* p3DAudioPath,
    IDirectSoundBuffer8* pDSBuffer)
{
  HRESULT       hr;
 
  // Create a standard audiopath with a source and 
  // environment reverb buffers. Don't activate the path;
  // SetFX fails if the buffer is running. 
 
  if( FAILED(hr = pPerformance->CreateStandardAudioPath(
      DMUS_APATH_DYNAMIC_3D, 64, FALSE, &p3DAudioPath)))
    return hr;
   
  // Get the buffer in the audiopath.
 
  if( FAILED(hr = p3DAudioPath->GetObjectInPath(DMUS_PCHANNEL_ALL,
      DMUS_PATH_BUFFER, 0, GUID_NULL, 0, IID_IDirectSoundBuffer8, 
      (LPVOID*) &pDSBuffer)))
    return hr;
 
  // Describe the effect.
 
  DSEFFECTDESC dsEffect;
  dsEffect.dwSize = sizeof(DSEFFECTDESC);
  dsEffect.dwFlags = 0;
  dsEffect.guidDSFXClass = GUID_DSFX_STANDARD_ECHO;
  dsEffect.dwReserved1 = 0;
  dsEffect.dwReserved2 = 0;
 
  DWORD dwResults;
 
  // Set the effect.
  if (FAILED(hr = pDSBuffer->SetFX(1, &dsEffect, &dwResults)))
  {
    p3DAudioPath->Activate(TRUE);
    return hr;
  }
  // You can check the value of dwResults here to ascertain 
  // whether the effect was allocated, and how.
 
  // Activate the path.
 
  p3DAudioPath->Activate(TRUE);
  return hr;
}