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

Статья
03/04/2024

Создает и настраивает исходный голос.

Синтаксис

HRESULT CreateSourceVoice(
  [out]          IXAudio2SourceVoice        **ppSourceVoice,
  [in]           const WAVEFORMATEX         *pSourceFormat,
  [in]           UINT32                     Flags,
  [in]           float                      MaxFrequencyRatio,
  [in, optional] IXAudio2VoiceCallback      *pCallback,
  [in, out]      const XAUDIO2_VOICE_SENDS  *pSendList,
  [in, optional] const XAUDIO2_EFFECT_CHAIN *pEffectChain
);

Параметры

[out] ppSourceVoice

В случае успешного выполнения возвращает указатель на новый объект IXAudio2SourceVoice .

[in] pSourceFormat

Указатель на одну из структур, приведенных в таблице ниже. Эта структура содержит ожидаемый формат для всех звуковых буферов, отправленных в исходный голос. XAudio2 поддерживает типы голоса PCM и ADPCM.

Тег format	Структура формата волн	Размер (в байтах)
WAVE_FORMAT_PCM (0x0001)	PCMWAVEFORMAT	16
-или-	WAVEFORMATEX	18
WAVE_FORMAT_IEEE_FLOAT (0x0003) [32-разрядная версия]	PCMWAVEFORMAT	18
WAVE_FORMAT_ADPCM (0x0002) [MS-ADPCM]	ADPCMWAVEFORMAT	50
WAVE_FORMAT_EXTENSIBLE (0xFFFE)	WAVEFORMATEXTENSIBLE	40

XAudio2 поддерживает следующие форматы PCM.

8-разрядное целое число (без знака) PCM
16-разрядное целое число PCM (оптимальный формат для XAudio2)
20-разрядное целое число PCM (в 24- или 32-разрядных контейнерах)
24-разрядное целое число PCM (в 24- или 32-разрядных контейнерах)
32-разрядное целое число PCM
32-разрядный float PCM (предпочтительный формат после 16-разрядного целого числа)

Количество каналов в исходном голосе должно быть меньше или равно XAUDIO2_MAX_AUDIO_CHANNELS. Частота выборки исходного голоса должна находиться в диапазоне от XAUDIO2_MIN_SAMPLE_RATE до XAUDIO2_MAX_SAMPLE_RATE.

Примечание Форматы данных PCM, такие как PCMWAVEFORMAT и ADPCMWAVEFORMAT , для которых требуется больше информации, чем предоставляет WAVEFORMATEX , имеют структуру WAVEFORMATEX в качестве первого элемента в своих структурах формата. При создании исходного голоса с одним из этих форматов приведите структуру формата к структуре WAVEFORMATEX и используйте ее в качестве значения для pSourceFormat.

[in] Flags

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

Значение	Описание
XAUDIO2_VOICE_NOPITCH	В голосе нет элемента управления тоном.
XAUDIO2_VOICE_NOSRC	Преобразование частоты выборки в голосе недоступно. Выходные данные голоса должны иметь одинаковую частоту выборки. Примечание Флаг XAUDIO2_VOICE_NOSRC приводит к тому, что голос будет вести себя так, как если бы был указан флаг XAUDIO2_VOICE_NOPITCH.
XAUDIO2_VOICE_USEFILTER	Эффект фильтра должен быть доступен для этого голоса.

Примечание Флаг XAUDIO2_VOICE_MUSIC не поддерживается в Windows.

[in] MaxFrequencyRatio

Максимально допустимое отношение частоты, которое можно задать для этого голоса. Значение этого аргумента должно находиться в диапазоне от XAUDIO2_MIN_FREQ_RATIO до XAUDIO2_MAX_FREQ_RATIO. Последующие вызовы IXAudio2SourceVoice::SetFrequencyRatio зажимаются между XAUDIO2_MIN_FREQ_RATIO и MaxFrequencyRatio. Максимальное значение для этого аргумента определяется как XAUDIO2_MAX_FREQ_RATIO, что позволяет увеличить шаг до 10 октав.

Если значение MaxFrequencyRatio меньше 1,0, голос будет использовать это соотношение сразу после создания (а не значение по умолчанию 1,0).

Xbox 360
Для голосов XMA существует еще одно ограничение на аргумент MaxFrequencyRatio и частоту выборки голоса. Произведение этих двух номеров не может превышать XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO для голосов одного канала или XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL для голосов с любым другим количеством каналов. Если значение , указанное для Параметра MaxFrequencyRatio , слишком велико для указанного формата, вызов CreateSourceVoice завершается ошибкой и создает сообщение об отладке.

Xbox 360

Для голосов XMA существует еще одно ограничение на аргумент MaxFrequencyRatio и частоту выборки голоса. Произведение этих двух номеров не может превышать XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MONO для голосов одного канала или XAUDIO2_MAX_RATIO_TIMES_RATE_XMA_MULTICHANNEL для голосов с любым другим количеством каналов. Если значение , указанное для Параметра MaxFrequencyRatio , слишком велико для указанного формата, вызов CreateSourceVoice завершается ошибкой и создает сообщение об отладке.

Примечание Вы можете использовать наименьшее возможное значение MaxFrequencyRatio , чтобы сократить использование памяти XAudio2.

[in, optional] pCallback

Указатель на предоставленный клиентом интерфейс обратного вызова IXAudio2VoiceCallback.

[in, out] pSendList

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

[in, optional] pEffectChain

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

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

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

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

Исходный голос включает преобразование частоты выборки с переменной скоростью для преобразования данных из исходного формата в скорость вывода, необходимую для списка отправки голоса. Если вы используете список отправки СО ЗНАЧЕНИЕМ NULL, целевой частотой выборки будет частота выборки входных данных главного голоса. Если вы предоставляете один голос в pSendList, частота выборки входных данных этого голоса является целевой скоростью. Если в pSendList указано несколько голосов, все выходные голоса исходного голоса должны работать с одинаковой частотой выборки входных данных.

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

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

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

XAudio2 использует внутренний пул памяти для голосов с тем же форматом. Это означает, что выделение памяти для голосов будет происходить реже по мере создания и последующего уничтожения дополнительных голосов. Чтобы свести к минимуму JIT-выделение, заголовок может создать ожидаемое максимальное количество голосов, необходимых заранее, а затем удалить их при необходимости. Затем голоса будут повторно использоваться из пула XAudio2. Пул памяти привязан к экземпляру обработчика XAudio2. Вы можете освободить всю память, используемую экземпляром обработчика XAudio2, уничтожив объект XAudio2 и повторно воссоздав его по мере необходимости (принудительное увеличение пула памяти за счет предварительного выделения потребуется повторно применить по мере необходимости).

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

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