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 code example creates a performance and obtains a pointer to the IDirectMusicPerformance8 interface:

IDirectMusicPerformance8* pPerf;
 
if (FAILED(CoCreateInstance(
    CLSID_DirectMusicPerformance,
    NULL,
    CLSCTX_INPROC, 
    IID_IDirectMusicPerformance8,
    (void**)&pPerf
  )))
{
  pPerf = NULL;
}

After the performance is created, it must be initialized. If your application is using audiopaths, as is recommended, you must call the IDirectMusicPerformance8::InitAudio method. Applications using the earlier channel-to-port mapping model call IDirectMusicPerformance8::Init instead. For more information, see Migrating from Ports to Audiopaths.

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 or not 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 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 creating a DirectSoundCapture object or for playing waves directly into 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 need to do this.

The following code example 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.

// hWnd is the application window handle 
 
if (SUCCEEDED(pPerf->InitAudio(NULL, NULL, hWnd, 
    DMUS_APATH_SHARED_STEREOPLUSREVERB, 16, 
    DMUS_AUDIOF_ALL, NULL)))
{
  // Performance initialized.
}