IDirectSoundBuffer8::GetObjectInPath Method

Article
09/10/2011

[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.]

The GetObjectInPath method retrieves an interface for an effect object associated with the buffer.

Syntax

HRESULT GetObjectInPath(
         REFGUID rguidObject ,
         DWORD dwIndex ,
         REFGUID rguidInterface ,
         LPVOID * ppObject
)

Parameters

rguidObject
Unique class identifier of the object being searched for, such as GUID_DSFX_STANDARD_ECHO. Set this parameter to GUID_All_Objects to search for objects of any class.
dwIndex
Index of the object within objects of that class in the path. See Remarks.
rguidInterface
Unique identifier of the desired interface. See Remarks.
ppObject
Address of a variable that receives the desired interface pointer.

Return Value

If the method succeeds, the return value is DS_OK. If the method fails, the return value may be one of the following error values:

Return code

DSERR_CONTROLUNAVAIL

DSERR_INVALIDPARAM

DSERR_OBJECTNOTFOUND

Remarks

Any DMO that has been set on a buffer by using SetFX can be retrieved, even it has not been allocated resources.

The following interfaces can be retrieved for the various DMOs supplied with DirectX.

rguidInterface	*ppObject
IID_IDirectSoundFXGargle8	IDirectSoundFXGargle8
IID_IDirectSoundFXChorus8	IDirectSoundFXChorus8
IID_IDirectSoundFXFlanger8	IDirectSoundFXFlanger8
IID_IDirectSoundFXEcho8	IDirectSoundFXEcho8
IID_IDirectSoundFXDistortion8	IDirectSoundFXDistortion8
IID_IDirectSoundFXCompressor8	IDirectSoundFXCompressor8
IID_IDirectSoundFXParamEq8	IDirectSoundFXParamEq8
IID_IDirectSoundFXWavesReverb8	IDirectSoundFXWavesReverb8
IID_IDirectSoundFXI3DL2Reverb8	IDirectSoundFXI3DL2Reverb8

In addition, the following interfaces are available for any of the standard DMOs. For information on these interfaces, see the Help for DirectX Media Objects.

rguidInterface	*ppObject
IID_IMediaObject	IMediaObject
IID_IMediaObjectInPlace	IMediaObjectInPlace
IID_IMediaParams	IMediaParams

NoteWhen the DirectSound API is used to play buffers, parameter curves (envelopes) set by using the IMediaParams interface do not work, because DirectSound does not timestamp the DMO buffers.

The value in dwIndex is the index of the object within the array of effects passed to SetFX. This is not necessarily the actual position of the object in the effects chain, because some effects might not have been created.

An object is returned solely on the basis of whether it matches rguidObject and dwIndex. It is up to the application to ensure that rguidInterface specifies an interface that can be expected to be found on the object.

Requirements

Header: Declared in DSound.h.

Library: Use Dsound3d.dll.

Partager via