IDirectMusic::SetDirectSound

The IDirectMusic::SetDirectSound method connects DirectMusic to a DirectSound object for wave output.

HRESULT SetDirectSound(
  LPDIRECTSOUND pDirectSound,
  HWND hWnd
);

Parameters

pDirectSound

Address of the IDirectSound interface to use for output. If this parameter is NULL, the method creates a DirectSound 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 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 because it is the caller's responsibility to supply a valid window handle in the call to IDirectSound::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 object is the one used for rendering audio on all ports. This default can be overridden by using the IDirectMusicPort::SetDirectSound method.

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

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

If you created the DirectSound 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, it is not wise to assume that the application window is in the foreground during initialization. In general, the top-level application window handle should be passed to DirectMusic, DirectSound, and DirectDraw. See the Remarks for IDirectSound::SetCooperativeLevel.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dmusicc.h.

See Also

Integrating DirectMusic and DirectSound