^{Using 3-D Sound in DirectMusic}

Using the DirectSound API, you can locate DirectMusic sounds in space and can apply Doppler shift to moving sounds.

3-D effects are applied to individual DirectSound buffers. Because you can direct different sounds along different audiopaths, each with its own buffer, it's easy to apply different parameters to different sounds.

To apply 3-D effects to a buffer, you must obtain an IDirectSound3DBuffer8 interface to a buffer that has 3-D capabilities, such as one in the DMUS_APATH_DYNAMIC_3D standard audiopath. You can also create a suitable audiopath from a configuration object that specifies 3-D parameters for a buffer.

The following example code creates a standard audiopath and retrieves an IDirectSound3DBuffer8 interface. Assume that g_pPerformance is a valid IDirectMusicPerformance8 pointer.

HRESULT                  hr;
IDirectMusicAudioPath8*  g_p3DAudioPath;
IDirectSound3DBuffer8*   g_pDS3DBuffer; 

if (SUCCEEDED(hr = g_pPerformance->CreateStandardAudioPath(
    DMUS_APATH_DYNAMIC_3D, 64, TRUE, &g_p3DAudioPath)))
{
  hr = g_p3DAudioPath->GetObjectInPath( 
      DMUS_PCHANNEL_ALL, DMUS_PATH_BUFFER, 0,
      GUID_NULL, 0, IID_IDirectSound3DBuffer8, 
      (LPVOID*) &g_pDS3DBuffer);
}
if (FAILED(hr))
{
  ErrorExit(hr);  // Add error-handling code.
}

To adjust global 3-D parameters and manipulate the position and orientation of the listener, you must obtain an IDirectSound3DListener8 interface from the primary buffer in any audiopath by using IDirectMusicAudioPath8::GetObjectInPath or IDirectMusicSegmentState8::GetObjectInPath, setting the dwStage parameter to DMUS_PATH_PRIMARY_BUFFER. The following example function retrieves the listener from an audiopath:

HRESULT GetListener(IDirectMusicAudioPath8* pPath, IDirectSound3DListener8** ppListener)
{
  HRESULT hr = E_INVALIDARG;

  if (NULL != pPath)
  {
    hr = pPath->GetObjectInPath(0, DMUS_PATH_PRIMARY_BUFFER, 0,
                                GUID_NULL, 0, IID_IDirectSound3DListener8, 
                                (LPVOID*) ppListener);
  }
  return hr;
}}

See Also

• Retrieving Objects from an Audiopath
• Standard Audiopaths.