The information in this topic pertains only to applications written in C++. See Overview of DirectMusic Classes.

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.

Collection

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.

Instrument

An instrument from a collection is represented by a pointer to the IDirectMusicInstrument interface. This pointer can be passed to the IDirectMusicPerformance::DownloadInstrument or the 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.

Band

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 or style.

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 to effect program changes.

The key differences between a collection and a band are as follows:

• A collection is a group of instruments available for use in the playback of any segment. A band is a group of instruments that actually plays a particular segment.
• Instruments in a collection contain DLS data defining their timbre. Instruments in a band contain no such data but are linked to instruments in one or more collections.
• An instrument from a collection is not inherently associated with any particular performance channel (PChannel) of a segment. A band assigns the patch number of an instrument to each PChannel in a segment and assigns a voice priority to the channel.
• A collection does not contain any information about how the instruments are to be played. A band contains settings for the volume, pan, and transposition of each instrument.