Microsoft DirectX 9.0

Using DirectMusic Ports

This section covers access to DirectMusic ports, which is usually required only by applications that do not use audiopaths. A port is a device that sends or receives data. It can correspond to a hardware device, a software synthesizer, or a software filter.

Each port in a DirectMusic application is represented by an IDirectMusicPort8 interface. Methods of this interface are used to retrieve information about the device, manage the memory on the device, download and unload DLS instruments, read incoming data, and cue playback buffers.

If your application initializes the performance by using IDirectMusicPerformance8::InitAudio, as is recommended, the audiopath manages ports and the mapping of performance channels to ports. You can obtain an interface to a port in the audiopath by using the IDirectMusicPerformance8::PChannelInfo method.

Every performance must have at least one port. If you want to use a port other than the default port, or to set special parameters for the default port, first set up a DMUS_PORTPARAMS8 structure. You don't have to fill in all members, but you must let DirectMusic know which members have valid information by putting the appropriate flags in the dwValidParams member. Then pass the structure to the IDirectMusic8::CreatePort method.

The following example function demonstrates how an object might be created for the default port, setting five channel groups on the port.

HRESULT CreateTypicalPort(IDirectMusic8* pDM)
{
  IDirectMusicPort8*  pPort;
  DMUS_PORTPARAMS  dmos;
 
  if (NULL == pDM) return E_INVALIDARG;
  ZeroMemory(&dmos, sizeof(DMUS_PORTPARAMS));
  dmos.dwSize = sizeof(DMUS_PORTPARAMS);
  dmos.dwValidParams = DMUS_PORTPARAMS_CHANNELGROUPS;
  dmos.dwChannelGroups = 5;
  return pDM->CreatePort(GUID_NULL, &dmos, &pPort, NULL);
}

After creating a port, you must activate it by calling IDirectMusic8::Activate or IDirectMusicPort8::Activate and then attach it to the performance by using the IDirectMusicPerformance8::AddPort method.

When you add a port to a performance, assign a block of performance channels to it by calling the IDirectMusicPerformance8::AssignPChannelBlock method. The only time this isn't necessary is when you add the default port by passing NULL to IDirectMusicPerformance8::AddPort. In that case, PChannels 0 through 15 are assigned to the MIDI channels in the first group on the port.

You can map PChannels differently, add more PChannels, or assign PChannels to a different port by using the IDirectMusicPerformance8::AssignPChannelBlock and IDirectMusicPerformance8::AssignPChannel methods.

More information about ports is contained in the following topics: