IXAudio2：：CreateMasteringVoice 方法 (xaudio2.h)

發行項
03/04/2024

建立並設定主控語音。

語法

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

參數

[out] ppMasteringVoice

如果成功，則會傳回新 IXAudio2MasteringVoice 物件的指標。

[in] InputChannels

主控語音在其輸入音訊中預期的通道數目。 InputChannels 必須小於或等於XAUDIO2_MAX_AUDIO_CHANNELS。

您可以將 InputChannels 設定為 XAUDIO2_DEFAULT_CHANNELS，這會導致 XAudio2 嘗試偵測系統喇叭組態設定。

[in] InputSampleRate

主控語音輸入音訊數據的取樣率。此速率必須是XAUDIO2_QUANTUM_DENOMINATOR的倍數。 InputSampleRate 必須介於 XAUDIO2_MIN_SAMPLE_RATE 和 XAUDIO2_MAX_SAMPLE_RATE之間。

您可以將 InputSampleRate 設定為 XAUDIO2_DEFAULT_SAMPLERATE，而預設是由目前平台決定。

Windows XP 預設為 44100。

Windows Vista 和 Windows 7 預設為音效控制台中指定的設定。此設定的預設值為 44100 (，如果驅動程式) 則為 48000。

Flags

[in] Flags

指定主控語音行為的旗標。這可以是 0 或 XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT。

[in] szDeviceId

要接收輸出音訊之裝置的標識碼。指定 NULL 的預設值會導致 XAudio2 選取全域預設音訊裝置。在 Windows 10 或更新版本上，除非傳入 Flags，否則 XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT NULL 也會加入加入 WASAPI 虛擬化用戶端。

[in, optional] pEffectChain

XAUDIO2_EFFECT_CHAIN 結構的指標，描述在主控語音中使用的效果鏈結，或 NULL 不使用任何效果。

[in, optional] StreamCategory

要用於這個主控語音的音訊數據流類別。

傳回值

如果成功，則傳回S_OK;否則為錯誤碼。傳回ERROR_NOT_FOUND如果沒有任何預設音訊裝置存在，而且 NULL 會以 szDeviceId 參數的形式傳入。

如需 XAudio2 特定錯誤碼的描述，請參閱 XAudio2 錯誤碼。

備註

主控語音會接收一或多個來源或副混音的輸出。他們會處理數據，並將其傳送至音訊輸出裝置。

一般而言，您應該使用大部分標題的音訊內容所使用的輸入取樣率來建立主控語音。主控語音會執行從此輸入取樣率到實際裝置輸出速率的取樣率轉換。

在主控語音存在之前，您無法建立來源或副混音。如果有任何來源或副混音仍存在，您就無法終結主控語音。

所有來源和副混音語音之後，都會處理主控語音。這表示您不需要指定 ProcessingStage 參數來控制處理順序。

XAudio2 只允許一次有一個主控語音存在。如果您嘗試建立多個語音，則會傳回XAUDIO2_E_INVALID_CALL。如果需要額外的主控語音，例如，針對已設定不同音訊類別的輸出裝置，您必須建立額外的 XAudio2 實例。

第一次建立時，主控語音處於啟動狀態。

從回呼 (呼叫 CreateMasteringVoice 無效，也就是 IXAudio2EngineCallback 或 IXAudio2VoiceCallback) 。如果您在回呼內呼叫 CreateMasteringVoice ，它會傳回XAUDIO2_E_INVALID_CALL。

以 pEffectChain 自變數的形式傳入的XAUDIO2_EFFECT_CHAIN，在 CreateMasteringVoice 成功完成之後就不再需要內含的任何XAUDIO2_EFFECT_DESCRIPTOR資訊，而且可能會在呼叫 CreateMasteringVoice 之後立即刪除。

請注意，DirectX SDK XAUDIO2版本的 CreateMasteringVoice 採用 DeviceIndex 自變數，而不是 szDeviceId 和 StreamCategory 自變數。這反映標準 Windows 裝置列舉模型所需的變更。