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 或更高版本上，NULL 还会选择加入 WASAPI 虚拟化客户端，除非XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT在 Flags 中传递。

[in, optional] pEffectChain

指向描述在主语音中使用的效果链的XAUDIO2_EFFECT_CHAIN 结构的指针，或 NULL 表示不使用任何效果。

[in, optional] StreamCategory

用于此主语音的音频流类别。

返回值

如果成功，则返回S_OK;否则为错误代码。如果不存在默认音频设备并且 NULL 作为 szDeviceId 参数传入，则返回ERROR_NOT_FOUND。

有关 XAudio2 特定错误代码的说明，请参阅 XAudio2 错误代码。

注解

主语音接收一个或多个源语音或子混合语音的输出。它们处理数据，并将其发送到音频输出设备。

通常，应创建具有输入采样率的主语音，该速率将由游戏的大部分音频内容使用。主语音执行从此输入采样率到实际设备输出速率的采样率转换。

在主语音存在之前，无法创建源语音或子混合语音。如果任何源或子混合语音仍然存在，则无法销毁主语音。

始终在所有源语音和子混合语音之后处理主语音。这意味着无需指定 ProcessingStage 参数来控制处理顺序。

XAudio2 仅允许同时存在一个主语音。如果尝试创建多个语音，则会返回XAUDIO2_E_INVALID_CALL。如果需要其他主语音（例如，对于设置了不同音频类别的输出设备），则需要创建额外的 XAudio2 实例。

首次创建时，主语音处于启动状态。

从回调 (（即 IXAudio2EngineCallback 或 IXAudio2VoiceCallback) ）中调用 CreateMasteringVoice 无效。如果在回调中调用 CreateMasteringVoice ，它将返回XAUDIO2_E_INVALID_CALL。

在 CreateMasteringVoice 成功完成后，不再需要作为 pEffectChain 参数传入的XAUDIO2_EFFECT_CHAIN以及其中包含的任何XAUDIO2_EFFECT_DESCRIPTOR信息，并且可能在调用 CreateMasteringVoice 后立即删除。

请注意，DirectX SDK XAUDIO2版本的 CreateMasteringVoice 采用 DeviceIndex 参数，而不是 szDeviceId 和 StreamCategory 参数。这反映了标准 Windows 设备枚举模型所需的更改。