DSBCAPS Structure

[The feature associated with this page, DirectSound, is a legacy feature. It has been superseded by WASAPI and Audio Graphs. Media Casting have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use Media Casting instead of DirectSound, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The DSBCAPS structure describes the capabilities of a DirectSound buffer object. It is used by the IDirectSoundBuffer8::GetCaps method.

Syntax

typedef struct DSBCAPS {
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwBufferBytes;
    DWORD dwUnlockTransferRate;
    DWORD dwPlayCpuOverhead;
} DSBCAPS;

Members

• dwSize
  Size of the structure, in bytes. This member must be initialized before the structure is used.

• dwFlags
  Flags that specify buffer-object capabilities. Use one or more of the values shown in the following table.

  Value	Description
  DSBCAPS_CTRL3D	The buffer has 3D control capability.
  DSBCAPS_CTRLFREQUENCY	The buffer has frequency control capability.
  DSBCAPS_CTRLFX	The buffer supports effects processing.
  DSBCAPS_CTRLPAN	The buffer has pan control capability.
  DSBCAPS_CTRLVOLUME	The buffer has volume control capability.
  DSBCAPS_CTRLPOSITIONNOTIFY	The buffer has position notification capability. See the Remarks for DSCBUFFERDESC.
  DSBCAPS_GETCURRENTPOSITION2	The buffer uses the new behavior of the play cursor when IDirectSoundBuffer8::GetCurrentPosition is called. In the first version of DirectSound, 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. This flag affects only emulated devices; 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, or when IDirectSoundBuffer8::AcquireResources is called.
  DSBCAPS_LOCHARDWARE	The buffer uses hardware mixing.
  DSBCAPS_LOCSOFTWARE	The buffer is in software memory and uses software mixing.
  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.
  DSBCAPS_STATIC	The buffer is in on-board hardware memory.
  DSBCAPS_STICKYFOCUS	The buffer has sticky focus. If the user switches to another application not using DirectSound, the buffer is still audible. However, if the user switches to another DirectSound application, the buffer is muted.
  DSBCAPS_TRUEPLAYPOSITION	Force IDirectSoundBuffer8::GetCurrentPosition to return the buffer's true play position. This flag is only valid in Windows Vista.

• dwBufferBytes
  Size of this buffer, in bytes.

• dwUnlockTransferRate
  The rate, in kilobytes per second, at which data is transferred to the buffer memory when IDirectSoundBuffer8::Unlock is called. High-performance applications can use this value to determine the time required for IDirectSoundBuffer8::Unlock to execute. For software buffers located in system memory, the rate will be very high because no processing is required. For hardware buffers, the rate might be slower because the buffer might have to be downloaded to the sound card, which might have a limited transfer rate.

• dwPlayCpuOverhead
  The processing overhead as a percentage of main processor cycles needed to mix this sound buffer. For hardware buffers, this member will be zero because the mixing is performed by the sound device. For software buffers, this member depends on the buffer format and the speed of the system processor.

Remarks

The DSBCAPS structure contains information similar to that found in the DSCBUFFERDESC structure passed to the IDirectSound8::CreateSoundBuffer method, with some additional information. Additional information includes the location of the buffer (hardware or software) and some cost measures (such as the time to download the buffer if located in hardware, and the processing overhead to play the buffer if it is mixed in software).

The dwFlags member contains the same flags used by the DSBUFFERDESC structure. The only difference is that in the DSBCAPS structure, either the DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE flag is specified, according to the location of the buffer. In the DSBUFFERDESC structure, these flags are optional and are used to force the buffer to be located in either hardware or software.

To use #defines implemented in Windows Vista, set the DIRECTSOUND_VERSION to 0x1000 before including DSound.h.

Requirements

Header: Declared in DSound.h.

See Also

IDirectSound8::CreateSoundBuffer
IDirectSoundBuffer8::GetCaps