CAudioPath

CAudioPath

Purpose: The audiopath manages the stages of data flow from the performance to the final mixer
Remark: The returns values are based on the DirectX9 constants except DM_FAILED
The functions raise a CDMusicException exception type with the error data.
Member functions:

Function: Activate
Declaration: HRESULT CAudioPath::Activate(BOOL bActivate)
Purpose: Activates or deactivates the audiopath
Parameters:

bActivate [in]: Boolean that specifies whether to activate (TRUE) or deactivate (FALSE) the audiopath

Returns:

S_OK

Succeeds

Throws:

S_FALSE	the audiopath is already in the requested state
DM_FAILED	Error, see DirectMidi causes

Top Index

Function: Get3DBuffer
Declaration: HRESULT CAudioPath::Get3DBuffer(C3DBuffer &_3DBuffer)
Purpose: Retrieves a reference to a C3DBuffer object
Parameters:

_3DBuffer [out]: A reference to the 3D buffer

Returns:

S_OK

Succeeds

Throws:

E_POINTER	An invalid pointer, usually NULL, was passed as a parameter
E_NOINTERFACE	No object interface is available
E_OUTOFMEMORY	Insufficient memory to complete the task
E_INVALIDARG	Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
DMUS_E_NOT_FOUND	The requested item is not contained by the object
DM_FAILED	Error, see DirectMidi causes

Top Index

Function: Get3DListener
Declaration: HRESULT CAudioPath::Get3DListener(C3DListener &_3DListener)
Purpose: Retrieves a reference to a C3DListener object
Parameters:

_3DListener [out]: A reference to the 3D listener

Returns:

S_OK

Succeeds

Throws:

E_POINTER	An invalid pointer, usually NULL, was passed as a parameter
E_NOINTERFACE	No object interface is available
E_OUTOFMEMORY	Insufficient memory to complete the task
E_INVALIDARG	Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
DMUS_E_NOT_FOUND	The requested item is not contained by the object
DM_FAILED	Error, see DirectMidi causes

Top Index

Function: GetObjectInPath
Declaration: HRESULT CAudioPath::GetObjectInPath(DWORD dwPChannel, DWORD dwStage, DWORD dwBuffer, REFGUID guidObject,DWORD dwIndex,REFGUID iidInterface,void **ppObject)
Purpose: Retrieves an interface for an object in the audiopath
Parameters:

dwPChannel [in]: Performance channel to search, or DMUS_PCHANNEL_ALL to search all channels. The first channel is numbered 0. (See Remarks.)
dwStage [in]: Stage in the audiopath. Can be one of the values in the following table

Value	Description
DMUS_PATH_AUDIOPATH_GRAPH	Get the audiopath toolgraph. One is created if none exists.
DMUS_PATH_AUDIOPATH_TOOL	Get a tool from the audiopath toolgraph.
DMUS_PATH_BUFFER	Get a DirectSound buffer.
DMUS_PATH_BUFFER_DMO	Get a DMO in a buffer.
DMUS_PATH_MIXIN_BUFFER	Get a global mix-in buffer.
DMUS_PATH_MIXIN_BUFFER_DMO	Get a DMO in a global mix-in buffer.
DMUS_PATH_PERFORMANCE	Get the performance.
DMUS_PATH_PERFORMANCE_GRAPH	Get the performance toolgraph. One is created if none exists.
DMUS_PATH_PERFORMANCE_TOOL	Get a tool from the performance toolgraph.
DMUS_PATH_PORT	Get the synthesizer.
DMUS_PATH_PRIMARY_BUFFER	Get the primary buffer.

dwBuffer [in]: Index of the buffer (if dwStage is DMUS_PATH_BUFFER or DMUS_PATH_MIXIN_BUFFER), or index of the buffer in which the DMO resides (if dwStage is DMUS_PATH_BUFFER_DMO or DMUS_PATH_MIXIN_BUFFER_DMO
guidObject [in]: Class identifier of the object, or GUID_All_Objects to search for an object of any class. This parameter is ignored if only a single class of object can exist at the stage specified by dwStage, and can be set to GUID_NULL
dwIndex [in]: Index of the object within a list of matching objects. Set to 0 to find the first matching object. If dwStage is DMUS_PATH_BUFFER or DMUS_PATH_MIXIN_BUFFER, this parameter is ignored, and the buffer index is specified by dwBuffer
iidInterface [in]: Identifier of the desired interface, such as IID_IDirectMusicTool
ppObject [out]: Address of a variable that receives a pointer to the requested interface

Remarks

The value in dwPChannel must be 0 for any stage that is not channel-specific. Objects in the following stages are channel-specific and can be retrieved by setting a channel number or DMUS_PCHANNEL_ALL in dwPChannel:

DMUS_PATH_AUDIOPATH_TOOL
DMUS_PATH_BUFFER
DMUS_PATH_BUFFER_DMO
DMUS_PATH_PERFORMANCE_TOOL
DMUS_PATH_PORT

The precedence of the parameters in filtering out unwanted objects is as follows:

dwStage.
guidObject. If this value is not GUID_All_Objects, only objects whose class identifier equals guidObject are searched. However, this parameter is ignored for stages where only a single class of object can exist, such as DMUS_PATH_AUDIOPATH_GRAPH.
dwPChannel. If the stage is channel-specific and this value is not DMUS_PCHANNEL_ALL, only objects on the channel are searched.
dwBuffer. This is used only if dwStage is DMUS_PATH_BUFFER, DMUS_PATH_MIXIN_BUFFER, DMUS_PATH_BUFFER_DMO, or DMUS_PATH_MIXIN_BUFFER_DMO.
dwIndex.

If a matching object is found but the interface specified by iidInterface cannot be obtained, the method fails

Returns:

S_OK

Succeeds

Throws:

E_POINTER	An invalid pointer, usually NULL, was passed as a parameter
E_NOINTERFACE	No object interface is available
E_OUTOFMEMORY	Insufficient memory to complete the task
E_INVALIDARG	Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
DMUS_E_NOT_FOUND	The requested item is not contained by the object
DM_FAILED	Error, see DirectMidi causes

Top Index

Function: ReleaseAudioPath
Declaration: HRESULT CAudioPath::ReleaseAudioPath()
Purpose: Releases the audiopath
Parameters: none

Returns:

S_FALSE	Error
S_OK	Succeeds

Top Index

Function: SetVolume
Declaration: HRESULT CAudioPath::SetVolume(long lVolume,DWORD dwDuration)
Purpose: Sets the audio volume on the audiopath. The volume can be faded in or out
Parameters:

lVolume [in]: Value that specifies the attenuation, in hundredths of a decibel.
This value must be in the range from -9600 to 0. Zero is full volume
dwDuration [in]: Value that specifies the time, in milliseconds, over which the volume change takes place. A value of 0 ensures maximum efficiency

Returns:

S_OK

Succeeds

Throws:

E_INVALIDARG	Invalid argument. Often, this error results from failing to initialize the dwSize member of a structure before passing it to the method
DMUS_E_NOT_INIT	A required object is not initialized or failed to initialize
DM_FAILED	Error, see DirectMidi causes

Top Index