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

Версия XAudio 2.9 доступна в виде пакета NuGet. Разработчики могут распространять эту версию XAudio 2.9 с помощью своих приложений. Это позволяет приложению использовать XAudio 2.9 в более ранних версиях Windows, которые не включают XAudio 2.9 в образ операционной системы. Использование этого распространяемого компонента предпочтительнее, чем распространение XAudio 2.7 из пакета DirectX SDK, так как 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.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 может привести к сбою, если фоновый поток продолжает выполнять код в ней.

В отличие от более старой версии 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_Alerts
• АудиоКатегория_ЗвуковыеЭффекты
• АудиоКатегория_ИгровойЧат
• АудиоКатегория_Речь

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

Важно проверить, что игра может обрабатывать изменение звукового устройства, например при подключении к наушникам или отключении. Это следует проверить с помощью наушников, которые поддерживают только частоту выборки 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-разрядный формат плавучей точки 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 может не справиться с изменением формата. Например, если приложение указало, что мастер-голос должен использовать частоту дискретизации 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 с пакетом обновления 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 передается as-is через подключение HDMI.

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

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

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

CreateHrtfApo

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