Microsoft DirectX 8.0 (C++) |
DLS コレクションを編集するアプリケーションを作成している場合は、DirectMusic 音色オブジェクトにカプセル化することなく、音色データをシンセサイザにダウンロードできる必要がある。
DLS データを操作するには、DLS の仕様およびファイル構造についての知識が必要となる。これらの情報の詳細については、MIDI Manufactures Association に問い合わせること。
未加工の音色データをダウンロードするには、最初に、次のサンプル コードのように IDirectMusicPortDownload8 インターフェイスへのポインタを取得する必要がある。ここでは、pIPort が IDirectMusicPort8 インターフェイスへの有効なポインタであることを想定している。
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 つを作成する。新しいウェーブ バッファ、次いで新しい音色バッファをダウンロードする。さらに古い音色バッファ、次いで古いウェーブ バッファをアンロードする。