IXAudio2::CreateMasteringVoice Method

Article
06/07/2010

Creates and configures a mastering voice.

Syntax

HRESULT CreateMasteringVoice(
         IXAudio2MasteringVoice **ppMasteringVoice,
         UINT32 InputChannels = XAUDIO2_DEFAULT_CHANNELS,
         UINT32 InputSampleRate = XAUDIO2_DEFAULT_SAMPLERATE,
         UINT32 Flags = 0,
         UINT32 DeviceIndex = 0,
         const XAUDIO2_EFFECT_CHAIN *pEffectChain = NULL
)

Parameters

ppMasteringVoice
[out] If successful, returns a pointer to the new IXAudio2MasteringVoice object.
InputChannels
[in] Number of channels the mastering voice expects in its input audio.

InputChannels must be less than or equal to XAUDIO2_MAX_AUDIO_CHANNELS.

InputChannels can be set to XAUDIO2_DEFAULT_CHANNELS, with the default being determined by the current platform.

Windows

Attempts to detect the system speaker configuration setup.

Xbox 360

Defaults to 5.1 surround.

Windows
Attempts to detect the system speaker configuration setup.

Xbox 360
Defaults to 5.1 surround.

InputSampleRate
[in] Sample rate of the input audio data of the mastering voice. This rate must be a multiple of XAUDIO2_QUANTUM_DENOMINATOR.

InputSampleRate must be between XAUDIO2_MIN_SAMPLE_RATE and XAUDIO2_MAX_SAMPLE_RATE.

InputSampleRate can be set to XAUDIO2_DEFAULT_SAMPLERATE, with the default being determined by the current platform.

Windows
Windows XP defaults to 44100. Windows Vista and Windows 7 default to the setting specified in the Sound Control Panel. The default for this setting is 44100 (or 48000 if required by the driver).

Windows XP defaults to 44100.

Windows Vista and Windows 7 default to the setting specified in the Sound Control Panel. The default for this setting is 44100 (or 48000 if required by the driver).

Xbox 360
Defaults to 48000.

Flags
[in] Flags that specify the behavior of the mastering voice. Must be 0.
DeviceIndex
[in] Index of the output device that will be sent input by the mastering voice. Specifying the default value of 0 causes XAudio2 to select the global default audio device.
pEffectChain
[in, optional] Pointer to an XAUDIO2_EFFECT_CHAIN structure that describe an effect chain to use in the mastering voice, or NULL to use no effects.

Return Value

Returns S_OK if successful, an error code otherwise. See XAudio2 Error Codes for descriptions of XAudio2 specific error codes.

Remarks

Mastering voices receive the output of one or more source or submix voices. They process the data and send it to the audio output device.

Typically, a mastering voice should be created with an input sample rate that will be used by the majority of the title's audio content. The mastering voice performs a sample rate conversion from this input sample rate to the actual device output rate. Alternatively, IXAudio2::GetDeviceDetails can be used to find the native audio rate, and that can be used throughout the majority of the title's audio graph.

No source or submix voices can be created until a mastering voice exists, and a mastering voice cannot be destroyed if any source or submix voices still exist.

Mastering voices are always processed after all source and submix voices. This means that you need not specify a ProcessingStage parameter to control the processing order.

Several mastering voices can exist at once, but only one of them can be started. Only one device can be used by XAudio2 at a time.

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

It is illegal to call CreateMasteringVoice from within a callback. If CreateMasteringVoice is called within a callback XAUDIO2_E_INVALID_CALL will be returned.

Requirements

Header: Declared in xaudio2.h.