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 returned.

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

See Remarks.

pDirectSound

IDirectSound interface to use by default for wave output. If this value is NULL, DirectMusic will create a DirectSound object. Note, however, that there should 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 will be 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 may return one of the following error values:

Remarks

This method should be called only once, and must be called before the performance can play.

There are three different ways of associating a DirectMusic object with the performance:

1. 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.
2. The application wants the performance to do the work of creating 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.
3. The application has no use for a DirectMusic object pointer, and just wants the performance to initialize itself. 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 in order to pass the current foreground window handle to DirectSound. However, it is not wise to assume that the application window will be 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.

QuickInfo

  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