IDirectMusicPerformance::Init

The IDirectMusicPerformance::Init method associates the performance with a DirectMusic object and a DirectSound object.

HRESULT Init(
  IDirectMusic** ppDirectMusic,
  LPDIRECTSOUND pDirectSound,
  HWND hWnd
);

Parameters

ppDirectMusic

Address of a variable containing the IDirectMusic interface pointer to be assigned to the performance, if one already exists. The reference count of the interface is incremented. Ports passed to the IDirectMusicPerformance::AddPort method must be created from this DirectMusic object.

If the variable contains NULL, a DirectMusic object is created, and the interface pointer is returned.

If ppDirectMusic is NULL, a DirectMusic object is created and used internally by the performance.

See Remarks.

pDirectSound

Address of a IDirectSound interface to use by default for wave output. If this value is NULL, DirectMusic creates a DirectSound object. There should, however, only be one DirectSound object per process. If your application uses DirectSound separately, it should pass in that interface here, or to IDirectMusic::SetDirectSound if the application creates the DirectMusic object explicitly.

hWnd

Window handle to be used for the creation of DirectSound. This parameter can be NULL, in which case the foreground window is used. See Remarks.

This parameter is ignored if pDirectSound is not NULL, in which case the application is responsible for setting the window handle in a call to IDirectSound::SetCooperativeLevel.

Return Values

If the method succeeds, the return value is S_OK.

If it fails, the method can return one of the following error values:

Remarks

This method should be called only once; it must be called before the performance can play.

A DirectMusic object can be associated with the performance in any of the following ways:

• The application creates its own DirectMusic object and gives it to the performance by passing the address of the IDirectMusic pointer in ppDirectMusic. In this case, the pDirectSound and hWnd parameters are ignored because the application is responsible for calling IDirectMusic::SetDirectSound.
• The application allows the performance to create the DirectMusic object and wants a pointer to that object. In this case, *ppDirectMusic is NULL on entry, and contains the IDirectMusic pointer on exit.
• The application allows the performance to initialize itself and does not need a DirectMusic object pointer. In this case, ppDirectMusic is NULL.

The performance must be terminated by using the IDirectMusicPerformance::CloseDown method before being released.

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 will be in the foreground during initialization. In general, the top-level application window handle is 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 dmusici.h.

See Also

Creating the Performance, Integrating DirectMusic and DirectSound