Setting Effects on Buffers

[The feature associated with this page, DirectSound, is a legacy feature. It has been superseded by WASAPI and Audio Graphs. Media Casting have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use Media Casting instead of DirectSound, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

You can set any number of effects on a secondary buffer that was created with the DSBCAPS_CTRLFX flag in the DSBUFFERDESC structure. The buffer must be stopped and not locked. Since DirectX 9.0, effects are never hardware-accelerated. It is possible to set an effect on a hardware buffer, but doing so confers no advantages.

Effects might not work smoothly on very small buffers. DirectSound does not permit the creation of effects-capable buffers that hold less than 150 milliseconds of data. This value is defined as DSBSIZE_FX_MIN.

The following sample function sets an echo effect on a buffer and displays the result in the output window of the development environment.

HRESULT SetEcho(LPDIRECTSOUNDBUFFER8 pDSBuffer)
{
  HRESULT hr;
  DWORD dwResults[1];  // One element for each effect.
 
  // Describe the effect.
  DSEFFECTDESC dsEffect;
  memset(&dsEffect, 0, sizeof(DSEFFECTDESC));
  dsEffect.dwSize = sizeof(DSEFFECTDESC);
  dsEffect.dwFlags = 0;
  dsEffect.guidDSFXClass = GUID_DSFX_STANDARD_ECHO;
 
  // Set the effect
  if (SUCCEEDED(hr = pDSBuffer->SetFX(1, &dsEffect, dwResults)))
  {
    switch (dwResults[0])
    {
      case DSFXR_LOCHARDWARE:
        OutputDebugString("Effect was placed in hardware.");
        break;
      case DSFXR_LOCSOFTWARE:
        OutputDebugString("Effect was placed in software.");
        break;
      case DSFXR_UNALLOCATED:
        OutputDebugString("Effect is not yet allocated to hardware or software.");
        break;
    }
  }
  return hr;
}