Microsoft DirectX 9.0 SDK Update (October 2004)

Retrieving Objects from an Audiopath

It is often necessary to retrieve an interface to a particular object within the audiopath. Common reasons to do so include the following:

To manipulate the 3-D properties of sounds by obtaining an IDirectSound3DBuffer8 interface.
To set global 3-D sound properties by obtaining an IDirectSound3DListener8 interface from the primary buffer.
To set effects on a secondary buffer by obtaining the IDirectSoundBuffer8 interface.
To set effect parameters by obtaining an interface to a DMO such as IDirectSoundFXI3DL2Reverb8.

Objects can be retrieved from an audiopath by calling IDirectMusicSegmentState8::GetObjectInPath on the segment state that is playing on the audiopath. You can also call IDirectMusicAudioPath8::GetObjectInPath on the audiopath object itself. The following table gives information about the parameters to these two methods.

*dwStage*	*guidObject*	dwPChannel used?	dwIndex used?	iidInterface (typical)
DMUS_PATH_AUDIOPATH (*)	Ignored	No	No	IID_IDirectMusicAudioPath8
DMUS_PATH_AUDIOPATH_GRAPH	Ignored	No	No	IID_IDirectMusicGraph8
DMUS_PATH_AUDIOPATH_TOOL	Tool class ID or GUID_All_Objects to enumerate	Yes	Yes	IID_IDirectMusicTool8
DMUS_PATH_BUFFER	Ignored	Yes	No, identify by dwBuffer	IID_IDirectSoundBuffer8
DMUS_PATH_BUFFER_DMO	DMO class ID, such as GUID_DSFX_STANDARD_GARGLE, or GUID_All_Objects to enumerate	Yes	Yes; index of DMO within buffer	GUID for standard DMO interface, such as IID_IDirectSoundFXGargle(**)
DMUS_PATH_MIXIN_BUFFER	Ignored	No	No, identify by dwBuffer	IID_IDirectSoundBuffer8
DMUS_PATH_MIXIN_BUFFER_DMO	DMO class ID, such as GUID_DSFX_STANDARD_I3DL2REVERB, or GUID_All_Objects to enumerate	No	Yes; index of DMO within buffer	GUID for standard DMO interface, such as IID_IDirectSoundFXI3DL2Reverb(**)
DMUS_PATH_PERFORMANCE	Ignored	No	No	IID_IDirectMusicPerformance8
DMUS_PATH_PERFORMANCE_GRAPH	Ignored	No	No	IID_IDirectMusicGraph8
DMUS_PATH_PERFORMANCE_TOOL	Tool class ID or GUID_All_Objects to enumerate	Yes	Yes	IID_IDirectMusicTool8
DMUS_PATH_PORT	Port class ID or GUID_All_Objects to enumerate	Yes	Yes	IID_IDirectMusicPort
DMUS_PATH_PRIMARY_BUFFER	Ignored	No	No	IID_IDirectSound3DListener8
DMUS_PATH_SEGMENT (*)	Ignored	No	No	IID_IDirectMusicSegment8
DMUS_PATH_SEGMENT_GRAPH (*)	Ignored	No	No	IID_IDirectMusicGraph8
DMUS_PATH_SEGMENT_TOOL (*)	Tool class ID or GUID_All_Objects to enumerate	Yes	Yes	IID_IDirectMusicTool8
DMUS_PATH_SEGMENT_TRACK (*)	Track class ID or GUID_All_Objects to enumerate	No	Yes	IID_IDirectMusicTrack8

Notes (*) Objects in this stage cannot be retrieved by IDirectMusicAudioPath8::GetObjectInPath.

(**) The standard DMOs provided with DirectX also support the IMediaObject, IMediaObjectInPlace, and IMediaParams interfaces.

For more information on the values for dwIndex when retrieving standard buffers, see Standard Audiopaths.

The following example function retrieves a segment from the segment state that was created when the segment was played:

HRESULT GetSegmentFromState(IDirectMusicSegmentState* pSegState, IDirectMusicSegment8** ppSeg)
{
  IDirectMusicSegmentState8* pSegState8;
  HRESULT hr;

  if (SUCCEEDED(hr = pSegState->QueryInterface(IID_IDirectMusicSegmentState8, 
                (void**) &pSegState8)))
  {
    hr = SUCCEEDED(pSegState8->GetObjectInPath(0, DMUS_PATH_SEGMENT, 0, 
                  GUID_NULL, 0, IID_IDirectMusicSegment, (void**) ppSeg));
    pSegState8->Release();
  }
  return hr;
}

If you already have an interface to an effects buffer, it is also possible to retrieve a DMO interface by using IDirectSoundBuffer8::GetObjectInPath.

You can retrieve an IDirectSoundBuffer8 interface for any buffer in the audiopath, but some methods are not valid. For more information, see the IDirectSoundBuffer8 interface in the DirectX documentation.

It is not possible to change parameters of a buffer that were set when the buffer was created by DirectMusic, such as the 3-D algorithm. However, you can specify such parameters when creating custom audiopaths in DirectMusic Producer.