Руководство разработчика по распространяемой версии XAudio 2.9

  • Статья

Версия XAudio 2.9 доступна в виде пакета NuGet. Разработчики могут распространять эту версию XAudio 2.9 вместе со своими приложениями. Это позволяет приложению использовать XAudio 2.9 в более старых версиях Windows, которые не включают XAudio 2.9 в образ операционной системы. Использование этого распространяемого компонента предпочтительнее, чем распространение XAudio 2.7 из пакета SDK DirectX, так как XAudio 2.7 не обновлялся с 2010 года.

Посетите целевую страницу DirectX , чтобы получить дополнительные ресурсы для разработчиков DirectX.

Поддерживаемые платформы

Пакет NuGet XAudio 2.9 (Microsoft.XAudio2.Redist.*.nupkg) включает 32-разрядную и 64-разрядную версии библиотеки DLL, которая реализует API XAudio 2.9. Библиотека DLL называется XAUDIO2_9REDIST.DLL. Эта библиотека DLL будет работать в Windows 7 с пакетом обновления 1 (SP1), Windows 8, Windows 8.1 и Windows 10.

Если библиотека DLL используется в системе Windows 10, она проверяет номер версии XAUDIO2_9.DLL, которая является частью операционной системы, и если операционная система является более новой, она делегируется всем вызовам API XAUDIO2_9.DLL в операционной системе. Это гарантирует, что приложения всегда используют последнюю версию XAudio 2.9, доступную на текущей платформе.

Библиотека DLL не предназначена для Xbox One. При использовании на Xbox One библиотека DLL всегда делегируют все вызовы API XAUDIO2_9.DLL в операционной системе Xbox One.

Библиотека DLL не предназначена для приложений UWP. Приложения UWP должны использовать XAUDIO2_9.DLL, которая является частью операционной системы.

Установка пакета NuGet

Самый простой способ установить пакет NuGet — использовать диспетчер пакетов NuGet в Microsoft Visual Studio. В этом случае файл проекта Visual Studio будет автоматически обновлен для включения Microsoft.XAudio2.Redist.targets. Targets-файл добавляет папку Include с файлами заголовков для XAudio2 в коллекцию путей включения проекта. Файл .targets также сделает ваш .DLL или .EXE ссылку на XAUDIO2REDIST. LIB и XAPOBASEREDIST. LIB.

Библиотека XAPOBASEREDIST. LIB требуется только в том случае, если вы планируете использовать пользовательский объект обработки XAudio (XAPO) и можете удалить его из microsoft.XAudio2.Redist.targets , если он не используется.

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

Для диспетчера xaudio2redistпакетов VC++ также доступен порт.

Компиляция приложения

Выбор заголовков для включения

Пакет NuGet XAudio 2.9 включает те же файлы заголовков XAudio2, которые входят в пакет SDK для Windows 10. Однако в файлы заголовков были внесены некоторые изменения, чтобы убедиться, что вы можете использовать их, явно ориентируясь на все поддерживаемые платформы, включая старые версии Windows.

При установке пакета NuGet с помощью диспетчера пакетов NuGet в Microsoft Visual Studio путь к файлам заголовков помещается перед путем к файлам заголовков пакета Windows SDK. Это означает, что если код в проекте включает XAUDIO2. Заголовок H, он получит кроссплатформенный заголовок из пакета NuGet. Обычно это желаемое поведение.

Следует соблюдать осторожность при добавлении пути к заголовкам включения вручную в проект, так как их указание в неправильном порядке может привести к возникновению XAUDIO2 для конкретной версии ОС . H , который будет включен из windows SDK, а не кроссплатформенной версии XAUDIO2.H.

Чтобы сделать включение заголовков менее подверженным ошибкам, пакет NuGet содержит версию каждого заголовка с добавлением "REDIST". Например, в дополнение к XAUDIO2. H, пакет NuGet также включает XAUDIO2REDIST.H. При желании код может напрямую включать XAUDIO2REDIST. H для устранения неоднозначности относительно того, какой файл заголовка используется. При включении -REDIST. Версия H файла заголовка, порядок, в котором каталоги включаемых файлов перечислены в файле проекта, не имеет значения.

Обратите внимание, что если ваше приложение также компилируется для Xbox One, следует продолжать включать XAUDIO2. H при компиляции для Xbox One, так как некоторые API для Xbox One исключаются из XAUDIO2REDIST.H. Этот пакет NuGet не предназначен для Xbox One.

Загрузка библиотеки DLL

Рекомендуется связать приложение с XAUDIO2REDIST. LIB и установка XAUDIO2_9REDIST.DLL в той же папке, что и исполняемый файл приложения. Это приведет к загрузке XAUDIO2_9REDIST.DLL сразу после запуска исполняемого файла. Однако при желании вы можете использовать LoadLibraryEx и GetProcAddress для загрузки XAUDIO2_9REDIST.DLL по требованию. Это хорошее решение, если приложению не всегда требуется использовать API XAudio2. Но в этом случае XAUDIO2_9REDIST.DLL следует загружать до завершения работы приложения, так как попытка выгрузить библиотеку DLL может привести к сбою, если фоновый поток по-прежнему выполняет код в библиотеке DLL.

В отличие от более ранней версии XAudio 2.7, невозможно использовать CoCreateInstance для загрузки библиотеки DLL.

Проверка подписи БИБЛИОТЕКи DLL

Двоичный файл XAUDIO2_9REDIST.DLL подписывается корпорацией Майкрософт с помощью подписи SHA-2. Поэтому любой код, который пытается проверить подпись, например модули защиты от обмана для игр, должен поддерживать SHA-2. Обратите внимание, что Windows 7 с пакетом обновления 1 (SP1) изначально не поддерживала SHA-2 и требует обновления для добавления этой функции. Обновление доступно как KB4474419.

Тестирование

Пространственный звук в новых версиях Windows 10

Начиная с обновления Windows 10 1903, XAudio 2.9 автоматически использует виртуальный объемный звук при выполнении определенных условий. Мы рекомендуем протестировать игру, которая создает многоканевой звук на Windows 10 1903 (или более поздней версии), чтобы убедиться, что игра звучит должным образом.

Включение пространственного звука

Пользователь может включить пространственный звуковой формат, щелкнув правой кнопкой мыши значок динамика в области уведомлений Windows.

XAudio 2.9 будет использовать выбранный пользователем пространственный звуковой формат, только если процесс, использующий API XAudio2, распознается как игра с помощью игровой панели Windows. Во время разработки возможно, что процесс еще не распознается как игра в игровой панели. Чтобы изменить это, используйте короткую клавиатуру Win+G, чтобы открыть меню игры во время игры. Затем щелкните значок "Параметры" и проверка флажок "Помните, что это игра".

Отказ от пространственного звука

Существует способ отказаться от использования XAudio2 пространственного звукового кодировщика, указав определенные значения для параметра AUDIO_STREAM_CATEGORY в IXAudio2::CreateMasteringVoice.

Пространственный звук включен для следующих категорий:

  • AudioCategory_ForegroundOnlyMedia
  • AudioCategory_GameEffects
  • AudioCategory_GameMedia
  • AudioCategory_Movie
  • AudioCategory_Media

Пространственный звук не включен, если указана какая-либо из следующих категорий:

  • AudioCategory_Other
  • AudioCategory_Communications
  • AudioCategory_Alerts
  • AudioCategory_SoundEffects
  • AudioCategory_GameChat
  • AudioCategory_Speech

Обработка ошибок

Важно проверить, может ли игра обрабатывать изменения в звуковом устройстве, например, когда наушники подключены или отключены. Это следует проверить с помощью наушников, поддерживающих только частоту выборки 44,1 кГц. Многие недорогие USB-наушники и гарнитуры Bluetooth поддерживают только 44,1 кГц. Переход между частотой дискретизации 48 кГц и частотой дискретизации 44,1 кГц может привести к ошибке даже при использовании функции конечной точки виртуального аудио . Ошибка не произойдет, если наушники также поддерживают 48 кГц. Обратите внимание, что функция конечной точки виртуального звука недоступна в Windows 7 с пакетом обновления 1 (SP1).

Код ошибки, возвращаемый XAudio 2.9, когда не удается автоматически восстановиться после изменения конечной точки звука , XAUDIO2_E_DEVICE_INVALIDATED. Однако рекомендуется, чтобы приложения не жестко кодит зависимости от кода ошибки, имеющего определенное значение.

Чтобы получить уведомление об ошибке, приложение должно реализовать интерфейс IXAudio2EngineCallback и предоставить указатель на этот интерфейс, вызвав метод IXAudio2::RegisterForCallbacks . Реализация приложения IXAudio2EngineCallback::OnCriticalError будет вызываться API XAudio2 при возникновении ошибки во время воспроизведения.

Обратите внимание, что IXAudio2EngineCallback::OnCriticalError не обязательно вызывается, если звуковой конвейер приостановлен. Например, если пользователь свернет приложение или приложение будет приостановлено по какой-либо причине, воспроизведение звука может быть приостановлено. Если в течение этого времени произошло изменение звукового устройства, ошибка возвращается только при вызове приложением IXAudio2::StartEngine и/или вызове IXAudio2SourceVoice::Start. Если воспроизведение может быть приостановлено в приложении, необходимо протестировать изменение звукового устройства во время приостановки воспроизведения, чтобы убедиться, что приложение все еще может восстановиться после этой ситуации.

Различия API XAudio 2.9 по сравнению с XAudio 2.7

В этом разделе приводится сводка некоторых различий API между XAudio 2.7 и распространяемой версией XAudio 2.9.

Поддерживаемые форматы

XAudio 2.9 поддерживает следующие форматы ввода на компьютере:

  • Линейный 16-разрядный PCM
  • Линейный 32-разрядный float PCM
  • 16-разрядная версия ADPCM
  • xWMA

Формат XMA поддерживается только на Xbox One.

Предпочитаемое ядро ЦП

Можно указать, какое ядро ЦП XAudio 2.9 должно использовать для потока обработки звука. Однако обычно рекомендуется разрешить XAudio 2.9 выбрать это значение самостоятельно. Для этого для параметра XAudio2Processor в вызове XAudio2Create задается значение XAUDIO2_USE_DEFAULT_PROCESSOR.

XAudio 2.9 выберет на Xbox One другое ядро ЦП, чем на компьютере. Метод IXAudio2Extension::GetProcessor можно использовать для определения выбранного ядра ЦП XAudio2.

Конечная точка виртуального звука

XAudio 2.9 будет использовать виртуальную конечную точку звука по умолчанию при работе на Windows 8 или более поздней версии. Это означает, что если конечная точка звука по умолчанию изменяется при использовании XAudio 2.9, она попытается автоматически переключиться на новую конечную точку звука. Пример того, когда это может произойти, когда конечная точка звука по умолчанию — это пара наушников, подключенных через USB, а затем пользователь отключает наушники. Это приведет к тому, что динамики будут новой конечной точкой звука по умолчанию.

Если приложение указывает определенный аудиоформат при вызове IXAudio2::CreateMasteringVoice, XAudio 2.9 может не выполнить этот параметр. Например, если приложение указало, что голос mastering должен использовать частоту выборки 48 кГц, а новое звуковое устройство поддерживает только 44,1 кГц, автоматический переключатель завершится сбоем, и XAudio 2.9 сообщит об ошибке XAUDIO2_E_DEVICE_INVALIDATED .

Приложение может отказаться от использования конечной точки виртуального звука, передав флаг XAUDIO2_NO_VIRTUAL_AUDIO_CLIENTв IXAudio2::CreateMasteringVoice.

Виртуальные звуковые конечные точки недоступны в Windows 7 с пакетом обновления 1 (SP1). Флаг XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT не влияет на Windows 7 с пакетом обновления 1 (SP1).

Категории звука

Приложение должно указать категорию для своего аудиопотока. Это делается путем предоставления значения из перечисления AudioCategory при вызове метода IXAudio2::CreateMasteringVoice . Например, AudioCategory_GameEffects. Категория аудио может повлиять на то, как Windows обрабатывает звук или как он представляет аудиопоток на панели управления громкости. Категория аудио также влияет на автоматическое включение виртуального объемного звука .

Длительность квантовой обработки звука

На большинстве компьютеров XAudio 2.9 обрабатывает звук за 10 миллисекундах. Это называется квантом обработки. Однако длительность этого кванта может отличаться от 10 миллисекунда на некоторых аппаратных устройствах. Приложения, которым необходимо знать точный квант, могут вызывать метод IXAudio2Extension::GetProcessingQuantum для получения значения.

Пространственный звук и виртуальный объемный

Начиная с обновления Windows 10 1903, XAudio 2.9 автоматически использует виртуальный объемный звук при выполнении определенных условий. Мы рекомендуем протестировать игру, которая генерирует многоканальные звуки на Windows 10 1903 (или более поздней версии), чтобы убедиться, что игра звучит должным образом. Сведения о том, как протестировать эту функцию, см. в разделе Тестирование пространственного звука .

Как правило, XAudio 2.9 выполняет свертывание любого многоканального звука в соответствии с "физическим" количеством аудиоканалов, поддерживаемых конечной точкой звука. Например, если игра предоставляет источник аудио 7.1 канала, но звук воспроизводится в наушниках, XAudio 2.9 свернет аудио 7.1 канала в стерео, используя стандартную для отрасли матрицу свертывания. Если компьютер подключен к конечной точке звука HDMI, аудиоканал 7.1 будет передаваться через подключение HDMI как есть.

Windows 10 добавляет поддержку пространственного звука с помощью централизованного кодировщика, который кодирует звук в выбранный пользователем формат пространственного звука. Windows 10 поставляется с пространственным звуковым форматом Под названием Windows Sonic. Другие форматы, например Dolby Atmos for Headphones, можно скачать из Microsoft Store. Некоторые форматы пространственного звука, такие как Windows Sonic и Dolby Atmos for Headphones, предназначены для использования в конечных точках стереозвука. Эти форматы сворачивают объемный звук в стерео с помощью собственных алгоритмов, которые достигают "виртуального" эффекта объемного звука. Другими словами, прослушиватель может воспринимать звук, появляющийся из разных позиций в трехмерном пространстве, даже когда он носит наушники или прослушивает одну пару стереодинамиков.

Аналогичные эффекты можно достичь с помощью API-интерфейсов X3DAudio , которые входят в состав XAudio 2.9. Отличие main заключается в том, что X3DAudio требует от разработчика приложения явного программирования для трехмерного звука, в то время как виртуальный объемный звук автоматически применяется к любому источнику звука на основе каналов.

В Windows 10 1903 и более поздних версий игры, использующие XAudio 2.9, будут использовать системный пространственный звуковой формат, который пользователь включил в конечной точке звука, если таковой имеется. Это означает, что XAudio 2.9 не будет выполнять обычное свертывание объемного звука в стерео. Вместо этого сигнал объемного звука будет доставлен в кодировщик пространственного звука (например, Windows Sonic) для получения эффекта виртуального объемного звука.

CreateHrtfApo

Функция CreateHrtfApo доступна только в Windows 10. Он не реализован в распространяемом компоненте XAudio 2.9.