Microsoft DirectX 9.0

DSBUFFERDESC

The DSBUFFERDESC structure describes the characteristics of a new buffer object. It is 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 of the buffer. The following values are defined.

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.
DSBCAPS_CTRLFX The buffer supports effects processing. The WAV 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. If neither this flag nor DSBCAPS_LOCSOFTWARE is specified, the buffer is placed in hardware if resources are available, or in software if hardware resources are not available.
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. Applies only to software buffers.
DSBCAPS_PRIMARYBUFFER The buffer is a primary buffer. If this value is not specified, a secondary sound buffer is created. Cannot be combined with DSBCAPS_CTRLFX.
DSBCAPS_STATIC The buffer is placed in on-board hardware memory, if available. No error occurs if such memory is not available. This flag has no effect on cards using the PCI bus. 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 0 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 0.

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).

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 a surround sound speaker configuration in Control Panel, the sound is panned among the available directional speakers. 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 algorithm 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 cycles. 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 fewer CPU cycles than DS3DALG_HRTF_FULL. Applies to software mixing only. Available on Windows 98 Second Edition and later operating systems when using WDM drivers.

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.

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 resources are available.

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.

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 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:

  1. If a free hardware 3-D voice is available, that 3-D hardware voice is used.
  2. 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 because the DS3DALG_NO_VIRTUALIZATION algorithm is a simple stereo pan algorithm
  3. If no free 2-D or 3-D hardware voices are available, the voice will be played in software using the DS3DALG_NO_VIRTUALIZATION algorithm.

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