DSCAPS 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 DSCAPS structure describes the capabilities of a device. It is used by the IDirectSound8::GetCaps method.

Syntax

typedef struct DSCAPS {
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwMinSecondarySampleRate, dwMaxSecondarySampleRate;
    DWORD dwPrimaryBuffers;
    DWORD dwMaxHwMixingAllBuffers;
    DWORD dwMaxHwMixingStaticBuffers;
    DWORD dwMaxHwMixingStreamingBuffers;
    DWORD dwFreeHwMixingAllBuffers;
    DWORD dwFreeHwMixingStaticBuffers;
    DWORD dwFreeHwMixingStreamingBuffers;
    DWORD dwMaxHw3DAllBuffers;
    DWORD dwMaxHw3DStaticBuffers;
    DWORD dwMaxHw3DStreamingBuffers;
    DWORD dwFreeHw3DAllBuffers;
    DWORD dwFreeHw3DStaticBuffers;
    DWORD dwFreeHw3DStreamingBuffers;
    DWORD dwTotalHwMemBytes;
    DWORD dwFreeHwMemBytes;
    DWORD dwMaxContigFreeHwMemBytes;
    DWORD dwUnlockTransferRateHwBuffers;
    DWORD dwPlayCpuOverheadSwBuffers;
    DWORD dwReserved1;
    DWORD dwReserved2;
} DSCAPS;

Members

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

• dwFlags
  Flags describing device capabilities. Can include the values shown in the following table.

  Value	Description
  DSCAPS_CERTIFIED	The driver has been tested and certified by Microsoft. This flag is always set for WDM drivers. To test for certification, use IDirectSound8::VerifyCertification.
  DSCAPS_CONTINUOUSRATE	The device supports all sample rates between the dwMinSecondarySampleRate and dwMaxSecondarySampleRate member values. Typically, this means that the actual output rate will be within +/- 10 hertz (Hz) of the requested frequency.
  DSCAPS_EMULDRIVER	The device does not have a DirectSound driver installed, so it is being emulated through the waveform-audio functions. Performance degradation should be expected.
  DSCAPS_PRIMARY16BIT	The device supports a primary buffer with 16-bit samples.
  DSCAPS_PRIMARY8BIT	The device supports primary buffers with 8-bit samples.
  DSCAPS_PRIMARYMONO	The device supports monophonic primary buffers.
  DSCAPS_PRIMARYSTEREO	The device supports stereo primary buffers.
  DSCAPS_SECONDARY16BIT	The device supports hardware-mixed secondary sound buffers with 16-bit samples.
  DSCAPS_SECONDARY8BIT	The device supports hardware-mixed secondary buffers with 8-bit samples.
  DSCAPS_SECONDARYMONO	The device supports hardware-mixed monophonic secondary buffers.
  DSCAPS_SECONDARYSTEREO	The device supports hardware-mixed stereo secondary buffers.

• dwMinSecondarySampleRate, dwMaxSecondarySampleRate
  Minimum and maximum sample rate specifications that are supported by this device's hardware secondary sound buffers.

• dwPrimaryBuffers
  Number of primary buffers supported. This value will always be 1.

• dwMaxHwMixingAllBuffers
  Number of buffers that can be mixed in hardware. This member can be less than the sum of dwMaxHwMixingStaticBuffers and dwMaxHwMixingStreamingBuffers. Resource tradeoffs frequently occur.

• dwMaxHwMixingStaticBuffers
  Maximum number of static buffers.

• dwMaxHwMixingStreamingBuffers
  Maximum number of streaming sound buffers.

• dwFreeHwMixingAllBuffers
  Number of unallocated buffers. On WDM drivers, this includes dwFreeHw3DAllBuffers.

• dwFreeHwMixingStaticBuffers
  Number of unallocated static buffers.

• dwFreeHwMixingStreamingBuffers
  Number of unallocated streaming buffers.

• dwMaxHw3DAllBuffers
  Maximum number of 3D buffers.

• dwMaxHw3DStaticBuffers
  Maximum number of static 3D buffers.

• dwMaxHw3DStreamingBuffers
  Maximum number of streaming 3D buffers.

• dwFreeHw3DAllBuffers
  Number of unallocated 3D buffers.

• dwFreeHw3DStaticBuffers
  Number of unallocated static 3D buffers.

• dwFreeHw3DStreamingBuffers
  Number of unallocated streaming 3D buffers.

• dwTotalHwMemBytes
  Size, in bytes, of the amount of memory on the sound card that stores static sound buffers.

• dwFreeHwMemBytes
  Size, in bytes, of the free memory on the sound card.

• dwMaxContigFreeHwMemBytes
  Size, in bytes, of the largest contiguous block of free memory on the sound card.

• dwUnlockTransferRateHwBuffers
  The rate, in kilobytes per second, at which data can be transferred to hardware static sound buffers. This and the number of bytes transferred determines the duration of a call to the IDirectSoundBuffer8::Unlock method.

• dwPlayCpuOverheadSwBuffers
  The processing overhead, as a percentage of main processor cycles, needed to mix software buffers. This varies according to the bus type, the processor type, and the clock speed.

• dwReserved1
  Not used.

• dwReserved2
  Not used.

Remarks

Some audio cards may be unable to report accurately the number of available or free hardware buffers. This can happen, for example, when the card can play more sounds at lower sampling rates than at higher rates. In general, a nonzero value in any of the members relating to number of free hardware buffers signifies that at least one hardware resource of the appropriate type is available.

The unlock transfer rate for software buffers is 0, because the data need not be transferred anywhere. Similarly, the play processing overhead for hardware buffers is 0 because the mixing is done by the sound device.

Requirements

Header: Declared in DSound.h.

See Also

IDirectSound8::GetCaps