Platform SDK: DirectX

下位レベル DLS

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、下位レベルでの DLS データの操作はサポートされていない。

[C++]

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

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

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

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

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

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

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

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

 :  GetBuffer メソッドは 2 つある。

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

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

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

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

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

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

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

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

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

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

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

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