| DirectX SDK |
The DSBUFFERDESC structure describes the necessary characteristics of a new DirectSoundBuffer object. This structure is used by the IDirectSound::CreateSoundBuffer method.
typedef struct {
DWORD dwSize;
DWORD dwFlags;
DWORD dwBufferBytes;
DWORD dwReserved;
LPWAVEFORMATEX lpwfxFormat;
GUID guid3DAlgorithm;
} DSBUFFERDESC, *LPDSBUFFERDESC;
typedef const DSBUFFERDESC *LPCDSBUFFERDESC;
The valid algorithms that can be specified are:
The HEL is set to be the default algorithm. Currently, this will select the DS3DALG_NO_VIRTUALIZATION algorithm, which provides a CPU- efficient, but basic 3-D effect. In the future, the algorithm used when DS3DALG_DEFAULT is set may be based on the user's preference by means of a control panel setting.
AVAILABLE ON: WDM or Vxd Drivers
The Direct3D API is mapped onto normal left and right stereo panning. At 90 degrees to the left, the sound is coming out of only the left speaker; at 90 degrees to the right, sound is coming out of only the right speaker. The vertical axis is ignored except for scaling of volume due to distance. Doppler shift and volume scaling are still applied, but the 3-D filtering is not performed on this buffer. This is the most efficient software implementation, but provides no virtual 3-D audio effect. When the DS3DALG_NO_VIRTUALIZATION flag is specified, Head Related Transfer Function (HRTF) processing will not be done. Note: Since DS3DALG_NO_VIRTUALIZATION uses only normal stereo panning, a buffer created with this algorithm may be accelerated by a 2-D hardware voice if no free 3-D hardware voices are available.
AVAILABLE ON: WDM or Vxd Drivers
The 3-D API is processed with the high quality 3-D audio algorithm. This flag applies only to the software HEL. This algorithm gives the highest quality 3-D audio effect, but uses more CPU.
AVAILABLE ON: Microsoft® Windows® 98 Second Edition and Windows 2000 that use WDM drivers. .
Note: If a sound buffer is created using one of the HRTF algorithms, and the HRTF algorithm is not available on the system (for example a non-WDM system), a partial-success code, DS_NO_VIRTUALIZATION, is returned. The sound buffer created will use the DS3DALG_NO_VIRTUALIZATION instead.
For this reason, applications should use the "SUCCEDED()" or "FAILED()" macros, rather than check explicitly for DS_OK when calling CreateSoundBuffer.
The 3-D API is processed with the efficient 3-D audio algorithm. This flag applies only to the software HEL. This algorithm gives a good 3-D audio effect, but uses less CPU than DS3DALG_HRTF_FULL.
AVAILABLE ON: Windows 98 Second Edition and Windows 2000 that use WDM drivers.
Note: If a sound buffer is created using one of the HRTF algorithms, and the HRTF algorithm is not available on the system (for example a non-WDM system), a partial-success code, DS_NO_VIRTUALIZATION, is returned. The sound buffer created will use the DS3DALG_NO_VIRTUALIZATION instead.
For this reason, applications should use the "SUCCEDED()" or "FAILED()" macros, rather than check explicitly for DS_OK when calling CreateSoundBuffer.
DSBCAPS_CTRLDEFAULT has been removed to encourage use of the individual flags that DSBCAPS_CTRLDEFAULT represents. DSBCAPS_CTRLDEFAULT was previously defined as DSBCAPS_CTRLPAN | DSBCAPS_CTRLVOLUME | DSBCAPS_CTRLFREQUENCY. By specifying only the flags you need, you cut down on unnecessary resource usage.
The DSBCAPS_LOCHARDWARE and DSBCAPS_LOCSOFTWARE flags used in the dwFlags member are optional and mutually exclusive. DSBCAPS_LOCHARDWARE forces the buffer to reside in memory located in the sound card. DSBCAPS_LOCSOFTWARE forces the buffer to reside in main system memory, if possible.
These flags are also defined for the dwFlags member of the DSBCAPS structure, and when used there, the specified flag indicates the actual location of the DirectSoundBuffer object.
When creating a primary buffer, applications must set the dwBufferBytes member to 0; DirectSound will determine the optimal buffer size for the particular sound device in use. To determine the size of a created primary buffer, call IDirectSoundBuffer::GetCaps.
The 3-D algorithms represent selection of the software emulation layer only; that is the software algorithm that is used when no hardware is present for acceleration. In order to maximize hardware utilization, DS3DALG_NO_VIRTUALIZATION is treated as a special case. If no free 3-D hardware voices are available, the buffer is then treated as a 2-D buffer, but with 3-D API control. Specifically, when a sound buffer is created with DS3DALG_NO_VIRTUALIZATION (or the buffer is played if the buffer is created with DSBPLAY_LOCDEFER) the following procedure is followed:
If a free hardware 3-D voice is available, that 3-D hardware voice is used.
If no free hardware 3-D voices are available and a 2-D hardware voice is available, that 2-D hardware voice will be used. This is possible since the NO_VIRTUALIZATION algorithm is a simple stereo pan algorithm
If no free 2-D or 3-D hardware voices are available, the voice will be played in software using the NO_VIRTUALIZATION algorithm.
Note Sound buffers created with the DSBCAPS_CTRLPOSITIONNOTIFY flag must set a notification event. If you create a sound buffer with the NOTIFY flag, but don't actually set any notifications, the behavior is undefined. You may experience sounds being played back twice. Therefore, applications should not use DSBCAPS_CTRLPOSITIONNOTIFY unless they actually set a notification event.
Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dsound.h.