Entwicklerhandbuch für weitervertreibbare Version von XAudio 2.9

Eine Version von XAudio 2.9 ist als NuGet-Paket verfügbar. Entwickler können diese Version von XAudio 2.9 mit ihren Apps erneut verteilen. Dadurch kann eine App XAudio 2.9 in älteren Versionen von Windows verwenden, die XAudio 2.9 nicht als Teil des Betriebssystemimages enthalten. Die Verwendung dieser Verteilertabelle wird gegenüber der Umverteilung von XAudio 2.7 aus dem DirectX SDK bevorzugt, da XAudio 2.7 seit 2010 nicht aktualisiert wurde.

Stellen Sie sicher, dass Sie die DirectX-Zielseite für weitere Ressourcen für DirectX-Entwickler besuchen.

Unterstützte Plattformen

Das XAudio 2.9 NuGet-Paket (Microsoft.XAudio2.Redist.*.nupkg) enthält eine 32-Bit- und eine 64-Bit-Version einer DLL, die die XAudio 2.9-API implementiert. Die DLL wird als XAUDIO2_9REDIST.DLL bezeichnet. Diese DLL funktioniert unter Windows 7 SP1, Windows 8, Windows 8.1, Windows 10 und Windows 11. Es gibt auch eine ARM64-Version der DLL für Windows 11 auf ARM.

Wenn die DLL auf einem Windows 10/Windows 11-System verwendet wird, überprüft sie die Versionsnummer der XAUDIO2_9.DLL, die Teil des Betriebssystems ist, und wenn das Betriebssystem neuer ist, delegiert er alle API-Aufrufe an XAUDIO2_9.DLL im Betriebssystem. Dadurch wird sichergestellt, dass Apps immer die neueste Version von XAudio 2.9 verwenden, die auf der aktuellen Plattform verfügbar ist.

Die DLL ist nicht für Xbox One oder Xbox Series X|S vorgesehen. Bei Verwendung auf Xbox delegiert die DLL immer alle API-Aufrufe an XAUDIO2_9.DLL im Xbox-Betriebssystem.

Die DLL ist nicht für UWP-Apps vorgesehen. UWP-Apps sollten die XAUDIO2_9.DLL verwenden, die Teil des Betriebssystems ist.

Installieren des NuGet-Pakets

Die einfachste Möglichkeit zum Installieren des NuGet-Pakets besteht darin, den NuGet-Paket-Manager in Microsoft Visual Studio zu verwenden. Wenn Sie dies tun, wird Ihre Visual Studio-Projektdatei automatisch aktualisiert, um Microsoft.XAudio2.Redist.targets einzuschließen. Die .targets-Datei fügt den Include-Ordner mit den Headerdateien für XAudio2 zu Ihrer Sammlung von Projekt-Include-Pfaden hinzu. Die .targets Datei sorgt dafür, dass Ihre .DLL- oder .EXE-Datei mit XAUDIO2REDIST.LIB und XAPOBASEREDIST.LIB verlinkt wird.

Die Bibliothek XAPOBASEREDIST.LIB ist nur erforderlich, wenn Sie beabsichtigen, ein benutzerdefiniertes XAudio Processing Object (XAPO) zu implementieren, und Sie können es aus Microsoft.XAudio2.Redist.targets entfernen, wenn es nicht verwendet wird.

Sie können auch andere Tools verwenden, um den Inhalt des NuGet-Pakets zu extrahieren oder die Dateierweiterung sogar in .zip umzubenennen und die Dateien mit jedem ZIP-Extraktortool zu extrahieren.

Außerdem steht ein xaudio2redist Port für den VC++-Paket-Manager zur Verfügung.

Kompilieren Ihrer App

Auswahl der zu inkludierenden Kopfzeilen

Das XAudio 2.9 NuGet-Paket enthält dieselben XAudio2-Headerdateien, die im Windows 10 SDK enthalten sind. Die Headerdateien haben jedoch einige Anpassungen vorgenommen, um sicherzustellen, dass Sie sie verwenden können, während sie explizit auf alle unterstützten Plattformen ausgerichtet sind, einschließlich älterer Versionen von Windows.

Wenn Sie das NuGet-Paket mit dem NuGet-Paket-Manager in Microsoft Visual Studio installieren, wird der Pfad zu den Headerdateien vor dem Pfad zu den Windows SDK-Headerdateien platziert. Dies bedeutet, dass der Code in Ihrem Projekt, wenn er die XAUDIO2.H-Headerdatei enthält, den plattformübergreifenden Header aus dem NuGet-Paket übernimmt. Dies ist normalerweise das gewünschte Verhalten.

Sie sollten vorsichtig sein, den Pfad zu den Include-Headern manuell zum Projekt hinzuzufügen, da das Festlegen in falscher Reihenfolge dazu führen kann, dass die betriebssystemspezifische XAUDIO2.H aus dem Windows SDK anstelle der plattformübergreifenden Version von XAUDIO2.H einbezogen wird.

Damit die Einbindung von Headern weniger fehleranfällig ist, enthält das NuGet-Paket eine Version jedes Headers, an die "REDIST" angehängt ist. Beispielsweise umfasst das NuGet-Paket zusätzlich zu XAUDIO2.H auch XAUDIO2REDIST.H. Wenn Sie es vorziehen, kann Ihr Code direkt die Datei XAUDIO2REDIST.H einbinden, um jegliche Mehrdeutigkeit darüber zu beseitigen, welche Headerdatei verwendet wird. Wenn Sie die -REDIST.H-Version einer Headerdatei einfügen, spielt die Reihenfolge der Include-Verzeichnisse in der Projektdatei keine Rolle.

Beachten Sie, dass Sie XAUDIO2.H weiterhin einschließen sollten, wenn Ihre App auch für Xbox One kompiliert wird, da einige Xbox-One-spezifische APIs von XAUDIO2REDIST.H ausgeschlossen sind. Dieses NuGet-Paket ist nicht für Xbox One vorgesehen.

Laden der DLL

Es wird empfohlen, Ihre App mit XAUDIO2REDIST.LIB zu verknüpfen und XAUDIO2_9REDIST.DLL im selben Ordner wie die ausführbare Datei Ihrer App zu installieren. Dies führt dazu, dass XAUDIO2_9REDIST.DLL geladen wird, sobald die ausführbare Datei gestartet wird. Wenn Es Ihnen jedoch lieber ist, können Sie LoadLibraryEx und GetProcAddress verwenden, um XAUDIO2_9REDIST.DLL bei Bedarf zu laden. Dies ist eine gute Lösung, wenn Ihre App nicht immer die XAudio2-APIs verwenden muss. Wenn Sie dies tun, sollten Sie die XAUDIO2_9REDIST.DLL geladen lassen, bis die App beendet wird, da der Versuch, die DLL zu entladen, zu einem Absturz führen kann, wenn ein Hintergrundthread weiterhin Code in der DLL ausführt.

Im Gegensatz zu den älteren XAudio 2.7 ist es nicht möglich, coCreateInstance zum Laden der DLL zu verwenden.

Überprüfen der DLL-Signatur

Die XAUDIO2_9REDIST.DLL Binärdatei wird von Microsoft mit einer SHA-2-Signatur signiert. Jeder Code, der versucht, die Signatur zu überprüfen, z. B. Anti-Cheat-Module für Spiele, muss daher SHA-2 unterstützen. Beachten Sie, dass Windows 7 SP1 SHA-2 ursprünglich nicht unterstützt hat und ein Update erfordert, um diese Funktionalität hinzuzufügen. Das Update ist als KB4474419 verfügbar.

Testen

Räumlicher Sound in neueren Versionen von Windows 10

Ab dem Windows 10 1903-Update verwendet XAudio 2.9 automatisch virtuelle Surround-Sound, wenn bestimmte Bedingungen erfüllt sind. Es wird empfohlen, Spiele zu testen, die unter Windows 10 1903 (oder höher) Multikanalsound generieren, um sicherzustellen, dass das Spiel erwartungsgemäß klingt.

Aktivieren des räumlichen Klangs

Der Benutzer kann ein räumliches Soundformat aktivieren, indem er mit der rechten Maustaste auf das Lautsprechersymbol in der Windows-Taskleiste klickt.

XAudio 2.9 verwendet nur das ausgewählte räumliche Soundformat des Benutzers, wenn der Prozess, der die XAudio2-API verwendet, von der Windows Game Bar als Spiel erkannt wird. Während der Entwicklung ist es möglich, dass der Prozess von der Game Bar noch nicht als Spiel erkannt wird. Um dies zu ändern, verwenden Sie die Kurzkürzung der Win+G-Tastatur, um die Spielleiste anzuzeigen, während das Spiel ausgeführt wird. Klicken Sie dann auf das Symbol "Einstellungen", und aktivieren Sie das Kontrollkästchen mit der Meldung "Denken Sie daran, dass es sich um ein Spiel handelt".

Deaktivierung von räumlichem Klang

Es gibt eine Möglichkeit, dass XAudio2 den räumlichen Soundgeber nicht verwendet, indem bestimmte Werte für den Parameter AUDIO_STREAM_CATEGORY in IXAudio2::CreateMasteringVoice angegeben werden.

Räumlicher Sound ist für diese Kategorien aktiviert:

• Audiokategorie_NurVordergrundMedien
• AudioKategorie_Spieleffekte
• AudioKategorie_SpielMedien
• AudioKategorie_Film
• AudioKategorie_Medien

Räumlicher Sound ist nicht aktiviert, wenn eine der folgenden Kategorien angegeben ist:

• Audiokategorie_Andere
• AudioKategorie_Kommunikation
• AudioKategorie_Warnungen
• AudioCategory_Soundeffekte
• AudioKategorie_SpielChat
• AudioKategorie_Rede

Fehlerbehandlung

Es ist wichtig, zu testen, ob Das Spiel eine Änderung des Audiogeräts verarbeiten kann, z. B. wenn Kopfhörer angeschlossen sind oder nicht angeschlossen sind. Dies sollte mit Kopfhörern getestet werden, die nur 44,1 kHz Samplingrate unterstützen. Viele Low-End-USB-Kopfhörer und Bluetooth-Headsets unterstützen nur 44,1 kHz. Der Übergang zwischen 48 kHz Samplingrate und 44,1 kHz Samplingrate kann auch dann zu einem Fehler führen, wenn das Feature des virtuellen Audioendpunkts verwendet wird. Der Fehler tritt nicht auf, wenn die Kopfhörer auch 48 kHz unterstützen. Beachten Sie, dass das Feature für virtuelle Audioendpunkte unter Windows 7 SP1 nicht verfügbar ist.

Der von XAudio 2.9 zurückgegebene Fehlercode, wenn XAudio 2.9 sich von einer Änderung des Audioendpunkts nicht automatisch erholen kann, ist XAUDIO2_E_DEVICE_INVALIDATED. Es wird jedoch empfohlen, dass Apps keine Abhängigkeit vom Fehlercode mit einem bestimmten Wert hart codieren.

Um über den Fehler benachrichtigt zu werden, sollte die App die IXAudio2EngineCallback-Schnittstelle implementieren und einen Zeiger auf diese Schnittstelle bereitstellen, indem sie die IXAudio2::RegisterForCallbacks-Methode aufruft. Die App-Implementierung von IXAudio2EngineCallback::OnCriticalError wird von der XAudio2-API aufgerufen, wenn während der Wiedergabe ein Fehler auftritt.

Beachten Sie, dass IXAudio2EngineCallback::OnCriticalError nicht notwendigerweise aufgerufen wird, wenn die Audiopipeline angehalten wird. Wenn der Benutzer beispielsweise die App minimiert oder die App aus irgendeinem Grund in den Ruhezustand versetzt wird, kann die Audiowiedergabe pausiert werden. Wenn die Änderung des Audiogeräts während dieses Zeitraums auftritt, wird der Fehler nur zurückgegeben, wenn die App IXAudio2::StartEngine aufruft und/oder IXAudio2SourceVoice::Start aufruft. Wenn die Wiedergabe mit Ihrer App angehalten werden kann, sollten Sie das Ändern des Audiogeräts testen, während die Wiedergabe angehalten wird, um zu überprüfen, ob die App weiterhin aus dieser Situation wiederhergestellt werden kann.

XAudio 2.9-API-Unterschiede im Vergleich zu XAudio 2.7

Dieser Abschnitt enthält eine Zusammenfassung der API-Unterschiede zwischen XAudio 2.7 und der verteilbaren Version von XAudio 2.9.

Unterstützte Formate

XAudio 2.9 unterstützt diese Eingabeformate auf DEM PC:

• Linearer 16-Bit-PCM
• Linearer 32-Bit-Gleitkomma-PCM
• 16-Bit-ADPCM
• xWMA

Das XMA-Format wird nur auf Xbox One unterstützt.

Bevorzugter CPU-Kern

Es ist möglich, anzugeben, welcher CPU-Kern XAudio 2.9 für den Audioverarbeitungsthread verwendet werden soll. Es ist jedoch meist vorzuziehen, dass XAudio 2.9 diesen Wert selbst auswählt. Dazu legen Sie den XAudio2Processor-Parameter im Aufruf von XAudio2Create auf XAUDIO2_USE_DEFAULT_PROCESSOR fest.

XAudio 2.9 wählt einen anderen CPU-Kern auf Xbox One als auf dem PC aus. Die IXAudio2Extension::GetProcessor-Methode kann verwendet werden, um zu bestimmen, welcher CPU-Kern XAudio2 ausgewählt wurde.

Virtueller Audioendpunkt

XAudio 2.9 verwendet standardmäßig einen virtuellen Audioendpunkt, wenn er unter Windows 8 oder höher ausgeführt wird. Dies bedeutet: Wenn sich der Standardmäßige Audioendpunkt ändert, während XAudio 2.9 verwendet wird, wird versucht, automatisch zum neuen Audioendpunkt zu wechseln. Ein Beispiel dafür, wann dies passieren kann, wenn der Standardaudioendpunkt ein Kopfhörerpaar ist, das über USB angeschlossen ist, und der Benutzer hebt dann die Kopfhörer ab. Dies bewirkt, dass die Lautsprecher der neue Standardaudioendpunkt sind.

Wenn die App beim Aufrufen von IXAudio2::CreateMasteringVoice ein bestimmtes Audioformat angibt, ist es möglicherweise nicht möglich, dass XAudio 2.9 diese Option ausführen kann. Wenn die App beispielsweise angegeben hat, dass die Mastering Voice eine Samplingrate von 48 kHz verwenden soll und das neue Audiogerät nur 44,1 kHz unterstützt, schlägt der automatische Schalter fehl, und XAudio 2.9 meldet den XAUDIO2_E_DEVICE_INVALIDATED Fehler.

Es ist möglich, dass die App die Verwendung des virtuellen Audioendpunkts abwählen kann, indem Sie das XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT-Flag an IXAudio2::CreateMasteringVoice übergeben.

Virtuelle Audioendpunkte sind unter Windows 7 SP1 nicht verfügbar. Das XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT-Flag hat keine Auswirkungen auf Windows 7 SP1.

Audiokategorien

Die App sollte eine Kategorie für den Audiodatenstrom angeben. Dazu wird ein Wert aus der AudioCategory-Aufzählung beim Aufrufen der IXAudio2::CreateMasteringVoice-Methode bereitgestellt. Beispiel: AudioCategory_GameEffects. Die Audiokategorie kann sich darauf auswirken, wie Windows den Sound verarbeitet oder wie er den Audiodatenstrom in der Lautstärkesteuerung darstellt. Die Audiokategorie wirkt sich auch auf die automatische Aktivierung des virtuellen Surroundsounds aus.

Dauer des Audioverarbeitungsquantums

Auf den meisten PCs verarbeitet XAudio 2.9 Audio in 10 Millisekundenblöcken. Dies wird als Quantenverarbeitung bezeichnet. Die Dauer dieses Quantums kann sich jedoch auf bestimmten Hardware von 10 Millisekunden unterscheiden. Apps, die genau das Quantum kennen müssen, können die IXAudio2Extension::GetProcessingQuantum-Methode aufrufen, um den Wert abzurufen.

Räumlicher Sound und virtuelle Umgebung

Ab dem Windows 10 1903-Update verwendet XAudio 2.9 automatisch virtuellen Surround-Sound, wenn bestimmte Bedingungen erfüllt sind. Es wird empfohlen, Spiele zu testen, die unter Windows 10 1903 (oder höher) Multikanalsound generieren, um sicherzustellen, dass das Spiel erwartungsgemäß klingt. Eine Erläuterung zum Testen dieses Features finden Sie im Abschnitt " Raumsound testen".

Normalerweise führt XAudio 2.9 eine Faltung aller Mehrkanalaudios durch, um der "physischen" Anzahl von Audiokanälen zu entsprechen, die vom Audioendpunkt unterstützt werden. Zum Beispiel, wenn das Spiel eine 7.1-Kanal-Audioquelle liefert, der Sound jedoch auf Kopfhörern wiedergegeben wird, konvertiert XAudio 2.9 das 7.1-Kanal-Audio mit einer Downmix-Matrix nach Industriestandard in Stereo. Wenn der PC an einen HDMI-Audioendpunkt angeschlossen ist, wird das 7.1-Kanal-Audio as-is über die HDMI-Verbindung übertragen.

Windows 10 bietet Unterstützung für räumliches Audio unter Verwendung eines zentralisierten Encoders, der Audio in ein vom Benutzer ausgewähltes räumliches Soundformat codiert. Windows 10 ist im Lieferumfang eines räumlichen Soundformats mit dem Namen Windows Sonic enthalten. Andere Formate wie Dolby Atmos für Headphones können aus dem Microsoft Store heruntergeladen werden. Einige der räumlichen Soundformate, z. B. Windows Sonic und Dolby Atmos für Headphones, sind für die Verwendung auf Stereo-Audioendpunkten konzipiert. Diese Formate werden mit proprietären Algorithmen, die einen "virtuellen" Surround-Soundeffekt erzielen, auf Stereo heruntergemischt. Mit anderen Worten, der Hörer kann Sound aus verschiedenen Positionen im 3D-Raum wahrnehmen, auch wenn er nur Kopfhörer trägt oder auf ein einzelnes Paar Stereolautsprecher hört.

Ähnliche Effekte können mit den X3DAudio-APIs erzielt werden, die in XAudio 2.9 enthalten sind. Der Hauptunterschied besteht darin, dass X3DAudio erfordert, dass der App-Entwickler explizit für 3D-Audio programmieren muss, während der virtuelle Surround-Sound automatisch auf jede tradional kanalbasierte Soundquelle angewendet wird.

Unter Windows 10 1903 und neueren Versionen verwenden Spiele, die XAudio 2.9 nutzen, das systemweite Raumsoundformat, das der Benutzer am Audioendpunkt aktiviert hat, falls vorhanden. Dies bedeutet, dass XAudio 2.9 die übliche Umwandlung des Surround-Sounds in Stereo nicht durchführt. Stattdessen wird das Surround-Soundsignal an den Räumlichen Sound-Encoder (z. B. Windows Sonic) übermittelt, um einen virtuellen Surround-Soundeffekt zu erzielen.

CreateHrtfApo

Die CreateHrtfApo-Funktion ist nur unter Windows 10 verfügbar. Es ist nicht im XAudio 2.9 Redistributable-Paket implementiert.