Microsoft DirectX 9.0

IDirectMusicPerformance8::InitAudio

The InitAudio method initializes the performance and optionally sets up a default audiopath. This method must be called before the performance can play using audiopaths.

This method should be used in most cases instead of IDirectMusicPerformance8::Init.

Syntax

HRESULT InitAudio(
  IDirectMusic** ppDirectMusic,
  IDirectSound** ppDirectSound,
  HWND hWnd,
  DWORD dwDefaultPathType,
  DWORD dwPChannelCount,
  DWORD dwFlags,
  DMUS_AUDIOPARAMS *pParams
);

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.

If the variable pointed to by ppDirectMusic contains NULL, a DirectMusic object is created and the 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.

ppDirectSound

Address of a variable that specifies or receives an IDirectSound interface pointer for a DirectSound device object to use by default for waveform output. If this parameter contains a NULL pointer, DirectMusic creates a private DirectSound device object. If the variable pointed to contains NULL, DirectMusic creates a DirectSound device object and returns the interface pointer. See Remarks.

hWnd

Window handle to use 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 an IDirectSound interface pointer is passed to the method in ppDirectSound. In that case the application is responsible for setting the window handle by using IDirectSound8::SetCooperativeLevel.

dwDefaultPathType

Value that specifies the default audiopath type. Can be zero if no default path type is wanted. For a list of defined values, see IDirectMusicPerformance8::CreateStandardAudioPath.

dwPChannelCount

Value that specifies the number of performance channels to allocate to the path, if dwDefaultPathType is not zero.

dwFlags

Flags that specify requested features. If pParams is not NULL, this value is ignored and the requested features are specified in the dwFeatures member of the DMUS_AUDIOPARAMS structure. The values listed in the following table are defined for use in this parameter.

Value Description
DMUS_AUDIOF_3D 3-D buffers.
DMUS_AUDIOF_ALL All features.
DMUS_AUDIOF_BUFFERS Multiple buffers.
DMUS_AUDIOF_DMOS Additional DMOs.
DMUS_AUDIOF_ENVIRON Environmental modeling.
DMUS_AUDIOF_EAX EAX effects.
DMUS_AUDIOF_STREAMING Support for streaming waveforms.

pParams

Address of a DMUS_AUDIOPARAMS structure that specifies parameters for the synthesizer and receives information about what parameters were set. Can be NULL if the default parameters are wanted.

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.

Return code
DMUS_E_ALREADY_INITED
DSERR_BUFFERLOST
DSERR_PRIOLEVELNEEDED
DSERR_UNINITIALIZED
E_NOINTERFACE
E_OUTOFMEMORY
E_POINTER

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 the following ways.

If you specify an interface pointer in ppDirectSound, it must be an interface to an object of class CLSID_DirectSound8. Objects of this class support both IDirectSound and IDirectSound8, but the IDirectSound interface must be passed. For information on how to create an object of this class, see the Remarks for IDirectSound8. The DirectSound device object must be fully initialized before being passed to InitAudio. If the object was created by using CoCreateInstance, call IDirectSound8::Initialize. Set the cooperative level to DSSCL_PRIORITY by using IDirectSound8::SetCooperativeLevel.

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.

The parameters set in dwFlags and pParams apply to the default audiopath and any audiopaths created subsequently.

The method fails with DSERR_BUFFERLOST if a value other than zero is passed in dwDefaultPathType and any application has initialized DirectSound with the write-primary cooperative level.

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

Requirements

  Header: Declared in dmusici.h.

See Also