Creates and configures a source voice.
HRESULT CreateSourceVoice( IXAudio2SourceVoice **ppSourceVoice, const WAVEFORMATEX *pSourceFormat, UINT32 Flags, float MaxFrequencyRatio, IXAudio2VoiceCallback *pCallback, const XAUDIO2_VOICE_SENDS *pSendList, const XAUDIO2_EFFECT_CHAIN *pEffectChain );
If successful, returns a pointer to the new IXAudio2SourceVoice object.
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_IEEE_FLOAT (0x0003) [32-bit]||PCMWAVEFORMAT||18|
|WAVE_FORMAT_ADPCM (0x0002) [MS-ADPCM]||ADPCMWAVEFORMAT||50|
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)
Returns S_OK if successful; otherwise, an error code.
See XAudio2 Error Codes for descriptions of XAudio2-specific error codes.
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.