DirectX SDK

DSBCAPS

The DSBCAPS type specifies the capabilities of a DirectSoundBuffer object, for use by the DirectSoundBuffer.GetCaps method.

Type DSBCAPS
    lBufferBytes As Long
    lFlags As CONST_DSBCAPSFLAGS
    lPlayCpuOverhead As Long
    lUnlockTransferRate As Long
End Type

Members

lBufferBytes

Size of this buffer, in bytes.

lFlags

One of more of the following constants of the CONST_DSBCAPSFLAGS enumeration that specify buffer-object capabilities.

DSBCAPS_CTRL3D: The buffer is either a primary buffer or a secondary buffer that uses 3-D control. To create a primary buffer, the lFlags member of the DSBUFFERDESC type should include the DSBCAPS_PRIMARYBUFFER flag.
DSBCAPS_CTRLFREQUENCY: The buffer must have frequency control capability.
DSBCAPS_CTRLPAN: The buffer must have pan control capability.
DSBCAPS_CTRLVOLUME: The buffer must have volume 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 will always be a software buffer. This is because the VxD driver model doesn't support the notify interface. With WDM drivers, a position notification enabled buffer may be in hardware, if hardware is available.
Calling DirectSoundBuffer.Play with the DSBPLAY_LOCHARDWARE flag will fail when playing a buffer created with this flag set. Sound buffers created with the DSBCAPS_CTRLPOSITIONNOTIFY flag must set a notification event. If you create a sound buffer with the NOTIFY flag, but don't actually set any notifications, the behavior is undefined. You may experience sounds being played back twice. Therefore, applications should not use DSBCAPS_CTRLPOSITIONNOTIFY unless they actually set a notification event.
DSBCAPS_GETCURRENTPOSITION2: Indicates that DirectSoundBuffer.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. Now, if the DSBCAPS_GETCURRENTPOSITION2 flag is specified, the application can get a more accurate play position. 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_EXCLUSIVE or DSSCL_WRITEPRIMARY flag for its cooperative level. In this case, the global sounds from other applications will not be audible.
DSBCAPS_LOCHARDWARE: The buffer is in hardware memory and 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.
DSBCAPS_PRIMARYBUFFER: Indicates that the buffer is a primary sound buffer. If this value is not specified, a secondary sound buffer will be created.
DSBCAPS_STATIC: Indicates that the buffer will be used for static sound data. Typically, these buffers are loaded once and played many times. These buffers are candidates for hardware memory.
DSBCAPS_STICKYFOCUS: Changes the focus behavior of the sound buffer. This flag can be specified in a DirectSound.CreateSoundBuffer call. With this flag set, an application using DirectSound can continue to play its sticky focus buffers if the user switches to another application not using DirectSound. In this situation, the application's normal buffers are muted, but the sticky focus buffers are still audible. This is useful for nongame applications, such as movie playback (DirectShow®), when the user wants to hear the soundtrack while typing in Microsoft Word or Microsoft® Excel, for example. However, if the user switches to another DirectSound application, all sound buffers, both normal and sticky focus, in the previous application are muted.

lPlayCpuOverhead

Specifies the processing overhead as a percentage of main processing cycles needed to mix this sound buffer. For hardware buffers, this member will be 0 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.

lUnlockTransferRate

Specifies the rate, in kilobytes per second, at which data is transferred to the buffer memory. High-performance applications can use this value to determine the time required for DirectSoundBuffer.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.

Remarks

The DSBCAPS type contains information similar to that found in the DSBUFFERDESC type passed to the DirectSound.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).

Note The lFlags member of the DSBCAPS type contains the same flags used by the DSBUFFERDESC type. The only difference is that in the DSBCAPS type, either the DSBCAPS_LOCHARDWARE or DSBCAPS_LOCSOFTWARE flag will be specified, according to the location of the buffer memory. In the DSBUFFERDESC type, 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 the NOTIFY flag, but don't actually set any notifications, the behavior is undefined. You may experience sounds being played back twice. Therefore, applications should not use DSBCAPS_CTRLPOSITIONNOTIFY unless they actually set a notification event.

DSBCAPS

Members

Remarks

See Also