IDirectMusicBand8::Download

Microsoft DirectX 9.0 SDK Update (October 2004)

IDirectMusicBand8::Download

The Download method downloads the DLS data for instruments in the band to a performance object.

Syntax

HRESULT Download(
  IDirectMusicPerformance* pPerformance
);

Parameters

pPerformance

Performance to which instruments are to be downloaded. The performance manages the mapping of performance channels to DirectMusic ports.

Return Values

If the method succeeds, the return value is S_OK, or DMUS_S_PARTIALDOWNLOAD. (See Remarks.)

If it fails, the method can return one of the error values shown in the following table.

Return code

DMUS_E_NOT_INIT

E_OUTOFMEMORY

E_POINTER

Remarks

The method downloads each instrument in the band by calling the IDirectMusicPerformance8::DownloadInstrument method. DownloadInstrument, in turn, uses the performance channel of the instrument to find the appropriate port, and then calls the IDirectMusicPort8::DownloadInstrument method on that port.

After a band has been downloaded, the instruments in the band can be selected, either individually with program-change MIDI messages, or all at once by playing a band segment created through a call to the IDirectMusicBand8::CreateSegment method.

Because a downloaded band uses synthesizer resources, it should be unloaded when no longer needed by using the IDirectMusicBand8::Unload method.

This method may return S_OK even though the port does not support DLS.

If the download completely fails, DMUS_E_NOT_INIT is returned. This usually means that the performance was not properly connected to an initialized port. Because this is a complete failure, there is no need to call IDirectMusicBand8::Unload later.

If the download partially succeeds, DMUS_S_PARTIALDOWNLOAD is returned. This means that some of the instruments successfully downloaded and others did not. This usually occurs because of programming error in setting up the performance and port. The best way to find the problem is to set debug traces to 1 for Dmime.dll, Dmband.dll, and Dmsynth.dll. See Debugging DirectMusic Projects.

The following are some common causes of a partial download:

The band has instruments on performance channels that have not been set up on the performance (by using IDirectMusicPerformance8::AssignPChannelBlock).
The band has instruments on performance channels that are on channel groups not allocated on the port.
The band has instruments in a DLS format incompatible with the synthesizer they are being downloaded to.

Requirements

Header: Dmusici.h
Library: Dmband.dll, Dmbandd.dll

See Also