An instrument is an object that represents a basic musical timbre or other sound. For all ports except legacy hardware MIDI ports, each instrument is associated with its own set of downloadable sounds (DLS), which must be downloaded to the port before the instrument can be used.
Downloadable sounds can be handled at three levels of abstraction. At the highest level, you load a band from a file and let the band object handle the DLS downloading for the instruments. At the next level, you directly access individual instruments in a collection and download them to a port. At the lowest level, you work with the DLS data itself.
The following objects and interfaces are used for managing instruments.
Instruments are stored in a DirectMusicCollection object, which represents an instance of a DLS file. Once the DirectMusicCollection object has been loaded, the IDirectMusicCollection interface can be used to enumerate instruments in the collection and to obtain a pointer to an instrument that has a given MIDI patch number.
An instrument from a collection is represented by a pointer to the IDirectMusicInstrument interface. This pointer can be passed to the IDirectMusicPerformance::DownloadInstrument or IDirectMusicPort::DownloadInstrument method to download DLS data to a port.
Once an instrument has been downloaded, it is represented by an IDirectMusicDownloadedInstrument interface pointer. This pointer is used only to unload the instrument by calling IDirectMusicPort::UnloadInstrument.
Applications that need to download their own DLS data for an instrument (such as collection editing tools) use the methods of the IDirectMusicPortDownload interface (implemented by the port object) to get that data to the synthesizer. When this interface is used to allocate a buffer for instrument data, an IDirectMusicDownload interface pointer is returned. The single method of this interface can be used to obtain a pointer to the buffer itself.
The DirectMusicBand object represents a set of instruments and MIDI program changes for a musical segment. The band is created in an authoring tool and can be loaded separately from a file, or it can be part of an authored segment.
The IDirectMusicBand interface can be used to download and unload bands. It also has a method for creating a secondary segment from a band. This segment can be played by the performance in order to effect program changes.
The key differences between a collection and a band are as follows: