Platform SDK: DirectX |
IDirectMusicBand::Download メソッドは、バンド内の音色の DLS データをパフォーマンス オブジェクトにダウンロードする。このメソッドは、IDirectMusicPerformance::DownloadInstrument メソッドを呼び出すことによって、バンド内の各音色をダウンロードする。DownloadInstrument は音色の P チャンネルを使って適切なポートを見つけ、そのポートに対して IDirectMusicPort::DownloadInstrument メソッドを呼び出す。
バンドのダウンロードが終わると、そのバンド内の音色は、プログラム チェンジ MIDI メッセージにより個別に選択するか、IDirectMusicBand::CreateSegment メソッドを呼び出して作成したバンド セグメントを再生することにより一度にすべてを選択できる。
HRESULT Download( IDirectMusicPerformance* pPerformance );
成功すれば S_OK または DMUS_S_PARTIALDOWNLOAD を返す (「注意」を参照すること)。
失敗すれば次のエラー値のいずれかを返す。
DMUS_E_NOT_INIT |
E_OUTOFMEMORY |
E_POINTER |
ダウンロードしたバンドはシンセサイザ リソースを使うため、必要のないときは IDirectMusicBand::Unload メソッドを使ってアンロードしなければならない。
現在のバージョンの DirectMusic の場合、ポートが DLS をサポートしていなくても S_OK が返されることがある。
ダウンロードが完全に失敗した場合は、DMUS_E_NOT_INIT が返される。これは通常、初期化されたポートにパフォーマンスが正常に接続されなかったことを意味する。これは完全な失敗であるため、後で IDirectMusicBand::Unload を呼び出す必要はない。
ダウンロードが一部成功した場合は、DMUS_S_PARTIALDOWNLOAD が返される。これは、正常にダウンロードできた音色とダウンロードできなかった音色があることを意味する。その原因は通常、パフォーマンスとポートの設定においてプログラミング エラーが発生したためである。問題を特定する最良の方法は、Dmime.dll、Dmband.dll、および Dmsynth.dll のデバッグ トレースを 1 に設定することである (「DirectMusic プロジェクトのデバッグ」を参照)。
部分的なダウンロードが発生する一般的な原因を以下に示す。
Windows NT/2000 : Windows 2000 が必要。
Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
ヘッダー : dmusici.hで宣言。