Platform SDK: DirectX

音色の操作

[Visual Basic]

ここでは、C++ でのアプリケーション開発について説明する。DirectX for Visual Basic では、アプリケーションがコレクションの個々の音色を操作することはできない。

[C++]

DirectMusicCollection を作成してコレクション ファイルからロードした後、IDirectMusicCollection::EnumInstrument メソッドを使って、利用可能なすべての音色のパッチ番号と名前を取り出せる。

次のコード例では、コレクション内のすべての音色を列挙し、その名前とパッチ番号を表示している。

void myListInstruments(
        IDirectMusicCollection *pCollection)
 
{
    HRESULT hr = S_OK;
    DWORD dwPatch;
    WCHAR wszName[MAX_PATH];
    DWORD dwIndex;
    for (dwIndex = 0; hr == S_OK; dwIndex++)
    {
        hr = pCollection->EnumInstrument(
                dwIndex, &dwPatch, wszName, MAX_PATH);
        if (hr == S_OK)
        {
           printf("パッチ %lx は、%S。\n",dwPatch,wszName);
        }
    }
}

IDirectMusicCollection::GetInstrument メソッドに特定の音色のパッチ番号を渡すことにより、その音色へのポインタを取得できる。

音色を取得した後、IDirectMusicInstrument::SetPatch メソッドを使ってパッチ番号を変更できる。

コレクションをロードし、音色を取り出す作業は、音色を利用可能にするための最初のステップに過ぎない。次に、これらの音色をポートにダウンロードしなければならない。

音色をポートにダウンロードするには、IDirectMusicInstrument インターフェイス ポインタを IDirectMusicPort::DownloadInstrument メソッドに渡す。このメソッドは、ポートで DLS データを利用可能にする。音色を特定のパフォーマンスに関連付けることはない。

IDirectMusicPerformance::DownloadInstrument メソッドを使って、音色をダウンロードすることもできる。DLS データのダウンロードに加えて、このメソッドは音色を特定のパフォーマンス チャンネルに割り当てる。

メモリを節約するために、指定された音符の範囲で必要なウェーブとアーティキュレーションだけがダウンロードされる。たとえば、バスーンを使う場合、低音の C から中間の B までの音符範囲に相当するデータだけをダウンロードするよう指定することがある。その範囲内のリージョン のデータだけをダウンロードすべきである。

次のコード例では、指定されたコレクション、パッチ番号、ポート、および音符範囲に対して、コレクションから音色を取り出し、その音色をダウンロードしている。この関数は、1 つの DMUS_NOTERANGE 構造体からなる配列を作成し、この配列を IDirectMusicPort::DownloadInstrument メソッドに渡す。一般的には、音符の 1 つの範囲だけを指定するが、複数の範囲を指定することもできる。配列へのポインタの代わりに NULL を渡すと、すべての範囲のデータがダウンロードされる。

HRESULT myDownload(
    IDirectMusicCollection *pCollection,    // DLS コレクション
    IDirectMusicPort *pPort,                // ダウンロード先ポート
    IDirectMusicDownloadedInstrument **ppDLInstrument, 
    DWORD dwPatch,                          // 要求された音色
    DWORD dwLowNote,                        // 音符範囲の下限の音符
    DWORD dwHighNote)                       // 音符範囲の上限の音符
 
{
    HRESULT hr;
    IDirectMusicInstrument* pInstrument;
    hr = pCollection->GetInstrument(dwPatch, &pInstrument);
    if (SUCCEEDED(hr))
    {
        DMUS_NOTERANGE NoteRange[1];         // オプションの音符範囲
        NoteRange[0].dwLowNote = dwLowNote;
        NoteRange[0].dwHighNote = dwHighNote;
        hr = pPort->DownloadInstrument(pInstrument, 
                ppDLInstrument, 
                NoteRange,   // 範囲の配列
                1);          // 配列内の要素数
        pInstrument->Release();
    }
    return hr;
}

Download メソッドは、IDirectMusicDownloadedInstrument インターフェイスへのポインタを返す。このポインタの目的は、それ以降に IDirectMusicPort::UnloadInstrument メソッドを呼び出すときに音色を識別することだけであり、このメソッドは特定のポートから音色インスタンスをアンロードする (DirectMusicCollection は、特定のポートにバインドされない。異なる音色を異なるポートにダウンロードすることも、1 つの音色を複数のポートにダウンロードすることもできる)。

次のコード例では、音色をダウンロードした後、アンロードしている。この例は、IDirectMusicDownloadedInstrument ポインタの使用方法を示している。

HRESULT myFickleDownload(
        IDirectMusicInstrument* pInstrument,
        IDirectMusicPort *pPort,
        DWORD dwPatch)
 
{
    HRESULT hr;
    IDirectMusicDownloadedInstrument * pDLInstrument;
    hr = pPort->DownloadInstrument(
            pInstrument, &pDLInstrument, 
            NULL, 0);
    if (SUCCEEDED(hr))
    {
        pPort->UnloadInstrument(pDLInstrument);
        pDLInstrument->Release();
    }
    return hr;
}

IDirectMusicBand::Download メソッドは、バンド内のすべての音色を自動的にダウンロードする。開発者がパフォーマンスへのポインタを渡すだけで、このメソッドはそのパフォーマンスに付加された適切なポートに各音色をダウンロードする。