Platform SDK: DirectX

DSBCAPS

The DSBCAPS structure specifies the capabilities of a DirectSound buffer object, for use by the IDirectSoundBuffer::GetCaps method.

typedef struct { 
    DWORD  dwSize; 
    DWORD  dwFlags; 
    DWORD  dwBufferBytes; 
    DWORD  dwUnlockTransferRate; 
    DWORD  dwPlayCpuOverhead; 
} DSBCAPS, *LPDSBCAPS; 
 
typedef const DSBCAPS *LPCDSBCAPS;

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.

DSBCAPS_CTRL3D: The buffer has 3-D control capability.
DSBCAPS_CTRLFREQUENCY: The buffer has frequency control capability.
DSBCAPS_CTRLPAN: The buffer has pan control capability.
DSBCAPS_CTRLVOLUME: The buffer has volume control capability.
DSBCAPS_CTRLPOSITIONNOTIFY: The buffer has position notification capability. On VxD drivers, a sound buffer created with this flag is always a software buffer, because the VxD driver model doesn't support notifications. With WDM drivers, a notification-enabled buffer can be in hardware, if hardware is available. This flag causes IDirectSoundBuffer::Play to fail if the DSBPLAY_LOCHARDWARE flag is passed to that method.
DSBCAPS_GETCURRENTPOSITION2: IDirectSoundBuffer::GetCurrentPosition 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 get 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 are not audible.
DSBCAPS_LOCDEFER: The buffer can be assigned to a hardware or software resource at play time.
DSBCAPS_LOCHARDWARE: The buffer uses hardware mixing.
DSBCAPS_LOCSOFTWARE: The buffer is in software memory and uses software mixing.
DSBCAPS_MIXIN: The buffer can receive sends from other buffers.
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 primary sound buffer. If this value is not specified, a secondary sound buffer is created.
DSBCAPS_STATIC: The buffer is in on-board hardware memory.
DSBCAPS_STICKYFOCUS: The buffer has sticky focus. If the user switches to another application that does not use DirectSound, the buffer is still audible. However, if the user switches to another DirectSound application, the buffer is muted.

dwBufferBytes

Size of this buffer, in bytes.

dwUnlockTransferRate

The rate, in kilobytes per second, at which data is transferred to the buffer memory when IDirectSoundBuffer::Unlock is called. High-performance applications can use this value to determine the time required for IDirectSoundBuffer::Unlock to execute. For software buffers located in system memory, the rate is 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 processing cycles needed to mix this sound buffer. For hardware buffers, this member is 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 DSBUFFERDESC structure passed to the IDirectSound::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 it is located in hardware, and the processing overhead to play the buffer if it is mixed in software.

Note The dwFlags member of the DSBCAPS structure 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.

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 set any notifications, the behavior is undefined, and you might experience sounds being played back twice.

Requirements

  Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dsound.h.

DSBCAPS

Members

Remarks

Requirements

See Also