WAVEFORMATEXTENSIBLE 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 WAVEFORMATEXTENSIBLE structure defines the format of waveform-audio data for formats having more than two channels or higher sample resolutions than allowed by WAVEFORMATEX.
This structure is not part of the DirectSound API but is documented here for convenience.
Syntax
typedef struct WAVEFORMATEXTENSIBLE {
WAVEFORMATEX Format;
WORD wValidBitsPerSample;
WORD wSamplesPerBlock;
WORD wReserved;
DWORD dwChannelMask;
DWORD SubFormat;
} WAVEFORMATEXTENSIBLE;
Members
- Format
WAVEFORMATEX structure that specifies the basic format. The wFormatTag member must be WAVE_FORMAT_EXTENSIBLE, defined in Mmreg.h. The cbSize member must be at least 22. - wValidBitsPerSample
Number of bits of precision in the signal. Usually equal to WAVEFORMATEX.wBitsPerSample. However, wBitsPerSample is the container size and must be a multiple of 8, whereas wValidBitsPerSample can be any value not exceeding the container size. For example, if the format uses 20-bit samples, wBitsPerSample must be at least 24, but wValidBitsPerSample is 20. - wSamplesPerBlock
Number of samples contained in one compressed block of audio data. This value is used in buffer estimation. This value is used with compressed formats that have a fixed number of samples within each block. This value can be set to zero if a variable number of samples is contained in each block of compressed audio data. In this case, buffer estimation and position information needs to be obtained in other ways. - wReserved
Reserved for internal use by operating system. Set to zero. - dwChannelMask
Bitmask specifying the assignment of channels in the stream to speaker positions. See Remarks. - SubFormat
Subformat of the data, such as KSDATAFORMAT_SUBTYPE_PCM. The subformat information is similar to that provided by the tag in the WAVEFORMATEX structure's wFormatTag member.
Remarks
WAVEFORMATEXTENSIBLE can describe any format that can be described by WAVEFORMATEX, but provides additional support for more than two channels, for greater precision in the number of bits per sample, and for new compression schemes.
WAVEFORMATEXTENSIBLE can safely be cast to WAVEFORMATEX, because it simply configures the extra bytes specified by WAVEFORMATEX.cbSize. DirectSound recognizes the WAVE_FORMAT_EXTENSIBLE format tag and correctly plays multiple-channel and compressed formats in hardware buffers, as long as these formats are supported by the driver.
The dwChannelMask member specifies which channels are present in the multichannel stream. The least significant bit corresponds with the front left speaker, the next least significant bit corresponds to the front right speaker, and so on. The bits, in order of significance, are defined in Ksmedia.h and Mmreg.h as follows.
| Speaker position | Flag bit |
|---|---|
| SPEAKER_FRONT_LEFT | 0x1 |
| SPEAKER_FRONT_RIGHT | 0x2 |
| SPEAKER_FRONT_CENTER | 0x4 |
| SPEAKER_LOW_FREQUENCY | 0x8 |
| SPEAKER_BACK_LEFT | 0x10 |
| SPEAKER_BACK_RIGHT | 0x20 |
| SPEAKER_FRONT_LEFT_OF_CENTER | 0x40 |
| SPEAKER_FRONT_RIGHT_OF_CENTER | 0x80 |
| SPEAKER_BACK_CENTER | 0x100 |
| SPEAKER_SIDE_LEFT | 0x200 |
| SPEAKER_SIDE_RIGHT | 0x400 |
| SPEAKER_TOP_CENTER | 0x800 |
| SPEAKER_TOP_FRONT_LEFT | 0x1000 |
| SPEAKER_TOP_FRONT_CENTER | 0x2000 |
| SPEAKER_TOP_FRONT_RIGHT | 0x4000 |
| SPEAKER_TOP_BACK_LEFT | 0x8000 |
| SPEAKER_TOP_BACK_CENTER | 0x10000 |
| SPEAKER_TOP_BACK_RIGHT | 0x20000 |
For more information on this structure, see the document Multiple Channel Audio Data and WAVE Files, available at www.microsoft.com.
Requirements
Header: Declared in Mmreg.h, Ksproxy.h.