IXAudio2::CreateMasteringVoice method

Creates and configures a mastering voice.

Syntax

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

Parameters

ppMasteringVoice

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

X2DEFAULT

TBD

X2DEFAULT

TBD

X2DEFAULT

TBD

X2DEFAULT

TBD

X2DEFAULT

TBD

X2DEFAULT

TBD

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