Entwicklerhandbuch für die weiterverteilbare 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 weiterverteilen. Dadurch kann eine App XAudio 2.9 unter älteren Versionen von Windows verwenden, die XAudio 2.9 nicht als Teil des Betriebssystemimages enthalten. Die Verwendung dieser Verteiler wird gegenüber der Verteilung von XAudio 2.7 aus dem DirectX SDK bevorzugt, da XAudio 2.7 seit 2010 nicht mehr aktualisiert wurde.

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

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 und Windows 10.

Wenn die DLL auf einem Windows 10-System verwendet wird, überprüft sie die Versionsnummer der XAUDIO2_9.DLL, die Teil des Betriebssystems ist, und wenn das Betriebssystem neuer ist, delegiert sie 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 vorgesehen. Bei Verwendung auf Xbox One delegiert die DLL immer alle API-Aufrufe an XAUDIO2_9.DLL im Xbox One-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 ist die Verwendung des NuGet-Paket-Managers in Microsoft Visual Studio. Wenn Sie dies tun, wird Ihre Visual Studio-Projektdatei automatisch aktualisiert, um Microsoft.XAudio2.Redist.targets einzuschließen. Die TARGETS-Datei fügt der Auflistung der Projekteinschließpfade den Include-Ordner mit den Headerdateien für XAudio2 hinzu. Die TARGETS-Datei stellt auch Ihren .DLL oder .EXE Link mit XAUDIO2REDIST her. LIB und XAPOBASEREDIST. LIB.

Die Bibliothek XAPOBASEREDIST. LIB ist nur erforderlich, wenn Sie beabsichtigen, ein benutzerdefiniertes XAudio Processing Object (XAPO) zu impementieren, 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 sogar die Dateierweiterung umzubenennen, um die Dateien mit einem beliebigen ZIP-Extraktortool zu .zip und zu extrahieren.

Es ist auch ein xaudio2redist Port für den VC++-Paket-Manager verfügbar.

Kompilieren Ihrer App

Auswählen der einzuschließenden Header

Das XAudio 2.9-NuGet-Paket enthält die gleichen XAudio2-Headerdateien, die im Windows 10 SDK enthalten sind. Die Headerdateien wurden jedoch angepasst, 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 mithilfe des NuGet-Paket-Managers in Microsoft Visual Studio installieren, wird der Pfad zu den Headerdateien vor dem Pfad zu den Windows SDK-Headerdateien platziert. Dies bedeutet, dass, wenn der Code in Ihrem Projekt XAUDIO2 enthält. H-Header, wird der plattformübergreifende Header aus dem NuGet-Paket abgerufen. Dies ist normalerweise das gewünschte Verhalten.

Sie sollten vorsichtig sein, wenn Sie den Pfad zu den Includeheadern manuell zum Projekt hinzufügen, da die Angabe dieser Header in der falschen Reihenfolge die betriebssystemversionsspezifische XAUDIO2 verursachen kann. H soll aus dem Windows SDK und nicht aus der plattformübergreifenden Version von XAUDIO2.H eingeschlossen werden.

Um die Einbindung von Headern weniger fehleranfällig zu machen, enthält das NuGet-Paket eine Version jedes Headers, an den "REDIST" angefügt ist. Beispielsweise zusätzlich zu XAUDIO2. H, das NuGet-Paket enthält auch XAUDIO2REDIST.H. Wenn Sie möchten, kann Ihr Code XAUDIO2REDIST direkt enthalten. H, um Unklarheiten darüber zu beseitigen, welche Headerdatei verwendet wird. Beim Einschließen von -REDIST. H-Version einer Headerdatei, die Reihenfolge, in der die Includedateiverzeichnisse in der Projektdatei aufgeführt sind, spielt keine Rolle.

Beachten Sie, dass Sie XAUDIO2 weiterhin einschließen sollten, wenn Ihre App auch für Xbox One kompiliert wird. H beim Kompilieren für Xbox One, 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 zu verknüpfen. LIBerieren und installieren Sie XAUDIO2_9REDIST.DLL im selben Ordner wie die ausführbare Datei Ihrer App. Dies führt dazu, dass XAUDIO2_9REDIST.DLL geladen wird, sobald Ihre ausführbare Datei gestartet wird. Wenn Sie es vorziehen, können Sie jedoch 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, einen Absturz verursachen kann, wenn ein Hintergrundthread weiterhin Code in der DLL ausführt.

Im Gegensatz zum ä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

Raumklang in neueren Versionen von Windows 10

Ab dem Windows 10 1903-Update verwendet XAudio 2.9 automatisch virtuellen Surround-Sound, wenn bestimmte Bedingungen erfüllt sind. Es wird empfohlen, ein Spiel zu testen, das mehrkanaligen Sound auf Windows 10 1903 (oder höher) generiert, um zu überprüfen, ob das Spiel wie erwartet klingt.

Aktivieren von Raumklang

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

XAudio 2.9 verwendet nur das vom Benutzer ausgewählte räumliche Soundformat, 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 Spielleiste noch nicht als Spiel erkannt wird. Um dies zu ändern, verwenden Sie die Win+G-Tastaturkurz, um die Spielleiste während der Ausführung des Spiels anzuzeigen. Klicken Sie dann auf das Symbol "Einstellungen", und aktivieren Sie das Kontrollkästchen "Denken Sie daran, dass dies ein Spiel ist".

Abmeldung von raumbezogenem Sound

Es gibt eine Möglichkeit, die Verwendung des Raumklangencoders von XAudio2 zu deaktivieren, indem Sie bestimmte Werte für den parameter AUDIO_STREAM_CATEGORY in IXAudio2::CreateMasteringVoice angeben.

Raumklang ist für die folgenden Kategorien aktiviert:

• AudioCategory_ForegroundOnlyMedia
• AudioCategory_GameEffects
• AudioCategory_GameMedia
• AudioCategory_Movie
• AudioCategory_Media

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

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

Fehlerbehandlung

Es ist wichtig zu testen, ob Das Spiel eine Änderung des Audiogeräts verarbeiten kann, z. B. wenn Kopfhörer angeschlossen oder nicht angeschlossen werden. Dies sollte mit Kopfhörern getestet werden, die nur eine Abtastrate von 44,1 kHz unterstützen. Viele Low-End-USB-Kopfhörer und Bluetooth-Headsets unterstützen nur 44,1 kHz. Der Übergang zwischen einer Abtastrate von 48 kHz und einer Abtastrate von 44,1 kHz kann selbst dann zu einem Fehler führen, wenn die Funktion des virtuellen Audioendpunkts verwendet wird. Der Fehler tritt nicht auf, wenn der Kopfhörer auch 48 kHz unterstützt. 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 er nach einer Änderung des Audioendpunkts nicht automatisch wiederhergestellt werden kann , ist XAUDIO2_E_DEVICE_INVALIDATED. Es wird jedoch empfohlen, dass Apps eine Abhängigkeit vom Fehlercode mit einem bestimmten Wert nicht 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 unbedingt aufgerufen wird, wenn die Audiopipeline angehalten wird. Wenn der Benutzer beispielsweise die App minimiert oder die App aus irgendeinem Grund angehalten wird, wird die Audiowiedergabe möglicherweise angehalten. Wenn die Änderung des Audiogeräts während dieser Zeit auftritt, wird der Fehler nur zurückgegeben, wenn die App IXAudio2::StartEngine 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 ist, um zu überprüfen, ob die App nach dieser Situation weiterhin wiederhergestellt werden kann.

Unterschiede bei der XAudio 2.9-API im Vergleich zu XAudio 2.7

Dieser Abschnitt enthält eine Zusammenfassung einiger 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-Float-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 verwenden soll. Es wird jedoch in der Regel bevorzugt, XAudio 2.9 diesen Wert selbst zu wählen. Dazu legen Sie den XAudio2Processor-Parameter im Aufruf von XAudio2Create auf XAUDIO2_USE_DEFAULT_PROCESSOR fest.

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

Virtueller Audioendpunkt

XAudio 2.9 verwendet standardmäßig einen virtuellen Audioendpunkt, wenn Windows 8 oder höher ausgeführt wird. Dies bedeutet, dass, wenn sich der Standard-Audioendpunkt ändert, während XAudio 2.9 verwendet wird, automatisch auf den neuen Audioendpunkt umgestellt wird. Ein Beispiel dafür, wenn der Standardaudioendpunkt ein Kopfhörerpaar ist, das über USB verbunden ist und der Benutzer dann den Kopfhörer absteckt. Dies führt dazu, dass die Lautsprecher der neue Standardaudioendpunkt sind.

Wenn die App beim Aufrufen von IXAudio2::CreateMasteringVoice ein bestimmtes Audioformat angibt, ist es für XAudio 2.9 möglicherweise nicht möglich, diesen Schalter auszuführen. Wenn die App beispielsweise angegeben hat, dass die Mastering Voice eine Abtastrate 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 das XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT-Flag an IXAudio2::CreateMasteringVoice übergeben wird.

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 ihren Audiodatenstrom angeben. Dies erfolgt durch Bereitstellen eines Werts aus der AudioCategory-Enumeration beim Aufrufen der IXAudio2::CreateMasteringVoice-Methode . Beispiel: AudioCategory_GameEffects. Die Audiokategorie kann beeinflussen, 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 der Audioverarbeitung mit Quanten

Auf den meisten PCs verarbeitet XAudio 2.9 Audio in Blöcken von 10 Millisekunden. Dies wird als Verarbeitungsquanten bezeichnet. Die Dauer dieses Quantens kann jedoch auf einer Hardware von 10 Millisekunden abweichen. Apps, die das genaue Quantum kennen müssen, können die IXAudio2Extension::GetProcessingQuantum-Methode aufrufen, um den Wert abzurufen.

Raumklang und virtuelle Umgebung

Ab dem Update Windows 10 1903 verwendet XAudio 2.9 automatisch virtuellen Surround-Sound, wenn bestimmte Bedingungen erfüllt sind. Es wird empfohlen, ein Spiel zu testen, das mehrkanaligen Sound auf Windows 10 1903 (oder höher) generiert, um zu überprüfen, ob das Spiel wie erwartet klingt. Weitere Informationen zum Testen dieses Features finden Sie im Abschnitt testen des räumlichen Klangs .

Normalerweise führt XAudio 2.9 eine Faltung aller mehrkanaligen Audiodaten durch, um der "physischen" Anzahl von Audiokanälen zu entsprechen, die vom Audioendpunkt unterstützt werden. Wenn das Spiel beispielsweise eine 7.1-Kanal-Audioquelle bereitstellt, der Sound aber auf Kopfhörern wiedergegeben wird, wird XAudio 2.9 das Audiosignal mit 7.1 Kanälen mithilfe einer herunterklappbaren Matrix nach Industriestandard in Stereo umklappen. Wenn der PC mit einem HDMI-Audioendpunkt verbunden ist, wird das 7.1-Kanal-Audio unverändert über die HDMI-Verbindung übertragen.

Windows 10 fügt Unterstützung für räumliche Audiodaten hinzu, indem ein zentralisierter Encoder verwendet wird, der Audiodaten in ein vom Benutzer ausgewähltes räumliches Soundformat codiert. Windows 10 ist mit einem räumlichen Soundformat namens Windows Sonic enthalten. Andere Formate, z. B. Dolby Atmos for Headphones, können aus dem Microsoft Store heruntergeladen werden. Einige der räumlichen Soundformate, z. B. Windows Sonic und Dolby Atmos for Headphones, sind für die Verwendung auf Stereo-Audioendpunkten konzipiert. Diese Formate werden mit proprietären Algorithmen, die einen "virtuellen" Surround-Sound-Effekt erzielen, in Stereo eingeklappt. Anders ausgedrückt: Der Hörer kann Sound aus verschiedenen Positionen im 3D-Raum wahrnehmen, auch wenn er nur Kopfhörer trägt oder an einem einzelnen Stereolautsprecher lauscht.

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

Ab Windows 10 1903 und höher verwenden Spiele, die XAudio 2.9 verwenden, das systemweite räumliche Soundformat, das der Benutzer ggf. für den Audioendpunkt aktiviert hat. Dies bedeutet, dass XAudio 2.9 nicht das übliche Herunterklappen von Surround-Sound in Stereo ausführt. Stattdessen wird das Surround-Soundsignal an den Raumklangencoder (z. B. Windows Sonic) übermittelt, um einen virtuellen Surround-Soundeffekt zu erzielen.

CreateHrtfApo

Die CreateHrtfApo-Funktion ist nur auf Windows 10 verfügbar. Es ist nicht im verteilbaren XAudio 2.9 implementiert.