Retrieving Objects from an Audiopath

DirectMusic

Microsoft DirectX 9.0 SDK Update (Summer 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.


© 2004 Microsoft Corporation. All rights reserved.