IDirectMusicPerformance8::Init

The Init method associates the performance with a DirectMusic object and a DirectSound object. If the application is not using audiopaths, this method must be called before the performance can play.

For applications that use audiopaths, this method has been superseded by IDirectMusicPerformance8::InitAudio.

Syntax

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

Parameters

ppDirectMusic

Address of a variable that specifies or receives an interface pointer to a DirectMusic object.

If the variable pointed to by ppDirectMusic contains a valid IDirectMusic or IDirectMusic8 interface pointer, the existing object is assigned to the performance. The reference count of the interface is incremented. Ports passed to the IDirectMusicPerformance8::AddPort method must be created from this DirectMusic object.

If the variable pointed to by ppDirectMusic contains NULL, a DirectMusic object is created and an IDirectMusic interface pointer is returned. Use QueryInterface to obtain IDirectMusic8.

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

See Remarks.

pDirectSound

IDirectSound8 interface pointer to use by default for wave output. If this value is NULL, DirectMusic creates a DirectSound object. There should, however, be only one DirectSound object per process. If your application uses DirectSound separately, it should pass in that interface here, or to IDirectMusic8::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 IDirectSound8::SetCooperativeLevel.

Return Values

If the method succeeds, the return value is S_OK.

If it fails, the method can return one of the error values shown in the following table.

Remarks

This method can be called only once. It cannot be used to retrieve an existing IDirectMusic8 interface.

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 IDirectMusic8 pointer in ppDirectMusic. In this case, the pDirectSound and hWnd parameters are ignored because the application is responsible for calling IDirectMusic8::SetDirectSound.
• The application allows the performance to create the DirectMusic object and needs 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 IDirectMusicPerformance8::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. It is best to pass the top-level application window handle.

Requirements

  Header: Declared in dmusici.h.

See Also

• IDirectMusicPerformance8
• Migrating from Ports to Audiopaths