DSBUFFERDESC
新しい DirectSoundBuffer オブジェクトの特性を記述する。IDirectSound8::CreateSoundBuffer メソッドで使われる。
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
- 新しい DirectSoundBuffer オブジェクトを作成するときに含める能力を識別するフラグ。次のフラグが定義されている。「注意」を参照すること。
- DSBCAPS_CTRL3D
- バッファは 3D コントロール能力を備えている。DSBCAPS_CTRLPAN と組み合わせることはできない。また、lpwfxFormat でステレオ フォーマットを指定されているバッファには設定できない。
- DSBCAPS_CTRLFREQUENCY
- バッファは周波数コントロール能力を備えている。DSBCAPS_CTRLFX と組み合わせることはできない。
- DSBCAPS_CTRLFX
- バッファはエフェクト処理をサポートしている。DSBCAPS_CTRLFREQUENCY と組み合わせることはできない。lpwfxFormat のウェーブ フォーマットは、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_STATIC が指定されていて、ハードウェア リソースが利用可能であっても、バッファをソフトウェア メモリに配置して、ソフトウェア ミキシングを使わなければならない。
- DSBCAPS_MUTE3DATMAXDISTANCE
- サウンドは、最大距離で無音になる。最大距離を超えるとバッファの再生が停止するので、プロセッサ時間を消費しないで済む。
- DSBCAPS_PRIMARYBUFFER
- このバッファはプライマリ サウンド バッファである。この値を指定しない場合は、セカンダリ サウンド バッファが作成される。DSBCAPS_CTRLFX と組み合わせることはできない。
- DSBCAPS_STATIC
- オンボード ハードウェア メモリが利用可能な場合、バッファはそこに置かれる。このようなメモリが利用できない場合でも、エラーは発生しない。これに対して DSBCAPS_LOCHARDWARE は、バッファを強制的にハードウェア メモリ (おそらく、ドライバがバッファのミキシングに使うシステム メモリ) に置くので、このようなメモリが利用できない場合はエラーを引き起こす。このフラグは、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 HEL が使う二重スピーカの仮想アルゴリズムのユニーク識別子。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 オーディオ アルゴリズムで処理される。このフラグは、ソフトウェア HEL のみに適用される。このアルゴリズムは最高品質の 3D オーディオ エフェクトを与えるが、CPU をより多く消費する。「注意」を参照すること。
ソフトウェア ミキシングにのみ適用される。WDM ドライバを使った、Microsoft® Windows® 98 Second Edition と Windows 2000 で利用できる。
注 サウンド バッファを HRTF アルゴリズムのいずれかを使って作成し、HRTF アルゴリズムがシステムで利用不可能な場合は (たとえば、WDM システムではない場合)、コード DS_NO_VIRTUALIZATION が返される。作成されたサウンド バッファは、代わりに DS3DALG_NO_VIRTUALIZATION を使う。これにより、アプリケーションは CreateSoundBuffer の呼び出し時に明示的に DS_OK をチェックするのではなく、SUCCEEDED マクロや FAILED マクロを使う必要がある。
- DS3DALG_HRTF_LIGHT
- 3D API は、効率的な 3D オーディオ アルゴリズムで処理される。このフラグは、ソフトウェア HEL のみに適用される。このアルゴリズムは優れた 3D オーディオ エフェクトを与え、DS3DALG_HRTF_FULL ほど CPU に負荷をかけない。
ソフトウェア ミキシングにのみ適用される。WDM ドライバを使った、Windows 98 Second Edition と Windows 2000 で利用できる。
注 サウンド バッファを HRTF アルゴリズムのいずれかを使って作成し、HRTF アルゴリズムがシステムで利用不可能な場合は (たとえば、WDM システムではない場合)、コード DS_NO_VIRTUALIZATION が返される。作成されたサウンド バッファは、代わりに DS3DALG_NO_VIRTUALIZATION を使う。これにより、アプリケーションは CreateSoundBuffer の呼び出し時に明示的に DS_OK をチェックするのではなく、SUCCEEDED マクロや FAILED マクロを使う必要がある。
注意
プライマリ バッファを作成する際、アプリケーションは dwBufferBytes メンバを 0 に設定しなければならない。DirectSound は、使用中の特定のサウンド デバイスに対する最適なバッファ サイズを決定する。作成されたプライマリ バッファの大きさを取得するには、IDirectSoundBuffer8::GetCaps を呼び出す。
DSBCAPS_CTRLDEFAULT フラグはもうサポートされていない。このフラグは、DSBCAPS_CTRLPAN | DSBCAPS_CTRLVOLUME | DSBCAPS_CTRLFREQUENCY として定義された。必要なフラグだけを指定することにより、不必要なリソースを減らすことができる。
DSBCAPS_CTRLPOSITIONNOTIFY フラグで作成されたサウンド バッファには、通知イベントを設定すべきである。このフラグでサウンド バッファを作成し、実際には何も通知を設定しないと、動作が定義されず、サウンドが 2 回再生されることがある。
VxD ドライバの場合、DSBCAPS_CTRLPOSITIONNOTIFY を使って作成されたサウンド バッファは常にソフトウェア バッファである。これは、VxD ドライバ モデルが通知をサポートしないためである。ハードウェアが利用可能な場合は、WDM ドライバにより、通知可能なバッファがハードウェアに存在することがある。このフラグ設定で作成されたバッファの再生中は、DSBPLAY_LOCHARDWARE フラグによる IDirectSoundBuffer8::Play の呼び出しは失敗する。
DSBCAPS_LOCHARDWARE と DSBCAPS_LOCSOFTWARE の各フラグはオプションであり、互いに排他的である。DSBCAPS_LOCHARDWARE は、強制的にバッファをハードウェアに配置する。これは、バッファがサウンド カードによってミキシングされることを意味する。DSBCAPS_LOCSOFTWARE は、強制的にバッファをソフトウェアに配置する。この場合、バッファは CPU によってミキシングされる。これらのフラグは、DSBCAPS 構造体の dwFlags メンバ用にも定義されており、バッファの実際の場所を示す。
3D アルゴリズムは、ソフトウェア エミュレーション レイヤのみの選択を行う。これは、アクセラレーション用のハードウェアがない場合に使われるソフトウェア アルゴリズムである。ハードウェアの利用を最大にするために、DS3DALG_NO_VIRTUALIZATION は特別な場合として扱われる。3D ハードウェア ボイスの空きを利用できない場合、バッファは 3D API コントロールと共に 2D バッファとして扱われる。特に、サウンド バッファが DS3DALG_NO_VIRTUALIZATION で作成されている場合、またはバッファが DSBPLAY_LOCDEFER で作成されている場合は、バッファの演奏中に次の手順に従う。
- 3D ハードウェア ボイスの空きが利用可能な場合は、その 3D ハードウェア ボイスを使う。
- 3D ハードウェア ボイスの空きが利用不可能で、2D ハードウェア ボイスが利用可能な場合は、その 2D ハードウェア ボイスを使う。これが可能なのは、DS3DALG_NO_VIRTUALIZATION アルゴリズムが単純なステレオ パン アルゴリズムだからである。
- 2D または 3D ハードウェア ボイスの空きが利用不可能な場合、ボイスは DS3DALG_NO_VIRTUALIZATION アルゴリズムを使ってソフトウェアで再生される。
DSSPEAKER_HEADPHONE や DSSPEAKER_STEREO 以外のスピーカ構成が有効な場合、この処理は二重スピーカ構成に対する処理と同じように行われる。
バッファを HRTF アルゴリズムのいずれかを使って作成し、HRTF アルゴリズムがシステムで利用不可能な場合は (たとえば、WDM システムではない場合)、コード DS_NO_VIRTUALIZATION が返される。作成されたサウンド バッファは、代わりに DS3DALG_NO_VIRTUALIZATION を使う。これにより、アプリケーションは CreateSoundBuffer の呼び出し時に明示的に DS_OK をチェックするのではなく、SUCCEEDED マクロや FAILED マクロを使う必要がある。
ヘッダー : dsound.h で宣言。
参照
IDirectSound8::CreateSoundBuffer、DirectSound バッファ、ISA および PCI カードでのハードウェア アクセラレーション