IXAudio2::CreateMasteringVoice method

Creates and configures a mastering voice.

Syntax

HRESULT CreateMasteringVoice(
  IXAudio2MasteringVoice     **ppMasteringVoice,
  UINT32                     InputChannels,
  UINT32                     InputSampleRate,
  UINT32                     Flags,
  LPCWSTR                    szDeviceId,
  const XAUDIO2_EFFECT_CHAIN *pEffectChain,
  AUDIO_STREAM_CATEGORY      StreamCategory
);

Parameters

ppMasteringVoice

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

InputChannels

InputSampleRate

Flags

szDeviceId

pEffectChain

StreamCategory

Return Value

Returns S_OK if successful; otherwise, an error code. Returns ERROR_NOT_FOUND if no default audio device exists and NULL is passed in as the szDeviceId parameter.

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, you should create a mastering voice 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.

You cannot create a source or submix voices until a mastering voice exists. You cannot destroy a mastering voice 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.

XAudio2 only allows one mastering voice to exist at once. If you attempt to create more than one voice, XAUDIO2_E_INVALID_CALL is returned. If an additional mastering voice is needed, for example for an output device with a different audio category set, you will need to create an additional XAudio2 instance.

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

It is invalid to call CreateMasteringVoice from within a callback (that is, IXAudio2EngineCallback or IXAudio2VoiceCallback). If you call CreateMasteringVoice 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 CreateMasteringVoice successfully completes, and may be deleted immediately after CreateMasteringVoice is called.

Note that the DirectX SDK XAUDIO2 version of CreateMasteringVoice took a DeviceIndex argument instead of a szDeviceId and a StreamCategory argument. This reflects the changes needed for the standard Windows device enumeration model.

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