Platform SDK: DirectX

IDirectMusicPort::DownloadInstrument

IDirectMusicPort::DownloadInstrument メソッドは、DLS デバイスに楽器をダウンロードするために使われる。音色をダウンロードすることは、音色を構成するデータを DLS デバイスに渡すことを意味する。この中には、楽器が必要とするアーティキュレーションデータとすべてのウェーブが含まれる。ウェーブのスペースを節約するために、その範囲で必要とされるウェーブとアーティキュレーションだけがダウンロードされる。このメソッドは IDirectMusicDownloadedInstrument インターフェイスポインタを返すが、これは後で楽器をアンロードするために使われる。

HRESULT DownloadInstrument(
  IDirectMusicInstrument *pInstrument,
  IDirectMusicDownloadedInstrument **ppDownloadedInstrument,
  DMUS_NOTERANGE *pNoteRanges,
  DWORD dwNumNoteRanges;
  );

パラメータ

pInstrument
メソッドによるデータのダウンロード元となる音色。
ppDownloadedInstrument
IDirectMusicDownloadedInstrument インターフェイスへのポインタを受け取る変数のアドレス。
pNoteRanges
DMUS_NOTERANGE 構造体の配列のアドレス。配列内の各エントリは、楽器が応答しなければならない MIDI 音符メッセージの連続範囲を指定する。音色のリージョンがダウンロードされるのは、そのリージョン内の少なくとも 1 つの音符が DMUS_NOTERANGE 構造体で指定されている場合に限られる。
dwNumNoteRanges
pNoteRanges が指す配列内の DMUS_NOTERANGE 構造体の数。この値が 0 に設定されている場合、pNoteRanges パラメータは無視され、この音色のすべてのリージョンとウェーブ データがダウンロードされる。

戻り値

成功すれば S_OK を返す。

失敗すれば次のエラー値のいずれかを返す。

E_POINTER
E_OUTOFMEMORY
E_NOTIMPL

注意

メモリの浪費を防ぐには、音色が不要になったときに、IDirectMusicPort::UnloadInstrumentIDirectMusicDownloadedInstrument::Release の両方を呼び出して、アンロードしなければならない。

動作環境

  Windows NT/2000 : Windows 2000 が必要。
  Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
  ヘッダー : dmusicc.h で宣言。

参照

IDirectMusicPort::Compact音色の操作