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.