Microsoft DirectX 9.0

IDirectMusic8::SetDirectSound

The SetDirectSound method connects DirectMusic to a DirectSound device object for output from the synthesizer.

This method is not used by most applications. The DirectSound device object is normally created and connected to the performance by IDirectMusicPerformance8::InitAudio.

Syntax

HRESULT SetDirectSound(
  LPDIRECTSOUND pDirectSound,
  HWND hWnd
);

Parameters

pDirectSound

Address of the IDirectSound8 interface to use for output. If this parameter is NULL, the method creates a DirectSound device object and sets the DSSCL_PRIORITY cooperative level. (See Remarks.) If this parameter contains an IDirectSound pointer, the caller is responsible for setting the cooperative level.

hWnd

Window handle to the DirectSound device object created by this call. If this value is NULL, the current foreground window is set as the focus window. (See Remarks.)

If pDirectSound is a valid interface, this parameter is ignored. It is the caller's responsibility to supply a valid window handle in the call to IDirectSound8::SetCooperativeLevel.

Return Values

If the method succeeds, the return value is S_OK.

If it fails, the method can return DMUS_E_DSOUND_ALREADY_SET.

Remarks

The specified DirectSound device object is the one used for rendering audio on all ports. This default can be overridden on a particular port by using the IDirectMusicPort8::SetDirectSound method.

Whenever the IDirectMusic8::SetDirectSound method is called, any existing DirectSound device object is released.

When pDirectSound is NULL, a new DirectSound device object is not created until a port that uses DirectSound is activated, and the DirectSound device object is automatically released when the last port using it is deactivated.

If you created the DirectSound device object yourself, you can release it by calling this method with NULL in the pDirectSound parameter after deactivating all ports. (It is an error to call SetDirectSound on an active port.)

You can pass NULL in the hWnd parameter to pass the current foreground window handle to DirectSound. However, do not assume that the application window is in the foreground during initialization. In general, the top-level application window handle should be passed to DirectMusic and DirectSound.

Requirements

  Header: Declared in dmusicc.h.

See Also