Microsoft DirectX 8.0 (C++)

下位レベル DLS

DLS コレクションを編集するアプリケーションを作成している場合は、DirectMusic 音色オブジェクトにカプセル化することなく、音色データをシンセサイザにダウンロードできる必要がある。

DLS データを操作するには、DLS の仕様およびファイル構造についての知識が必要となる。これらの情報の詳細については、MIDI Manufactures Association に問い合わせること。

未加工の音色データをダウンロードするには、最初に、次のサンプル コードのように IDirectMusicPortDownload8 インターフェイスへのポインタを取得する必要がある。ここでは、pIPortIDirectMusicPort8 インターフェイスへの有効なポインタであることを想定している。

IDirectMusicPortDownload **ppIDownloadPort;
 
HRESULT hr = pIPort->QueryInterface(IID_IDirectMusicPortDownload8,
        (void **) ppIDownloadPort);

HRESULT が S_OK ではない場合、そのポートは DLS のダウンロードをサポートしていない。

次に、準備およびダウンロードしなければならないバッファを識別する。音色をシンセサイザに送信するには、音色全体の定義を表し、すべてのリージョンとアーティキュレーションを備えた 1 つの音色バッファと、一連のウェーブ バッファを作成する。音色がリージョン用に参照する 1 つのウェーブにつき、1 つのウェーブ バッファを作成する。

各バッファには、固有の識別子を付けなければならない。これらの識別子を使ってバッファ間のリンク、特にリージョンとウェーブのリンクを解決する。ダウンロードする必要のあるバッファ数を集計し、IDirectMusicPortDownload8::GetDLId を呼び出して、識別子の範囲を割り当てる。たとえば、1 つの音色を 3 つのウェーブと共にダウンロードする場合、全部で 4 つのバッファをダウンロードしなければならないので、4 つの識別子を要求する。

バッファごとに必要なサイズを計算し、次に IDirectMusicPortDownload8::AllocateBuffer を呼び出してそのサイズを割り当てる。このメソッドは、バッファを表す IDirectMusicDownload8 インターフェイスを返す。メモリにアクセスするには、IDirectMusicDownload8::GetBuffer を呼び出す。

  GetBuffer メソッドは 2 つある。

IDirectMusicPortDownload8::GetBuffer は、ダウンロード識別子が既知のバッファ オブジェクトに対する IDirectMusicDownload インターフェイス ポインタを返す。

IDirectMusicDownload::GetBuffer は、バッファのメモリへのポインタを返す。

今度はデータをバッファに書き込む。各バッファは DMUS_DOWNLOADINFO 構造体によって指定された場所で始まる。この構造体は、サイズとダウンロードの機能を定義する。この構造体は、次の方法で準備しなければならない。

DMUS_DOWNLOADINFO 構造体は、常に DMUS_OFFSETTABLE 構造体に従う。このオフセット テーブルを使って、データ内のすべてのリンクを管理する。データ内の構造体がほかの構造体を参照する場合はいつでも、ポインタではなく整数のインデックス番号を使う。データ内にある参照可能なすべての構造体には、一意のインデックス番号が割り当てられている。DMUS_OFFSETTABLE は、この整数インデックス番号をデータ内のバイト オフセットに平行移動する。

音色データまたはウェーブ データは、DMUS_OFFSETTABLE に従う。音色をダウンロードする場合は、DMUS_INSTRUMENT 構造体で指定された場所からデータが始まる。それ以外のものをダウンロードする場合は、DMUS_WAVE 構造体で指定された場所からデータが始まる。

DMUS_INSTRUMENT 構造体に従う音色データは、次の構造体で構成される。

DMUS_WAVE 構造体で示されるウェーブ データは、DMUS_WAVEDATA 構造体で構成される。

バッファすべてが準備できている場合、IDirectMusicPortDownload8::Download を使ってそれらをダウンロードする。最初にウェーブ バッファをダウンロードすること。その結果ウェーブ バッファが適切な場所に配置され、音色をダウンロードするときに参照できる。

バッファをダウンロードすると、シンセサイザは音色を演奏できる状態になる。バッファをダウンロードした後、そのバッファで使われているメモリにはアクセスできなくなる。

その後、音色の演奏が終了したら、バッファのアンロードと解放を行う。最初に音色バッファをアンロードし、次にすべてのウェーブ バッファをアンロードする。アンロードするには、IDirectMusicDownload8 ポインタを IDirectMusicPortDownload8::Unload に渡す。次に、IDirectMusicDownload8::Release を呼び出して、各バッファを解放する。

既にダウンロードされている音色を更新する場合、ダウンロード済みのバッファの上書きはできない。代わりに、ウェーブではなく音色を置き換える。音色を置き換えるには、IDirectMusicPortDownload8::AllocateBuffer を呼び出し、適切なバッファ サイズを指定して新しい IDirectMusicDownload8 インターフェイスを割り当てる。IDirectMusicPortDownload8::GetDLId を呼び出して、バッファの新しい識別子を生成すること。新しいアーティキュレーション情報をバッファに書き込み、次にバッファをダウンロードする。次に、IDirectMusicPortDownload8::Unload を呼び出して、以前にダウンロードされていたバッファをアンロードする。

ウェーブ バッファを更新する場合は、もう 1 つステップが増える。新しいウェーブ バッファと、そのバッファを参照する更新された音色バッファの 2 つを作成する。新しいウェーブ バッファ、次いで新しい音色バッファをダウンロードする。さらに古い音色バッファ、次いで古いウェーブ バッファをアンロードする。