Guide du développeur pour la version redistribuable de XAudio 2.9

Article
01/28/2024

Une version de XAudio 2.9 est disponible en tant que package NuGet. Les développeurs peuvent redistribuer cette version de XAudio 2.9 avec leurs applications. Cela permet à une application d’utiliser XAudio 2.9 sur les versions antérieures de Windows qui n’incluent pas XAudio 2.9 dans le cadre de l’image du système d’exploitation. L’utilisation de ce redistribuable est préférée par rapport à la redistribution de XAudio 2.7 à partir du Kit de développement logiciel (SDK) DirectX, car XAudio 2.7 n’a pas été mis à jour depuis 2010.

Assurez-vous de visiter la page d’accueil DirectX pour plus de ressources pour les développeurs DirectX.

Plateformes prises en charge

Le package XAudio 2.9 NuGet (Microsoft.XAudio2.Redist.*.nupkg) inclut une version 32 bits et une version 64 bits d’une DLL qui implémente l’API XAudio 2.9. La DLL est appelée XAUDIO2_9REDIST.DLL. Cette DLL fonctionnera sur Windows 7 SP1, Windows 8, Windows 8.1 et Windows 10.

Lorsque la DLL est utilisée sur un système Windows 10, elle vérifie le numéro de version du XAUDIO2_9.DLL qui fait partie du système d’exploitation, et si le système d’exploitation est plus récent, il déléguera tous les appels d’API à XAUDIO2_9.DLL dans le système d’exploitation. Cela garantit que les applications utilisent toujours la dernière version de XAudio 2.9 disponible sur la plateforme actuelle.

La DLL n’est pas destinée à Xbox One. Si elle est utilisée sur Xbox One, la DLL déléguera toujours tous les appels d’API à XAUDIO2_9.DLL dans le système d’exploitation Xbox One.

La DLL n’est pas destinée aux applications UWP. Les applications UWP doivent utiliser la XAUDIO2_9.DLL qui fait partie du système d’exploitation.

Installation du package Nuget

Le moyen le plus simple d’installer le package NuGet consiste à utiliser la NuGet Gestionnaire de package dans Microsoft Visual Studio. Si vous effectuez cette opération, votre fichier projet Visual Studio sera automatiquement mis à jour pour inclure Microsoft.XAudio2.Redist.targets. Le fichier .targets ajoute le dossier Include avec les fichiers d’en-tête du XAudio2 à votre collection de chemins d’accès inclus dans le projet. Le fichier .targets crée également votre lien .DLL ou .EXE avec XAUDIO2REDIST. LIB et XAPOBASEREDIST. LIB.

Bibliothèque XAPOBASEREDIST. LIB n’est nécessaire que si vous envisagez d’imputer un objet de traitement XAudio personnalisé (XAPO) et que vous pouvez le supprimer de Microsoft.XAudio2.Redist.targets s’il n’est pas utilisé.

Vous pouvez également utiliser d’autres outils pour extraire le contenu du package NuGet, ou même renommer l’extension de fichier en .zip et extraire les fichiers avec n’importe quel outil d’extraction ZIP.

Il existe également un xaudio2redist port disponible pour le VC++ Gestionnaire de package.

Compilation de votre application

Choix des en-têtes à inclure

Le package de NuGet XAudio 2.9 inclut les mêmes fichiers d’en-tête XAudio2 inclus dans le Kit de développement logiciel (SDK) Windows 10. Toutefois, les fichiers d’en-tête ont eu des ajustements pour s’assurer que vous pouvez les utiliser tout en ciblant explicitement toutes les plateformes prises en charge, y compris les versions antérieures de Windows.

Si vous installez le package NuGet à l’aide de l’NuGet Gestionnaire de package dans Microsoft Visual Studio, le chemin d’accès aux fichiers d’en-tête est placé devant le chemin d’accès aux fichiers d’en-tête du Kit de développement logiciel (SDK) Windows. Cela signifie que si le code de votre projet inclut XAUDIO2. En-tête H, il récupère l’en-tête multiplateforme du package NuGet. Il s’agit normalement du comportement souhaité.

Vous devez être prudent si vous ajoutez le chemin d’accès aux en-têtes include manuellement au projet, car la spécification de ces en-têtes dans l’ordre incorrect peut entraîner l’erreur XAUDIO2 spécifique au système d’exploitation. H à inclure à partir du Kit de développement logiciel (SDK) Windows, plutôt que la version multiplateforme de XAUDIO2.H.

Pour rendre l’inclusion d’en-têtes moins sujettes aux erreurs, le package NuGet contient une version de chaque en-tête avec « REDIST » ajouté à celui-ci. Par exemple, en plus de XAUDIO2. H, le package NuGet inclut également XAUDIO2REDIST.H. Si vous préférez, votre code peut inclure directement XAUDIO2REDIST. H pour éliminer toute ambiguïté concernant le fichier d’en-tête utilisé. Lorsque vous incluez -REDIST. La version H d’un fichier d’en-tête, l’ordre dans lequel les répertoires de fichiers include sont répertoriés dans le fichier projet n’est pas important.

Notez que si votre application est également compilée pour Xbox One, vous devez continuer à inclure XAUDIO2. H lors de la compilation pour Xbox One, car certaines API spécifiques à Xbox One sont exclues de XAUDIO2REDIST.H. Ce package NuGet n’est pas destiné à Xbox One.

Chargement de la DLL

Nous vous recommandons de lier votre application à XAUDIO2REDIST. LIB et installez XAUDIO2_9REDIST.DLL dans le même dossier que l’exécutable de votre application. Cela entraîne le chargement de XAUDIO2_9REDIST.DLL dès que votre exécutable est lancé. Toutefois, si vous préférez, vous pouvez utiliser LoadLibraryEx et GetProcAddress pour charger XAUDIO2_9REDIST.DLL à la demande. Il s’agit d’une bonne solution si votre application n’a pas toujours besoin d’utiliser les API XAudio2. Toutefois, si vous effectuez cette opération, vous devez conserver le XAUDIO2_9REDIST.DLL chargé jusqu’à ce que l’application quitte, car la tentative de décharger la DLL peut entraîner un incident si un thread en arrière-plan exécute toujours du code dans la DLL.

Contrairement à l’ancien XAudio 2.7, il n’est pas possible d’utiliser CoCreateInstance pour charger la DLL.

Vérification de la signature DLL

Le fichier binaire XAUDIO2_9REDIST.DLL est signé par Microsoft à l’aide d’une signature SHA-2. Tout code qui tente de valider la signature, par exemple, les modules anti-triche pour les jeux, doit donc prendre en charge SHA-2. Notez que Windows 7 SP1 n’a pas pris en charge SHA-2 à l’origine et nécessite une mise à jour pour ajouter cette fonctionnalité. La mise à jour est disponible en tant que KB4474419.

Test

Son spatial dans les versions plus récentes de Windows 10

À compter de la mise à jour Windows 10 1903, XAudio 2.9 utilise automatiquement le son surround virtuel, si certaines conditions sont remplies. Nous vous recommandons de tester le jeu qui génère un son multi channel sur Windows 10 1903 (ou version ultérieure) pour vérifier que le jeu sonne comme prévu.

Activation du son spatial

L’utilisateur peut activer un format sonore spatial en cliquant avec le bouton droit sur l’icône de l’orateur dans la barre d’état système Windows.

XAudio 2.9 utilise uniquement le format sonore spatial sélectionné par l’utilisateur si le processus qui utilise l’API XAudio2 est reconnu comme un jeu par la barre de jeux Windows. Pendant le développement, il est possible que le processus ne soit pas encore reconnu comme un jeu par la barre de jeux. Pour changer cela, utilisez le clavier Win+G raccourci pour afficher la barre de jeu pendant l’exécution du jeu. Cliquez ensuite sur l’icône « Paramètres » et cochez la case qui indique : « N’oubliez pas qu’il s’agit d’un jeu ».

Désactivation du son spatial

Il existe un moyen de refuser d’utiliser XAudio2 l’encodeur sonore spatial en spécifiant certaines valeurs pour le paramètre AUDIO_STREAM_CATEGORY dans IXAudio2::CreateMasteringVoice.

Le son spatial est activé pour ces catégories :

AudioCategory_ForegroundOnlyMedia
AudioCategory_GameEffects
AudioCategory_GameMedia
AudioCategory_Movie
AudioCategory_Media

Le son spatial n’est pas activé si l’une des catégories suivantes est spécifiée :

AudioCategory_Other
AudioCategory_Communications
AudioCategory_Alerts
AudioCategory_SoundEffects
AudioCategory_GameChat
AudioCategory_Speech

Gestion des erreurs

Il est important de tester que vous pouvez gérer une modification de l’appareil audio, par exemple, lorsque les casques sont branchés ou déconnectés. Cela doit être testé avec des casques qui prennent uniquement en charge le taux d’échantillonnage de 44,1 kHz. De nombreux casques USB bas de gamme et Bluetooth casques prennent uniquement en charge 44,1 kHz. La transition entre le taux d’échantillonnage de 48 kHz et le taux d’échantillonnage de 44,1 kHz peut entraîner une erreur même lorsque la fonctionnalité de point de terminaison audio virtuel est utilisée. L’erreur ne se produit pas si les casques prennent également en charge 48 kHz. Notez que la fonctionnalité de point de terminaison audio virtuel n’est pas disponible sur Windows 7 SP1.

Le code d’erreur retourné par XAudio 2.9 lorsqu’il ne peut pas récupérer automatiquement à partir d’un changement de point de terminaison audio est XAUDIO2_E_DEVICE_INVALIDATED. Toutefois, nous vous recommandons de ne pas coder en dur une dépendance sur le code d’erreur ayant une valeur spécifique.

Pour être averti de l’erreur, l’application doit implémenter l’interface IXAudio2EngineCallback et fournir un pointeur vers cette interface en appelant la méthode IXAudio2::RegisterForCallbacks . L’implémentation de l’application IXAudio2EngineCallback::OnCriticalError sera appelée par l’API XAudio2 si une erreur se produit pendant la lecture.

Notez que IXAudio2EngineCallback::OnCriticalError n’est pas nécessairement appelé si le pipeline audio est suspendu. Par exemple, si l’utilisateur réduit l’application ou que l’application est suspendue pour une raison quelconque, la lecture audio peut être suspendue. Si la modification de l’appareil audio se produit pendant cette période, l’erreur est retournée uniquement lorsque l’application appelle IXAudio2::StartEngine et/ou appelle IXAudio2SourceVoice::Start. Si la lecture peut être suspendue avec votre application, vous devez tester la modification de l’appareil audio pendant que la lecture est suspendue, pour vérifier que l’application peut toujours récupérer à partir de cette situation.

Différences d’API XAudio 2.9 par rapport à XAudio 2.7

Cette section fournit un résumé de certaines des différences d’API entre XAudio 2.7 et la version redistribuable de XAudio 2.9.

Formats pris en charge

XAudio 2.9 prend en charge ces formats d’entrée sur PC :

PCM linéaire 16 bits
PCM float 32 bits linéaire
ADPCM 16 bits
xWMA

Le format XMA n’est pris en charge que sur Xbox One.

Cœur processeur préféré

Il est possible de spécifier le cœur du processeur XAudio 2.9 à utiliser pour son thread de traitement audio. Toutefois, il est généralement préférable de laisser XAudio 2.9 choisir cette valeur elle-même. Pour ce faire, définissez le paramètre XAudio2Processor dans l’appel à XAudio2Create sur XAUDIO2_USE_DEFAULT_PROCESSOR.

XAudio 2.9 choisit un cœur de processeur différent sur Xbox One que sur PC. La méthode IXAudio2Extension::GetProcessor peut être utilisée pour déterminer le cœur du processeur XAudio2 choisi.

Point de terminaison audio virtuel

XAudio 2.9 utilise par défaut un point de terminaison audio virtuel lors de l’exécution sur Windows 8 ou une version ultérieure. Cela signifie que si le point de terminaison audio par défaut change pendant que XAudio 2.9 est utilisé, il tente de basculer automatiquement vers le nouveau point de terminaison audio. Exemple de cas où cela peut se produire lorsque le point de terminaison audio par défaut est une paire de casques connectés via USB, puis que l’utilisateur déconnecte le casque. Cela entraîne l’arrivée des haut-parleurs au nouveau point de terminaison audio par défaut.

Si l’application spécifie un format audio spécifique lors de l’appel d’IXAudio2::CreateMasteringVoice, il peut ne pas être possible pour XAudio 2.9 d’effectuer ce commutateur. Par exemple, si l’application a spécifié que la voix mastering doit utiliser un taux d’échantillonnage de 48 kHz et que le nouvel appareil audio prend uniquement en charge 44,1 kHz, le commutateur automatique échoue, et XAudio 2.9 signale l’erreur XAUDIO2_E_DEVICE_INVALIDATED .

L’application peut refuser l’utilisation du point de terminaison audio virtuel en passant l’indicateur de XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT à IXAudio2::CreateMasteringVoice.

Les points de terminaison audio virtuels ne sont pas disponibles sur Windows 7 SP1. L’indicateur XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT n’a aucun effet sur Windows 7 SP1.

Catégories audio

L’application doit spécifier une catégorie pour son flux audio. Ceci est effectué en fournissant une valeur de l’énumération AudioCategory lors de l’appel de la méthode IXAudio2::CreateMasteringVoice . Par exemple, AudioCategory_GameEffects. La catégorie audio peut affecter la façon dont Windows traite le son ou comment il représente le flux audio dans le panneau de configuration de volume. La catégorie audio affecte également si le son entoure virtuel est automatiquement activé.

Durée du traitement audio quantique

Sur la plupart des PC, XAudio 2.9 traite l’audio en 10 millisecondes. Il s’agit du quantum de traitement. Toutefois, la durée de ce quantum peut être différente de 10 millisecondes sur certains matériels. Les applications qui doivent connaître le quantum exact peuvent appeler la méthode IXAudio2Extension::GetProcessingQuantum pour récupérer la valeur.

Son spatial et son environnement virtuel

Normalement, XAudio 2.9 effectue un pliage audio multicanal pour correspondre au nombre « physique » de canaux audio pris en charge par le point de terminaison audio. Par exemple, si le jeu fournit une source audio de canal 7.1, mais que le son est lu sur les casques, XAudio 2.9 plie l’audio du canal 7.1 en stéréo, à l’aide d’une matrice de repli standard du secteur. Si le PC est connecté à un point de terminaison audio HDMI, l’audio du canal 7.1 est transmis comme c’est le cas via la connexion HDMI.

Windows 10 ajoute la prise en charge de l’audio spatial, à l’aide d’un encodeur centralisé qui encode l’audio dans un format sonore spatial sélectionné par l’utilisateur. Windows 10 est fourni avec un format sonore spatial appelé Windows Sonic. D’autres formats, tels que Dolby Atmos for Headphones, peuvent être téléchargés à partir du Microsoft Store. Certains des formats sonores spatiaux, tels que Windows Sonic et Dolby Atmos for Headphones, sont conçus pour être utilisés sur les points de terminaison audio stéréo. Ces formats plient le son entoure en stéréo à l’aide d’algorithmes propriétaires qui obtiennent un effet sonore « virtuel ». En d’autres termes, l’écouteur peut percevoir le son qui apparaît à partir de différentes positions dans l’espace 3D, même s’il ne porte que des casques, ou pendant l’écoute sur une paire unique de haut-parleurs stéréo.

Des effets similaires peuvent être obtenus à l’aide des API X3DAudio incluses avec XAudio 2.9. La principale différence est que X3DAudio exige que le développeur d’applications programme explicitement pour l’audio 3D, tandis que le son entoure virtuel est appliqué automatiquement à n’importe quelle source sonore basée sur un canal tradional.

Sur Windows 10 1903 et versions ultérieures, les jeux qui utilisent XAudio 2.9 utilisent le format sonore spatial à l’échelle du système que l’utilisateur a activé sur le point de terminaison audio, le cas échéant. Cela signifie que XAudio 2.9 n’effectue pas le pliage habituel du son entoure en stéréo. Au lieu de cela, le signal sonore entoure sera remis à l’encodeur sonore spatial (par exemple, Windows Sonic) pour obtenir un effet sonore entoure virtuel.

CreateHrtfApo

La fonction CreateHrtfApo est disponible uniquement sur Windows 10. Il n’est pas implémenté dans le redistribuable XAudio 2.9.