Метод IXAudio2::CreateMasteringVoice (xaudio2.h)

Статья
03/08/2023

Создает и настраивает голос мастера.

Синтаксис

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

Количество каналов, которые голос хозяина ожидает во входном звуке. Входные каналы должны быть меньше или равны 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, если требуется драйвером).

Флаги

[in] Flags

Флаги, указывающие поведение голоса хозяина. Это может быть 0 или XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT.

[in] szDeviceId

Идентификатор устройства для получения выходного звука. Если задать значение по умолчанию NULL, XAudio2 выберет глобальное звуковое устройство по умолчанию. В Windows 10 или более поздних версий значение NULL также согласится на использование виртуализированного клиента WASAPI, если XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT не передано в разделе Флаги.

[in, optional] pEffectChain

Указатель на структуру XAUDIO2_EFFECT_CHAIN , описывающую цепочку эффектов, используемую в голосе для овладения, или значение NULL, чтобы не использовать эффекты.

[in, optional] StreamCategory

Категория аудиопотока, используемая для этого голоса.

Возвращаемое значение

В случае успешного выполнения возвращает S_OK; в противном случае — код ошибки. Возвращает ERROR_NOT_FOUND, если звуковое устройство по умолчанию не существует и в качестве параметра szDeviceId передается значение NULL.

Описание кодов ошибок XAudio2 см. в разделе Коды ошибок XAudio2 .

Голоса для овладения получают выходные данные одного или нескольких исходных или субмикшных голосов. Они обрабатывают данные и отправляют их на устройство вывода звука.

Как правило, необходимо создать голос с частотой выборки ввода, которая будет использоваться большинством аудиосодержимого заголовка. Голос хозяина выполняет преобразование частоты выборки из этой входной частоты выборки в фактическую скорость вывода устройства.

Вы не сможете создать исходные или подмиксные голоса, пока не будет создан голос для управления. Вы не можете уничтожить голос мастера, если какие-либо исходные или субмикшные голоса по-прежнему существуют.

Управление голосами всегда обрабатывается после всех исходных и субмикшированных голосов. Это означает, что не нужно указывать параметр ProcessingStage для управления порядком обработки.

XAudio2 позволяет существовать одновременно только одному голосу для овладения. При попытке создать несколько голосов, возвращается XAUDIO2_E_INVALID_CALL. Если требуется дополнительный голос мастеринга, например для устройства вывода с другим набором категорий аудио, необходимо создать дополнительный экземпляр XAudio2.

При первом создании мастеринг голоса находятся в запущенном состоянии.

Недопустимо вызывать CreateMasteringVoice из обратного вызова (то есть IXAudio2EngineCallback или IXAudio2VoiceCallback). При вызове Метода CreateMasteringVoice в обратном вызове возвращается XAUDIO2_E_INVALID_CALL.

XAUDIO2_EFFECT_CHAIN, передаваемая в качестве аргумента pEffectChain, и все содержащиеся в нем XAUDIO2_EFFECT_DESCRIPTOR сведения больше не требуются после успешного завершения CreateMasteringVoice и могут быть удалены сразу после вызова CreateMasteringVoice.

Обратите внимание, что пакет SDK для DirectX XAUDIO2 версии CreateMasteringVoice принял аргумент DeviceIndex вместо szDeviceId и аргумента StreamCategory. Это отражает изменения, необходимые для стандартной модели перечисления устройств Windows.