^{Creating the Performance}

The performance object is the overall manager of playback. Among the tasks it performs are the following:

• Managing ports and audiopaths
• Mapping channels to audiopaths
• Playing and stopping segments
• Dispatching messages
• Managing tools and timing

Most applications have a single performance object, but it is possible to have more than one performance with different parameters, such as master tempo or volume.

The following example function creates a performance and returns a pointer to the IDirectMusicPerformance8 interface:

HRESULT GetPerformance(IDirectMusicPerformance8** ppPerf)
{
  return CoCreateInstance(CLSID_DirectMusicPerformance,
                NULL, CLSCTX_INPROC, IID_IDirectMusicPerformance8,
               (void**)ppPerf);
}

After the performance is created, it must be initialized. If your application is using audiopaths, you must call the IDirectMusicPerformance8::InitAudio method. Applications using the earlier channel-to-port mapping model must call IDirectMusicPerformance8::Init instead.

An important part of initialization is the creation of a DirectMusic object. You can pass an existing IDirectMusic8 interface pointer to IDirectMusicPerformance8::InitAudio, but in most cases it is more convenient to have InitAudio create the DirectMusic object. You can also choose whether to retrieve a pointer to the IDirectMusic8 interface, depending on how much control you need over ports and the master clock. Most applications don't need access to the methods of IDirectMusic8 and can pass NULL as the ppDirectMusic parameter of InitAudio.

InitAudio can also take an existing DirectSound device object. DirectSound manages the sound data after it leaves the synthesizer. In most cases you can let InitAudio create this object. You don't need an interface to it unless you intend to use DirectSound for other purposes such as playing waveforms directly into DirectSound secondary buffers rather than through the DirectMusic performance.

By passing a DMUS_AUDIOPARAMS structure to InitAudio, the application can request synthesizer capabilities or set a synthesizer other than the default one. Most applications don't have to do this.

The following example function initializes the performance without retrieving pointers to the DirectMusic and DirectSound objects. It creates a standard default audiopath with 16 performance channels and all available features on the port. The hWnd parameter is the application window handle.

BOOLEAN Init(IDirectMusicPerformance8* pPerf, HWND hWnd)
{
  if (FAILED(pPerf->InitAudio(NULL, NULL, hWnd, 
      DMUS_APATH_SHARED_STEREOPLUSREVERB, 16, 
      DMUS_AUDIOF_ALL, NULL)))
  {
    return FALSE;
  }
  else return TRUE;
}