| Microsoft DirectX 8.1 (C++) |
The DSBUFFERDESC structure describes the characteristics of a new DirectSoundBuffer object. Used by the IDirectSound8::CreateSoundBuffer method and by the DirectSoundFullDuplexCreate8 function.
An earlier version of this structure, DSBUFFERDESC1, is maintained in Dsound.h for compatibility with DirectX 7 and earlier.
Syntax
typedef struct {
DWORD dwSize;
DWORD dwFlags;
DWORD dwBufferBytes;
DWORD dwReserved;
LPWAVEFORMATEX lpwfxFormat;
GUID guid3DAlgorithm;
} DSBUFFERDESC, *LPDSBUFFERDESC;
typedef const DSBUFFERDESC *LPCDSBUFFERDESC;
Members
dwSize
Size of the structure, in bytes. This member must be initialized before the structure is used.
dwFlags
Flags specifying the capabilities to include when creating a new DirectSoundBuffer object. The following values are defined. See also Remarks.
| Value | Description |
| DSBCAPS_CTRL3D | The buffer has 3-D control capability. Cannot be combined with DSBCAPS_CTRLPAN, and cannot be set for a buffer with a stereo format in lpwfxFormat. |
| DSBCAPS_CTRLFREQUENCY | The buffer has frequency control capability. Cannot be combined with DSBCAPS_CTRLFX. |
| DSBCAPS_CTRLFX | The buffer supports effects processing. Cannot be combined with DSBCAPS_CTRLFREQUENCY. The wave format in lpwfxFormat must be an 8-bit or 16-bit PCM format with no more than two channels, and the buffer must be large enough to hold at least DSBSIZE_FX_MIN milliseconds of data. |
| DSBCAPS_CTRLPAN | The buffer has pan control capability. Cannot be combined with DSBCAPS_CTRL3D. |
| DSBCAPS_CTRLPOSITIONNOTIFY | The buffer has position notification capability. See Remarks. |
| DSBCAPS_CTRLVOLUME | The buffer has volume control capability. |
| DSBCAPS_GETCURRENTPOSITION2 | The IDirectSoundBuffer8::GetCurrentPosition method uses the new behavior of the play cursor. In DirectSound in DirectX 1, the play cursor was significantly ahead of the actual playing sound on emulated sound cards; it was directly behind the write cursor. Now, if the DSBCAPS_GETCURRENTPOSITION2 flag is specified, the application can get a more accurate play cursor. If this flag is not specified, the old behavior is preserved for compatibility. Note that this flag affects only emulated sound cards. If a DirectSound driver is present, the play cursor is accurate for DirectSound in all versions of DirectX. |
| DSBCAPS_GLOBALFOCUS | The buffer is a global sound buffer. With this flag set, an application using DirectSound can continue to play its buffers if the user switches focus to another application, even if the new application uses DirectSound. The one exception is if you switch focus to a DirectSound application that uses the DSSCL_WRITEPRIMARY flag for its cooperative level. In this case, the global sounds from other applications will not be audible. |
| DSBCAPS_LOCDEFER | The buffer can be assigned to a hardware or software resource at play time. This flag must be set for buffers that use voice management. |
| DSBCAPS_LOCHARDWARE | The buffer must use hardware mixing, If the device does not support hardware mixing or if the required hardware memory is not available, the call to IDirectSound8::CreateSoundBuffer method will fail. The application must ensure that a mixing channel is available for this buffer; this condition is not guaranteed. |
| DSBCAPS_LOCSOFTWARE | The buffer must be in software memory and use software mixing, even if DSBCAPS_STATIC is specified and hardware resources are available. |
| DSBCAPS_MUTE3DATMAXDISTANCE | The sound is reduced to silence at the maximum distance. The buffer will stop playing when the maximum distance is exceeded, so that processor time is not wasted. |
| DSBCAPS_PRIMARYBUFFER | The buffer is a |
| DSBCAPS_STATIC | The buffer is placed in on-board hardware memory, if available. No error occurs if such memory is not available. Compare this flag with DSBCAPS_LOCHARDWARE, which forces the buffer into hardware memory (probably system memory used by the driver for its mixing buffers) and causes an error if no such memory is available. This flag cannot be combined with DSBCAPS_CTRLFX. |
| DSBCAPS_STICKYFOCUS | The buffer has sticky focus. If the user switches to another application not using DirectSound, the application's normal buffers are muted, but sticky focus buffers are still audible. |
dwBufferBytes
Size of the new buffer, in bytes. This value must be zero when creating a buffer with the DSBCAPS_PRIMARYBUFFER flag. For secondary buffers, the minimum and maximum sizes allowed are specified by DSBSIZE_MIN and DSBSIZE_MAX, defined in Dsound.h.
dwReserved
Reserved. Must be zero.
lpwfxFormat
Address of a WAVEFORMATEX or WAVEFORMATEXTENSIBLE structure specifying the waveform format for the buffer. This value must be NULL for primary buffers. The application can use IDirectSoundBuffer8::SetFormat to set the format of the primary buffer.
guid3DAlgorithm
Unique identifier of the two-speaker virtualization algorithm to be used by DirectSound3D hardware emulation. If DSBCAPS_CTRL3D is not set in dwFlags, this member must be GUID_NULL (DS3DALG_DEFAULT). See also Remarks.
The following algorithm identifiers are defined.
| Value | Description | Availability |
| DS3DALG_DEFAULT | DirectSound uses the default algorithm. In most cases this is DS3DALG_NO_VIRTUALIZATION. On WDM drivers, if the user has selected surround sound in Control Panel, the sound is panned among the left, center, right, and surround channels. | Applies to software mixing only. Available on WDM or Vxd Drivers. |
| DS3DALG_NO_VIRTUALIZATION | 3-D output 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, HRTF processing will not be done.
Because 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. |
Applies to software mixing only. Available on WDM or Vxd Drivers. |
| DS3DALG_HRTF_FULL | The 3-D API is processed with the high quality 3-D audio algorithm. This algorithm gives the highest quality 3-D audio effect, but uses more CPU. See Remarks. . | Applies to software mixing only. Available on Microsoft® Windows® 98 Second Edition and later operating systems when using WDM drivers. |
| DS3DALG_HRTF_LIGHT | The 3-D API is processed with the efficient 3-D audio algorithm. This algorithm gives a good 3-D audio effect, but uses less CPU than DS3DALG_HRTF_FULL. | Applies to software mixing only. Available on Windows 98 Second Edition and later operating systems when using 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 success code, DS_NO_VIRTUALIZATION, is returned. The sound buffer created will use DS3DALG_NO_VIRTUALIZATION instead. For this reason, applications should use the SUCCEEDED or FAILED macros rather than checking explicitly for DS_OK when calling CreateSoundBuffer.
Remarks
When creating a primary buffer, applications must set the dwBufferBytes member to zero. DirectSound will determine the best buffer size for the particular sound device in use. To determine the size of a created primary buffer, call IDirectSoundBuffer8::GetCaps.
The DSBCAPS_CTRLDEFAULT flag is no longer supported. This flag was defined as DSBCAPS_CTRLPAN | DSBCAPS_CTRLVOLUME | DSBCAPS_CTRLFREQUENCY. By specifying only the flags you need, you cut down on unnecessary resource usage.
Sound buffers created with the DSBCAPS_CTRLPOSITIONNOTIFY flag must set a notification event. If you create a sound buffer with this flag but don't actually set any notifications, the behavior is undefined, and you might experience sounds being played back twice.
On VxD drivers, a sound buffer created with DSBCAPS_CTRLPOSITIONNOTIFY is always a software buffer, because the VxD driver model does not support notifications. With WDM drivers, a notification-enabled buffer can be in hardware, if hardware is available. Calling IDirectSoundBuffer8::Play with the DSBPLAY_LOCHARDWARE flag will fail when playing a buffer created with this flag set.
The DSBCAPS_LOCHARDWARE and DSBCAPS_LOCSOFTWARE flags are optional and mutually exclusive. DSBCAPS_LOCHARDWARE forces the buffer to reside in hardware, meaning that it will be mixed by the sound card. DSBCAPS_LOCSOFTWARE forces the buffer to reside in software, where it is mixed by the CPU. These flags are also defined for the dwFlags member of the DSBCAPS structure, where they indicate the actual location of the buffer.
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 when the buffer is played if the buffer was created with DSBPLAY_LOCDEFER, the following procedure is followed:
If a speaker configuration other than DSSPEAKER_HEADPHONE or DSSPEAKER_STEREO is in effect, the processing will be done as if for a two-speaker configuration.
If a 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 success code, DS_NO_VIRTUALIZATION, is returned. The sound buffer created will use DS3DALG_NO_VIRTUALIZATION instead. For this reason, applications should use the SUCCEEDED or FAILED macros rather than checking explicitly for DS_OK when calling CreateSoundBuffer.
Requirements
Header: Declared in Dsound.h.
See Also