Platform SDK: DirectX |
ここでは、C++ でのアプリケーション開発について説明する。
IKsPropertySet インターフェイスを通して、DirectSound はサウンド カードとその関連ドライバの提供する拡張サービスをサポートできる。
プロパティはセットに編成される。GUID がセットを識別し、ULONG がセット内の特定のプロパティを識別する。たとえば、ハードウェア ベンダーが反響エフェクトを作成できるカードを設計し、DSPROPERTY_REVERBPROPERTIES_HALL と DSPROPERTY_REVERBPROPERTIES_STADIUM などのプロパティを保持するプロパティ セット DSPROPSETID_ReverbProperties を定義することも考えられる。
通常、番号 0 で始まる C 言語の列挙型を使ってプロパティ識別子を定義する。
個別のプロパティにパラメータを関連付けてもよい。IKsPropertySet インターフェイスの仕様は、意図的にそれらのパラメータを未定義にしているので、プロパティセットの設計者は、設計対象のセット内のプロパティにとって最も役立つ方法で設計を行える。パラメータの正確な意味は、プロパティの定義によって決まる。
サウンド カード上の拡張プロパティを利用するには、最初にそのドライバが IKsPropertySet インターフェイスをサポートしているかどうかを確認し、サポートしている場合はそのインターフェイスへのポインタを取得しなければならない。これを行うには、DirectSound3DBuffer オブジェクト上の現存するインターフェイスに対して QueryInterface メソッドを呼び出す。
HRESULT hr = lpDirectSound3DBuffer->QueryInterface( IID_IKsPropertySet, (void**)&lpKsPropertySet));
この例では、lpDirectSound3DBuffer はバッファのインターフェイスへのポインタであり、IKsPropertySet インターフェイスが見つかった場合は、lpKsPropertySet はそのアドレスを受け取る。IID_lpKsPropertySet は、Dsound.h 内で定義されている GUID である。
バッファがハードウェア アクセラレートされている場合に限り、この呼び出しは成功する。成功した場合は、IKsPropertySet::QuerySupport メソッドを使って特定のプロパティを検索できる。PropertySetId パラメータの値は、ハードウェア ベンダーによって定義された GUID である。
特定のプロパティに対するサポートが存在すると確認した後は、IKsPropertySet::Set メソッドによるプロパティの状態の変更と、IKsPropertySet::Get メソッドによる現在の状態の確認が行える。pPropertyData パラメータを使って、プロパティの状態の設定と取得を行う。
IKsPropertySet::Set の pPropertyParams パラメータが指す構造体内のオブジェクトに、追加のプロパティ パラメータを渡してもよい。このパラメータの正確な使用方法は、プロパティ セットに関するハードウェア ベンダーの仕様書で定義されるが、プロパティ セットのインスタンスを定義するために使われるのが普通である。実際には、pPropertyParams を使うことはほとんどない。
少し変わった例について取り上げる。あるサウンド カードには、数人の有名なテノール歌手の声で一連の歌を演奏する機能が備わっているとする。ドライバ開発者は、DSPROPERTY_SONG_IRISH_EYES や DSPROPERTY_SONG_O_SOLE_MIO などのプロパティを保持するプロパティ セット DSPROPSETID_Song を作成する。ドライバ開発者はこのプロパティ セットをすべてのテノール歌手に適用し、pPropertyParams がテノールのインスタンスを定義すると指定した。ここでアプリケーション開発者は、Caruso (カルーゾ) にこれらの歌のいずれかを歌わせたいと考えている。
/* ハードウェア ベンダーが既にヘッダー ファイル内で CARUSO と START を定義していることを想定する。*/ DWORD dwTenor = CARUSO; BOOL StartOrStop = START; HRESULT hr = lpKsPropertySet->Set( DSPROPSETID_Song, DSPROPERTY_SONG_IRISH_EYES, &dwTenor, sizeof(dwTenor), &StartOrStop, sizeof(StartOrStop));