Microsoft DirectX 8.0 (C++)

音色の操作

コレクション オブジェクトを作成したり、コレクション ファイルやリソースからロードした場合、音色は特定のポートにバインドされない。異なる音色を異なるポートにダウンロードすることも、1 つの音色を複数のポートにダウンロードすることもできる。

IDirectMusicCollection8::EnumInstrument メソッドを使って、利用可能なすべての音色のパッチ番号および名前を取得できる。

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

void myListInstruments(
        IDirectMusicCollection8 *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("Patch %lx is %S\n",dwPatch,wszName);
        }
    }
}

IDirectMusicCollection8::GetInstrument メソッドに特定の音色のパッチ番号を渡して、特定の音色へのポインタを取得する。

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

単一の音色をポートにダウンロードするには、IDirectMusicInstrument8 インターフェイス ポインタを IDirectMusicPort8::DownloadInstrument または IDirectMusicPerformance8::DownloadInstrument メソッドに渡す。この呼び出しは、ポートで DLS データを利用可能にする。音色を特定のパフォーマンスやオーディオパスに関連付けることはない。

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

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

HRESULT myDownload(
    IDirectMusicCollection8 *pCollection,    // DLS コレクション
    IDirectMusicPort8 *pPort,                // 転送先ポート
    IDirectMusicDownloadedInstrument8 **ppDLInstrument, 
    DWORD dwPatch,                          // 要求された音色
    DWORD dwLowNote,                        // 範囲内の低いノート
    DWORD dwHighNote)                       // 範囲内の高いノート
 
{
    HRESULT hr;
    IDirectMusicInstrument8* 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;
}

DownloadInstrument メソッドは、IDirectMusicDownloadedInstrument8 インターフェイスへのポインタを返す。このポインタの目的は、それ以降に IDirectMusicPort8::UnloadInstrument メソッドを呼び出すときに音色を識別することだけであり、このメソッドは特定のポートから音色インスタンスをアンロードする。

次の関数では、音色をダウンロードした後、アンロードしている。この例は、IDirectMusicDownloadedInstrument8 ポインタの使用方法を示すだけのものである。

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