CONST_DSBCAPSFLAGS

The CONST_DSBCAPSFLAGS enumeration is used in the DSBUFFERDESC types to specify desired capabilities of a new buffer and in DSBCAPS to describe capabilities of an existing buffer.

Syntax

Enum CONST_DSBCAPSFLAGS
  DSBCAPS_CTRL3D              =     16 (&H10)
  DSBCAPS_CTRLCHANNELVOLUME   =   1024 (&H400)
  DSBCAPS_CTRLFREQUENCY       =     32 (&H20)
  DSBCAPS_CTRLFX              =    512 (&H200)
  DSBCAPS_CTRLPAN             =     64 (&H40)
  DSBCAPS_CTRLPOSITIONNOTIFY  =    256 
  DSBCAPS_CTRLVOLUME          =    128 (&H80)
  DSBCAPS_GETCURRENTPOSITION2 =  65536 (&H10000)
  DSBCAPS_GLOBALFOCUS         =  32768 (&H8000)
  DSBCAPS_LOCDEFER            = 262144 (&H40000)
  DSBCAPS_LOCHARDWARE         =      4 
  DSBCAPS_LOCSOFTWARE         =      8 
  DSBCAPS_MUTE3DATMAXDISTANCE = 131072 (&H20000)
  DSBCAPS_PRIMARYBUFFER       =      1 
  DSBCAPS_STATIC              =      2 
  DSBCAPS_STICKYFOCUS         =  16384 (&H4000)
End Enum

Constants

DSBCAPS_CTRL3D

The buffer supports 3-D control.

DSBCAPS_CTRLCHANNELVOLUME

The buffer supports setting channel volumes. This control is available only on mono buffers and cannot be combined with DSBCAPS_CTRL3D or DSBCAPS_CTRLPAN.

DSBCAPS_CTRLFREQUENCY

The buffer supports frequency control. Cannot be combined with DSBCAPS_CTRLFX.

DSBCAPS_CTRLFX

The buffer supports effects. Cannot be combined with DSBCAPS_CTRLFREQUENCY. The wave format must be an 8-bit or 16-bit PCM format with no more than two channels.

DSBCAPS_CTRLPAN

The buffer supports pan control.

DSBCAPS_CTRLPOSITIONNOTIFY

The buffer supports position notification. See Remarks.

DSBCAPS_CTRLVOLUME

The buffer supports volume control.

DSBCAPS_GETCURRENTPOSITION2

DirectSoundSecondaryBuffer8.GetCurrentPosition uses the new behavior of the play cursor. Always set this flag on secondary buffers.

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. However, if the focus is switched to a DirectSound application that uses the DSSCL_WRITEPRIMARY flag for its cooperative level, the global sounds from other applications are not audible.

DSBCAPS_LOCDEFER

The buffer is not assigned to hardware or software until it is played. This flag must be set for buffers that use voice management.

DSBCAPS_LOCHARDWARE

The buffer uses hardware mixing. If the device does not support hardware mixing or if the required hardware memory is not available, the call to the DirectSound8.CreateSoundBuffer method fails. The application must ensure that a mixing channel will be available for this buffer; this condition is not guaranteed.

DSBCAPS_LOCSOFTWARE

The buffer uses software mixing, even if DSBCAPS_STATIC is specified and hardware resources are available.

DSBCAPS_MUTE3DATMAXDISTANCE

The buffer stops playing when the maximum distance from the listener is exceeded, so that processor time is not wasted.

DSBCAPS_PRIMARYBUFFER

The buffer is a primary sound buffer. Cannot be combined with DSBCAPS_CTRLFX

DSBCAPS_STATIC

The buffer is placed in memory on the sound card, if available. This is not the same as DSBCAPS_LOCHARDWARE, which forces the buffer to be placed in memory, usually system memory, managed by the driver. Cannot be combined with DSBCAPS_CTRLFX.

DSBCAPS_STICKYFOCUS

The buffer has sticky focus. An application using DirectSound can continue to play such buffers if the user switches to an application that is 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 when the user wants to hear the soundtrack while using another application. However, if the user switches to a DirectSound application, all sound buffers, both normal and sticky focus, in the previous application are muted.

Remarks

When a buffer is being created, 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. In the DSBCAPS type, the flag indicates the actual location of the buffer.

If you create a sound buffer with the DSBCAPS_CTRLPOSITIONNOTIFY flag but fail to set notifications, the behavior is undefined, and sounds may be played twice.

On VxD drivers, if a sound buffer is created with DSBCAPS_CTRLPOSITIONNOTIFY, the buffer is always a software buffer. Calling DirectSoundSecondaryBuffer8.Play with the DSBPLAY_LOCHARDWARE flag will fail when playing a buffer created with this flag set. With WDM drivers, a notification-enabled buffer can be in hardware, if hardware is available.