Platform SDK: DirectX

ポートのプロパティ セット

[Visual Basic]

ここでは、C++ で記述されたアプリケーションに関連のある内容だけを説明する。DirectX for Visual Basic では、ポートのプロパティ セットはサポートされない。

[C++]

DirectMusic は、プロパティ セットを通して、ハードウェアとドライバの新しい機能に対するサポートを提供する。プロパティ セットは GUID によって表され、セット内の各項目は 0 から始まるインデックス番号を割り当てられている。

ハードウェア ベンダーは新しい機能をプロパティとして定義し、GUID を含め、それらのプロパティに関する仕様を公示する。IKsControl::KsProperty メソッドを使って、プロパティが利用可能であるかどうかを確認し、プロパティの値を設定および取り出すことができる。IDirectMusicPort::QueryInterface メソッドを呼び出し、インターフェイス識別子として IID_IKsControl を渡すことにより、ポートに対応する.IKsControl インターフェイスを取得する。

プロパティ セットは GUID によって表され、セットの各項目は 0 から始まるインデックスによって表される。GUID に対してインデックス化された項目の意味が変更されることはない。DirectMusic でサポートされるプロパティ セットのリストについては、KSPROPERTY を参照すること。

DirectMusic であらかじめ定義されているプロパティ セットはすべて、ただ 1 つの項目を持っており、通常、インデックス番号は 0 に設定されている。カーネルストリーミング (KS) プロパティの完全定義もサポートされており、ベンダーは任意の数の項目とインスタンス、および任意のサイズのデータを持つプロパティ セットを自由に作成できる。

プロパティ項目の要求をポートに対して送信する作業は、ポートの実装に依存する。Win32 ハンドル ベースのマルチメディア呼び出し (midiOut midiIn の各関数) を利用して DirectMusic のエミュレーションを行っているポートでは、どのプロパティもサポートされない。

次のコード例では、IKsControl::KsProperty メソッドを使って、ポートが General MIDI サウンド セットをハードウェアでサポートしているかどうかを調べている。

BOOL IsGMSupported(IDirectMusicPort *pPort) 
{ 
    HRESULT     hr; 
    IKsControl  *pControl; 
    KSPROPERTY  ksp; 
    DWORD       dwFlags; 
    ULONG       cb; 
    BOOL        fIsSupported;
 
    // IKsControl インターフェイスのクエリ。
    hr = pPort->QueryInterface(IID_IKsControl, (void**)&pControl); 
    if (FAILED(hr)) 
    { 
        // ポートはプロパティをサポートしない。GM がサポートされないとする。
        return FALSE; 
    }
    // GM について確認する。
    ksp.Set   = GUID_DMUS_PROP_GM_Hardware; 
    ksp.Id    = 0; 
    ksp.Flags = KSPROPERTY_TYPE_BASICSUPPORT;
    hr = pControl->KsProperty(&ksp, sizeof(ksp),
            &dwFlags, sizeof(dwFlags), &cb);
    fIsSupported = FALSE; 
    if (SUCCEEDED(hr) || (cb >= sizeof(dwFlags))
    {
        // セットはサポートされる。
        fIsSupported = (BOOL)(dwFlags & KSPROPERTY_TYPE_GET);
    }
    pControl->Release();
    return fIsSupported;
}

次のコード例は、プロパティを変更する方法を示している。この場合、ソフトウェア シンセサイザのリバーブ プロパティは、DMUS_WAVES_REVERB_PARAMS 構造体に含まれるプロパティに設定される。

/* m_* 変数は、有効な値で初期化されていると仮定する。
   m_pPort は IDirectMusicPort へのポインタである。*/
 
DMUS_WAVES_REVERB_PARAMS Params;
 
Params.fInGain = m_fReverbIn;
Params.fHighFreqRTRatio = m_fReverbHigh;
Params.fReverbMix = m_fReverbMix;
Params.fReverbTime = m_fReverbTime;
 
IKsControl *pControl;
if (m_pPort)
{
    // IKsControl インターフェイスのクエリ。
    HRESULT hr = m_pPort->QueryInterface(IID_IKsControl,
            (void**)&pControl);
    if (SUCCEEDED(hr)) 
    {
        KSPROPERTY ksp;
        ULONG cb;
 
        ZeroMemory(&ksp, sizeof(ksp));
        ksp.Set   = GUID_DMUS_PROP_WavesReverb;
        ksp.Id    = 0;
        ksp.Flags = KSPROPERTY_TYPE_SET;
 
        pControl->KsProperty(&ksp,
                             sizeof(ksp),
                             (LPVOID)&Params,
                             sizeof(Params),
                             &cb);
        pControl->Release();
    }
}

次のコード例では、m_pPort で表されるポートでリバーブ エフェクトを有効にしている。

DWORD dwEffects = 0;
IKsControl *pControl;
HRESULT hr = m_pPort->QueryInterface(IID_IKsControl,
        (void**)&pControl);
if (SUCCEEDED(hr)) 
{
  KSPROPERTY ksp;
  ULONG cb;
 
  ZeroMemory(&ksp, sizeof(ksp));
  dwEffects = DMUS_EFFECT_REVERB;
  ksp.Set   = GUID_DMUS_PROP_Effects;
  ksp.Id    = 0;
  ksp.Flags = KSPROPERTY_TYPE_SET;
 
  pControl->KsProperty(&ksp,
             sizeof(ksp),
             (LPVOID)&dwEffects,
             sizeof(dwEffects),
             &cb);
  pControl->Release();
}

最後の例は、その他のエフェクトを現状のまま、リバーブだけをオフにする方法を示している。

DWORD dwEffects = 0;
IKsControl *pControl;
HRESULT hr = m_pPort->QueryInterface(IID_IKsControl,
        (void**)&pControl);
if (SUCCEEDED(hr)) 
{
  KSPROPERTY ksp;
  ULONG cb;
 
  ZeroMemory(&ksp, sizeof(ksp));
  ksp.Set   = GUID_DMUS_PROP_Effects;
  ksp.Id    = 0;
  ksp.Flags = KSPROPERTY_TYPE_GET;
 
  pControl->KsProperty(&ksp,
             sizeof(ksp),
             (LPVOID)&dwEffects,
             sizeof(dwEffects),
             &cb);

  ZeroMemory(&ksp, sizeof(ksp));
  dwEffects = dwEffects & ~DMUS_EFFECT_REVERB;
  ksp.Set   = GUID_DMUS_PROP_Effects;
  ksp.Id    = 0;
  ksp.Flags = KSPROPERTY_TYPE_SET;
 
  pControl->KsProperty(&ksp,
             sizeof(ksp),
             (LPVOID)&dwEffects,
             sizeof(dwEffects),
             &cb);

  pControl->Release();
}