WAVEFORMATEX Structure

  • Article

The WAVEFORMATEX structure defines the format of waveform-audio data. Only format information common to all waveform-audio data formats is included in this structure. For formats that require additional information, this structure is included as the first member in another structure containing the additional information.

Syntax

typedef struct tWAVEFORMATEX {
    WORD wFormatTag;
    WORD nChannels;
    DWORD nSamplesPerSec;
    DWORD nAvgBytesPerSec;
    WORD nBlockAlign;
    WORD wBitsPerSample;
    WORD cbSize;
} WAVEFORMATEX, *PWAVEFORMATEX, *LPWAVEFORMATEX;

Members

  • wFormatTag
    Waveform-audio format type.

    Format tags are registered with Microsoft Corporation for many compression algorithms. The following table identifies possible format tags.

    Format Tag Data Format Data Structure Containing the WAVEFORMATEX
    WAVE_FORMAT_PCM PCM data with one or two channels. None
    WAVE_FORMAT_IEEE_FLOAT PCM data with one or two channels. None
    WAVE_FORMAT_EXTENSIBLE PCM data that has more than two channels or uses a channel mask. WAVEFORMATEXTENSIBLE
    WAVE_FORMAT_ADPCM ADPCM data. ADPCMWAVEFORMAT
    WAVE_FORMAT_XMA2 XMA2 data. XMA2WAVEFORMATEX
    WAVE_FORMAT_WMAUDIO2 xWMA data. xWMA data will be have a flag of WAVE_FORMAT_WMAUDIO2 or WAVE_FORMAT_WMAUDIO3 depending on the encoder being used. None or WAVEFORMATEXTENSIBLE depending on the number of channels as with PCM data.
    WAVE_FORMAT_WMAUDIO3 xWMA data. xWMA data will be have a flag of WAVE_FORMAT_WMAUDIO2 or WAVE_FORMAT_WMAUDIO3 depending on the encoder being used. None or WAVEFORMATEXTENSIBLE depending on the number of channels as with PCM data.

  • nChannels
    Number of channels in the waveform-audio data. Monaural data uses one channel and stereo data uses two channels. nChannels must be less than or equal to XAUDIO2_MAX_AUDIO_CHANNELS.

  • nSamplesPerSec
    Sample rate, in samples per second (hertz). If wFormatTag is WAVE_FORMAT_PCM, then common values for nSamplesPerSec are 8.0 kHz, 11.025 kHz, 22.05 kHz, and 44.1 kHz. For non-PCM formats, this member must be computed according to the manufacturer's specification for the format tag. nSamplesPerSec must be between XAUDIO2_MIN_SAMPLE_RATE and XAUDIO2_MAX_SAMPLE_RATE.

  • nAvgBytesPerSec
    Required average data-transfer rate, in bytes per second, for the format tag. If wFormatTag is WAVE_FORMAT_PCM, nAvgBytesPerSec should be equal to the product of nSamplesPerSec and nBlockAlign. For non-PCM formats, this member must be computed according to the manufacturer's specification for the format tag.

  • nBlockAlign
    Block alignment, in bytes. The block alignment is the minimum atomic unit of data for the wFormatTag format type. If wFormatTag is WAVE_FORMAT_PCM or WAVE_FORMAT_EXTENSIBLE, then nBlockAlign must be equal to the product of nChannels and wBitsPerSample divided by 8 (bits per byte). For non-PCM formats, this member must be computed according to the manufacturer's specification for the format tag. Software must process a multiple of nBlockAlign bytes of data at a time. Data written to and read from a device must start at the beginning of a block. For example, it is illegal to start playback of PCM data in the middle of a sample (that is, on a non-block-aligned boundary).

  • wBitsPerSample
    Bits per sample for the wFormatTag format type.

    wBitsPerSample has the following restrictions on allowable values.

    • If wFormatTag is WAVE_FORMAT_PCM, then wBitsPerSample must be equal to 8 or 16, other values are not supported.

    • If wFormatTag is WAVE_FORMAT_EXTENSIBLE, this value can be any integer multiple of 8. Some compression schemes cannot define a value for wBitsPerSample, so this member can be zero.

    • For non-PCM formats, this member must be set according to the manufacturer's specification for the format tag.

  • cbSize
    Size, in bytes, of extra format information appended to the end of the WAVEFORMATEX structure. This information can be used by non-PCM formats to store extra attributes for wFormatTag. If no extra information is required by the wFormatTag, this member must be set to zero. This member is for the WAVE_FORMAT_PCM format.

    The value of cbSize can be determined by taking the sizeof the containing structure indicated in the chart in the wFormat description and subtracting the sizeof WAVEFORMATEX structure. For example, the value for the WAVE_FORMAT_XMA2 format could be determined with the following code:

    sizeof(XMA2WAVEFORMATEX) - sizeof(WAVEFORMATEX)

Remarks

Format-specific extensions can be defined for particular formats by using a non-zero cbSize value and adding extra fields to the end of this structure.

The members of WAVEFORMATEX correspond to values contained in the 'fmt ' RIFF chunk of the audio file being played. The values loaded from the chunk will need to be byte swapped when loading the file on Xbox 360.

Requirements

Header: Declared in audiodefs.h.

See Also

XAudio2 Structures