Przewodnik dla deweloperów dotyczący wersji redystrybucyjnej XAudio 2.9

Wersja pakietu XAudio 2.9 jest dostępna jako pakiet NuGet . Deweloperzy mogą rozpowszechniać tę wersję programu XAudio 2.9 przy użyciu swoich aplikacji. Dzięki temu aplikacja może używać interfejsu XAudio 2.9 w starszych wersjach systemu Windows, które nie zawierają biblioteki XAudio 2.9 w ramach obrazu systemu operacyjnego. Użycie tego konkretnego pakietu redystrybucyjnego jest preferowane zamiast redystrybucji biblioteki XAudio 2.7 z zestawu SDK DirectX, gdyż XAudio 2.7 nie był aktualizowany od 2010 roku.

Upewnij się, że odwiedź stronę docelową DirectX , aby uzyskać więcej zasobów dla deweloperów DirectX.

Obsługiwane platformy

Pakiet NuGet XAudio 2.9 (Microsoft.XAudio2.Redist.*.nupkg) zawiera 32-bitową i 64-bitową wersję biblioteki DLL, która implementuje interfejs API XAudio 2.9. Biblioteka DLL jest nazywana XAUDIO2_9REDIST.DLL. Ta biblioteka DLL będzie działać w systemach Windows 7 z dodatkiem SP1, Windows 8, Windows 8.1, Windows 10 i Windows 11. Istnieje również wersja biblioteki DLL ARM64 dla systemu Windows 11 na platformie ARM.

Gdy biblioteka DLL jest używana w systemie Windows 10/Windows 11, sprawdza numer wersji XAUDIO2_9.DLL, który jest częścią systemu operacyjnego, a jeśli system operacyjny jest nowszy, deleguje wszystkie wywołania interfejsu API do XAUDIO2_9.DLL w systemie operacyjnym. Dzięki temu aplikacje zawsze korzystają z najnowszej wersji programu XAudio 2.9 dostępnej na bieżącej platformie.

Biblioteka DLL nie jest przeznaczona dla konsoli Xbox One ani Xbox Series X|S. W przypadku użycia na konsoli Xbox biblioteka DLL zawsze deleguje wszystkie wywołania interfejsu API do XAUDIO2_9.DLL w systemie operacyjnym Xbox.

Biblioteka DLL nie jest przeznaczona dla aplikacji platformy UWP. Aplikacje platformy UWP powinny używać XAUDIO2_9.DLL, które są częścią systemu operacyjnego.

Instalowanie pakietu NuGet

Najprostszym sposobem zainstalowania pakietu NuGet jest użycie Menedżera pakietów NuGet w programie Microsoft Visual Studio. Jeśli to zrobisz, plik projektu programu Visual Studio zostanie automatycznie zaktualizowany w celu uwzględnienia elementów Docelowych Microsoft.XAudio2.Redist.. Plik .targets dodaje folder Include z plikami nagłówkowymi dla XAudio2 do ścieżek dołączania projektu. Plik targets spowoduje połączenie plików .DLL lub .EXE z XAUDIO2REDIST.LIB i XAPOBASEREDIST.LIB.

Biblioteka XAPOBASEREDIST.LIB jest wymagana tylko wtedy, gdy zamierzasz implementować niestandardowy obiekt przetwarzania XAudio (XAPO) i można ją usunąć z Microsoft.XAudio2.Redist.targets, jeśli nie jest używana.

Możesz również użyć innych narzędzi, aby wyodrębnić zawartość pakietu NuGet, a nawet zmienić nazwę rozszerzenia pliku na .zip i wyodrębnić pliki za pomocą dowolnego narzędzia wyodrębniającego ZIP.

Istnieje również xaudio2redist port dostępny dla Menedżera pakietów VC++.

Kompilowanie aplikacji

Wybieranie nagłówków do uwzględnienia

Pakiet NuGet XAudio 2.9 zawiera te same pliki nagłówkowe XAudio2, które znajdują się w zestawie SDK systemu Windows 10. Jednak pliki nagłówkowe miały pewne korekty, aby upewnić się, że można ich używać podczas jawnego określania wartości docelowej dla wszystkich platform obsługiwanych , w tym starszych wersji systemu Windows.

Jeśli zainstalujesz pakiet NuGet przy użyciu Menedżera pakietów NuGet w programie Microsoft Visual Studio, ścieżka do plików nagłówkowych zostanie umieszczona przed ścieżką do plików nagłówkowych zestawu Windows SDK. Oznacza to, że jeśli kod w projekcie zawiera nagłówek XAUDIO2.H, to zostanie on pobrany jako nagłówek międzyplatformowy z pakietu NuGet. Jest to zwykle pożądane zachowanie.

Należy zachować ostrożność w przypadku ręcznego dodawania ścieżki do nagłówków dołączeń do projektu, ponieważ określenie ich w niewłaściwej kolejności może spowodować dołączenie pliku XAUDIO2.H specyficznego dla wersji systemu operacyjnego z zestawu Windows SDK, zamiast międzyplatformowej wersji XAUDIO2.H.

Aby zmniejszyć podatność na błędy przy dołączaniu nagłówków, pakiet NuGet zawiera wersję każdego nagłówka z dopiskiem "REDIST". Na przykład oprócz XAUDIO2. H, pakiet NuGet zawiera również XAUDIO2REDIST.H. Jeśli wolisz, kod może bezpośrednio zawierać XAUDIO2REDIST. H, aby wyeliminować wszelkie niejednoznaczności dotyczące używanego pliku nagłówka. Podczas dołączania wersji pliku nagłówkowego -REDIST.H, kolejność katalogów plików dołączanych w pliku projektu nie ma znaczenia.

Należy pamiętać, że jeśli aplikacja jest również kompilowana dla konsoli Xbox One, należy nadal dołączać XAUDIO2. H podczas kompilowania dla konsoli Xbox One, ponieważ niektóre interfejsy API specyficzne dla konsoli Xbox One są wykluczone z XAUDIO2REDIST.H. Ten pakiet NuGet nie jest przeznaczony dla konsoli Xbox One.

Ładowanie biblioteki DLL

Zalecamy połączenie aplikacji z XAUDIO2REDIST. LIB i zainstaluj XAUDIO2_9REDIST.DLL w tym samym folderze co plik wykonywalny aplikacji. Spowoduje to załadowanie XAUDIO2_9REDIST.DLL zaraz po uruchomieniu pliku wykonywalnego. Jeśli jednak wolisz, możesz użyć poleceń LoadLibraryEx i GetProcAddress , aby załadować XAUDIO2_9REDIST.DLL na żądanie. Jest to dobre rozwiązanie, jeśli aplikacja nie zawsze musi używać interfejsów API XAudio2. Jeśli jednak to zrobisz, należy utrzymywać załadowany plik XAUDIO2_9REDIST.DLL do momentu zakończenia działania aplikacji, ponieważ próba od załadowania pliku DLL może spowodować awarię, jeśli wątek w tle nadal wykonuje kod w DLL.

W przeciwieństwie do starszej wersji XAudio 2.7 nie można użyć klasy CoCreateInstance do załadowania biblioteki DLL.

Weryfikowanie podpisu biblioteki DLL

Plik binarny XAUDIO2_9REDIST.DLL jest podpisany przez firmę Microsoft przy użyciu podpisu SHA-2. Każdy kod, który próbuje zweryfikować podpis, np. moduły chroniące przed oszustwami dla gier, muszą zatem obsługiwać algorytm SHA-2. Należy pamiętać, że system Windows 7 z dodatkiem SP1 nie obsługiwał pierwotnie algorytmu SHA-2 i wymaga aktualizacji w celu dodania tej funkcji. Aktualizacja jest dostępna jako KB4474419.

Testowanie

Dźwięk przestrzenny w nowszych wersjach systemu Windows 10

Począwszy od aktualizacji systemu Windows 10 1903, XAudio 2.9 automatycznie używa wirtualnego dźwięku otaczającego, jeśli spełnione są pewne warunki. Zalecamy testowanie gry, która generuje dźwięk wielokanałowy w systemie Windows 10 1903 (lub nowszym), aby sprawdzić, czy gra brzmi zgodnie z oczekiwaniami.

Włączanie dźwięku przestrzennego

Użytkownik może włączyć format dźwięku przestrzennego, klikając prawym przyciskiem myszy ikonę głośnika na pasku zadań systemu Windows.

XAudio 2.9 będzie używać tylko wybranego przez użytkownika formatu dźwięku przestrzennego, jeśli proces korzystający z interfejsu API XAudio2 jest rozpoznawany jako gra przez Windows Game Bar. Podczas opracowywania może się zdarzyć, że proces nie jest jeszcze rozpoznawany jako gra przez Pasek gier. Aby to zmienić, użyj skrótu klawiatury Win+G, aby podnieść pasek gry, gdy gra jest uruchomiona. Następnie kliknij ikonę "Ustawienia" i zaznacz pole wyboru "Pamiętaj, że jest to gra".

Rezygnacja z korzystania z dźwięku przestrzennego

Istnieje sposób, aby zrezygnować z używania kodera dźwięku przestrzennego XAudio2, określając pewne wartości parametru AUDIO_STREAM_CATEGORY w ixAudio2::CreateMasteringVoice.

Dźwięk przestrzenny jest włączony dla następujących kategorii:

• KategoriaDźwięku_TylkoMediatło
• KategoriaAudio_EfektyGry
• KategoriaDźwięku_MediaGry
• KategoriaAudio_Film
• KategoriaAudio_Media

Dźwięk przestrzenny nie jest włączony, jeśli określono dowolną z następujących kategorii:

• KategoriaAudio_Inne
• KategoriaDźwięku_Komunikacja
• KategoriaDźwięku_Alarmy
• KategoriaDźwiękowa_EfektyDźwiękowe
• KategoriaDźwięku_GameChat
• KategoriaDźwięku_Mowa

Obsługa błędów

Ważne jest, aby sprawdzić, czy gra może obsługiwać zmianę urządzenia audio, na przykład gdy słuchawki są podłączone lub odłączone. Należy to przetestować przy użyciu słuchawek, które obsługują tylko częstotliwość próbkowania 44,1 kHz. Wiele niskokońcowych słuchawek USB i zestawów słuchawkowych Bluetooth obsługuje tylko 44,1 kHz. Przejście między częstotliwością próbkowania 48 kHz a częstotliwością próbkowania 44,1 kHz może spowodować błąd nawet wtedy, gdy jest używana funkcja wirtualnego punktu końcowego audio . Błąd nie wystąpi, jeśli słuchawki obsługują również 48 kHz. Należy pamiętać, że funkcja wirtualnego punktu końcowego audio nie jest dostępna w systemie Windows 7 z dodatkiem SP1.

Kod błędu zwracany przez XAudio 2.9, gdy nie może automatycznie przywrócić sprawności po zmianie punktu końcowego audio, to XAUDIO2_E_DEVICE_INVALIDATED. Zalecamy jednak, aby aplikacje nie uzależniały się sztywno od kodu błędu o określonej wartości.

Aby otrzymywać powiadomienia o błędzie, aplikacja powinna zaimplementować interfejs IXAudio2EngineCallback i podać wskaźnik do tego interfejsu, wywołując metodę IXAudio2::RegisterForCallbacks . Implementacja aplikacji IXAudio2EngineCallback::OnCriticalError zostanie wywołana przez interfejs API XAudio2, jeśli podczas odtwarzania wystąpi błąd.

Należy pamiętać, że IXAudio2EngineCallback::OnCriticalError nie musi być wywoływany, jeśli potok audio jest wstrzymany. Jeśli na przykład użytkownik zminimalizuje aplikację lub aplikacja zostanie wstrzymana z jakiegokolwiek powodu, odtwarzanie audio może zostać wstrzymane. Jeśli w tym czasie nastąpi zmiana urządzenia audio, błąd zostanie zwrócony tylko wtedy, gdy aplikacja wywołuje ixAudio2::StartEngine i/lub wywołuje IXAudio2SourceVoice::Start. Jeśli odtwarzanie można wstrzymać za pomocą aplikacji, należy przetestować zmianę urządzenia audio podczas wstrzymania odtwarzania, aby sprawdzić, czy aplikacja nadal może odzyskać sprawność po tej sytuacji.

Różnice interfejsu API XAudio 2.9 w porównaniu z interfejsem XAudio 2.7

Ta sekcja zawiera podsumowanie niektórych różnic interfejsu API między XAudio 2.7 a wersją redystrybucyjną XAudio 2.9.

Obsługiwane formaty

Program XAudio 2.9 obsługuje te formaty wejściowe na komputerze:

• Liniowy 16-bitowy komputer PCM
• Liniowy 32-bitowy zmiennoprzecinkowy PCM
• 16-bitowe narzędzie ADPCM
• xWMA

Format XMA jest obsługiwany tylko na konsoli Xbox One.

Preferowany rdzeń procesora

Można określić, który rdzeni procesora CPU XAudio 2.9 powinien być używany dla wątku przetwarzania dźwięku. Jednak zazwyczaj preferowane jest, aby firma XAudio 2.9 sama wybrała tę wartość. Aby to zrobić, należy ustawić parametr XAudio2Processor w wywołaniu funkcji XAudio2Create na XAUDIO2_USE_DEFAULT_PROCESSOR.

XAudio 2.9 wybierze inny rdzeń procesora CPU na konsoli Xbox One niż na komputerze. Metody IXAudio2Extension::GetProcessor można użyć do określenia, który rdzeń procesora został wybrany przez XAudio2.

Wirtualny punkt końcowy audio

Program XAudio 2.9 domyślnie używa wirtualnego punktu końcowego dźwięku podczas uruchamiania w systemie Windows 8 lub nowszym. Oznacza to, że jeśli domyślny punkt końcowy dźwięku zmieni się podczas użycia biblioteki XAudio 2.9, podejmie próbę automatycznego przełączenia się do nowego punktu końcowego audio. Przykładem tego, kiedy może się to zdarzyć, gdy domyślnym punktem końcowym dźwięku jest para słuchawek podłączonych za pośrednictwem portu USB, a następnie użytkownik odłącza słuchawki. Spowoduje to, że głośniki będą nowym domyślnym punktem końcowym dźwięku.

Jeśli aplikacja określa określony format dźwięku podczas wywoływania IXAudio2::CreateMasteringVoice, może nie być możliwe, aby program XAudio 2.9 wykonał ten przełącznik. Na przykład, jeśli aplikacja określi, że Głos Masteringowy ma używać częstotliwości próbkowania 48 kHz, a nowe urządzenie audio obsługuje tylko 44,1 kHz, wtedy automatyczne przełączanie nie zadziała i XAudio 2.9 zgłosi błąd XAUDIO2_E_DEVICE_INVALIDATED.

Aplikacja może zrezygnować z korzystania z wirtualnego punktu końcowego audio, przekazując flagę XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT do ixAudio2::CreateMasteringVoice.

Wirtualne punkty końcowe audio nie są dostępne w systemie Windows 7 z dodatkiem SP1. Flaga XAUDIO2_NO_VIRTUAL_AUDIO_CLIENT nie ma wpływu na system Windows 7 z dodatkiem SP1.

Kategorie Audio

Aplikacja powinna określić kategorię strumienia audio. W tym celu należy podanie wartości z wyliczenia AudioCategory przy wywoływaniu metody IXAudio2::CreateMasteringVoice. Na przykład AudioCategory_GameEffects. Kategoria audio może mieć wpływ na sposób, w jaki system Windows przetwarza dźwięk lub jak reprezentuje strumień audio w panelu sterowania głośnością. Kategoria audio ma również wpływ na to, czy wirtualny dźwięk przestrzenny jest automatycznie włączony.

Czas trwania przetwarzania dźwięku kwantowego

Na większości komputerów XAudio 2.9 przetwarza dźwięk w fragmentach po 10 milisekund. Jest to nazywane kwantem przetwarzania. Jednak czas trwania tego kwantu może być inny niż 10 milisekund na pewnym sprzęcie. Aplikacje, które muszą znać dokładny kwant, mogą wywołać metodę IXAudio2Extension::GetProcessingQuantum w celu pobrania wartości.

Dźwięk przestrzenny i wirtualne otoczenie dźwiękowe

Począwszy od aktualizacji systemu Windows 10 1903, XAudio 2.9 automatycznie używa wirtualnego dźwięku otaczającego, jeśli spełnione są pewne warunki. Zalecamy testowanie gry, która generuje dźwięk wielokanałowy w systemie Windows 10 1903 (lub nowszym), aby sprawdzić, czy gra brzmi zgodnie z oczekiwaniami. Zobacz sekcję testowania dźwięku przestrzennego , aby zapoznać się z omówieniem sposobu testowania tej funkcji.

Zwykle XAudio 2.9 wykonuje zwijanie w dół dowolnego dźwięku wielokanałowego, aby dopasować "fizyczną" liczbę kanałów audio obsługiwanych przez punkt końcowy audio. Jeśli na przykład gra zapewnia źródło dźwięku 7.1, ale dźwięk jest odtwarzany na słuchawkach, XAudio 2.9 zmienia dźwięk 7.1 na dźwięk stereo, używając standardowej w branży macierzy składania. Jeśli komputer jest podłączony do punktu końcowego audio HDMI, dźwięk 7.1 kanału zostanie przesłany as-is przez połączenie HDMI.

System Windows 10 dodaje obsługę dźwięku przestrzennego przy użyciu scentralizowanego kodera, który koduje dźwięk w wybranym przez użytkownika formacie dźwięku przestrzennego . Windows 10 zawiera format dźwięku przestrzennego o nazwie Windows Sonic. Inne formaty, takie jak Dolby Atmos for Headphones, można pobrać ze Sklepu Microsoft. Niektóre formaty dźwięku przestrzennego, takie jak Windows Sonic i Dolby Atmos dla słuchawek, zostały zaprojektowane tak, aby były używane w punktach końcowych dźwięku stereo. Formaty te redukują dźwięk przestrzenny do stereo przy użyciu opatentowanych algorytmów, które osiągają efekt dźwięku „wirtualnego” przestrzennego. Innymi słowy, słuchacz może słyszeć dźwięk pojawiający się z różnych pozycji w przestrzeni 3D nawet podczas noszenia słuchawek lub podczas słuchania przy użyciu jednej pary głośników stereo.

Podobne efekty można osiągnąć, korzystając z interfejsów API X3DAudio, które są częścią XAudio 2.9. Główną różnicą jest to, że X3DAudio wymaga, aby deweloper aplikacji jawnie programował dźwięk 3D, podczas gdy wirtualny dźwięk przestrzenny jest stosowany automatycznie do dowolnego tradycyjnego źródła dźwięku opartego na kanałach.

Na systemach Windows 10 1903 i nowszych gry korzystające z XAudio 2.9 będą używać formatu dźwięku przestrzennego systemowego, który użytkownik włączył na wyjściu audio, jeśli jest on włączony. Oznacza to, że XAudio 2.9 nie będzie wykonywać zwykłego downmixingu dźwięku przestrzennego do stereo. Zamiast tego sygnał dźwięku otaczającego zostanie dostarczony do kodera dźwiękowego przestrzennego (np. Windows Sonic), aby osiągnąć wirtualny efekt dźwięku otaczającego.

CreateHrtfApo

Funkcja CreateHrtfApo jest dostępna tylko w systemie Windows 10. Nie jest on implementowany w zestawie redystrybucyjnym XAudio 2.9.