DSBUFFERDESC
DSBUFFERDESC 構造体は、新しいバッファ オブジェクトの特性を記述する。IDirectSound8::CreateSoundBuffer メソッドおよび DirectSoundFullDuplexCreate8 関数で使う。
DirectX 7 以前との互換性を保つために、この構造体の前のバージョンである DSBUFFERDESC1 も dsound.h で維持されている。
構文
typedef struct {
DWORD dwSize;
DWORD dwFlags;
DWORD dwBufferBytes;
DWORD dwReserved;
LPWAVEFORMATEX lpwfxFormat;
GUID guid3DAlgorithm;
} DSBUFFERDESC, *LPDSBUFFERDESC;
typedef const DSBUFFERDESC *LPCDSBUFFERDESC;
メンバ
dwSize
構造体のサイズ (バイト単位)。構造体を使う前に、このメンバを初期化しなければならない。
dwFlags
バッファの能力を示すフラグ。次の値が定義されている。
| 値 | 説明 |
| DSBCAPS_CTRL3D | バッファは 3D コントロール能力を備えている。DSBCAPS_CTRLPAN と組み合わせることはできない。また、lpwfxFormat でステレオ フォーマットを指定されているバッファには設定できない。 |
| DSBCAPS_CTRLFREQUENCY | バッファは周波数コントロール能力を備えている。 |
| DSBCAPS_CTRLFX | バッファはエフェクト処理をサポートしている。lpwfxFormat の WAV フォーマットは、2 チャンネル以下の 8 ビットまたは 16 ビットの PCM フォーマットでなければならない。また、バッファには、少なくとも DSBSIZE_FX_MIN ミリ秒のデータを格納できるサイズが必要である。 |
| DSBCAPS_CTRLPAN | バッファはパン コントロール能力を備えている。DSBCAPS_CTRL3D と組み合わせることはできない。 |
| DSBCAPS_CTRLPOSITIONNOTIFY | バッファは位置通知能力を備えている。「注意」を参照すること。 |
| DSBCAPS_CTRLVOLUME | バッファはボリューム コントロール能力を備えている。 |
| DSBCAPS_GETCURRENTPOSITION2 | IDirectSoundBuffer8::GetCurrentPosition メソッドでは、再生カーソルの新しい動作を使う。DirectX 1 の DirectSound では、エミュレートされたサウンド カードの再生カーソルは実際の再生サウンドよりはるか前方にあり、書き込みカーソルの直後に置かれていた。現在は、DSBCAPS_GETCURRENTPOSITION2 フラグを指定すると、アプリケーションはより正確な再生カーソルを取得できる。このフラグを指定していない場合、互換性を保つために過去の動作が維持される。このフラグは、エミュレートされたサウンド カードにのみ影響を及ぼすことに注意する。DirectSound ドライバが存在する場合は、どのバージョンの DirectX でも DirectSound の再生カーソルは正確な位置を示す。 |
| DSBCAPS_GLOBALFOCUS | バッファはグローバルなサウンド バッファである。このフラグを設定すると、ユーザーが他のアプリケーションにフォーカスを移動し、その新しいアプリケーションが DirectSound を使う場合でも、DirectSound を使っているアプリケーションは引き続きそのバッファを再生できる。1 つの例外は、協調レベルで DSSCL_WRITEPRIMARY フラグを設定した DirectSound アプリケーションにフォーカスを移動した場合である。この場合、他のアプリケーションからのグローバルなサウンドは聞こえなくなる。 |
| DSBCAPS_LOCDEFER | 再生時、バッファはハードウェアまたはソフトウェアのリソースに割り当てられる。ボイス管理を使うバッファには、このフラグが設定されなければならない。 |
| DSBCAPS_LOCHARDWARE | バッファはハードウェア ミキシングを使わなければならない。デバイスがハードウェア ミキシングをサポートしていない場合、または必要なハードウェア メモリを利用できない場合は、IDirectSound8::CreateSoundBuffer メソッドの呼び出しは失敗する。アプリケーションは、このバッファがミキシング チャンネルを利用できることを確認する必要がある。この状況は保証されていない。このフラグと DSBCAPS_LOCSOFTWARE のどちらも指定されていない場合には、バッファは、リソースが利用できればハードウェアに配置され、ハードウェア リソースが利用できなければソフトウェアに配置される。 |
| DSBCAPS_LOCSOFTWARE | DSBCAPS_STATIC が指定されていて、ハードウェア リソースが利用可能であっても、バッファをソフトウェア メモリに配置して、ソフトウェア ミキシングを使わなければならない。 |
| DSBCAPS_MUTE3DATMAXDISTANCE | サウンドは、最大距離で無音になる。最大距離を超えるとバッファの再生が停止するので、プロセッサ時間を消費しないで済む。ソフトウェア バッファに対してのみ適用される。 |
| DSBCAPS_PRIMARYBUFFER | バッファはプライマリ バッファである。この値を指定しない場合は、セカンダリ サウンド バッファが作成される。DSBCAPS_CTRLFX と組み合わせることはできない。 |
| DSBCAPS_STATIC | オンボード ハードウェア メモリが利用可能な場合、バッファはそこに置かれる。このようなメモリが利用できない場合でも、エラーは発生しない。PCI バスを使うカードでは、このフラグは意味を持たない。DSBCAPS_CTRLFX と組み合わせることはできない。 |
| DSBCAPS_STICKYFOCUS | バッファはスティッキー フォーカスを備えている。ユーザーが DirectSound を使っていない他のアプリケーションに切り替えた場合、アプリケーションの標準バッファは無音になるが、スティッキー フォーカス バッファは引き続き音を出す。 |
dwBufferBytes
新しいバッファのサイズ (バイト単位)。DSBCAPS_PRIMARYBUFFER フラグを指定してバッファを作成する場合は、この値は 0 でなければならない。セカンダリ バッファで許容される最小サイズと最大サイズは、dsound.h で定義されている DSBSIZE_MIN と DSBSIZE_MAX である。
dwReserved
予約済み。0 でなければならない。
lpwfxFormat
バッファのウェーブフォーム フォーマットを指定する WAVEFORMATEX 構造体または WAVEFORMATEXTENSIBLE 構造体のアドレス。プライマリ バッファでは、この値は NULL でなければならない。アプリケーションは IDirectSoundBuffer8::SetFormat を使って、プライマリ バッファのフォーマットを設定できる。
guid3DAlgorithm
DirectSound3D のハードウェア エミュレーションが使う 2 スピーカ仮想化アルゴリズムの一意な識別子。DSBCAPS_CTRL3D が dwFlags に設定されていない場合、このメンバは GUID_NULL (DS3DALG_DEFAULT) でなければならない。
次のアルゴリズム識別子が定義されている。
| 値 | 説明 | 利用可能性 |
| DS3DALG_DEFAULT | DirectSound はデフォルトのアルゴリズムを使う。通常は、DS3DALG_NO_VIRTUALIZATION である。WDM ドライバでは、コントロール パネルでサラウンド サウンドのスピーカ構成が選択されていると、サウンドは利用可能な方向のスピーカ間でパンされる。 | ソフトウェア ミキシングにのみ適用される。WDM ドライバまたは VxD ドライバで利用できる。 |
| DS3DALG_NO_VIRTUALIZATION | 3D 出力は、標準の左右ステレオのパンにマップされる。左に 90°のとき、サウンドは左スピーカだけから聞こえ、右に 90°のとき、サウンドは右スピーカだけから聞こえる。垂直軸では、距離によってボリュームが調節されるだけである。このバッファでは、ドップラー シフトとボリューム調節は適用されるが、3D フィルタリングは行われない。これは最も効率的なソフトウェアの実装であるが、仮想 3D オーディオ エフェクトは提供しない。DS3DALG_NO_VIRTUALIZATION アルゴリズムを指定すると、HRTF 処理は行われない。
DS3DALG_NO_VIRTUALIZATION は標準のステレオのパンのみを使うので、このアルゴリズムで作成されたバッファは、3D ハードウェア ボイスの空きを利用できない場合、2D ハードウェア ボイスによってアクセラレートされる。 |
ソフトウェア ミキシングにのみ適用される。WDM ドライバまたは VxD ドライバで利用できる。 |
| DS3DALG_HRTF_FULL | 3D API は、高品質の 3D オーディオ アルゴリズムで処理される。このアルゴリズムは最高品質の 3D オーディオ エフェクトを実現するが、より多くの CPU サイクルを使う。「注意」を参照すること。 | ソフトウェア ミキシングにのみ適用される。WDM ドライバの使用時には、Microsoft Windows 98 Second Edition 以降のオペレーティング システムで利用できる。 |
| DS3DALG_HRTF_LIGHT | 3D API は、効率的な 3D オーディオ アルゴリズムで処理される。このアルゴリズムは優れた 3D オーディオ エフェクトを実現し、DS3DALG_HRTF_FULL ほど CPU に負荷をかけない。 | ソフトウェア ミキシングにのみ適用される。WDM ドライバの使用時には、Windows 98 Second Edition 以降のオペレーティング システムで利用できる。 |
注意
プライマリ バッファを作成するときは、dwBufferBytes メンバに 0 を設定しなければならない。使用している特定のサウンド デバイスに最適なバッファのサイズは、DirectSound によって決定される。作成されたプライマリ バッファのサイズを取得するには、IDirectSoundBuffer8::GetCaps を呼び出す。
DSBCAPS_CTRLDEFAULT フラグはサポートされていない。このフラグは、DSBCAPS_CTRLPAN | DSBCAPS_CTRLVOLUME | DSBCAPS_CTRLFREQUENCY として定義されていた。必要なフラグだけを指定することにより、不要なリソースを減らすことができる。
VXD ドライバの場合、DSBCAPS_CTRLPOSITIONNOTIFY を使って作成されたサウンド バッファは常にソフトウェア バッファである。これは、VXD ドライバ モデルが通知をサポートしないためである。WDM ドライバでは、ハードウェア リソースが利用可能な場合は、通知をサポートするバッファをハードウェアに置くことができる。
DSBCAPS_LOCHARDWARE フラグと DSBCAPS_LOCSOFTWARE フラグはオプションであり、互いに排他的である。DSBCAPS_LOCHARDWARE は、強制的にバッファをハードウェアに配置する。つまり、バッファはサウンド カードによってミキシングされる。DSBCAPS_LOCSOFTWARE は、強制的にバッファをソフトウェアに配置する。この場合、バッファは CPU によってミキシングされる。これらのフラグは、DSBCAPS 構造体の dwFlags メンバに対しても定義されている。
3D アルゴリズムは、ソフトウェア エミュレーション レイヤのみの選択を表す。つまり、アクセラレーション用のハードウェアがない場合に使われるソフトウェア アルゴリズムである。ハードウェアの利用を最大にするために、DS3DALG_NO_VIRTUALIZATION は特別な場合として扱われる。3D ハードウェア ボイスの空きを利用できない場合、バッファは 3D コントロールと共に 2D バッファとして扱われる。特に、サウンド バッファを DS3DALG_NO_VIRTUALIZATION で作成する場合、または DSBPLAY_LOCDEFER で作成されたバッファを再生する場合は、次の手順に従う。
- 利用可能な 3D ハードウェア ボイスがある場合は、その 3D ハードウェア ボイスを使う。
- 利用できる 3D ハードウェア ボイスに空きがなく、2D ハードウェア ボイスを利用できる場合は、その 2D ハードウェア ボイスを使う。これが可能なのは、DS3DALG_NO_VIRTUALIZATION アルゴリズムが単純なステレオ パン アルゴリズムだからである。
- 利用できる 2D または 3D ハードウェア ボイスに空きがない場合は、ボイスは DS3DALG_NO_VIRTUALIZATION アルゴリズムを使ってソフトウェアで再生される。
DSSPEAKER_HEADPHONE または DSSPEAKER_STEREO 以外のスピーカ構成が有効な場合、処理は 2 スピーカ構成に対する処理と同じように行われる。
バッファを HRTF アルゴリズムのいずれかを使って作成し、HRTF アルゴリズムがシステムで利用不可能な場合は (たとえば、WDM システムではない場合)、正常終了のコード DS_NO_VIRTUALIZATION が返される。作成されたサウンド バッファは、代わりに DS3DALG_NO_VIRTUALIZATION を使う。このため、アプリケーションでは、CreateSoundBuffer の呼び出し時に明示的に DS_OK をチェックするのではなく、SUCCEEDED マクロまたは FAILED マクロを使う必要がある。
要件
** ヘッダー:**Dsound.h で宣言。
参照