A port is a device that sends or receives musical data. It may correspond to a hardware device, a software synthesizer, or a software filter.
Each port in a DirectMusic application is represented by an IDirectMusicPort 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.
Every performance must have at least one port. To create a port object, you must first set up a DMUS_PORTPARAMS structure. You don't have to fill in all members, but you do need to let DirectMusic know which members have valid information by putting the appropriate flags in the dwValidParams member. Then you pass the structure to the IDirectMusic::CreatePort method.
The following C++ code demonstrates how an object might be created for the default port, setting five channel groups on the port. It is assumed that pDirectMusic is a valid IDirectMusic pointer.
IDirectMusicPort* pPort;
DMUS_PORTPARAMS dmos;
ZeroMemory( &dmos, sizeof(DMUS_PORTPARAMS) );
dmos.dwSize = sizeof(DMUS_PORTPARAMS);
dmos.dwValidParams = DMUS_PORTPARAMS_CHANNELGROUPS;
dmos.dwChannelGroups = 5;
HRESULT hr = pDirectMusic->CreatePort( GUID_NULL, &dmos,
&pPort, NULL )
Once you have a port, you must activate it by calling IDirectMusic::Activate or IDirectMusicPort::Activate and attach it to the performance by using the IDirectMusicPerformance::AddPort method.
When you add a port to a performance, you must assign a block of PChannels to it by calling the IDirectMusicPerformance::AssignPChannelBlock method. The only time this is not necessary is when you add the default port by passing NULL to IDirectMusicPerformance::AddPort. In that case, PChannels 0 to 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 IDirectMusicPerformance::AssignPChannelBlock and IDirectMusicPerformance::AssignPChannel methods.
More information about ports is contained in the following topics: