Platform SDK: DirectX

IDirectMusicPerformance::DownloadInstrument

IDirectMusicPerformance::DownloadInstrument メソッドは、音色の DLS データをポートにダウンロードする。

HRESULT DownloadInstrument(
  IDirectMusicInstrument* pInst,
  DWORD dwPChannel,
  IDirectMusicDownloadedInstrument** ppDownInst,
  DMUS_NOTERANGE* pNoteRanges, 
  DWORD dwNumNoteRanges, 
  IDirectMusicPort** ppPort,
  DWORD* pdwGroup,
  DWORD* pdwMChannel
);

パラメータ

pInst
ダウンロードする音色を含む変数のアドレス。
dwPChannel
楽器の割り当て先のパフォーマンス チャンネル (P チャンネル)。
ppDownInst
ダウンロードされた楽器へのポインタを受け取る変数のアドレス。
pNoteRanges
DMUS_NOTERANGE 構造体の配列のアドレス。配列内の各エントリは、楽器が応答しなければならない MIDI 音符メッセージの連続範囲を指定する。音色のリージョンがダウンロードされるのは、そのリージョン内の少なくとも 1 つの音符が DMUS_NOTERANGE 構造体で指定されている場合に限られる。
dwNumNoteRanges
pNoteRanges が指す配列内の DMUS_NOTERANGE 構造体の数。この値が 0 に設定されている場合、pNoteRanges パラメータは無視され、この音色用のすべてのリージョンとウェーブ データがダウンロードされる。
ppPort
音色のダウンロード先のポートへのポインタを受け取る変数のアドレス。
pdwGroup
音色の割り当て先のグループを受け取る変数のアドレス。
pdwMChannel
音色の割り当て先の MIDI チャンネルを受け取る変数のアドレス。

戻り値

成功すれば S_OK を返す。

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

E_INVALIDARG
E_POINTER

注意

音色のダウンロードは通常、バンドによって処理されるため、ほとんどのアプリケーションではこのメソッドを使う必要がない。「バンドのダウンロードとアンロード」を参照すること。

P チャンネルがポートに割り当てられていない場合、このメソッドは E_INVALIDARG を返す。

リソースの浪費を防ぐには、音色が不要になったときに、IDirectMusicPort::UnloadInstrument メソッドを使ってアンロードする。

動作環境

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

参照

IDirectMusicPort::DownloadInstrument,IDirectMusicPort::UnloadInstrument音色の操作