Microsoft DirectX 8.0 (C++)

IDirectMusicBand8::Download

バンド内の音色の DLS データをパフォーマンス オブジェクトにダウンロードする。

HRESULT Download(
  IDirectMusicPerformance* pPerformance
);

パラメータ

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

戻り値

成功した場合は 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 で宣言。

参照

IDirectMusicBand8::Unload