Platform SDK: DirectX

DSBUFFERDESC

The DSBUFFERDESC structure describes the 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;

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.

DSBCAPS_CTRL3D: The buffer must have 3-D control capability.
DSBCAPS_CTRLFREQUENCY: The buffer must have frequency control capability.
DSBCAPS_CTRLPAN: The buffer must have pan control capability.
DSBCAPS_CTRLPOSITIONNOTIFY: The buffer must have position notification capability. On VxD drivers, if a sound buffer is created with DSBCAPS_CTRLPOSITIONNOTIFY, this buffer is always a software buffer. With WDM drivers, a notification-enabled buffer can be in hardware, if a hardware buffer is available. See Remarks.
DSBCAPS_CTRLVOLUME: The buffer must have volume control capability.
DSBCAPS_GETCURRENTPOSITION2: The IDirectSoundBuffer::GetCurrentPosition method should use 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. In subsequent versions, if the DSBCAPS_GETCURRENTPOSITION2 flag is specified, the application can retrieve a more accurate play position. If this flag is not specified, the earlier behavior is preserved for compatibility. 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 is hardware mixing, If the device does not support hardware mixing or if the required hardware memory is not available, the call to IDirectSound::CreateSoundBuffer method fails. The application must ensure that a mixing channel is available for this buffer; this condition is not guaranteed.
DSBCAPS_LOCSOFTWARE: The buffer is to be stored in software memory and uses software mixing, even if DSBCAPS_STATIC is specified and hardware resources are available.
DSBCAPS_MUTE3DATMAXDISTANCE: The sound is to be reduced to silence at the maximum distance. The buffer stops playing when the maximum distance is exceeded, so that processor time is not wasted.
DSBCAPS_PRIMARYBUFFER: The buffer is a primary sound buffer. If this value is not specified, a secondary sound buffer is created.
DSBCAPS_STATIC: The buffer is to be placed in on-board hardware memory, if available. No error occurs if no such memory is 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.
DSBCAPS_STICKYFOCUS: The buffer is to have sticky focus. If the user switches to another application that does not use 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 primary buffers. For secondary buffers, the minimum and maximum sizes allowed are specified by DSBSIZE_MIN and DSBSIZE_MAX, defined in Dsound.h.

dwReserved

Reserved.

lpwfxFormat

Address of a structure specifying the waveform format for the buffer. This value must be NULL for primary buffers. The application can use IDirectSoundBuffer::SetFormat to set the format of the primary buffer.

guid3DAlgorithm

Unique identifier of the two-speaker virtualization algorithm to be used by the DirectSound3D HEL. If the DSCAPS_CTRL3D flag is not set for the sound buffer, this value is ignored. If DSBCAPS_CTRL3D is not set in dwFlags, this member must be GUID_NULL (DS3DALG_DEFAULT). Valid for DirectX 7.0 and later. See also Remarks.

The following algorithm identifiers are defined.

DS3DALG_DEFAULT

The HEL is set as the default algorithm. Currently, this selects the DS3DALG_NO_VIRTUALIZATION algorithm, which provides a CPU- efficient but basic 3-D effect.

Applies to Software Mixing Only. Available on WDM or Vxd Drivers.

DS3DALG_NO_VIRTUALIZATION

The Direct3D API is mapped onto normal left and right stereo panning. At 90 degrees to the left, the sound comes from only the left speaker; at 90 degrees to the right, sound comes from only the right speaker. The vertical axis is ignored except for volume scaling 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 flag applies only to the software HEL. 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 Windows 2000 when using WDM drivers. .

Note: If a sound buffer is created using an HRTF algorithm, 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.

DS3DALG_HRTF_LIGHT

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.

Applies to Software Mixing only. Available on Windows 98 Second Edition and Windows 2000 when using WDM drivers.

Remarks

When creating a primary buffer, applications must set the dwBufferBytes member to zero. DirectSound determines the best buffer size for the particular sound device in use. To determine the size of a created primary buffer, call IDirectSoundBuffer::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.

The DSBCAPS_LOCHARDWARE and DSBCAPS_LOCSOFTWARE flags are optional and mutually exclusive. DSBCAPS_LOCHARDWARE forces the buffer to reside in hardware, meaning that it is 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, and when used there, the specified flag indicates the actual location of the DirectSoundBuffer object.

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. 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 treated as a 2-D buffer, but with 3-D API control. Specifically, when a sound buffer is created with DS3DALG_NO_VIRTUALIZATION and DSBCAPS_LOCDER, 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 voice is available and a 2-D hardware voice is available, that 2-D hardware voice is used. This is possible because the DS3DALG_NO_VIRTUALIZATION algorithm is a simple stereo pan algorithm
If no free 2-D or 3-D hardware voices are available, the voice is 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 is done as if for a two-speaker configuration.

If a buffer is created using an HRTF algorithm, 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.

Sound buffers created with the DSBCAPS_CTRLPOSITIONNOTIFY flag must set a notification event. If you create a sound buffer with the flag, but don't set any notifications, the behavior is undefined.

Requirements

  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.

DSBUFFERDESC

Members

Remarks

Requirements

See Also