IXAudio2::CreateSubmixVoice Method

Creates and configures a submix voice.

Syntax

public:
HRESULT CreateSubmixVoice(
         IXAudio2SubmixVoice **ppSubmixVoice,
         UINT32 InputChannels,
         UINT32 InputSampleRate,
         UINT32 Flags,
         UINT32 ProcessingStage,
         const XAUDIO2_VOICE_SENDS *pSendList,
         const XAUDIO2_EFFECT_CHAIN *pEffectChain
)

Parameters

ppSubmixVoice
Type: IXAudio2SubmixVoice **

[out] On success, returns a pointer to the new IXAudio2SubmixVoice object.

InputChannels
Type: UINT32

Number of channels in the input audio data of the submix voice. InputChannels must be less than or equal to XAUDIO2_MAX_AUDIO_CHANNELS.

InputSampleRate
Type: UINT32

Sample rate of the input audio data of submix voice. This rate must be a multiple of XAUDIO2_QUANTUM_DENOMINATOR. InputSampleRate must be between XAUDIO2_MIN_SAMPLE_RATE and XAUDIO2_MAX_SAMPLE_RATE.

Flags
Type: UINT32

Flags that specify the behavior of the submix voice. It can be 0 or the following:

Value	Description
XAUDIO2_DO_NO_USE_SHAPE	Xbox One specific flag, forcing XAudio2 to not allocate or use any SHAPE resources (including XMA). By default XAudio2 will allocate SHAPE and XMA contexts. If this flag is used in XAudio2Create, no voices will use SHAPE or XMA.
XAUDIO2_VOICE_USEFILTER	The filter effect should be available on this voice.

ProcessingStage
Type: UINT32

An arbitrary number that specifies when this voice is processed with respect to other submix voices, if the XAudio2 engine is running other submix voices. The voice is processed after all other voices that include a smaller ProcessingStage value and before all other voices that include a larger ProcessingStage value. Voices that include the same ProcessingStage value are processed in any order. A submix voice cannot send to another submix voice with a lower or equal ProcessingStage value. This prevents audio being lost due to a submix cycle.

pSendList
Type: XAUDIO2_VOICE_SENDS *

[in, optional] Pointer to a list of XAUDIO2_VOICE_SENDS structures that describe the set of destination voices for the submix voice. If pSendList is NULL, the send list will default to a single output to the first mastering voice created.

pEffectChain
Type: XAUDIO2_EFFECT_CHAIN *

[in, optional] Pointer to a list of XAUDIO2_EFFECT_CHAIN structures that describe an effect chain to use in the submix voice.

Return value

Type: HRESULT

Returns S_OK if successful; otherwise, an error code.

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

Remarks

Submix voices receive the output of one or more source or submix voices. They process the output, and then send it to another submix voice or to a mastering voice.

A submix voice performs a sample rate conversion from the input sample rate to the input rate of its output voices in pSendList. If you specify multiple voice sends, they must all have the input same sample rate.

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

When first created, submix voices are in the started state.

XAudio2 uses an internal memory pooler for voices with the same format. This means that 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 CreateSubmixVoice from within a callback (that is, IXAudio2EngineCallback or IXAudio2VoiceCallback). If you call CreateSubmixVoice 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 CreateSubmixVoice successfully completes, and may be deleted immediately after CreateSubmixVoice is called.

Requirements

Header: Declared in xaudio2.h.