Guía del desarrollador para la versión redistribuible de XAudio 2.9

Artículo
06/13/2023

Una versión de XAudio 2.9 está disponible como un paquete NuGet. Los desarrolladores pueden redistribuir esta versión de XAudio 2.9 con sus aplicaciones. Esto permite que una aplicación use XAudio 2.9 en versiones anteriores de Windows que no incluyan XAudio 2.9 como parte de la imagen del sistema operativo. El uso de este redistribuible es preferible a redistribuir XAudio 2.7 desde el SDK de DirectX, ya que XAudio 2.7 no se ha actualizado desde 2010.

Asegúrese de visitar la página de aterrizaje de DirectX para obtener más recursos para desarrolladores de DirectX.

Plataformas compatibles

El paquete NuGet XAudio 2.9 (Microsoft.XAudio2.Redist.*.nupkg) incluye una versión de 32 bits y una versión de 64 bits de un archivo DLL que implementa la API XAudio 2.9. El archivo DLL se denomina XAUDIO2_9REDIST.DLL. Este archivo DLL funcionará en Windows 7 SP1, Windows 8, Windows 8.1 y Windows 10.

Cuando el archivo DLL se usa en un sistema Windows 10, comprueba el número de versión del XAUDIO2_9.DLL que forma parte del sistema operativo y, si el sistema operativo es más reciente, delegará todas las llamadas API a XAUDIO2_9.DLL en el sistema operativo. Esto garantiza que las aplicaciones siempre usen la versión más reciente de XAudio 2.9 que está disponible en la plataforma actual.

La DLL no está pensada para Xbox One. Si se usa en Xbox One, el archivo DLL siempre delegará todas las llamadas API a XAUDIO2_9.DLL en el sistema operativo Xbox One.

La DLL no está pensada para aplicaciones para UWP. Las aplicaciones para UWP deben usar el XAUDIO2_9.DLL que forma parte del sistema operativo.

Instalación del paquete de NuGet

La manera más fácil de instalar el paquete NuGet es usar el Administrador de paquetes NuGet en Microsoft Visual Studio. Si lo hace, el archivo de proyecto de Visual Studio se actualizará automáticamente para incluir Microsoft.XAudio2.Redist.targets. El archivo .targets agrega la carpeta Include con los archivos de encabezado de XAudio2 a la colección de rutas de acceso de inclusión del proyecto. El archivo .targets también hará que su .DLL o .EXE vínculo con XAUDIO2REDIST. LIB y XAPOBASEREDIST. LIB.

Biblioteca XAPOBASEREDIST. LIB solo es necesario si piensa impementar un objeto de procesamiento XAudio personalizado (XAPO) y puede quitarlo de Microsoft.XAudio2.Redist.targets si no se usa.

También puede usar otras herramientas para extraer el contenido del paquete NuGet, o incluso cambiar el nombre de la extensión de archivo a .zip y extraer los archivos con cualquier herramienta extractora ZIP.

También hay un xaudio2redist puerto disponible para el Administrador de paquetes vc++.

Compilación de la aplicación

Elección de los encabezados que se van a incluir

El paquete NuGet XAudio 2.9 incluye los mismos archivos de encabezado XAudio2 que se incluyen en el SDK de Windows 10. Sin embargo, los archivos de encabezado han tenido algunos ajustes para asegurarse de que puede usarlos mientras se destina explícitamente a todas las plataformas compatibles, incluidas las versiones anteriores de Windows.

Si instala el paquete NuGet mediante el Administrador de paquetes NuGet en Microsoft Visual Studio, la ruta de acceso a los archivos de encabezado se coloca delante de la ruta de acceso a los archivos de encabezado de Windows SDK. Esto significa que si el código del proyecto incluye XAUDIO2. Encabezado H, recogerá el encabezado multiplataforma del paquete NuGet. Normalmente, este es el comportamiento deseado.

Debe tener cuidado si agregar la ruta de acceso a los encabezados de inclusión manualmente al proyecto, ya que especificarlos en el orden incorrecto puede provocar que XAUDIO2 específico de la versión del sistema operativo . H que se incluirá desde Windows SDK, en lugar de la versión multiplataforma de XAUDIO2.H.

Para que la inclusión de encabezados sea menos propensa a errores, el paquete NuGet contiene una versión de cada encabezado con "REDIST" anexado a él. Por ejemplo, además de XAUDIO2. H, el paquete NuGet también incluye XAUDIO2REDIST.H. Si lo prefiere, el código puede incluir directamente XAUDIO2REDIST. H para eliminar cualquier ambigüedad sobre qué archivo de encabezado se está usando. Al incluir -REDIST. La versión H de un archivo de encabezado, el orden en el que se enumeran los directorios de archivos de inclusión en el archivo del proyecto no importa.

Ten en cuenta que si tu aplicación también se está compilando para Xbox One, debes seguir incluyendo XAUDIO2. H al compilar para Xbox One, ya que algunas API específicas de Xbox One se excluyen de XAUDIO2REDIST.H. Este paquete NuGet no está pensado para Xbox One.

Carga del archivo DLL

Te recomendamos que vincules tu aplicación con XAUDIO2REDIST. LIB e instale XAUDIO2_9REDIST.DLL en la misma carpeta que el ejecutable de la aplicación. Esto hará que XAUDIO2_9REDIST.DLL se carguen tan pronto como se inicie el archivo ejecutable. Sin embargo, si lo prefiere, puede usar LoadLibraryEx y GetProcAddress para cargar XAUDIO2_9REDIST.DLL a petición. Esta es una buena solución si la aplicación no siempre necesita usar las API XAudio2. Pero si lo haces, debes mantener el XAUDIO2_9REDIST.DLL cargado hasta que se cierre la aplicación, ya que intentar descargar el archivo DLL puede provocar un bloqueo si un subproceso en segundo plano sigue ejecutando código en el archivo DLL.

A diferencia de la versión anterior de XAudio 2.7, no es posible usar CoCreateInstance para cargar el archivo DLL.

Comprobación de la firma del archivo DLL

El XAUDIO2_9REDIST.DLL binario está firmado por Microsoft mediante una firma SHA-2. Cualquier código que intente validar la firma, por ejemplo, módulos anti-trucos para juegos, por lo tanto, debe admitir SHA-2. Tenga en cuenta que Windows 7 SP1 no admitía originalmente SHA-2 y requiere una actualización para agregar esa funcionalidad. La actualización está disponible como KB4474419.

Prueba

Sonido espacial en versiones más recientes de Windows 10

A partir de la actualización Windows 10 1903, XAudio 2.9 usa automáticamente el sonido envolvente virtual, si se cumplen ciertas condiciones. Recomendamos probar el juego que genere sonido de varios canales en Windows 10 1903 (o posterior) para comprobar que el juego suena según lo previsto.

Habilitación del sonido espacial

El usuario puede habilitar un formato de sonido espacial haciendo clic con el botón derecho en el icono del altavoz en la bandeja del sistema de Windows.

XAudio 2.9 solo usará el formato de sonido espacial seleccionado por el usuario si el proceso que usa la API XAudio2 es reconocido como un juego por la barra de juegos de Windows. Durante el desarrollo, es posible que el proceso aún no sea reconocido como un juego por la barra de juegos. Para cambiar esto, usa el short-cut del teclado Win+G para abrir la barra de juegos mientras se ejecuta el juego. A continuación, haga clic en el icono "Configuración" y active la casilla que dice "Recuerde que se trata de un juego".

No participar en el sonido espacial

Hay una manera de no participar en que XAudio2 use el codificador de sonido espacial especificando determinados valores para el parámetro AUDIO_STREAM_CATEGORY en IXAudio2::CreateMasteringVoice.

El sonido espacial está habilitado para estas categorías:

AudioCategory_ForegroundOnlyMedia
AudioCategory_GameEffects
AudioCategory_GameMedia
AudioCategory_Movie
AudioCategory_Media

El sonido espacial no está habilitado si se especifica alguna de las siguientes categorías:

AudioCategory_Other
AudioCategory_Communications
AudioCategory_Alerts
AudioCategory_SoundEffects
AudioCategory_GameChat
AudioCategory_Speech

Control de errores

Es importante probar que el juego puede controlar un cambio en el dispositivo de audio, por ejemplo, cuando los auriculares están conectados o desconectados. Esto debe probarse con auriculares que solo admiten la frecuencia de muestreo de 44,1 kHz. Muchos auriculares USB de gama baja y auriculares Bluetooth solo admiten 44,1 kHz. La transición entre la frecuencia de muestreo de 48 kHz y la frecuencia de muestreo de 44,1 kHz puede provocar un error incluso cuando se usa la característica de punto de conexión de audio virtual . El error no se producirá si los auriculares también admiten 48 kHz. Tenga en cuenta que la característica de punto de conexión de audio virtual no está disponible en Windows 7 SP1.

El código de error devuelto por XAudio 2.9 cuando no se puede recuperar automáticamente de un cambio en el punto de conexión de audio es XAUDIO2_E_DEVICE_INVALIDATED. Sin embargo, se recomienda que las aplicaciones no codifiquen de forma rígida una dependencia del código de error que tenga un valor específico.

Para recibir una notificación del error, la aplicación debe implementar la interfaz IXAudio2EngineCallback y proporcionar un puntero a esa interfaz invocando el método IXAudio2::RegisterForCallbacks . La API XAudio2 invocará la implementación de la aplicación IXAudio2EngineCallback::OnCriticalError si se produce un error durante la reproducción.

Tenga en cuenta que IXAudio2EngineCallback::OnCriticalError no se invoca necesariamente si la canalización de audio está en pausa. Por ejemplo, si el usuario minimiza la aplicación o la aplicación se suspende por cualquier motivo, la reproducción de audio podría pausarse. Si el cambio en el dispositivo de audio se produce durante este tiempo, el error solo se devuelve cuando la aplicación invoca IXAudio2::StartEngine o invoca IXAudio2SourceVoice::Start. Si la reproducción se puede pausar con la aplicación, debes probar el cambio del dispositivo de audio mientras la reproducción está en pausa, para comprobar que la aplicación todavía puede recuperarse de esta situación.

Diferencias de api de XAudio 2.9 en comparación con XAudio 2.7

En esta sección se proporciona un resumen de algunas de las diferencias de API entre XAudio 2.7 y la versión redistribuible de XAudio 2.9.

Formatos compatibles

XAudio 2.9 admite estos formatos de entrada en pc:

PCM lineal de 16 bits
PCM flotante lineal de 32 bits
ADPCM de 16 bits
xWMA

El formato XMA solo se admite en Xbox One.

Núcleo de CPU preferido

Es posible especificar qué núcleo de CPU XAudio 2.9 debe usar para su subproceso de procesamiento de audio. Sin embargo, normalmente se prefiere permitir que XAudio 2.9 elija este valor por sí mismo. Para ello, establezca el parámetro XAudio2Processor en la llamada a XAudio2Create en XAUDIO2_USE_DEFAULT_PROCESSOR.

XAudio 2.9 elegirá un núcleo de CPU diferente en Xbox One que en pc. El método IXAudio2Extension::GetProcessor se puede usar para determinar qué núcleo de CPU ha elegido XAudio2.

Punto de conexión de audio virtual

XAudio 2.9 usará un punto de conexión de audio virtual de forma predeterminada, cuando se ejecute en Windows 8 o posterior. Esto significa que si el punto de conexión de audio predeterminado cambia mientras se usa XAudio 2.9, intentará cambiar automáticamente al nuevo punto de conexión de audio. Un ejemplo de cuándo esto puede ocurrir cuando el punto de conexión de audio predeterminado es un par de auriculares que están conectados a través de USB y, a continuación, el usuario desconecta los auriculares. Esto hará que los altavoces sean el nuevo punto de conexión de audio predeterminado.

Si la aplicación especifica un formato de audio específico al invocar IXAudio2::CreateMasteringVoice, es posible que no sea posible que XAudio 2.9 realice este modificador. Por ejemplo, si la aplicación especifica que la voz de masterización usará una frecuencia de muestreo de 48 kHz y el nuevo dispositivo de audio solo admite 44,1 kHz, se producirá un error en el conmutador automático y XAudio 2,9 notificará el error XAUDIO2_E_DEVICE_INVALIDATED .

Es posible que la aplicación no use el punto de conexión de audio virtual pasando la marca XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT a IXAudio2::CreateMasteringVoice.

Los puntos de conexión de audio virtual no están disponibles en Windows 7 SP1. La marca XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT no tiene ningún efecto en Windows 7 SP1.

Categorías de audio

La aplicación debe especificar una categoría para su secuencia de audio. Para ello, se proporciona un valor de la enumeración AudioCategory al invocar el método IXAudio2::CreateMasteringVoice . Por ejemplo, AudioCategory_GameEffects. La categoría de audio puede afectar a cómo Windows procesa el sonido o cómo representa la secuencia de audio en el panel de control de volumen. La categoría de audio también afecta si el sonido envolvente virtual se habilita automáticamente.

Duración del procesamiento de audio cuántico

En la mayoría de los equipos, XAudio 2.9 procesa audio en fragmentos de 10 milisegundos. Esto se denomina quantum de procesamiento. Sin embargo, la duración de este cuántico puede ser diferente de 10 milisegundos en algún hardware. Las aplicaciones que necesitan conocer el cuántico exacto pueden invocar el método IXAudio2Extension::GetProcessingQuantum para recuperar el valor.

Sonido espacial y envolvente virtual

Normalmente, XAudio 2.9 realiza un plegado de cualquier audio multicanal para que coincida con el número "físico" de canales de audio admitidos por el punto de conexión de audio. Por ejemplo, si el juego proporciona una fuente de audio de canal 7.1, pero el sonido se reproduce en auriculares, XAudio 2.9 plegará el audio de canal 7.1 en estéreo, utilizando una matriz de plegado estándar del sector. Si el equipo está conectado a un punto de conexión de audio HDMI, el audio del canal 7.1 se transmitirá tal cual a través de la conexión HDMI.

Windows 10 agrega compatibilidad con el audio espacial, mediante un codificador centralizado que codifica el audio en un formato de sonido espacial seleccionado por el usuario. Windows 10 incluye un formato de sonido espacial llamado Windows Sonic. Otros formatos, como Dolby Atmos for Headphones, se pueden descargar de Microsoft Store. Algunos de los formatos de sonido espacial, como Windows Sonic y Dolby Atmos for Headphones, están diseñados para usarse en puntos de conexión de audio estéreo. Estos formatos doblan el sonido envolvente a estéreo mediante algoritmos propietarios que logran un efecto de sonido envolvente "virtual". En otras palabras, el agente de escucha puede percibir que el sonido aparece de diferentes posiciones en el espacio 3D incluso mientras solo usa auriculares, o mientras escucha en un solo par de altavoces estéreo.

Se pueden lograr efectos similares mediante las API X3DAudio que se incluyen con XAudio 2.9. La principal diferencia es que X3DAudio requiere que el desarrollador de la aplicación programe explícitamente para audio 3D, mientras que el sonido envolvente virtual se aplica automáticamente a cualquier fuente de sonido basada en canal tradional.

En Windows 10 1903 y versiones posteriores, los juegos que usan XAudio 2.9 usarán el formato de sonido espacial de todo el sistema que el usuario ha habilitado en el punto de conexión de audio, si existe. Esto significa que XAudio 2.9 no realizará el plegado habitual del sonido envolvente en estéreo. En su lugar, la señal de sonido envolvente se entregará al codificador de sonido espacial (por ejemplo, Windows Sonic) para lograr un efecto de sonido envolvente virtual.

CreateHrtfApo

La función CreateHrtfApo solo está disponible en Windows 10. No se implementa en el redistribuible XAudio 2.9.

Share via