Platform SDK: DirectX

IDirectMusicBand::Download

IDirectMusicBand::Download メソッドは、バンド内の音色の DLS データをパフォーマンス オブジェクトにダウンロードする。このメソッドは、IDirectMusicPerformance::DownloadInstrument メソッドを呼び出すことによって、バンド内の各音色をダウンロードする。DownloadInstrument は音色の P チャンネルを使って適切なポートを見つけ、そのポートに対して IDirectMusicPort::DownloadInstrument メソッドを呼び出す。

バンドのダウンロードが終わると、そのバンド内の音色は、プログラム チェンジ MIDI メッセージにより個別に選択するか、IDirectMusicBand::CreateSegment メソッドを呼び出して作成したバンド セグメントを再生することにより一度にすべてを選択できる。

HRESULT Download(
  IDirectMusicPerformance* pPerformance
);

パラメータ

pPerformance
楽器のダウンロード先のパフォーマンス。パフォーマンスは P チャンネルから DirectMusic ポートへのマッピングを管理する。

戻り値

成功すれば 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で宣言。

参照

IDirectMusicBand::Unload