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

Artykuł
03/21/2025

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 odwiedzisz stronę główną 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 i Windows 10.

Gdy biblioteka DLL jest używana w systemie Windows 10, 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. W przypadku użycia na konsoli Xbox One biblioteka DLL zawsze deleguje wszystkie wywołania interfejsu API do XAUDIO2_9.DLL w systemie operacyjnym Xbox One.

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 Microsoft.XAudio2.Redist.targets. Plik .targets dodaje folder Include z plikami nagłówkowymi XAudio2 do ścieżek dołączania projektu. Plik .targets sprawi, że .DLL lub .EXE zostaną powiązane z XAUDIO2REDIST.LIB i XAPOBASEREDIST.LIB.

Biblioteka XAPOBASEREDIST.LIB jest wymagana tylko wtedy, gdy zamierzasz implementować niestandardowy obiekt przetwarzania XAudio (XAPO); można ją usunąć z Microsoft.XAudio2.Redist.targets, jeśli jest nieuż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.

Dostępny jest również port xaudio2redist 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 za pomocą 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łączania do projektu, ponieważ określenie ich w niewłaściwej kolejności może spowodować XAUDIO2 specyficzne dla systemu operacyjnego. H do dołączenia z zestawu Windows SDK, a nie 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ć 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 wyłączyć użycie kodera dźwięku przestrzennego w XAudio2, poprzez określenie określonych wartości dla 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
AudioCategory_GameMedia
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
AudioCategory_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 wrócić do 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 udostępnić wskaźnik do tego interfejsu, wywołując metodę IXAudio2::RegisterForCallbacks. Implementacja aplikacji IXAudio2EngineCallback::OnCriticalError zostanie wywołana przez API XAudio2, jeżeli podczas odtwarzania wystąpi błąd.

Należy pamiętać, że IXAudio2EngineCallback::OnCriticalError nie musi być wywoływana, 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 jest zwracany 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ść. W tym celu należy ustawić parametr XAudio2Processor w wywołaniu 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 XAudio 2.9 wykonał ten przełącznik. Jeśli na przykład aplikacja określiła, że Mastering Voice będzie używać częstotliwości próbkowania 48 kHz, a nowe urządzenie audio obsługuje tylko 44,1 kHz, automatyczne przełączanie nie powiedzie się, a 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 podać wartość z wyliczenia AudioCategory podczas wywoływania 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

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 do wybranego przez użytkownika formatu 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ąć przy użyciu interfejsów API X3DAudio, które są dołączone do 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.

Udostępnij za pośrednictwem