Microsoft DirectX 8.0 (C++)

IDirectMusicPerformance8::DownloadInstrument

音色に対応する DLS データをポートにダウンロードする。

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

パラメータ

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

戻り値

成功した場合は S_OK を返す。

失敗した場合は、次のいずれかのエラー値を返す。

E_INVALIDARG
E_POINTER

注意

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

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

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

動作環境

  ヘッダー : dmusici.h で宣言。

参照

IDirectMusicPort8::DownloadInstrumentIDirectMusicPort8::UnloadInstrument音色の操作