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