IXAudio2::CreateSourceVoice method

Creates and configures a source voice.

Syntax

HRESULT CreateSourceVoice(
  IXAudio2SourceVoice        **ppSourceVoice,
  const WAVEFORMATEX         *pSourceFormat,
  UINT32                     Flags,
  float                      MaxFrequencyRatio,
  IXAudio2VoiceCallback      *pCallback,
  const XAUDIO2_VOICE_SENDS  *pSendList,
  const XAUDIO2_EFFECT_CHAIN *pEffectChain
);

Parameters

ppSourceVoice

If successful, returns a pointer to the new IXAudio2SourceVoice object.

pSourceFormat

Pointer to a one of the structures in the table below. This structure contains the expected format for all audio buffers submitted to the source voice. XAudio2 supports PCM and ADPCM voice types.

Format tag Wave format structure Size (in bytes)
WAVE_FORMAT_PCM (0x0001) PCMWAVEFORMAT 16
-or- WAVEFORMATEX 18
WAVE_FORMAT_IEEE_FLOAT (0x0003) [32-bit] PCMWAVEFORMAT 18
WAVE_FORMAT_ADPCM (0x0002) [MS-ADPCM] ADPCMWAVEFORMAT 50
WAVE_FORMAT_EXTENSIBLE (0xFFFE) WAVEFORMATEXTENSIBLE 40
 

XAudio2 supports the following PCM formats.

  • 8-bit (unsigned) integer PCM
  • 16-bit integer PCM (optimal format for XAudio2)
  • 20-bit integer PCM (either in 24 or 32 bit containers)
  • 24-bit integer PCM (either in 24 or 32 bit containers)
  • 32-bit integer PCM
  • 32-bit float PCM (preferred format after 16-bit integer)
The number of channels in a source voice must be less than or equal to XAUDIO2_MAX_AUDIO_CHANNELS. The sample rate of a source voice must be between XAUDIO2_MIN_SAMPLE_RATE and XAUDIO2_MAX_SAMPLE_RATE.
Note  PCM data formats such as PCMWAVEFORMAT and ADPCMWAVEFORMAT that require more information than provided by WAVEFORMATEX have a WAVEFORMATEX structure as the first member in their format structures. When you create a source voice with one of those formats, cast the format's structure as a WAVEFORMATEX structure and use it as the value for pSourceFormat.
 

Flags

MaxFrequencyRatio

pCallback

pSendList

pEffectChain

Return Value

Returns S_OK if successful; otherwise, an error code.

See XAudio2 Error Codes for descriptions of XAudio2-specific error codes.

Remarks

Source voices read audio data from the client. They process the data and send it to the XAudio2 processing graph.

A source voice includes a variable-rate sample rate conversion, to convert data from the source format sample rate to the output rate required for the voice send list. If you use a NULL send list, the target sample rate will be the mastering voice's input sample rate. If you provide a single voice in pSendList, that voice's input sample rate is the target rate. If you provide multiple voices in the pSendList, all the source voice's output voices must be running at the same input sample rate.

You cannot create any source or submix voices until a mastering voice exists, and you cannot destory a mastering voice if any source or submix voices still exist.

Source voices are always processed before any submix or mastering voices. This means that you do not need a ProcessingStage parameter to control the processing order.

When first created, source voices are in the stopped state.

XAudio2 uses an internal memory pooler for voices with the same format. This means memory allocation for voices will occur less frequently as more voices are created and then destroyed. To minimize just-in-time allocations, a title can create the anticipated maximum number of voices needed up front, and then delete them as necessary. Voices will then be reused from the XAudio2 pool. The memory pool is tied to an XAudio2 engine instance. You can reclaim all the memory used by an instance of the XAudio2 engine by destroying the XAudio2 object and recreating it as necessary (forcing the memory pool to grow via preallocation would have to be reapplied as needed).

It is invalid to call CreateSourceVoice from within a callback (that is, IXAudio2EngineCallback or IXAudio2VoiceCallback). If you call CreateSourceVoice within a callback, it returns XAUDIO2_E_INVALID_CALL.

The XAUDIO2_EFFECT_CHAIN that is passed in as the pEffectChain argument and any XAUDIO2_EFFECT_DESCRIPTOR information contained within it are no longer needed after CreateSourceVoice successfully completes, and may be deleted immediately after CreateSourceVoice is called.

Platform Requirements

Windows 10 (XAudio2.9); Windows 8, Windows Phone 8 (XAudio 2.8); DirectX SDK (XAudio 2.7)

Requirements

   
Target Platform Windows
Header xaudio2.h

See Also

How to: Build a Basic Audio Processing Graph

IXAudio2

XAPO Overview

XAudio2 Sample Rate Conversions